commit aa5e262f3ab777845b031ea08728937ed5c86b12
Author: glass beadian <glassbeadian@hdys.band>
Date:   Sat Oct 10 11:56:42 2026 +0000

    Tactical Media Broadcast Hub — initial release
    
    Self-hosted multi-platform broadcast newsroom for activist collectives:
    publishing pipeline with group approval and DST-proof scheduling, TweetDeck-style
    column wall with hostile-content-safe rendering, live control room with Auto
    Director, bridged chat governance with polls and quorum, distributed sandboxed
    transcode workers, encrypted content-addressed archive, monthly analytics.
    
    MIT licensed. See README.md and docs/.

diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000..87bebe6
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,10 @@
+# Build outputs that must never enter an image context (the helper binaries are rebuilt in-image).
+**/node_modules
+**/src/gate/rust/target
+apps/media-worker/bin
+# WP3 compiled images must build from source, without local outputs or data.
+**/dist
+**/.next
+.git
+tmp
+infra/occupymedia/files
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000..99580d0
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,9 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..167c4e6
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,22 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 9.12.0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      - run: pnpm build
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..3df549e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,31 @@
+node_modules/
+dist/
+.next/
+.turbo/
+coverage/
+*.log
+.env
+.env.*
+!.env.example
+.DS_Store
+runs/
+.omo/
+.codegraph/
+tmp/
+target/
+__pycache__/
+AGENTS.md
+
+# internal build-process artifacts — never release
+audit-*.json
+docs/reports/
+docs/research/
+docs/model-assignments.md
+docs/audit-final.md
+docs/execution-levels.md
+docs/proposal.md
+docs/work-breakdown.md
+docs/frontend-deep-dive.md
+docs/s2a-compositor-gate-report.md
+infra/occupymedia/files/
+apps/media-worker/tmp-wp12/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..d4089ef
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Tactical Media Broadcast Hub contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8410019
--- /dev/null
+++ b/README.md
@@ -0,0 +1,63 @@
+# Tactical Media Broadcast Hub
+
+Self-hosted multi-tenant social / video / livestream management platform with a
+generic connector system and a Virtual Channel / Auto Director subsystem.
+
+Built for collectives that need to coordinate media across platforms without
+concentrating access in one person's hands. Every credential lives in an
+encrypted vault. Every editorial decision lands in a tamper-evident audit log.
+Every feature is multi-tenant with row-level security.
+
+## Features
+
+- **Publishing pipeline** — drafts → group approval → schedule → fenced dispatch → receipts. Multi-platform fan-out (Mastodon, Telegram, Bluesky, PeerTube, Facebook, Instagram, Threads, LinkedIn, Reddit, Twitch, Discord, Slack). DST-proof scheduling.
+- **Column wall** — live multi-platform feed columns, TweetDeck-style. Safe rendering (hostile-HTML tested). Per-source cooldown + adaptive backoff.
+- **Live Control Room** — browser multiview, TAKE/CUT, preview/program, lower-thirds, scrolling chyrons, audio mixing, tally.
+- **Auto-Director** — priority rules switch sources automatically so the stream never dies mid-action.
+- **Chat governance** — bridged chats (Telegram/Twitch/Discord) into one overlay. Polls with configurable quorum. Approval gates on every post. Machine-readable reason codes.
+- **Distributed transcode workers** — laptops and GPUs join as render workers over Tailscale. Per-job sandboxed FFmpeg (UID/seccomp/no-network).
+- **Archive** — content-addressed encrypted S3, dedup, full-text search, CSV/JSON export. Deleted platform content stays citable.
+- **Analytics** — month-partitioned snapshots, current + previous month with deltas, per-provider breakdown.
+
+## Quickstart
+
+```bash
+pnpm install
+pnpm lint && pnpm typecheck && pnpm build
+
+# infrastructure
+docker compose -f infra/docker-compose.yml up -d postgres redis temporal minio otel-collector prometheus grafana
+
+# everything incl. media stub + mock live source + mock RTMP sink
+docker compose -f infra/docker-compose.yml --profile dev up -d
+
+# apps
+pnpm dev            # api :3000, web :3001(adjust if colliding), scheduler, media-worker :3100
+curl localhost:3000/healthz
+curl localhost:3000/readyz
+```
+
+## Documentation
+
+| Section | Path |
+|---|---|
+| Engineering guide | [`docs/engineering-guide.md`](docs/engineering-guide.md) |
+| Admin guide | [`docs/admin-guide.md`](docs/admin-guide.md) |
+| User manual | [`docs/user-manual-v2.md`](docs/user-manual-v2.md) |
+| Design docs | [`docs/design/`](docs/design/) |
+| Streaming architecture | [`docs/design/streaming-architecture.md`](docs/design/streaming-architecture.md) |
+| Deployment (occupymedia.cc) | [`infra/occupymedia/DEPLOY.md`](infra/occupymedia/DEPLOY.md) |
+
+## Deterministic live-source testing
+
+```bash
+pnpm --filter @tactical-media-broadcast-hub/media-worker soak -- --hours 8 --out
+```
+
+## Security & trust model
+
+Self-hosted, end to end — no corporate cloud, no accounts needed to run the
+system itself. Multi-tenant with row-level security; platform credentials in an
+encrypted vault the database never sees in plaintext; every editorial action in
+a hash-chained audit log; anonymous-infrastructure friendly (the host carries
+boxes, not content — storage is ciphertext).
diff --git a/apps/api/migrations/001_tenants.sql b/apps/api/migrations/001_tenants.sql
new file mode 100644
index 0000000..90d5cd5
--- /dev/null
+++ b/apps/api/migrations/001_tenants.sql
@@ -0,0 +1,212 @@
+-- 001: tenant schema, RLS, audit chain, lifecycle triggers
+CREATE EXTENSION IF NOT EXISTS pgcrypto;
+
+CREATE TABLE workspaces (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  name text NOT NULL,
+  slug text NOT NULL UNIQUE,
+  authz_epoch bigint NOT NULL DEFAULT 1,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE users (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  external_id text NOT NULL UNIQUE,
+  email text NOT NULL,
+  display_name text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE memberships (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  role text NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, user_id)
+);
+
+CREATE TABLE role_permissions (
+  role text NOT NULL,
+  permission text NOT NULL,
+  PRIMARY KEY (role, permission)
+);
+
+CREATE TABLE connections (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  provider text NOT NULL,
+  channel_id text NOT NULL,
+  fields jsonb NOT NULL DEFAULT '{}',
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE credentials (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  connection_id uuid REFERENCES connections(id) ON DELETE CASCADE,
+  kind text NOT NULL,
+  ciphertext bytea NOT NULL,
+  key_version int NOT NULL DEFAULT 1,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  rotated_at timestamptz
+);
+
+CREATE TABLE audit_log (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid REFERENCES workspaces(id) ON DELETE CASCADE,
+  actor_user_id uuid,
+  actor_role text,
+  action text NOT NULL,
+  target_type text NOT NULL,
+  target_id text NOT NULL,
+  diff jsonb,
+  at timestamptz NOT NULL DEFAULT now(),
+  seq bigint GENERATED ALWAYS AS IDENTITY,
+  prev_hash text,
+  hash text NOT NULL
+);
+CREATE INDEX audit_log_ws_chain ON audit_log (workspace_id, seq DESC) WHERE workspace_id IS NOT NULL;
+CREATE INDEX audit_log_system_chain ON audit_log (seq DESC) WHERE workspace_id IS NULL;
+
+-- Tenancy guard for SECURITY DEFINER functions (audit finding #3):
+-- every cross-tenant function takes an explicit workspace parameter and
+-- asserts it against the session's tenant context.
+CREATE FUNCTION fn_assert_tenant(p_workspace_id uuid) RETURNS void
+LANGUAGE plpgsql STABLE AS $$
+DECLARE v_ctx text;
+BEGIN
+  v_ctx := current_setting('app.workspace_id', true);
+  IF v_ctx IS NULL OR v_ctx = '' OR v_ctx::uuid IS DISTINCT FROM p_workspace_id THEN
+    RAISE EXCEPTION 'tenant context mismatch' USING ERRCODE = '42501';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM workspaces w WHERE w.id = p_workspace_id) THEN
+    RAISE EXCEPTION 'unknown workspace' USING ERRCODE = '42501';
+  END IF;
+END $$;
+
+-- Hash chain: tenant rows chain per workspace; system rows chain on the
+-- workspace_id IS NULL branch. Branch selection is by TENANT CONTEXT
+-- PRESENCE, never by role (audit findings #1/#6: sp_scheduler/vault callers
+-- with an active tenant context must append to that tenant's chain).
+CREATE FUNCTION audit_hash(p_prev text, p_actor uuid, p_action text, p_target_id text, p_at timestamptz)
+RETURNS text LANGUAGE sql IMMUTABLE AS $$
+  SELECT encode(digest(
+    coalesce(p_prev, '') || '|' || coalesce(p_actor::text, '') || '|' ||
+    p_action || '|' || p_target_id || '|' || extract(epoch FROM p_at)::text,
+    'sha256'), 'hex')
+$$;
+
+CREATE FUNCTION audit_append(
+  p_workspace_id uuid,
+  p_actor_user_id uuid,
+  p_actor_role text,
+  p_action text,
+  p_target_type text,
+  p_target_id text,
+  p_diff jsonb DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_id uuid; v_prev text; v_hash text; v_now timestamptz := clock_timestamp();
+BEGIN
+  PERFORM fn_assert_tenant(p_workspace_id);
+  SELECT hash INTO v_prev FROM audit_log
+   WHERE workspace_id = p_workspace_id ORDER BY seq DESC LIMIT 1;
+  v_hash := audit_hash(v_prev, p_actor_user_id, p_action, p_target_id, v_now);
+  INSERT INTO audit_log (workspace_id, actor_user_id, actor_role, action, target_type, target_id, diff, at, prev_hash, hash)
+  VALUES (p_workspace_id, p_actor_user_id, p_actor_role, p_action, p_target_type, p_target_id, p_diff, v_now, v_prev, v_hash)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+CREATE FUNCTION audit_append_system(
+  p_actor_user_id uuid,
+  p_action text,
+  p_target_type text,
+  p_target_id text,
+  p_diff jsonb DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_id uuid; v_prev text; v_hash text; v_now timestamptz := clock_timestamp();
+BEGIN
+  IF coalesce(current_setting('app.workspace_id', true), '') <> '' THEN
+    RAISE EXCEPTION 'system append must not run inside a tenant context (use audit_append)';
+  END IF;
+  SELECT hash INTO v_prev FROM audit_log
+   WHERE workspace_id IS NULL ORDER BY seq DESC LIMIT 1;
+  v_hash := audit_hash(v_prev, p_actor_user_id, p_action, p_target_id, v_now);
+  INSERT INTO audit_log (workspace_id, actor_user_id, action, target_type, target_id, diff, at, prev_hash, hash)
+  VALUES (NULL, p_actor_user_id, p_action, p_target_type, p_target_id, p_diff, v_now, v_prev, v_hash)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+-- Tamper detection: recompute the chain.
+CREATE FUNCTION audit_verify_chain(p_workspace_id uuid DEFAULT NULL) RETURNS boolean
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = public AS $$
+DECLARE r record; v_prev text := NULL;
+BEGIN
+  FOR r IN SELECT * FROM audit_log
+            WHERE workspace_id IS NOT DISTINCT FROM p_workspace_id
+            ORDER BY seq ASC LOOP
+    IF r.prev_hash IS DISTINCT FROM v_prev THEN RETURN false; END IF;
+    IF audit_hash(r.prev_hash, r.actor_user_id, r.action, r.target_id, r.at) <> r.hash THEN
+      RETURN false;
+    END IF;
+    v_prev := r.hash;
+  END LOOP;
+  RETURN true;
+END $$;
+
+-- Lifecycle immutability (audit finding #8): tenant rows never change tenant.
+CREATE FUNCTION reject_workspace_change() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.workspace_id IS DISTINCT FROM OLD.workspace_id THEN
+    RAISE EXCEPTION 'workspace_id is immutable' USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_conn_ws_immutable BEFORE UPDATE ON connections
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_cred_ws_immutable BEFORE UPDATE ON credentials
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_mem_ws_immutable BEFORE UPDATE ON memberships
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- Continuous authz (audit finding #2): membership/role changes bump the
+-- workspace authz epoch so live sessions fail closed on next check.
+-- COALESCE matters: OLD is NULL-valued on INSERT, NEW on DELETE.
+CREATE FUNCTION bump_authz_epoch() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  UPDATE workspaces SET authz_epoch = authz_epoch + 1
+   WHERE id = COALESCE(NEW.workspace_id, OLD.workspace_id);
+  RETURN COALESCE(NEW, OLD);
+END $$;
+
+CREATE TRIGGER trg_mem_bump_epoch AFTER INSERT OR UPDATE OR DELETE ON memberships
+  FOR EACH ROW EXECUTE FUNCTION bump_authz_epoch();
+
+-- RLS: fail closed. Missing app.workspace_id => NULL => no tenant rows visible.
+-- FORCE: applies even to the table owner, so the single-role dev pool cannot
+-- silently bypass tenancy; tenant writes must go through withTenant().
+ALTER TABLE memberships ENABLE ROW LEVEL SECURITY;
+ALTER TABLE connections ENABLE ROW LEVEL SECURITY;
+ALTER TABLE credentials ENABLE ROW LEVEL SECURITY;
+ALTER TABLE audit_log ENABLE ROW LEVEL SECURITY;
+ALTER TABLE memberships FORCE ROW LEVEL SECURITY;
+ALTER TABLE connections FORCE ROW LEVEL SECURITY;
+ALTER TABLE credentials FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON memberships
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON connections
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON credentials
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_audit ON audit_log
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
diff --git a/apps/api/migrations/002_rbac_seed.sql b/apps/api/migrations/002_rbac_seed.sql
new file mode 100644
index 0000000..f0a286c
--- /dev/null
+++ b/apps/api/migrations/002_rbac_seed.sql
@@ -0,0 +1,90 @@
+-- 002: RBAC seed — 37 permissions across 10 roles
+-- publication.delete is a legacy seed (including Publisher). Deprecated for moderation;
+-- future hide/delete routes must use dedicated moderation permissions from 011.
+BEGIN;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Owner', p FROM unnest(ARRAY[
+  'workspace.view','workspace.settings','workspace.members.manage',
+  'connection.view','connection.manage','credential.manage',
+  'draft.view','draft.create','draft.edit','approval.request','approval.grant',
+  'publication.publish','publication.schedule','publication.delete',
+  'media.view','media.manage','inbox.view','inbox.reply','stream.view',
+  'analytics.view','audit.view',
+  'virtualchannel.view','virtualchannel.create','virtualchannel.edit',
+  'director.view','director.take','director.override_auto','director.change_layout','director.lock_program',
+  'streamsource.manage','streamoutput.manage',
+  'livestream.view','livestream.manage',
+  'livechat.view','livechat.send','livechat.moderate'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Admin', p FROM unnest(ARRAY[
+  'workspace.view','workspace.settings','workspace.members.manage',
+  'connection.view','connection.manage','credential.manage',
+  'draft.view','draft.create','draft.edit','approval.request','approval.grant',
+  'publication.publish','publication.schedule','publication.delete',
+  'media.view','media.manage','inbox.view','inbox.reply','stream.view',
+  'analytics.view','audit.view',
+  'virtualchannel.view','director.view','livestream.view','livechat.view'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Publisher', p FROM unnest(ARRAY[
+  'workspace.view','connection.view','draft.view','draft.create','draft.edit',
+  'approval.request','publication.publish','publication.schedule','publication.delete',
+  'media.view','media.manage','inbox.view','inbox.reply','stream.view','analytics.view'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Editor', p FROM unnest(ARRAY[
+  'workspace.view','connection.view','draft.view','draft.create','draft.edit',
+  'media.view','media.manage','inbox.view','inbox.reply','stream.view'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Approver', p FROM unnest(ARRAY[
+  'workspace.view','draft.view','approval.grant','analytics.view','audit.view'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Analyst', p FROM unnest(ARRAY[
+  'workspace.view','analytics.view','stream.view','audit.view'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Moderator', p FROM unnest(ARRAY[
+  'workspace.view','inbox.view','inbox.reply',
+  'livechat.view','livechat.send','livechat.moderate'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'VideoPublisher', p FROM unnest(ARRAY[
+  'workspace.view','draft.view','draft.create','draft.edit',
+  'publication.publish','publication.schedule','media.view','media.manage'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'StreamOperator', p FROM unnest(ARRAY[
+  'workspace.view','livestream.view','livestream.manage','stream.view'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'BroadcastOperator', p FROM unnest(ARRAY[
+  'workspace.view','virtualchannel.view',
+  'director.view','director.take','director.override_auto','director.change_layout','director.lock_program',
+  'streamsource.manage','livestream.view',
+  'livechat.view','livechat.send','livechat.moderate'
+]) AS p
+ON CONFLICT DO NOTHING;
+
+COMMIT;
diff --git a/apps/api/migrations/003_app_role.sql b/apps/api/migrations/003_app_role.sql
new file mode 100644
index 0000000..d5cbacf
--- /dev/null
+++ b/apps/api/migrations/003_app_role.sql
@@ -0,0 +1,19 @@
+-- 003: dedicated non-superuser app role for the runtime pool.
+-- Migrations run as the table owner (superuser in dev); the application and
+-- tests connect as sp_app — neither superuser nor owner — so FORCE ROW LEVEL
+-- SECURITY binds for real.
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'sp_app') THEN
+    CREATE ROLE sp_app LOGIN PASSWORD 'sp_app_dev' NOSUPERUSER NOCREATEDB NOCREATEROLE;
+  END IF;
+END $$;
+
+GRANT USAGE ON SCHEMA public TO sp_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO sp_app;
+GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO sp_app;
+
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO sp_app;
+ALTER DEFAULT PRIVILEGES IN SCHEMA public
+  GRANT USAGE, SELECT ON SEQUENCES TO sp_app;
diff --git a/apps/api/migrations/004_policy_nullif.sql b/apps/api/migrations/004_policy_nullif.sql
new file mode 100644
index 0000000..0ce94c4
--- /dev/null
+++ b/apps/api/migrations/004_policy_nullif.sql
@@ -0,0 +1,16 @@
+-- 004: pooled sessions can carry an empty-string GUC placeholder after
+-- SET LOCAL commits; NULLIF makes the RLS expressions fail closed cleanly
+-- instead of raising a cast error.
+DROP POLICY IF EXISTS tenant_isolation ON memberships;
+DROP POLICY IF EXISTS tenant_isolation ON connections;
+DROP POLICY IF EXISTS tenant_isolation ON credentials;
+DROP POLICY IF EXISTS tenant_audit ON audit_log;
+
+CREATE POLICY tenant_isolation ON memberships
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON connections
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON credentials
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_audit ON audit_log
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
diff --git a/apps/api/migrations/005_epoch_fix.sql b/apps/api/migrations/005_epoch_fix.sql
new file mode 100644
index 0000000..2965df9
--- /dev/null
+++ b/apps/api/migrations/005_epoch_fix.sql
@@ -0,0 +1,10 @@
+-- 005: fix epoch bump for INSERT (OLD is NULL on INSERT; the original
+-- UPDATE matched zero rows silently). CREATE OR REPLACE also strips any
+-- debug variant left in dev databases.
+CREATE OR REPLACE FUNCTION bump_authz_epoch() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  UPDATE workspaces SET authz_epoch = authz_epoch + 1
+   WHERE id = COALESCE(NEW.workspace_id, OLD.workspace_id);
+  RETURN COALESCE(NEW, OLD);
+END $$;
diff --git a/apps/api/migrations/006_publishing.sql b/apps/api/migrations/006_publishing.sql
new file mode 100644
index 0000000..952fea2
--- /dev/null
+++ b/apps/api/migrations/006_publishing.sql
@@ -0,0 +1,89 @@
+-- 006: publishing pipeline (drafts -> approval -> scheduling -> publication)
+CREATE TABLE drafts (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  author_user_id uuid NOT NULL REFERENCES users(id),
+  post jsonb NOT NULL,
+  state text NOT NULL DEFAULT 'editing'
+    CHECK (state IN ('editing', 'in_review', 'approved', 'rejected', 'scheduled', 'published')),
+  reviewer_user_id uuid REFERENCES users(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE scheduled_publications (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,
+  connection_id uuid NOT NULL REFERENCES connections(id),
+  publish_at timestamptz NOT NULL,
+  idempotency_key text NOT NULL UNIQUE,
+  state text NOT NULL DEFAULT 'pending'
+    CHECK (state IN ('pending', 'in_flight', 'done', 'failed')),
+  error text,
+  UNIQUE (draft_id)
+);
+
+CREATE TABLE publications (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,
+  connection_id uuid NOT NULL REFERENCES connections(id),
+  idempotency_key text NOT NULL UNIQUE,
+  remote_id text NOT NULL,
+  remote_url text,
+  published_at timestamptz NOT NULL,
+  provider_metadata jsonb NOT NULL DEFAULT '{}'
+);
+
+CREATE INDEX drafts_workspace_state ON drafts (workspace_id, state);
+CREATE INDEX scheduled_publications_due ON scheduled_publications (publish_at)
+  WHERE state = 'pending';
+CREATE INDEX publications_draft ON publications (draft_id);
+
+CREATE TRIGGER trg_draft_ws_immutable BEFORE UPDATE ON drafts
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_scheduled_pub_ws_immutable BEFORE UPDATE ON scheduled_publications
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_publication_ws_immutable BEFORE UPDATE ON publications
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE drafts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE scheduled_publications ENABLE ROW LEVEL SECURITY;
+ALTER TABLE publications ENABLE ROW LEVEL SECURITY;
+ALTER TABLE drafts FORCE ROW LEVEL SECURITY;
+ALTER TABLE scheduled_publications FORCE ROW LEVEL SECURITY;
+ALTER TABLE publications FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON drafts
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON scheduled_publications
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON publications
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON drafts, scheduled_publications, publications TO sp_app;
+
+-- Narrow SECURITY DEFINER lookups let the scheduler discover tenant context
+-- without weakening FORCE RLS for ordinary table access.
+CREATE FUNCTION publishing_schedule_workspace(p_idempotency_key text) RETURNS uuid
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT workspace_id
+  FROM scheduled_publications
+  WHERE idempotency_key = p_idempotency_key
+$$;
+
+CREATE FUNCTION publishing_due_schedules() RETURNS TABLE(idempotency_key text, publish_at timestamptz)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT sp.idempotency_key, sp.publish_at
+  FROM scheduled_publications sp
+  WHERE sp.state = 'pending' AND sp.publish_at <= now()
+  ORDER BY sp.publish_at
+$$;
+
+REVOKE ALL ON FUNCTION publishing_schedule_workspace(text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION publishing_due_schedules() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION publishing_schedule_workspace(text), publishing_due_schedules() TO sp_app;
diff --git a/apps/api/migrations/007_auth.sql b/apps/api/migrations/007_auth.sql
new file mode 100644
index 0000000..31298c7
--- /dev/null
+++ b/apps/api/migrations/007_auth.sql
@@ -0,0 +1,30 @@
+-- 007: first-party auth (email + password) and membership invitations.
+-- Passwords live in their own table (never in users, never in audit diffs);
+-- hashes are scrypt with a per-user salt, produced by apps/api/src/auth/password.ts.
+CREATE TABLE user_passwords (
+  user_id uuid PRIMARY KEY REFERENCES users(id) ON DELETE CASCADE,
+  password_hash text NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+-- Invited members exist as memberships before they first sign in.
+ALTER TABLE memberships
+  ADD COLUMN status text NOT NULL DEFAULT 'active'
+  CHECK (status IN ('active', 'invited'));
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON user_passwords TO sp_app;
+
+-- Login happens before any tenant context exists, and memberships is FORCE
+-- RLS. This narrow SECURITY DEFINER lookup returns only the caller-supplied
+-- user's own memberships so login can pick a workspace without weakening RLS.
+CREATE FUNCTION auth_user_memberships(p_user_id uuid)
+RETURNS TABLE(workspace_id uuid, role text, status text, created_at timestamptz)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT m.workspace_id, m.role, m.status, m.created_at
+  FROM memberships m
+  WHERE m.user_id = p_user_id
+  ORDER BY m.created_at ASC
+$$;
+
+REVOKE ALL ON FUNCTION auth_user_memberships(uuid) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION auth_user_memberships(uuid) TO sp_app;
diff --git a/apps/api/migrations/008_groups.sql b/apps/api/migrations/008_groups.sql
new file mode 100644
index 0000000..ac9ef3b
--- /dev/null
+++ b/apps/api/migrations/008_groups.sql
@@ -0,0 +1,104 @@
+-- 008: groups — sub-workspace sharing scopes for connections and assets.
+-- Group membership gates which connections a non-Owner/Admin can publish through.
+--
+-- Child tables carry a denormalised workspace_id so that:
+--   * RLS is the same direct column predicate as every other tenant table
+--     (no subquery policies);
+--   * composite FKs pin every row to ONE workspace — a group cannot hold a
+--     connection or a member from another tenant, even via the owner pool;
+--   * the epoch bump can read workspace_id from the row itself. Looking it up
+--     in groups would miss cascaded deletes (DELETE FROM groups -> its
+--     group_members rows), because the parent row is already gone when the
+--     child's AFTER trigger runs — deleting a group would silently skip the bump.
+
+-- Composite FK targets.
+ALTER TABLE connections ADD CONSTRAINT connections_id_workspace_key UNIQUE (id, workspace_id);
+
+CREATE TABLE groups (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  name text NOT NULL CHECK (btrim(name) <> ''),
+  description text NOT NULL DEFAULT '',
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, name),
+  UNIQUE (id, workspace_id)
+);
+
+CREATE TABLE group_members (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  group_id uuid NOT NULL,
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  added_by uuid REFERENCES users(id) ON DELETE SET NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (group_id, user_id),
+  FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id) ON DELETE CASCADE,
+  -- Only workspace members can join a group; leaving the workspace leaves its groups.
+  FOREIGN KEY (workspace_id, user_id) REFERENCES memberships(workspace_id, user_id) ON DELETE CASCADE
+);
+
+CREATE TABLE group_connections (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  group_id uuid NOT NULL,
+  connection_id uuid NOT NULL,
+  assigned_by uuid REFERENCES users(id) ON DELETE SET NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (group_id, connection_id),
+  FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id) ON DELETE CASCADE,
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections(id, workspace_id) ON DELETE CASCADE
+);
+
+CREATE TABLE group_assets (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  group_id uuid NOT NULL,
+  asset_id text NOT NULL CHECK (btrim(asset_id) <> ''), -- media asset storage key or id
+  assigned_by uuid REFERENCES users(id) ON DELETE SET NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (group_id, asset_id),
+  FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id) ON DELETE CASCADE
+);
+
+CREATE INDEX group_members_user ON group_members (workspace_id, user_id);
+CREATE INDEX group_connections_connection ON group_connections (connection_id);
+
+CREATE TRIGGER trg_group_ws_immutable BEFORE UPDATE ON groups
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_group_member_ws_immutable BEFORE UPDATE ON group_members
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_group_connection_ws_immutable BEFORE UPDATE ON group_connections
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_group_asset_ws_immutable BEFORE UPDATE ON group_assets
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- Continuous authz: group membership is an authorization input (it gates
+-- publishing), so changes bump the workspace epoch exactly like memberships.
+-- Reuses bump_authz_epoch() (001/005): it reads the row's own workspace_id,
+-- which also covers cascades from DELETE FROM groups / memberships.
+CREATE TRIGGER trg_group_member_bump_epoch AFTER INSERT OR UPDATE OR DELETE ON group_members
+  FOR EACH ROW EXECUTE FUNCTION bump_authz_epoch();
+
+ALTER TABLE groups ENABLE ROW LEVEL SECURITY;
+ALTER TABLE group_members ENABLE ROW LEVEL SECURITY;
+ALTER TABLE group_connections ENABLE ROW LEVEL SECURITY;
+ALTER TABLE group_assets ENABLE ROW LEVEL SECURITY;
+ALTER TABLE groups FORCE ROW LEVEL SECURITY;
+ALTER TABLE group_members FORCE ROW LEVEL SECURITY;
+ALTER TABLE group_connections FORCE ROW LEVEL SECURITY;
+ALTER TABLE group_assets FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON groups
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON group_members
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON group_connections
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON group_assets
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON groups, group_members, group_connections, group_assets TO sp_app;
diff --git a/apps/api/migrations/009_video.sql b/apps/api/migrations/009_video.sql
new file mode 100644
index 0000000..510ec73
--- /dev/null
+++ b/apps/api/migrations/009_video.sql
@@ -0,0 +1,52 @@
+-- 009: first-class video assets and their processing lifecycle
+CREATE TABLE video_assets (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  storage_key text NOT NULL,
+  mime_type text NOT NULL,
+  size_bytes bigint NOT NULL,
+  width int,
+  height int,
+  duration_ms int,
+  frame_rate numeric,
+  codec text,
+  audio_codec text,
+  thumbnail_key text,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE video_processing_jobs (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  video_asset_id uuid NOT NULL REFERENCES video_assets(id) ON DELETE CASCADE,
+  state text NOT NULL CHECK (state IN ('queued', 'probing', 'transcoding', 'complete', 'failed')),
+  progress_percent int NOT NULL DEFAULT 0,
+  output_key text,
+  error text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX video_assets_workspace_created
+  ON video_assets (workspace_id, created_at DESC, id DESC);
+CREATE INDEX video_processing_jobs_asset_created
+  ON video_processing_jobs (video_asset_id, created_at DESC);
+
+CREATE TRIGGER trg_video_asset_ws_immutable BEFORE UPDATE ON video_assets
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_video_job_ws_immutable BEFORE UPDATE ON video_processing_jobs
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE video_assets ENABLE ROW LEVEL SECURITY;
+ALTER TABLE video_processing_jobs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE video_assets FORCE ROW LEVEL SECURITY;
+ALTER TABLE video_processing_jobs FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON video_assets
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON video_processing_jobs
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON video_assets, video_processing_jobs TO sp_app;
diff --git a/apps/api/migrations/010_audit_hash_v2.sql b/apps/api/migrations/010_audit_hash_v2.sql
new file mode 100644
index 0000000..455eef8
--- /dev/null
+++ b/apps/api/migrations/010_audit_hash_v2.sql
@@ -0,0 +1,80 @@
+-- 010: hash the audit diff and serialize appends to each chain.
+BEGIN;
+
+ALTER TABLE audit_log ADD COLUMN hash_version smallint NOT NULL DEFAULT 1
+  CHECK (hash_version IN (1, 2));
+
+CREATE FUNCTION audit_hash_v2(p_prev text, p_actor uuid, p_action text, p_target_id text,
+                              p_at timestamptz, p_diff jsonb)
+RETURNS text LANGUAGE sql IMMUTABLE AS $$
+  SELECT encode(digest(
+    coalesce(p_prev, '') || '|' || coalesce(p_actor::text, '') || '|' ||
+    p_action || '|' || p_target_id || '|' || extract(epoch FROM p_at)::text || '|' ||
+    coalesce(p_diff::text, ''),
+    'sha256'), 'hex')
+$$;
+
+CREATE OR REPLACE FUNCTION audit_append(
+  p_workspace_id uuid, p_actor_user_id uuid, p_actor_role text, p_action text,
+  p_target_type text, p_target_id text, p_diff jsonb DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_id uuid; v_prev text; v_hash text; v_now timestamptz := clock_timestamp();
+BEGIN
+  PERFORM fn_assert_tenant(p_workspace_id);
+  PERFORM pg_advisory_xact_lock(hashtext('audit:' || p_workspace_id::text));
+  SELECT hash INTO v_prev FROM audit_log
+   WHERE workspace_id = p_workspace_id ORDER BY seq DESC LIMIT 1;
+  v_hash := audit_hash_v2(v_prev, p_actor_user_id, p_action, p_target_id, v_now, p_diff);
+  INSERT INTO audit_log (workspace_id, actor_user_id, actor_role, action, target_type, target_id,
+                         diff, at, prev_hash, hash, hash_version)
+  VALUES (p_workspace_id, p_actor_user_id, p_actor_role, p_action, p_target_type, p_target_id,
+          p_diff, v_now, v_prev, v_hash, 2)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+CREATE OR REPLACE FUNCTION audit_append_system(
+  p_actor_user_id uuid, p_action text, p_target_type text, p_target_id text,
+  p_diff jsonb DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_id uuid; v_prev text; v_hash text; v_now timestamptz := clock_timestamp();
+BEGIN
+  IF coalesce(current_setting('app.workspace_id', true), '') <> '' THEN
+    RAISE EXCEPTION 'system append must not run inside a tenant context (use audit_append)';
+  END IF;
+  PERFORM pg_advisory_xact_lock(hashtext('audit:system'));
+  SELECT hash INTO v_prev FROM audit_log
+   WHERE workspace_id IS NULL ORDER BY seq DESC LIMIT 1;
+  v_hash := audit_hash_v2(v_prev, p_actor_user_id, p_action, p_target_id, v_now, p_diff);
+  INSERT INTO audit_log (workspace_id, actor_user_id, action, target_type, target_id,
+                         diff, at, prev_hash, hash, hash_version)
+  VALUES (NULL, p_actor_user_id, p_action, p_target_type, p_target_id,
+          p_diff, v_now, v_prev, v_hash, 2)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+CREATE OR REPLACE FUNCTION audit_verify_chain(p_workspace_id uuid DEFAULT NULL) RETURNS boolean
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = public AS $$
+DECLARE r record; v_prev text := NULL; v_expected text;
+BEGIN
+  FOR r IN SELECT * FROM audit_log
+            WHERE workspace_id IS NOT DISTINCT FROM p_workspace_id
+            ORDER BY seq ASC LOOP
+    IF r.prev_hash IS DISTINCT FROM v_prev THEN RETURN false; END IF;
+    IF r.hash_version = 1 THEN
+      v_expected := audit_hash(r.prev_hash, r.actor_user_id, r.action, r.target_id, r.at);
+    ELSE
+      v_expected := audit_hash_v2(r.prev_hash, r.actor_user_id, r.action, r.target_id, r.at, r.diff);
+    END IF;
+    IF v_expected IS DISTINCT FROM r.hash THEN RETURN false; END IF;
+    v_prev := r.hash;
+  END LOOP;
+  RETURN true;
+END $$;
+
+COMMIT;
diff --git a/apps/api/migrations/012_live_sources.sql b/apps/api/migrations/012_live_sources.sql
new file mode 100644
index 0000000..5d0ca0b
--- /dev/null
+++ b/apps/api/migrations/012_live_sources.sql
@@ -0,0 +1,114 @@
+-- 012: WP8 Live Source Monitor — per-source reducer state + observation dedupe.
+-- (010/011 are reserved for the WP7 egress package; the monitor consumes those
+-- budgets later and deliberately carries no rate machinery of its own.)
+--
+-- One row per monitored source identity (connection_id, remote_ref): the keyed
+-- partition the MonitorObservation reducer folds into (proposal §4.4). Each
+-- child row carries a denormalised workspace_id so RLS stays a direct column
+-- predicate and composite FKs pin the row to ONE workspace's connection.
+--
+-- `version` is the per-source compare-and-swap token: every applied mutation
+-- bumps it, updates are guarded by `WHERE ... AND version = $n`, conflicting
+-- writers reload and re-evaluate, and downstream consumers (WS fan-out,
+-- outbox) drop non-increasing versions.
+
+CREATE TABLE source_monitor_states (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  connection_id uuid NOT NULL,
+  remote_ref text NOT NULL CHECK (btrim(remote_ref) <> ''),
+  state text NOT NULL DEFAULT 'OFFLINE'
+    CHECK (state IN ('OFFLINE', 'PROBING', 'LIVE', 'UNSTABLE', 'ERROR')),
+  version bigint NOT NULL DEFAULT 0 CHECK (version >= 0),
+  -- Highest *available* signal tier; NULL until the first fresh signal lands.
+  authoritative_tier text
+    CHECK (authoritative_tier IN ('media-health', 'hls-probe', 'webhook', 'api-poll')),
+  -- Last applied observedAt per signal tier. Staleness is judged WITHIN one
+  -- tier only (provider clocks are not comparable across signal sources).
+  last_media_health_at timestamptz,
+  last_hls_probe_at timestamptz,
+  last_webhook_at timestamptz,
+  last_api_poll_at timestamptz,
+  -- Remaining per-tier reducer bookkeeping: lastOutcome, lastProviderEventId,
+  -- deniedUntil, failStreak. jsonb keeps the reducer state shape in one place.
+  tier_status jsonb NOT NULL DEFAULT '{}'::jsonb,
+  ok_streak int NOT NULL DEFAULT 0 CHECK (ok_streak >= 0),
+  fail_streak int NOT NULL DEFAULT 0 CHECK (fail_streak >= 0),
+  state_entered_at timestamptz NOT NULL DEFAULT now(),
+  -- Hysteresis: min-hold keeps a freshly entered state from being cut down,
+  -- cooldown blocks the reverse transition (no rapid A -> B -> A).
+  hold_until timestamptz,
+  cooldown_until timestamptz,
+  previous_state text CHECK (previous_state IN ('OFFLINE', 'PROBING', 'LIVE', 'UNSTABLE', 'ERROR')),
+  last_transition_at timestamptz,
+  last_transition_reason text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, connection_id, remote_ref),
+  UNIQUE (id, workspace_id),
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id) ON DELETE CASCADE
+);
+
+CREATE INDEX source_monitor_states_ws_created
+  ON source_monitor_states (workspace_id, created_at DESC, id DESC);
+CREATE INDEX source_monitor_states_ws_state
+  ON source_monitor_states (workspace_id, state);
+
+-- Observation dedupe is enforced by the DB, not the app (proposal §4.4): a
+-- replayed providerEventId can never apply twice, regardless of which process
+-- or replica delivers it. Rows are journal entries, never mutated.
+CREATE TABLE monitor_seen_events (
+  workspace_id uuid NOT NULL,
+  provider_event_id text NOT NULL CHECK (btrim(provider_event_id) <> ''),
+  source_monitor_state_id uuid NOT NULL,
+  seen_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, provider_event_id),
+  FOREIGN KEY (source_monitor_state_id, workspace_id)
+    REFERENCES source_monitor_states (id, workspace_id) ON DELETE CASCADE
+);
+CREATE INDEX monitor_seen_events_seen_at ON monitor_seen_events (seen_at);
+
+CREATE TRIGGER trg_monitor_state_ws_immutable BEFORE UPDATE ON source_monitor_states
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_monitor_seen_event_ws_immutable BEFORE UPDATE ON monitor_seen_events
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE source_monitor_states ENABLE ROW LEVEL SECURITY;
+ALTER TABLE monitor_seen_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE source_monitor_states FORCE ROW LEVEL SECURITY;
+ALTER TABLE monitor_seen_events FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON source_monitor_states
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON monitor_seen_events
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON source_monitor_states, monitor_seen_events TO sp_app;
+
+-- Narrow SECURITY DEFINER lookup: the monitor/scheduler processes discover the
+-- tenant that owns a source without weakening FORCE RLS for ordinary access
+-- (same standing as publishing_schedule_workspace in 006).
+CREATE FUNCTION live_monitor_source_workspace(p_connection_id uuid, p_remote_ref text) RETURNS uuid
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT workspace_id
+  FROM source_monitor_states
+  WHERE connection_id = p_connection_id AND remote_ref = p_remote_ref
+  LIMIT 1
+$$;
+
+-- Retention for the dedupe journal. Runs in system context on purpose: pruned
+-- rows span tenants, and a tenant that stops recording must not leak journal
+-- rows forever.
+CREATE FUNCTION monitor_prune_seen_events(p_before timestamptz) RETURNS integer
+LANGUAGE sql SECURITY DEFINER SET search_path = public AS $$
+  WITH removed AS (
+    DELETE FROM monitor_seen_events WHERE seen_at < p_before RETURNING 1
+  )
+  SELECT count(*) FROM removed
+$$;
+
+REVOKE ALL ON FUNCTION live_monitor_source_workspace(uuid, text) FROM PUBLIC;
+REVOKE ALL ON FUNCTION monitor_prune_seen_events(timestamptz) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION live_monitor_source_workspace(uuid, text), monitor_prune_seen_events(timestamptz) TO sp_app;
diff --git a/apps/api/migrations/013_production.sql b/apps/api/migrations/013_production.sql
new file mode 100644
index 0000000..646b615
--- /dev/null
+++ b/apps/api/migrations/013_production.sql
@@ -0,0 +1,327 @@
+-- 013: Streaming slice S1 — production schema (docs/design/streaming-architecture.md
+-- §2, §4, §6 S1; proposal §4.4 same-channel invariant).
+--
+-- No virtual channel or channel-source table existed before this migration, so
+-- 013 creates the minimal `virtual_channels` / `virtual_channel_sources` the
+-- production tables hang off. `virtual_channel_sources.kind` is born with
+-- `playlist` alongside `hls` (§5.1: a playlist is an ordinary ingest kind).
+--
+-- Same-channel invariant (structural, not a handler check): every production
+-- row carries `virtual_channel_id`, and every reference to a scene, source or
+-- overlay goes through a composite FK that includes (workspace_id,
+-- virtual_channel_id). A slot can only reference a source of its own channel,
+-- a bus can only hold a scene of its own channel, an overlay revision can only
+-- belong to an overlay slot of its own channel — a cross-channel write fails
+-- at the constraint, whichever code path issued it.
+--
+-- Guard FKs (a reference that must block a direct delete but not a purge)
+-- are NO ACTION *and* DEFERRABLE INITIALLY DEFERRED. Plain NO ACTION is
+-- checked when each cascade step's RI trigger fires, so a workspace purge that
+-- reaches video_assets before it reaches playlist_items (deeper in the
+-- workspace -> channel -> source -> item chain) aborts mid-cascade. Deferred,
+-- the check runs at commit: a purge succeeds, a direct delete still fails.
+--
+-- Geometry is integer basis points of the output frame (0..10000), matching
+-- the desired-state v2 type layer (apps/api/src/media-control/production.ts).
+
+-- Video assets get the composite key that playlist items reference, so a
+-- playlist can never name another tenant's asset by raw id.
+ALTER TABLE video_assets ADD CONSTRAINT video_assets_id_workspace_key UNIQUE (id, workspace_id);
+
+-- Ownership columns (the row's parent aggregate) are immutable: moving a row
+-- to another parent is delete + create. A column listed with a leading '?' is
+-- an `ON DELETE SET NULL` reference: only its non-null -> NULL transition (the
+-- FK action itself) is permitted.
+CREATE FUNCTION reject_owner_change() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE
+  col text;
+  nullable boolean;
+  old_value text;
+  new_value text;
+BEGIN
+  FOREACH col IN ARRAY TG_ARGV LOOP
+    nullable := left(col, 1) = '?';
+    IF nullable THEN col := substr(col, 2); END IF;
+    old_value := to_jsonb(OLD) ->> col;
+    new_value := to_jsonb(NEW) ->> col;
+    IF new_value IS DISTINCT FROM old_value AND NOT (nullable AND new_value IS NULL) THEN
+      RAISE EXCEPTION '%.% is immutable', TG_TABLE_NAME, col USING ERRCODE = '23514';
+    END IF;
+  END LOOP;
+  RETURN NEW;
+END $$;
+
+CREATE TABLE virtual_channels (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  slug text NOT NULL CHECK (slug ~ '^[a-z0-9][a-z0-9-]{0,62}$'),
+  name text NOT NULL CHECK (btrim(name) <> '' AND length(name) <= 120),
+  desired_status text NOT NULL DEFAULT 'STOPPED' CHECK (desired_status IN ('STOPPED', 'RUNNING')),
+  observed_status text NOT NULL DEFAULT 'STOPPED'
+    CHECK (observed_status IN ('PENDING_CAPACITY', 'STOPPED', 'STARTING', 'RUNNING', 'DEGRADED', 'RESTARTING', 'FAILED', 'UNKNOWN')),
+  -- The single per-channel desiredVersion fence: every desired-state tx
+  -- (TAKE, scene edit, overlay swap, gain step) locks this row FOR UPDATE and
+  -- bumps it once.
+  desired_version bigint NOT NULL DEFAULT 0 CHECK (desired_version >= 0),
+  observed_version bigint NOT NULL DEFAULT 0 CHECK (observed_version >= 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, slug),
+  UNIQUE (workspace_id, id)
+);
+
+CREATE TABLE virtual_channel_sources (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('hls', 'playlist')),
+  label text NOT NULL CHECK (label ~ '^[[:alnum:]][[:alnum:] _.-]{0,63}$'),
+  priority int NOT NULL DEFAULT 0 CHECK (priority >= 0),
+  -- Connection the source was imported through (a candidate poller); NULL for
+  -- playlists and hand-entered URLs.
+  connection_id uuid,
+  -- Remote identity (import dedupe); a playlist is local and has none.
+  remote_ref text CHECK (remote_ref IS NULL OR btrim(remote_ref) <> ''),
+  hls_url text CHECK (hls_url IS NULL OR (hls_url ~ '^https://' AND length(hls_url) <= 2048)),
+  playlist_loop boolean,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CHECK (
+    (kind = 'hls' AND hls_url IS NOT NULL AND playlist_loop IS NULL) OR
+    (kind = 'playlist' AND hls_url IS NULL AND remote_ref IS NULL AND connection_id IS NULL AND playlist_loop IS NOT NULL)
+  ),
+  UNIQUE (workspace_id, virtual_channel_id, remote_ref),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, virtual_channel_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id) REFERENCES virtual_channels (workspace_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT DEFERRABLE INITIALLY DEFERRED
+);
+CREATE INDEX virtual_channel_sources_priority ON virtual_channel_sources (workspace_id, virtual_channel_id, priority);
+CREATE INDEX virtual_channel_sources_connection ON virtual_channel_sources (connection_id, workspace_id) WHERE connection_id IS NOT NULL;
+
+-- Ordered, pre-normalized assets of a playlist source (the worker's asset feeder walks these).
+CREATE TABLE playlist_items (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  source_id uuid NOT NULL,
+  position int NOT NULL CHECK (position >= 0 AND position < 500),
+  video_asset_id uuid NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, source_id, position),
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id, source_id) REFERENCES virtual_channel_sources (workspace_id, virtual_channel_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (video_asset_id, workspace_id) REFERENCES video_assets (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT DEFERRABLE INITIALLY DEFERRED
+);
+CREATE INDEX playlist_items_asset ON playlist_items (video_asset_id, workspace_id);
+
+CREATE TABLE production_scenes (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  label text NOT NULL CHECK (label ~ '^[[:alnum:]][[:alnum:] _.-]{0,63}$'),
+  layout text NOT NULL CHECK (layout IN ('single', 'pip', '2x1', '2x2', '3x3', '4x4', 'custom')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, virtual_channel_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id) REFERENCES virtual_channels (workspace_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+CREATE INDEX production_scenes_channel ON production_scenes (workspace_id, virtual_channel_id);
+
+CREATE TABLE scene_slots (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  scene_id uuid NOT NULL,
+  slot_index int NOT NULL CHECK (slot_index >= 0 AND slot_index < 16),
+  -- NULL = empty slot (renders the fallback); also the ON DELETE SET NULL target.
+  source_id uuid,
+  -- Explicit rectangle for custom layouts and PIP insets; all NULL = the layout's own cell.
+  x int, y int, w int, h int,
+  fit text NOT NULL DEFAULT 'contain' CHECK (fit IN ('contain', 'cover', 'crop')),
+  audio_mode text NOT NULL DEFAULT 'off' CHECK (audio_mode IN ('off', 'on', 'primary')),
+  gain_db smallint NOT NULL DEFAULT 0 CHECK (gain_db BETWEEN -24 AND 0 AND gain_db % 3 = 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CHECK ((x IS NULL AND y IS NULL AND w IS NULL AND h IS NULL) OR
+         (x IS NOT NULL AND y IS NOT NULL AND w IS NOT NULL AND h IS NOT NULL)),
+  CHECK (x >= 0 AND y >= 0 AND w > 0 AND h > 0),
+  CHECK (x + w <= 10000 AND y + h <= 10000),
+  UNIQUE (workspace_id, scene_id, slot_index),
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id, scene_id) REFERENCES production_scenes (workspace_id, virtual_channel_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Column-list SET NULL (PostgreSQL >= 15): empties the slot, keeps tenant + channel set.
+  FOREIGN KEY (workspace_id, virtual_channel_id, source_id) REFERENCES virtual_channel_sources (workspace_id, virtual_channel_id, id)
+    ON DELETE SET NULL (source_id) ON UPDATE RESTRICT
+);
+-- At most one primary audio slot per scene (program mix default: primary-only).
+CREATE UNIQUE INDEX scene_slots_one_primary ON scene_slots (workspace_id, scene_id) WHERE audio_mode = 'primary';
+CREATE INDEX scene_slots_source ON scene_slots (workspace_id, virtual_channel_id, source_id) WHERE source_id IS NOT NULL;
+CREATE INDEX scene_slots_scene ON scene_slots (workspace_id, virtual_channel_id, scene_id);
+
+CREATE TABLE production_buses (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  bus text NOT NULL CHECK (bus IN ('preview', 'program')),
+  -- Declared mutable reference: TAKE/CUT re-point it in place. NULL = empty bus.
+  -- NO ACTION: a scene on a bus cannot be deleted directly, but a channel
+  -- cascade that removes both succeeds (checked at end of statement).
+  scene_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, virtual_channel_id, bus),
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id) REFERENCES virtual_channels (workspace_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (workspace_id, virtual_channel_id, scene_id) REFERENCES production_scenes (workspace_id, virtual_channel_id, id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT DEFERRABLE INITIALLY DEFERRED
+);
+CREATE INDEX production_buses_scene ON production_buses (workspace_id, virtual_channel_id, scene_id) WHERE scene_id IS NOT NULL;
+
+-- An overlay slot sits on one scene; toggling `enabled` arms it on PST and it
+-- goes live with TAKE. Its pixels are always a pre-rendered asset (§4.2)
+-- except the server-generated clock, whose format is a closed enum.
+CREATE TABLE overlay_slots (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  scene_id uuid NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('lower_third', 'chyron', 'logo', 'clock')),
+  enabled boolean NOT NULL DEFAULT false,
+  layer smallint NOT NULL DEFAULT 0 CHECK (layer BETWEEN 0 AND 7),
+  pos_x int NOT NULL DEFAULT 0 CHECK (pos_x BETWEEN 0 AND 10000),
+  pos_y int NOT NULL DEFAULT 0 CHECK (pos_y BETWEEN 0 AND 10000),
+  chyron_speed_px_s smallint CHECK (chyron_speed_px_s BETWEEN 40 AND 400),
+  chyron_strip_width_px int CHECK (chyron_strip_width_px BETWEEN 1 AND 16384),
+  clock_format text CHECK (clock_format IN ('HH:MM', 'HH:MM:SS')),
+  -- Revision currently composited; NULL until the first render lands.
+  current_revision_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CHECK ((kind = 'chyron') = (chyron_speed_px_s IS NOT NULL AND chyron_strip_width_px IS NOT NULL)),
+  CHECK (kind = 'chyron' OR (chyron_speed_px_s IS NULL AND chyron_strip_width_px IS NULL)),
+  CHECK ((kind = 'clock') = (clock_format IS NOT NULL)),
+  CHECK (kind <> 'clock' OR current_revision_id IS NULL),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, virtual_channel_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id, scene_id) REFERENCES production_scenes (workspace_id, virtual_channel_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+CREATE INDEX overlay_slots_scene ON overlay_slots (workspace_id, virtual_channel_id, scene_id);
+
+-- Append-only history of an overlay slot's validated content and its rendered
+-- asset. FFmpeg only ever sees `asset_id` (sha256 content id from StorageService).
+CREATE TABLE overlay_revisions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  overlay_slot_id uuid NOT NULL,
+  template_id text NOT NULL CHECK (template_id ~ '^[a-z0-9][a-z0-9_-]{0,63}$'),
+  -- Typed field values (title <= 80, subtitle <= 120, style enum), validated in the app layer.
+  fields jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(fields) = 'object'),
+  render_state text NOT NULL DEFAULT 'pending' CHECK (render_state IN ('pending', 'rendered', 'failed')),
+  asset_id text CHECK (asset_id ~ '^[0-9a-f]{64}$'),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  CHECK ((render_state = 'rendered') = (asset_id IS NOT NULL)),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, virtual_channel_id, overlay_slot_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id, overlay_slot_id) REFERENCES overlay_slots (workspace_id, virtual_channel_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+CREATE INDEX overlay_revisions_slot ON overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, created_at DESC);
+
+-- The current revision must be one of THIS slot's revisions (same channel, same slot).
+ALTER TABLE overlay_slots ADD CONSTRAINT overlay_slots_current_revision_fkey
+  FOREIGN KEY (workspace_id, virtual_channel_id, id, current_revision_id)
+  REFERENCES overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, id)
+  ON DELETE SET NULL (current_revision_id) ON UPDATE RESTRICT;
+CREATE INDEX overlay_slots_current_revision ON overlay_slots (workspace_id, virtual_channel_id, id, current_revision_id)
+  WHERE current_revision_id IS NOT NULL;
+
+-- Immutability: tenant column everywhere, ownership columns per table.
+CREATE TRIGGER trg_virtual_channel_ws_immutable BEFORE UPDATE ON virtual_channels
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_vc_source_ws_immutable BEFORE UPDATE ON virtual_channel_sources
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_vc_source_owner_immutable BEFORE UPDATE ON virtual_channel_sources
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id', 'kind');
+CREATE TRIGGER trg_playlist_item_ws_immutable BEFORE UPDATE ON playlist_items
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_playlist_item_owner_immutable BEFORE UPDATE ON playlist_items
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id', 'source_id');
+CREATE TRIGGER trg_scene_ws_immutable BEFORE UPDATE ON production_scenes
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_scene_owner_immutable BEFORE UPDATE ON production_scenes
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id');
+CREATE TRIGGER trg_scene_slot_ws_immutable BEFORE UPDATE ON scene_slots
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_scene_slot_owner_immutable BEFORE UPDATE ON scene_slots
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id', 'scene_id', '?source_id');
+CREATE TRIGGER trg_bus_ws_immutable BEFORE UPDATE ON production_buses
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_bus_owner_immutable BEFORE UPDATE ON production_buses
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id', 'bus');
+CREATE TRIGGER trg_overlay_slot_ws_immutable BEFORE UPDATE ON overlay_slots
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_overlay_slot_owner_immutable BEFORE UPDATE ON overlay_slots
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id', 'scene_id', 'kind');
+CREATE TRIGGER trg_overlay_revision_ws_immutable BEFORE UPDATE ON overlay_revisions
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_overlay_revision_owner_immutable BEFORE UPDATE ON overlay_revisions
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id', 'overlay_slot_id', 'template_id', 'fields');
+
+ALTER TABLE virtual_channels ENABLE ROW LEVEL SECURITY;
+ALTER TABLE virtual_channel_sources ENABLE ROW LEVEL SECURITY;
+ALTER TABLE playlist_items ENABLE ROW LEVEL SECURITY;
+ALTER TABLE production_scenes ENABLE ROW LEVEL SECURITY;
+ALTER TABLE scene_slots ENABLE ROW LEVEL SECURITY;
+ALTER TABLE production_buses ENABLE ROW LEVEL SECURITY;
+ALTER TABLE overlay_slots ENABLE ROW LEVEL SECURITY;
+ALTER TABLE overlay_revisions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE virtual_channels FORCE ROW LEVEL SECURITY;
+ALTER TABLE virtual_channel_sources FORCE ROW LEVEL SECURITY;
+ALTER TABLE playlist_items FORCE ROW LEVEL SECURITY;
+ALTER TABLE production_scenes FORCE ROW LEVEL SECURITY;
+ALTER TABLE scene_slots FORCE ROW LEVEL SECURITY;
+ALTER TABLE production_buses FORCE ROW LEVEL SECURITY;
+ALTER TABLE overlay_slots FORCE ROW LEVEL SECURITY;
+ALTER TABLE overlay_revisions FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON virtual_channels
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON virtual_channel_sources
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON playlist_items
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON production_scenes
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON scene_slots
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON production_buses
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON overlay_slots
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON overlay_revisions
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON virtual_channels, virtual_channel_sources, playlist_items,
+  production_scenes, scene_slots, production_buses, overlay_slots, overlay_revisions TO sp_app;
diff --git a/apps/api/migrations/014_live_chat.sql b/apps/api/migrations/014_live_chat.sql
new file mode 100644
index 0000000..a13cb29
--- /dev/null
+++ b/apps/api/migrations/014_live_chat.sql
@@ -0,0 +1,236 @@
+-- 014: Streaming slice S5 — chat hub + device pairing
+-- (docs/design/streaming-architecture.md §3, §6 S5).
+--
+-- Design notes:
+--   * `live_chat_messages` is keyed by (workspace, channel) — the chat hub's
+--     aggregate is a virtual channel's live chat, and the seq cursor a client
+--     resumes with is per channel. Global provider dedupe uses a nonpartitioned
+--     claim journal; the paging index is (workspace_id, channel_id, seq).
+--   * Ordering is a hub-assigned `seq` under a row lock on the channel's
+--     chat_seq row; provider timestamps stay display-only (clocks skew, §3.2).
+--   * Monthly received_at partitions retain ingress ordering. PostgreSQL needs
+--     the partition key in unique constraints, so global provider dedupe lives
+--     in the nonpartitioned live_chat_seen_events journal, claimed in the same
+--     transaction as the message insert.
+--   * Devices and pairings carry their own workspace column and direct
+--     workspace FK so revocation is workspace-scoped; user_id references
+--     users(id) ON DELETE CASCADE so deleting a user removes their devices.
+--
+-- RLS / NULLIF / sp_app grants follow 012/013 conventions.
+
+-- One row per (workspace, channel) holding the chat sequence. FOR UPDATE on
+-- this row inside the ingest transaction is what makes seq assignment monotonic
+-- per channel (§3.2 "monotonic seq assigned at hub ingress").
+CREATE TABLE live_chat_seq (
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  channel_id uuid NOT NULL,
+  seq bigint NOT NULL DEFAULT 0 CHECK (seq >= 0),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, channel_id),
+  FOREIGN KEY (channel_id, workspace_id) REFERENCES virtual_channels (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+
+CREATE TABLE live_chat_messages (
+  id uuid NOT NULL DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  channel_id uuid NOT NULL,
+  -- Provider connection that produced the message (capability target).
+  connection_id uuid NOT NULL,
+  provider text NOT NULL CHECK (btrim(provider) <> ''),
+  -- Provider's own message id; the dedupe key with workspace + provider.
+  provider_msg_id text NOT NULL CHECK (btrim(provider_msg_id) <> ''),
+  -- Author
+  author_handle text NOT NULL CHECK (btrim(author_handle) <> ''),
+  author_display_name text,
+  author_avatar_url text,
+  author_badges jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(author_badges) = 'array'),
+  author_color text NOT NULL CHECK (author_color <> ''),
+  body text NOT NULL CHECK (length(body) <= 5000),
+  -- Reply threading (provider message id of the parent, nullable).
+  reply_to text,
+  -- Hub ingress
+  seq bigint NOT NULL CHECK (seq > 0),
+  sent_at timestamptz NOT NULL,
+  received_at timestamptz NOT NULL DEFAULT now(),
+  is_moderated boolean NOT NULL DEFAULT false,
+  source text NOT NULL DEFAULT 'live-chat' CHECK (source IN ('live-chat', 'social-reply', 'system')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (id, received_at),
+  UNIQUE (workspace_id, provider, provider_msg_id, received_at),
+  FOREIGN KEY (channel_id, workspace_id) REFERENCES virtual_channels (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT DEFERRABLE INITIALLY DEFERRED
+) PARTITION BY RANGE (received_at);
+
+-- Precreate monthly partitions; administrators run this before a new month.
+CREATE FUNCTION live_chat_ensure_month(p_month date) RETURNS void
+LANGUAGE plpgsql SET search_path = public AS $$
+DECLARE v_start timestamptz := date_trunc('month', p_month::timestamptz);
+  v_table text := 'live_chat_messages_' || to_char(v_start, 'YYYYMM');
+BEGIN
+  EXECUTE format('CREATE TABLE IF NOT EXISTS %I PARTITION OF live_chat_messages FOR VALUES FROM (%L) TO (%L)',
+    v_table, v_start, v_start + interval '1 month');
+  EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', v_table);
+  EXECUTE format('ALTER TABLE %I FORCE ROW LEVEL SECURITY', v_table);
+  IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname='public' AND tablename=v_table AND policyname='tenant_isolation') THEN
+    EXECUTE format('CREATE POLICY tenant_isolation ON %I USING (workspace_id = NULLIF(current_setting(''app.workspace_id'', true), '''')::uuid) WITH CHECK (workspace_id = NULLIF(current_setting(''app.workspace_id'', true), '''')::uuid)', v_table);
+  END IF;
+END $$;
+REVOKE ALL ON FUNCTION live_chat_ensure_month(date) FROM PUBLIC;
+SELECT live_chat_ensure_month((current_date - interval '1 month')::date);
+SELECT live_chat_ensure_month(current_date);
+SELECT live_chat_ensure_month((current_date + interval '1 month')::date);
+CREATE TABLE live_chat_messages_default PARTITION OF live_chat_messages DEFAULT;
+ALTER TABLE live_chat_messages_default ENABLE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_messages_default FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON live_chat_messages_default
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+CREATE INDEX live_chat_messages_channel_seq ON live_chat_messages (workspace_id, channel_id, seq);
+CREATE INDEX live_chat_messages_author ON live_chat_messages (workspace_id, channel_id, author_handle);
+
+-- Global provider-message/event claim journal, mirroring
+-- monitor_seen_events (ON CONFLICT DO NOTHING semantics come from the PK).
+CREATE TABLE live_chat_seen_events (
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  provider text NOT NULL CHECK (btrim(provider) <> ''),
+  provider_event_id text NOT NULL CHECK (btrim(provider_event_id) <> ''),
+  seen_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, provider, provider_event_id)
+);
+
+CREATE TRIGGER trg_live_chat_seen_event_ws_immutable BEFORE UPDATE ON live_chat_seen_events
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- Devices: Opticast authenticates with a device token, not a session cookie
+-- (§3.4). Epoch-gated: revoking bumps the epoch, tokens fail closed.
+CREATE TABLE devices (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  name text NOT NULL CHECK (btrim(name) <> '' AND length(name) <= 120),
+  scopes text[] NOT NULL DEFAULT '{livechat.view,stream.view}'::text[],
+  epoch bigint NOT NULL DEFAULT 1 CHECK (epoch >= 1),
+  authz_epoch bigint NOT NULL,
+  last_seen_at timestamptz,
+  revoked_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id)
+);
+CREATE INDEX devices_ws_user ON devices (workspace_id, user_id);
+CREATE INDEX devices_ws_revoked ON devices (workspace_id) WHERE revoked_at IS NULL;
+
+-- Single-use, TTL'd pairing codes. `redeemed_at` enforces single use; the
+-- expiry is checked by the app (a code may expire unredeemed, and a purge of
+-- expired rows is a plain DELETE).
+CREATE TABLE device_pairings (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  code text NOT NULL CHECK (code ~ '^[A-Z0-9]{4}-[A-Z0-9]{4}$'),
+  qr_payload text NOT NULL,
+  scopes text[] NOT NULL,
+  expires_at timestamptz NOT NULL,
+  redeemed_at timestamptz,
+  device_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (code),
+  UNIQUE (workspace_id, code),
+  FOREIGN KEY (device_id, workspace_id) REFERENCES devices (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT DEFERRABLE INITIALLY DEFERRED
+);
+CREATE INDEX device_pairings_ws_open ON device_pairings (workspace_id, code) WHERE redeemed_at IS NULL;
+
+CREATE TRIGGER trg_device_ws_immutable BEFORE UPDATE ON devices FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_device_pairing_ws_immutable BEFORE UPDATE ON device_pairings FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_live_chat_message_ws_immutable BEFORE UPDATE ON live_chat_messages FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_live_chat_seq_ws_immutable BEFORE UPDATE ON live_chat_seq FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE live_chat_seq ENABLE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_messages ENABLE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_seen_events ENABLE ROW LEVEL SECURITY;
+ALTER TABLE devices ENABLE ROW LEVEL SECURITY;
+ALTER TABLE device_pairings ENABLE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_seq FORCE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_messages FORCE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_seen_events FORCE ROW LEVEL SECURITY;
+ALTER TABLE devices FORCE ROW LEVEL SECURITY;
+ALTER TABLE device_pairings FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON live_chat_seq
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON live_chat_messages
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON live_chat_seen_events
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON devices
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON device_pairings
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON live_chat_seq, live_chat_messages, live_chat_seen_events,
+  devices, device_pairings TO sp_app;
+
+-- Retention (follow-on, noted here so the partition/retention row from the
+-- work-breakdown finds its anchor): pruning live_chat_seen_events older than
+-- the journal window, mirroring monitor_prune_seen_events from 012.
+CREATE FUNCTION live_chat_prune_seen_events(p_before timestamptz) RETURNS integer
+LANGUAGE sql SECURITY INVOKER SET search_path = public AS $$
+  WITH removed AS (
+    DELETE FROM live_chat_seen_events WHERE seen_at < p_before RETURNING 1
+  )
+  SELECT count(*) FROM removed
+$$;
+REVOKE ALL ON FUNCTION live_chat_prune_seen_events(timestamptz) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION live_chat_prune_seen_events(timestamptz) TO sp_app;
+
+-- Resolves only a valid short-lived bearer pairing code; no tenant rows exposed.
+CREATE FUNCTION device_pairing_workspace(p_code text) RETURNS uuid
+LANGUAGE sql SECURITY DEFINER SET search_path = public AS $$
+  SELECT workspace_id FROM device_pairings WHERE code=p_code AND expires_at > now()
+$$;
+REVOKE ALL ON FUNCTION device_pairing_workspace(text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION device_pairing_workspace(text) TO sp_app;
+
+-- Tenant-scoped retention for messages and their dedupe claims.
+CREATE FUNCTION live_chat_prune(p_workspace uuid, p_before timestamptz) RETURNS integer
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE v_count integer;
+BEGIN
+  PERFORM fn_assert_tenant(p_workspace);
+  DELETE FROM live_chat_messages WHERE workspace_id=p_workspace AND received_at < p_before;
+  GET DIAGNOSTICS v_count = ROW_COUNT;
+  DELETE FROM live_chat_seen_events WHERE workspace_id=p_workspace AND seen_at < p_before;
+  DELETE FROM device_pairings WHERE workspace_id=p_workspace AND expires_at < p_before;
+  RETURN v_count;
+END $$;
+REVOKE ALL ON FUNCTION live_chat_prune(uuid,timestamptz) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION live_chat_prune(uuid,timestamptz) TO sp_app;
+
+CREATE TABLE live_chat_requests (
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  route text NOT NULL,
+  request_key text NOT NULL,
+  request_hash text NOT NULL,
+  status text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','complete','failed')),
+  response jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id,user_id,route,request_key)
+);
+ALTER TABLE live_chat_requests ENABLE ROW LEVEL SECURITY;
+ALTER TABLE live_chat_requests FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON live_chat_requests
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE TRIGGER trg_live_chat_request_ws_immutable BEFORE UPDATE ON live_chat_requests
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+GRANT SELECT,INSERT,UPDATE,DELETE ON live_chat_requests TO sp_app;
diff --git a/apps/api/migrations/015_archive.sql b/apps/api/migrations/015_archive.sql
new file mode 100644
index 0000000..3f3e30c
--- /dev/null
+++ b/apps/api/migrations/015_archive.sql
@@ -0,0 +1,88 @@
+-- 015: WP15 Telegram live channel archive. All identities are tenant pinned.
+CREATE TABLE feed_subscriptions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  type text NOT NULL CHECK (type = 'telegram_channel'),
+  connection_id uuid NOT NULL,
+  channel_id text NOT NULL CHECK (btrim(channel_id) <> ''),
+  health text NOT NULL DEFAULT 'active' CHECK (health IN ('active', 'bot_removed', 'admin_required')),
+  health_checked_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, connection_id, channel_id),
+  UNIQUE (id, workspace_id),
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT
+);
+CREATE INDEX feed_subscriptions_channel ON feed_subscriptions (workspace_id, channel_id);
+
+CREATE TABLE archived_feed_items (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  remote_ref text NOT NULL CHECK (remote_ref ~ '^(-?[0-9]+|@[A-Za-z0-9_]+):[0-9]+$'),
+  channel_id text NOT NULL,
+  message_id bigint NOT NULL CHECK (message_id > 0),
+  media_group_id text,
+  text_content text NOT NULL DEFAULT '',
+  content_hash text NOT NULL CHECK (content_hash ~ '^[0-9a-f]{64}$'),
+  revision integer NOT NULL DEFAULT 1 CHECK (revision > 0),
+  media_refs jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(media_refs) = 'array'),
+  attribution jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(attribution) = 'object'),
+  protected_content boolean NOT NULL DEFAULT false,
+  posted_at timestamptz NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, remote_ref),
+  UNIQUE (id, workspace_id),
+  CHECK (remote_ref = channel_id || ':' || message_id::text)
+);
+CREATE INDEX archived_feed_items_cursor ON archived_feed_items (workspace_id, posted_at DESC, id DESC);
+
+CREATE TABLE archived_feed_revisions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  item_id uuid NOT NULL,
+  revision integer NOT NULL CHECK (revision > 0),
+  content_hash text NOT NULL CHECK (content_hash ~ '^[0-9a-f]{64}$'),
+  text_content text NOT NULL,
+  media_refs jsonb NOT NULL CHECK (jsonb_typeof(media_refs) = 'array'),
+  attribution jsonb NOT NULL CHECK (jsonb_typeof(attribution) = 'object'),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, item_id, revision),
+  FOREIGN KEY (item_id, workspace_id) REFERENCES archived_feed_items (id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT
+);
+
+-- drafts predates tenant-pinned references.
+ALTER TABLE drafts ADD CONSTRAINT drafts_id_workspace_key UNIQUE (id, workspace_id);
+
+CREATE TABLE archived_feed_drafts (
+  workspace_id uuid NOT NULL,
+  item_id uuid NOT NULL,
+  draft_id uuid NOT NULL UNIQUE,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, item_id, draft_id),
+  FOREIGN KEY (item_id, workspace_id) REFERENCES archived_feed_items (id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts (id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_feed_subscriptions_ws_immutable BEFORE UPDATE ON feed_subscriptions
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_archived_feed_items_ws_immutable BEFORE UPDATE ON archived_feed_items
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_archived_feed_revisions_ws_immutable BEFORE UPDATE ON archived_feed_revisions
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_archived_feed_drafts_ws_immutable BEFORE UPDATE ON archived_feed_drafts
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE feed_subscriptions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE archived_feed_items ENABLE ROW LEVEL SECURITY;
+ALTER TABLE archived_feed_revisions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE archived_feed_drafts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE feed_subscriptions FORCE ROW LEVEL SECURITY;
+ALTER TABLE archived_feed_items FORCE ROW LEVEL SECURITY;
+ALTER TABLE archived_feed_revisions FORCE ROW LEVEL SECURITY;
+ALTER TABLE archived_feed_drafts FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON feed_subscriptions USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid) WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON archived_feed_items USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid) WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON archived_feed_revisions USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid) WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON archived_feed_drafts USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid) WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON feed_subscriptions, archived_feed_items, archived_feed_revisions, archived_feed_drafts TO sp_app;
diff --git a/apps/api/migrations/016_username_auth.sql b/apps/api/migrations/016_username_auth.sql
new file mode 100644
index 0000000..a8d1e2d
--- /dev/null
+++ b/apps/api/migrations/016_username_auth.sql
@@ -0,0 +1,20 @@
+-- 016: username-based first-party auth.
+-- Usernames are the login identity (external_id = local:<username>); email is
+-- optional metadata for future password recovery. Existing email-keyed users
+-- get a username derived from their email local-part (or display name).
+ALTER TABLE users ADD COLUMN username text;
+
+UPDATE users SET username = COALESCE(
+  NULLIF(regexp_replace(lower(split_part(coalesce(email, ''), '@', 1)), '[^a-z0-9_.-]', '', 'g'), ''),
+  NULLIF(regexp_replace(lower(display_name), '[^a-z0-9_.-]', '', 'g'), ''),
+  'member'
+);
+-- Deterministic dedupe: colliding candidates get a short id suffix.
+UPDATE users u SET username = u.username || '_' || substr(u.id::text, 1, 4)
+WHERE EXISTS (SELECT 1 FROM users v WHERE v.username = u.username AND v.id < u.id);
+
+ALTER TABLE users ALTER COLUMN username SET NOT NULL;
+CREATE UNIQUE INDEX users_username_key ON users (username);
+ALTER TABLE users ALTER COLUMN email DROP NOT NULL;
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON users TO sp_app;
diff --git a/apps/api/migrations/017_invite_links.sql b/apps/api/migrations/017_invite_links.sql
new file mode 100644
index 0000000..aa6c933
--- /dev/null
+++ b/apps/api/migrations/017_invite_links.sql
@@ -0,0 +1,64 @@
+-- 017: multi-use, expiring workspace invite links (Telegram-style).
+-- One link, many claimants: anyone holding the token may join with the link's
+-- role until the link expires, is revoked, or exhausts max_uses (null =
+-- unlimited until expiry). Claimers arrive unauthenticated, so the claim path
+-- is the SECURITY DEFINER analogue of login (see invite_link_for_claim below):
+-- workspace_invite_links is FORCE RLS and no tenant context exists pre-join.
+CREATE TABLE workspace_invite_links (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  role text NOT NULL,
+  token text NOT NULL UNIQUE,
+  created_by uuid NOT NULL REFERENCES users(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  expires_at timestamptz NOT NULL,
+  max_uses int CHECK (max_uses IS NULL OR max_uses > 0),
+  use_count int NOT NULL DEFAULT 0 CHECK (use_count >= 0),
+  revoked_at timestamptz
+);
+
+CREATE TRIGGER trg_invite_link_ws_immutable BEFORE UPDATE ON workspace_invite_links
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- Same fail-closed tenant isolation as every tenant table (001/006 style):
+-- no app.workspace_id => NULL => no rows. FORCE binds sp_app too.
+ALTER TABLE workspace_invite_links ENABLE ROW LEVEL SECURITY;
+ALTER TABLE workspace_invite_links FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON workspace_invite_links
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON workspace_invite_links TO sp_app;
+
+-- Claim runs with NO tenant context (the claimer has no membership yet), and
+-- the table is FORCE RLS: ordinary SELECTs see zero rows. Like
+-- auth_user_memberships (007) and publishing_schedule_workspace (006), this
+-- narrow SECURITY DEFINER lookup exposes exactly one row keyed by the secret
+-- token — workspace_id discovery only; the caller enters the tenant context
+-- afterwards and every subsequent statement is RLS-bound as sp_app.
+CREATE FUNCTION invite_link_for_claim(p_token text)
+RETURNS TABLE(id uuid, workspace_id uuid, role text, expires_at timestamptz,
+              max_uses int, use_count int, revoked_at timestamptz)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT l.id, l.workspace_id, l.role, l.expires_at, l.max_uses, l.use_count, l.revoked_at
+  FROM workspace_invite_links l
+  WHERE l.token = p_token
+$$;
+
+REVOKE ALL ON FUNCTION invite_link_for_claim(text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION invite_link_for_claim(text) TO sp_app;
+
+-- Token lookup at claim time: point lookup served by the backing index of the
+-- inline UNIQUE constraint on token (auto-named workspace_invite_links_token_key).
+-- Statement for documentation/parity with 016's users_username_key — do NOT run twice:
+-- CREATE UNIQUE INDEX workspace_invite_links_token_key ON workspace_invite_links (token);
+
+-- Workspace listing (admin GET /team/invite-links), newest first:
+CREATE INDEX workspace_invite_links_ws_created
+  ON workspace_invite_links (workspace_id, created_at DESC);
+
+-- Expiry sweep / active-link diagnostics, mirroring the partial-index style of
+-- audit_log (001) and scheduled_publications_due (006):
+CREATE INDEX workspace_invite_links_expiry
+  ON workspace_invite_links (expires_at) WHERE revoked_at IS NULL;
diff --git a/apps/api/migrations/018_publishing_execution.sql b/apps/api/migrations/018_publishing_execution.sql
new file mode 100644
index 0000000..ef52838
--- /dev/null
+++ b/apps/api/migrations/018_publishing_execution.sql
@@ -0,0 +1,485 @@
+-- 018: WP3 publishing execution spine (fences, attempt journal, receipts).
+-- Preserves 006: same drafts / scheduled_publications / publications tables,
+-- same PKs, UNIQUE(draft_id) on schedules and global idempotency_key
+-- uniqueness. Adds the scheduling principal, revision/approval proof,
+-- credential generation/revocation, execution generation and the durable
+-- attempt journal the scheduler claims, fences and finalizes against.
+--
+-- The current runner (db/migrate.ts) wraps each file in ONE transaction, so
+-- this file is written to be transactional end to end: no CREATE INDEX
+-- CONCURRENTLY, bounded by lock_timeout, preflight fails closed on corrupt
+-- tenant references instead of silently reparenting them. Quiesce the
+-- publishing worker for the upgrade (plan §2 "Existing data rollout").
+SET LOCAL lock_timeout = '5s';
+
+-- ---------------------------------------------------------------------------
+-- Preflight: refuse to upgrade data that the tenant-composite FKs below would
+-- reject anyway, with an operator-readable reason. Nothing is reparented.
+-- ---------------------------------------------------------------------------
+DO $$
+DECLARE v_bad bigint;
+BEGIN
+  SELECT count(*) INTO v_bad FROM scheduled_publications sp
+   WHERE NOT EXISTS (SELECT 1 FROM drafts d WHERE d.id = sp.draft_id AND d.workspace_id = sp.workspace_id)
+      OR NOT EXISTS (SELECT 1 FROM connections c WHERE c.id = sp.connection_id AND c.workspace_id = sp.workspace_id);
+  IF v_bad > 0 THEN
+    RAISE EXCEPTION '018 preflight: % scheduled_publications rows reference a draft/connection in another workspace', v_bad;
+  END IF;
+  SELECT count(*) INTO v_bad FROM publications p
+   WHERE NOT EXISTS (SELECT 1 FROM drafts d WHERE d.id = p.draft_id AND d.workspace_id = p.workspace_id)
+      OR NOT EXISTS (SELECT 1 FROM connections c WHERE c.id = p.connection_id AND c.workspace_id = p.workspace_id);
+  IF v_bad > 0 THEN
+    RAISE EXCEPTION '018 preflight: % publications rows reference a draft/connection in another workspace', v_bad;
+  END IF;
+  SELECT count(*) INTO v_bad FROM credentials cr
+   WHERE cr.connection_id IS NOT NULL
+     AND NOT EXISTS (SELECT 1 FROM connections c WHERE c.id = cr.connection_id AND c.workspace_id = cr.workspace_id);
+  IF v_bad > 0 THEN
+    RAISE EXCEPTION '018 preflight: % credentials rows reference a connection in another workspace', v_bad;
+  END IF;
+  SELECT count(*) INTO v_bad FROM (
+    SELECT 1 FROM credentials WHERE kind = 'connector-oauth' AND connection_id IS NOT NULL
+     GROUP BY workspace_id, connection_id HAVING count(*) > 1
+  ) dup;
+  IF v_bad > 0 THEN
+    RAISE EXCEPTION '018 preflight: % connections have more than one connector-oauth credential; reconcile before upgrading', v_bad;
+  END IF;
+END $$;
+
+-- ---------------------------------------------------------------------------
+-- Credentials: generation + revocation. key_version is NOT a token
+-- generation (APV1 sealing writes version 1 on every rotation).
+-- ---------------------------------------------------------------------------
+ALTER TABLE credentials
+  ADD COLUMN generation bigint NOT NULL DEFAULT 1 CHECK (generation > 0),
+  ADD COLUMN revoked_at timestamptz;
+ALTER TABLE credentials ADD CONSTRAINT credentials_id_workspace_key UNIQUE (id, workspace_id);
+-- One live connector credential per connection; readers stop using LIMIT 1.
+CREATE UNIQUE INDEX credentials_connector_oauth_unique
+  ON credentials (workspace_id, connection_id) WHERE kind = 'connector-oauth';
+
+-- generation is DB-owned: any secret-material or lifecycle change rotates it,
+-- and callers cannot rewind it.
+CREATE FUNCTION credentials_bump_generation() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.ciphertext IS DISTINCT FROM OLD.ciphertext
+     OR NEW.key_version IS DISTINCT FROM OLD.key_version
+     OR NEW.rotated_at IS DISTINCT FROM OLD.rotated_at
+     OR NEW.revoked_at IS DISTINCT FROM OLD.revoked_at THEN
+    NEW.generation := OLD.generation + 1;
+  ELSE
+    NEW.generation := OLD.generation;
+  END IF;
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_cred_generation BEFORE UPDATE ON credentials
+  FOR EACH ROW EXECUTE FUNCTION credentials_bump_generation();
+-- Credentials are an execution-authorization input: changes bump the epoch
+-- exactly like memberships (reuses bump_authz_epoch, 001/005).
+CREATE TRIGGER trg_cred_bump_epoch
+  AFTER INSERT OR DELETE OR UPDATE OF ciphertext, key_version, rotated_at, revoked_at ON credentials
+  FOR EACH ROW EXECUTE FUNCTION bump_authz_epoch();
+
+-- ---------------------------------------------------------------------------
+-- Connections: tombstones keep journal evidence intact after removal.
+-- ---------------------------------------------------------------------------
+ALTER TABLE connections ADD COLUMN disconnected_at timestamptz;
+CREATE TRIGGER trg_conn_disconnect_bump_epoch AFTER UPDATE OF disconnected_at ON connections
+  FOR EACH ROW WHEN (NEW.disconnected_at IS DISTINCT FROM OLD.disconnected_at)
+  EXECUTE FUNCTION bump_authz_epoch();
+
+-- Group sharing gates userCanUseConnection, so it bumps the epoch too (008
+-- only covered group_members).
+CREATE TRIGGER trg_group_connection_bump_epoch AFTER INSERT OR UPDATE OR DELETE ON group_connections
+  FOR EACH ROW EXECUTE FUNCTION bump_authz_epoch();
+
+-- role_permissions is global. Every workspace's Owner/Admin/... roles come
+-- from it, so a change bumps all workspaces once per statement, locked in
+-- UUID order to avoid lock-order inversions between concurrent bumps.
+CREATE FUNCTION bump_all_authz_epochs() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM 1 FROM workspaces ORDER BY id FOR UPDATE;
+  UPDATE workspaces SET authz_epoch = authz_epoch + 1;
+  RETURN NULL;
+END $$;
+CREATE TRIGGER trg_role_permissions_bump_epoch AFTER INSERT OR UPDATE OR DELETE ON role_permissions
+  FOR EACH STATEMENT EXECUTE FUNCTION bump_all_authz_epochs();
+
+-- ---------------------------------------------------------------------------
+-- Drafts: revision + approval proof + business attempt counter.
+-- ---------------------------------------------------------------------------
+ALTER TABLE drafts
+  ADD COLUMN revision bigint NOT NULL DEFAULT 1 CHECK (revision > 0),
+  ADD COLUMN approved_revision bigint,
+  ADD COLUMN approved_hash text,
+  ADD COLUMN approved_at timestamptz,
+  ADD COLUMN review_reason text,
+  ADD COLUMN publication_attempt bigint NOT NULL DEFAULT 0 CHECK (publication_attempt >= 0);
+-- drafts_id_workspace_key (id, workspace_id) already exists from 015.
+
+-- ---------------------------------------------------------------------------
+-- Scheduled publications: principal/fence snapshot + execution generation.
+-- ---------------------------------------------------------------------------
+ALTER TABLE scheduled_publications
+  ADD COLUMN created_at timestamptz NOT NULL DEFAULT now(),
+  ADD COLUMN updated_at timestamptz NOT NULL DEFAULT now(),
+  ADD COLUMN scheduled_by_user_id uuid REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  ADD COLUMN required_permission text
+    CHECK (required_permission IN ('publication.schedule', 'publication.publish')),
+  ADD COLUMN authorized_epoch bigint,
+  ADD COLUMN approved_revision bigint,
+  ADD COLUMN post_hash text,
+  ADD COLUMN credential_id uuid,
+  ADD COLUMN credential_generation bigint,
+  ADD COLUMN generation bigint NOT NULL DEFAULT 1 CHECK (generation > 0),
+  ADD COLUMN attempt_no bigint NOT NULL DEFAULT 1 CHECK (attempt_no > 0),
+  ADD COLUMN execution_version smallint NOT NULL DEFAULT 0 CHECK (execution_version IN (0, 1)),
+  ADD COLUMN timezone text NOT NULL DEFAULT 'UTC',
+  ADD COLUMN local_publish_at timestamp,
+  ADD COLUMN tzdata_version text,
+  ADD COLUMN next_attempt_at timestamptz,
+  ADD COLUMN retry_count int NOT NULL DEFAULT 0 CHECK (retry_count >= 0),
+  ADD COLUMN error_code text;
+
+ALTER TABLE scheduled_publications DROP CONSTRAINT scheduled_publications_state_check;
+ALTER TABLE scheduled_publications ADD CONSTRAINT scheduled_publications_state_check
+  CHECK (state IN ('pending', 'in_flight', 'done', 'failed', 'needs_reauthorization', 'cancelled'));
+
+-- Legacy rows: timestamps from the draft, due time from publish_at, UTC zone.
+UPDATE scheduled_publications sp
+   SET created_at = d.created_at, updated_at = d.updated_at, next_attempt_at = sp.publish_at
+  FROM drafts d
+ WHERE d.id = sp.draft_id AND d.workspace_id = sp.workspace_id;
+
+-- Existing publications are authoritative: their schedule is done, draft published.
+UPDATE scheduled_publications sp SET state = 'done', error = NULL, error_code = NULL
+ WHERE EXISTS (SELECT 1 FROM publications p
+                WHERE p.workspace_id = sp.workspace_id
+                  AND (p.idempotency_key = sp.idempotency_key OR p.draft_id = sp.draft_id));
+UPDATE drafts d SET state = 'published'
+ WHERE d.state <> 'published'
+   AND EXISTS (SELECT 1 FROM publications p WHERE p.workspace_id = d.workspace_id AND p.draft_id = d.id);
+-- No recorded principal: never infer one from author/audit history.
+UPDATE scheduled_publications SET state = 'needs_reauthorization', error_code = 'LEGACY_AUTHORIZATION_MISSING'
+ WHERE state = 'pending';
+-- In flight without a publication: the send may have happened.
+UPDATE scheduled_publications SET state = 'failed', error_code = 'PUBLISH_OUTCOME_UNKNOWN'
+ WHERE state = 'in_flight';
+
+-- Upgraded (execution_version = 1) rows must carry every execution fence
+-- while executable or done. Legacy rows (0) are readable, never executable:
+-- every claim requires execution_version = 1.
+ALTER TABLE scheduled_publications ADD CONSTRAINT scheduled_publications_fences_check CHECK (
+  execution_version = 0
+  OR state IN ('failed', 'needs_reauthorization', 'cancelled')
+  OR (scheduled_by_user_id IS NOT NULL AND required_permission IS NOT NULL
+      AND authorized_epoch IS NOT NULL AND approved_revision IS NOT NULL
+      AND post_hash IS NOT NULL AND credential_id IS NOT NULL
+      AND credential_generation IS NOT NULL AND next_attempt_at IS NOT NULL)
+);
+
+ALTER TABLE scheduled_publications
+  ADD CONSTRAINT scheduled_publications_id_workspace_key UNIQUE (id, workspace_id);
+
+-- Tenant-composite replacements for 006's single-column FKs (same ON DELETE
+-- semantics; journal tables below add NO ACTION guards).
+ALTER TABLE scheduled_publications
+  DROP CONSTRAINT scheduled_publications_draft_id_fkey,
+  DROP CONSTRAINT scheduled_publications_connection_id_fkey,
+  ADD CONSTRAINT scheduled_publications_draft_ws_fkey FOREIGN KEY (draft_id, workspace_id)
+    REFERENCES drafts (id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  ADD CONSTRAINT scheduled_publications_connection_ws_fkey FOREIGN KEY (connection_id, workspace_id)
+    REFERENCES connections (id, workspace_id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  ADD CONSTRAINT scheduled_publications_credential_ws_fkey FOREIGN KEY (credential_id, workspace_id)
+    REFERENCES credentials (id, workspace_id) ON DELETE NO ACTION ON UPDATE RESTRICT;
+
+ALTER TABLE publications
+  DROP CONSTRAINT publications_draft_id_fkey,
+  DROP CONSTRAINT publications_connection_id_fkey,
+  ADD CONSTRAINT publications_draft_ws_fkey FOREIGN KEY (draft_id, workspace_id)
+    REFERENCES drafts (id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  ADD CONSTRAINT publications_connection_ws_fkey FOREIGN KEY (connection_id, workspace_id)
+    REFERENCES connections (id, workspace_id) ON DELETE NO ACTION ON UPDATE RESTRICT;
+
+-- Schedules: DB-owned updated_at; generation and execution_version only move forward.
+CREATE FUNCTION scheduled_publications_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.generation < OLD.generation THEN
+    RAISE EXCEPTION 'schedule generation cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.execution_version < OLD.execution_version THEN
+    RAISE EXCEPTION 'schedule execution_version cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  NEW.updated_at := now();
+  RETURN NEW;
+END $$;
+CREATE TRIGGER trg_scheduled_pub_guard BEFORE UPDATE ON scheduled_publications
+  FOR EACH ROW EXECUTE FUNCTION scheduled_publications_guard();
+
+-- ---------------------------------------------------------------------------
+-- Execution journal: one row per business attempt. Snapshot columns are
+-- immutable; mutable columns carry ownership (owner_token/claim_epoch/lease)
+-- and the dispatch marker.
+-- ---------------------------------------------------------------------------
+CREATE TABLE publishing_attempts (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  schedule_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  connection_id uuid NOT NULL,
+  attempt_no bigint NOT NULL CHECK (attempt_no > 0),
+  idempotency_key text NOT NULL CHECK (btrim(idempotency_key) <> ''),
+  schedule_generation bigint NOT NULL CHECK (schedule_generation > 0),
+  post_snapshot jsonb NOT NULL CHECK (jsonb_typeof(post_snapshot) = 'object'),
+  post_hash text NOT NULL CHECK (btrim(post_hash) <> ''),
+  scheduled_by_user_id uuid NOT NULL REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  required_permission text NOT NULL
+    CHECK (required_permission IN ('publication.schedule', 'publication.publish')),
+  approved_revision bigint NOT NULL CHECK (approved_revision > 0),
+  reviewer_user_id uuid NOT NULL REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  credential_id uuid NOT NULL,
+  credential_generation bigint NOT NULL CHECK (credential_generation > 0),
+  authorized_epoch bigint NOT NULL,
+  dispatch_count int NOT NULL DEFAULT 0 CHECK (dispatch_count >= 0 AND dispatch_count <= 5),
+  status text NOT NULL DEFAULT 'ready'
+    CHECK (status IN ('ready', 'in_progress', 'completed', 'failed', 'unknown', 'abandoned')),
+  claim_epoch bigint NOT NULL DEFAULT 0 CHECK (claim_epoch >= 0),
+  owner_token uuid,
+  lease_until timestamptz,
+  dispatch_started_at timestamptz,
+  provider_retry_deadline timestamptz,
+  error_code text,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  -- Ownership exists exactly while in progress.
+  CHECK ((status = 'in_progress') = (owner_token IS NOT NULL AND lease_until IS NOT NULL)),
+  CHECK (status = 'in_progress' OR (owner_token IS NULL AND lease_until IS NULL)),
+  -- A dispatch marker implies at least one counted dispatch.
+  CHECK (dispatch_started_at IS NULL OR dispatch_count > 0),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, draft_id, attempt_no),
+  UNIQUE (workspace_id, idempotency_key),
+  FOREIGN KEY (schedule_id, workspace_id) REFERENCES scheduled_publications (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (credential_id, workspace_id) REFERENCES credentials (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+-- Snapshot immutability, terminal statuses, and DB-owned claim epoch: every
+-- new owner token advances claim_epoch by exactly one, so a deposed owner's
+-- (owner_token, claim_epoch) pair can never match again.
+CREATE FUNCTION publishing_attempts_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF (NEW.schedule_id, NEW.draft_id, NEW.connection_id, NEW.attempt_no, NEW.idempotency_key,
+      NEW.schedule_generation, NEW.post_snapshot, NEW.post_hash, NEW.scheduled_by_user_id,
+      NEW.required_permission, NEW.approved_revision, NEW.reviewer_user_id,
+      NEW.credential_id, NEW.credential_generation, NEW.created_at)
+     IS DISTINCT FROM
+     (OLD.schedule_id, OLD.draft_id, OLD.connection_id, OLD.attempt_no, OLD.idempotency_key,
+      OLD.schedule_generation, OLD.post_snapshot, OLD.post_hash, OLD.scheduled_by_user_id,
+      OLD.required_permission, OLD.approved_revision, OLD.reviewer_user_id,
+      OLD.credential_id, OLD.credential_generation, OLD.created_at) THEN
+    RAISE EXCEPTION 'publishing attempt snapshot is immutable' USING ERRCODE = '23514';
+  END IF;
+  IF OLD.status IN ('completed', 'abandoned') AND NEW.status IS DISTINCT FROM OLD.status THEN
+    RAISE EXCEPTION 'publishing attempt % is terminal', OLD.status USING ERRCODE = '23514';
+  END IF;
+  IF NEW.dispatch_count < OLD.dispatch_count THEN
+    RAISE EXCEPTION 'dispatch_count cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.provider_retry_deadline IS DISTINCT FROM OLD.provider_retry_deadline
+     AND OLD.provider_retry_deadline IS NOT NULL THEN
+    RAISE EXCEPTION 'provider_retry_deadline is fixed at first dispatch' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.owner_token IS NOT NULL AND NEW.owner_token IS DISTINCT FROM OLD.owner_token THEN
+    NEW.claim_epoch := OLD.claim_epoch + 1;
+  ELSE
+    NEW.claim_epoch := OLD.claim_epoch;
+  END IF;
+  NEW.updated_at := now();
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_publishing_attempt_ws_immutable BEFORE UPDATE ON publishing_attempts
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_publishing_attempt_guard BEFORE UPDATE ON publishing_attempts
+  FOR EACH ROW EXECUTE FUNCTION publishing_attempts_guard();
+
+-- Durable provider evidence, separate from the attempt so it survives activity
+-- timeouts and stale-owner completion refusal. Append-only.
+CREATE TABLE publishing_receipts (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  attempt_id uuid NOT NULL,
+  remote_id text NOT NULL CHECK (btrim(remote_id) <> '' AND length(remote_id) <= 512),
+  remote_url text CHECK (remote_url IS NULL OR length(remote_url) <= 2048),
+  published_at timestamptz,
+  provider_metadata jsonb NOT NULL DEFAULT '{}' CHECK (jsonb_typeof(provider_metadata) = 'object'),
+  received_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, attempt_id),
+  FOREIGN KEY (attempt_id, workspace_id) REFERENCES publishing_attempts (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+-- Receipts are never rewritten. Deletion is only the workspace purge cascade
+-- (the parent workspace row is already gone when the cascade reaches here).
+CREATE FUNCTION publishing_receipts_append_only() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    IF EXISTS (SELECT 1 FROM workspaces w WHERE w.id = OLD.workspace_id) THEN
+      RAISE EXCEPTION 'publishing receipts are append-only' USING ERRCODE = '23514';
+    END IF;
+    RETURN OLD;
+  END IF;
+  RAISE EXCEPTION 'publishing receipts are append-only' USING ERRCODE = '23514';
+END $$;
+CREATE TRIGGER trg_publishing_receipt_append_only BEFORE UPDATE OR DELETE ON publishing_receipts
+  FOR EACH ROW EXECUTE FUNCTION publishing_receipts_append_only();
+
+-- Draft-creation request idempotency, committed atomically with the draft.
+CREATE TABLE publishing_requests (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  user_id uuid NOT NULL REFERENCES users(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  route text NOT NULL CHECK (btrim(route) <> ''),
+  request_key uuid NOT NULL,
+  request_hash text NOT NULL CHECK (btrim(request_hash) <> ''),
+  response jsonb NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, user_id, route, request_key)
+);
+CREATE TRIGGER trg_publishing_request_ws_immutable BEFORE UPDATE ON publishing_requests
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- ---------------------------------------------------------------------------
+-- Draft fence: content changes rotate the revision and void approval; they
+-- are refused while a dispatch is active or its outcome is unknown.
+-- ---------------------------------------------------------------------------
+CREATE FUNCTION drafts_revision_fence() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.publication_attempt < OLD.publication_attempt THEN
+    RAISE EXCEPTION 'publication_attempt cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.post IS DISTINCT FROM OLD.post THEN
+    IF EXISTS (SELECT 1 FROM publishing_attempts a
+                WHERE a.workspace_id = OLD.workspace_id AND a.draft_id = OLD.id
+                  AND (a.status = 'unknown'
+                       OR (a.status = 'in_progress' AND a.dispatch_started_at IS NOT NULL))) THEN
+      RAISE EXCEPTION 'draft content is locked while a dispatch is unsettled' USING ERRCODE = '55000';
+    END IF;
+    NEW.revision := OLD.revision + 1;
+    NEW.approved_revision := NULL;
+    NEW.approved_hash := NULL;
+    NEW.approved_at := NULL;
+    NEW.reviewer_user_id := NULL;
+  ELSE
+    NEW.revision := OLD.revision;
+  END IF;
+  RETURN NEW;
+END $$;
+CREATE TRIGGER trg_draft_revision_fence BEFORE UPDATE ON drafts
+  FOR EACH ROW EXECUTE FUNCTION drafts_revision_fence();
+
+-- ---------------------------------------------------------------------------
+-- RLS + grants for the new tenant tables (001/006/017 style).
+-- ---------------------------------------------------------------------------
+ALTER TABLE publishing_attempts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE publishing_receipts ENABLE ROW LEVEL SECURITY;
+ALTER TABLE publishing_requests ENABLE ROW LEVEL SECURITY;
+ALTER TABLE publishing_attempts FORCE ROW LEVEL SECURITY;
+ALTER TABLE publishing_receipts FORCE ROW LEVEL SECURITY;
+ALTER TABLE publishing_requests FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON publishing_attempts
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON publishing_receipts
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON publishing_requests
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+-- 003's default privileges grant all four verbs; narrow them explicitly:
+-- the journal is never deleted by the app, receipts are append-only.
+GRANT SELECT, INSERT, UPDATE ON publishing_attempts TO sp_app;
+REVOKE DELETE ON publishing_attempts FROM sp_app;
+GRANT SELECT, INSERT ON publishing_receipts TO sp_app;
+REVOKE UPDATE, DELETE ON publishing_receipts FROM sp_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON publishing_requests TO sp_app;
+
+-- ---------------------------------------------------------------------------
+-- Indexes: keyset lists (no OFFSET), due/recovery discovery, FK coverage.
+-- ---------------------------------------------------------------------------
+CREATE INDEX drafts_ws_updated ON drafts (workspace_id, updated_at DESC, id DESC);
+CREATE INDEX drafts_ws_state_updated ON drafts (workspace_id, state, updated_at DESC, id DESC);
+
+CREATE INDEX scheduled_publications_ws_publish ON scheduled_publications (workspace_id, publish_at DESC, id DESC);
+CREATE INDEX scheduled_publications_ws_conn_publish
+  ON scheduled_publications (workspace_id, connection_id, publish_at DESC, id DESC);
+CREATE INDEX scheduled_publications_next_due ON scheduled_publications (next_attempt_at, id)
+  WHERE state = 'pending';
+CREATE INDEX scheduled_publications_ws_credential ON scheduled_publications (workspace_id, credential_id)
+  WHERE credential_id IS NOT NULL;
+
+CREATE INDEX publications_ws_published ON publications (workspace_id, published_at DESC, id DESC);
+CREATE INDEX publications_ws_conn_published
+  ON publications (workspace_id, connection_id, published_at DESC, id DESC);
+
+CREATE INDEX publishing_attempts_ws_schedule ON publishing_attempts (workspace_id, schedule_id, attempt_no DESC);
+CREATE INDEX publishing_attempts_ws_connection ON publishing_attempts (workspace_id, connection_id);
+CREATE INDEX publishing_attempts_ws_credential ON publishing_attempts (workspace_id, credential_id);
+CREATE INDEX publishing_attempts_lease_recovery ON publishing_attempts (lease_until, id)
+  WHERE status = 'in_progress';
+
+-- ---------------------------------------------------------------------------
+-- Discovery (replaces 006). Identifiers/times only, bounded, fixed
+-- search_path, PUBLIC revoked. Callers enter withTenant(workspace_id) and
+-- re-verify key/generation ownership under RLS.
+-- ---------------------------------------------------------------------------
+DROP FUNCTION publishing_due_schedules();
+
+CREATE FUNCTION publishing_due_schedules(p_limit integer DEFAULT 100)
+RETURNS TABLE(workspace_id uuid, schedule_id uuid, idempotency_key text, generation bigint, publish_at timestamptz)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT due.workspace_id, due.schedule_id, due.idempotency_key, due.generation, due.publish_at
+  FROM (
+    SELECT sp.workspace_id, sp.id AS schedule_id, sp.idempotency_key, sp.generation,
+           sp.publish_at, sp.next_attempt_at AS due_at
+      FROM scheduled_publications sp
+     WHERE sp.state = 'pending' AND sp.execution_version = 1 AND sp.next_attempt_at <= now()
+    UNION ALL
+    SELECT a.workspace_id, a.schedule_id, a.idempotency_key, a.schedule_generation,
+           sp.publish_at, a.lease_until AS due_at
+      FROM publishing_attempts a
+      JOIN scheduled_publications sp ON sp.id = a.schedule_id AND sp.workspace_id = a.workspace_id
+     WHERE a.status = 'in_progress' AND a.lease_until < now()
+  ) due
+  ORDER BY due.due_at, due.schedule_id
+  LIMIT LEAST(GREATEST(COALESCE(p_limit, 100), 1), 100)
+$$;
+
+-- Attempt journal first (every executable key), then legacy schedules/publications.
+CREATE OR REPLACE FUNCTION publishing_schedule_workspace(p_idempotency_key text) RETURNS uuid
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT COALESCE(
+    (SELECT a.workspace_id FROM publishing_attempts a WHERE a.idempotency_key = p_idempotency_key LIMIT 1),
+    (SELECT sp.workspace_id FROM scheduled_publications sp WHERE sp.idempotency_key = p_idempotency_key),
+    (SELECT p.workspace_id FROM publications p WHERE p.idempotency_key = p_idempotency_key)
+  )
+$$;
+
+REVOKE ALL ON FUNCTION publishing_due_schedules(integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION publishing_schedule_workspace(text) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION publishing_due_schedules(integer), publishing_schedule_workspace(text) TO sp_app;
diff --git a/apps/api/migrations/019_publishing_integration.sql b/apps/api/migrations/019_publishing_integration.sql
new file mode 100644
index 0000000..6865c10
--- /dev/null
+++ b/apps/api/migrations/019_publishing_integration.sql
@@ -0,0 +1,103 @@
+-- 018 is retained unchanged: local anp_publishing_it records its application.
+-- These corrections use independently tracked resumable stages.
+-- wp3:phase expand transaction
+SET LOCAL lock_timeout = '5s';
+ALTER TABLE publishing_attempts ADD COLUMN first_dispatch_started_at timestamptz;
+CREATE OR REPLACE FUNCTION publishing_attempts_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF (NEW.schedule_id, NEW.draft_id, NEW.connection_id, NEW.attempt_no, NEW.idempotency_key,
+      NEW.schedule_generation, NEW.post_snapshot, NEW.post_hash, NEW.scheduled_by_user_id,
+      NEW.required_permission, NEW.approved_revision, NEW.reviewer_user_id,
+      NEW.credential_id, NEW.credential_generation, NEW.created_at)
+     IS DISTINCT FROM
+     (OLD.schedule_id, OLD.draft_id, OLD.connection_id, OLD.attempt_no, OLD.idempotency_key,
+      OLD.schedule_generation, OLD.post_snapshot, OLD.post_hash, OLD.scheduled_by_user_id,
+      OLD.required_permission, OLD.approved_revision, OLD.reviewer_user_id,
+      OLD.credential_id, OLD.credential_generation, OLD.created_at) THEN
+    RAISE EXCEPTION 'publishing attempt snapshot is immutable' USING ERRCODE = '23514';
+  END IF;
+  IF OLD.status IN ('completed', 'abandoned') AND NEW.status IS DISTINCT FROM OLD.status THEN
+    RAISE EXCEPTION 'publishing attempt % is terminal', OLD.status USING ERRCODE = '23514';
+  END IF;
+  IF OLD.first_dispatch_started_at IS NOT NULL AND NEW.first_dispatch_started_at IS DISTINCT FROM OLD.first_dispatch_started_at THEN
+    RAISE EXCEPTION 'first dispatch time is immutable' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.dispatch_count < OLD.dispatch_count THEN
+    RAISE EXCEPTION 'dispatch_count cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.provider_retry_deadline IS DISTINCT FROM OLD.provider_retry_deadline
+     AND OLD.provider_retry_deadline IS NOT NULL THEN
+    RAISE EXCEPTION 'provider_retry_deadline is fixed at first dispatch' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.owner_token IS NOT NULL AND NEW.owner_token IS DISTINCT FROM OLD.owner_token THEN
+    NEW.claim_epoch := OLD.claim_epoch + 1;
+  ELSE
+    NEW.claim_epoch := OLD.claim_epoch;
+  END IF;
+  NEW.updated_at := now();
+  RETURN NEW;
+END $$;
+
+CREATE OR REPLACE FUNCTION drafts_revision_fence() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.publication_attempt < OLD.publication_attempt THEN
+    RAISE EXCEPTION 'publication_attempt cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.post IS DISTINCT FROM OLD.post THEN
+    IF EXISTS (SELECT 1 FROM publishing_attempts a
+                WHERE a.workspace_id = OLD.workspace_id AND a.draft_id = OLD.id
+                  AND (a.status = 'unknown'
+                       OR (a.status IN ('ready', 'in_progress') AND a.dispatch_started_at IS NOT NULL))) THEN
+      RAISE EXCEPTION 'draft content is locked while a dispatch is unsettled' USING ERRCODE = '55000';
+    END IF;
+    NEW.revision := OLD.revision + 1;
+    NEW.approved_revision := NULL;
+    NEW.approved_hash := NULL;
+    NEW.approved_at := NULL;
+    NEW.reviewer_user_id := NULL;
+  ELSE
+    NEW.revision := OLD.revision;
+  END IF;
+  RETURN NEW;
+END $$;
+-- wp3:phase dispatch_backfill batch
+WITH batch AS (
+  SELECT id FROM publishing_attempts WHERE first_dispatch_started_at IS NULL AND dispatch_count > 0 LIMIT 1000 FOR UPDATE
+)
+UPDATE publishing_attempts a SET first_dispatch_started_at = CASE WHEN a.dispatch_count > 1 OR a.dispatch_started_at IS NULL THEN a.created_at ELSE a.dispatch_started_at END FROM batch WHERE a.id = batch.id;
+-- wp3:phase receipt_recovery_index concurrent
+CREATE INDEX CONCURRENTLY publishing_receipts_recovery ON publishing_receipts (workspace_id, attempt_id, received_at);
+-- wp3:phase cutover transaction
+SET LOCAL lock_timeout = '5s';
+DROP FUNCTION publishing_due_schedules(integer);
+CREATE FUNCTION publishing_due_schedules(p_limit integer DEFAULT 100)
+RETURNS TABLE(workspace_id uuid, schedule_id uuid, idempotency_key text, generation bigint, publish_at timestamptz, evidence_only boolean)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT due.workspace_id, due.schedule_id, due.idempotency_key, due.generation, due.publish_at, due.evidence_only
+  FROM (
+    SELECT sp.workspace_id, sp.id AS schedule_id, sp.idempotency_key, sp.generation,
+           sp.publish_at, sp.next_attempt_at AS due_at, false AS evidence_only
+      FROM scheduled_publications sp
+     WHERE sp.state = 'pending' AND sp.execution_version = 1 AND sp.next_attempt_at <= now() AND NOT EXISTS (SELECT 1 FROM publishing_attempts a JOIN publishing_receipts r ON r.attempt_id = a.id AND r.workspace_id = a.workspace_id WHERE a.idempotency_key = sp.idempotency_key AND a.workspace_id = sp.workspace_id)
+    UNION ALL
+    SELECT a.workspace_id, a.schedule_id, a.idempotency_key, a.schedule_generation,
+           sp.publish_at, a.lease_until AS due_at, false AS evidence_only
+      FROM publishing_attempts a
+      JOIN scheduled_publications sp ON sp.id = a.schedule_id AND sp.workspace_id = a.workspace_id
+     WHERE a.status = 'in_progress' AND a.lease_until < now() AND NOT EXISTS (SELECT 1 FROM publishing_receipts r WHERE r.attempt_id = a.id AND r.workspace_id = a.workspace_id)
+    UNION ALL
+    SELECT a.workspace_id, a.schedule_id, a.idempotency_key, a.schedule_generation,
+           sp.publish_at, r.received_at AS due_at, true AS evidence_only
+      FROM publishing_attempts a
+      JOIN publishing_receipts r ON r.attempt_id = a.id AND r.workspace_id = a.workspace_id
+      JOIN scheduled_publications sp ON sp.id = a.schedule_id AND sp.workspace_id = a.workspace_id
+     WHERE (a.status IN ('ready', 'failed', 'unknown') OR (a.status = 'in_progress' AND a.lease_until < now()))
+  ) due
+  ORDER BY due.due_at, due.schedule_id
+  LIMIT LEAST(GREATEST(COALESCE(p_limit, 100), 1), 100)
+$$;
+
+REVOKE ALL ON FUNCTION publishing_due_schedules(integer) FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION publishing_due_schedules(integer) TO sp_app;
diff --git a/apps/api/migrations/020_analytics.sql b/apps/api/migrations/020_analytics.sql
new file mode 100644
index 0000000..425cdec
--- /dev/null
+++ b/apps/api/migrations/020_analytics.sql
@@ -0,0 +1,93 @@
+-- 020: WP3 analytics snapshots — monthly per-workspace rollups.
+--
+-- One row per (workspace, month), refreshed in place by the snapshot writer
+-- (apps/api/src/analytics/snapshot.service.ts) with set-based SQL and an
+-- idempotent upsert on (workspace_id, month). Months are materialized as
+-- range partitions of a `month date` key, mirroring 014_live_chat.sql.
+--
+-- Creating future partitions: RLS on the partitioned parent does NOT apply to
+-- direct leaf access, so every leaf carries its own ENABLE/FORCE RLS and
+-- tenant_isolation policy. `analytics_ensure_month(date)` creates a month's
+-- partition idempotently with those controls; this migration precreates the
+-- previous, current and next month. Administrators run
+--     SELECT analytics_ensure_month(date '2025-09-01');
+-- ahead of each new month (cron it monthly, one statement, no downtime). The
+-- DEFAULT partition below catches any month whose partition was not created,
+-- so a missed call never drops data — it only loses pruning until the
+-- partition is created and the rows moved into it.
+--
+-- Partitioned-leaf register entry (proposal §4.4, exception (a)): PK carries
+-- the partition key, the table is never the target of an FK, and rows are
+-- referenced only by (workspace_id, month) / id soft links.
+--
+-- Query catalog (owning WP: WP3 — packages/db does not exist in this repo, so
+-- the catalog entries live here and in snapshot.service.ts):
+--   analytics.snapshot.refresh  INSERT .. ON CONFLICT (workspace_id, month) —
+--     served by the PK (workspace_id, month, id); write path, p95 <= 250 ms.
+--   analytics.snapshot.list     keyset page ORDER BY month DESC — same PK,
+--     backward index scan, p95 <= 20 ms.
+--   analytics.snapshot.summary  two PK point lookups (current + previous
+--     month), p95 <= 20 ms.
+CREATE TABLE analytics_snapshots (
+  id uuid NOT NULL DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Always a month start; the CHECK keeps the value aligned with its partition.
+  month date NOT NULL CHECK (month = date_trunc('month', month)::date),
+  publications_total bigint NOT NULL DEFAULT 0 CHECK (publications_total >= 0),
+  -- {provider: count} for publications published in the month.
+  publications_by_provider jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(publications_by_provider) = 'object'),
+  posts_archived_total bigint NOT NULL DEFAULT 0 CHECK (posts_archived_total >= 0),
+  -- Point-in-time current state at snapshot time (not a monthly delta):
+  -- connections not disconnected when the snapshot was taken.
+  active_connections int NOT NULL DEFAULT 0 CHECK (active_connections >= 0),
+  drafts_created_total bigint NOT NULL DEFAULT 0 CHECK (drafts_created_total >= 0),
+  publishing_attempts_total bigint NOT NULL DEFAULT 0 CHECK (publishing_attempts_total >= 0),
+  -- Attempts whose terminal status is 'failed', counted by their creation month.
+  publish_failures_total bigint NOT NULL DEFAULT 0 CHECK (publish_failures_total >= 0),
+  snapshot_started_at timestamptz NOT NULL DEFAULT now(),
+  snapshot_completed_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, month, id),
+  UNIQUE (workspace_id, month)
+) PARTITION BY RANGE (month);
+
+-- Idempotent: safe to re-run for the same month.
+CREATE FUNCTION analytics_ensure_month(p_month date) RETURNS void
+LANGUAGE plpgsql SET search_path = public AS $$
+DECLARE v_start date := date_trunc('month', p_month)::date;
+  v_table text := 'analytics_snapshots_' || to_char(v_start, 'YYYYMM');
+BEGIN
+  EXECUTE format('CREATE TABLE IF NOT EXISTS %I PARTITION OF analytics_snapshots FOR VALUES FROM (%L) TO (%L)',
+    v_table, v_start, (v_start + interval '1 month')::date);
+  EXECUTE format('ALTER TABLE %I ENABLE ROW LEVEL SECURITY', v_table);
+  EXECUTE format('ALTER TABLE %I FORCE ROW LEVEL SECURITY', v_table);
+  IF NOT EXISTS (SELECT 1 FROM pg_policies WHERE schemaname = 'public' AND tablename = v_table AND policyname = 'tenant_isolation') THEN
+    EXECUTE format('CREATE POLICY tenant_isolation ON %I USING (workspace_id = NULLIF(current_setting(''app.workspace_id'', true), '''')::uuid) WITH CHECK (workspace_id = NULLIF(current_setting(''app.workspace_id'', true), '''')::uuid)', v_table);
+  END IF;
+END $$;
+REVOKE ALL ON FUNCTION analytics_ensure_month(date) FROM PUBLIC;
+
+SELECT analytics_ensure_month((current_date - interval '1 month')::date);
+SELECT analytics_ensure_month(current_date);
+SELECT analytics_ensure_month((current_date + interval '1 month')::date);
+
+-- Safety net for months nobody pre-created (see header).
+CREATE TABLE analytics_snapshots_default PARTITION OF analytics_snapshots DEFAULT;
+ALTER TABLE analytics_snapshots_default ENABLE ROW LEVEL SECURITY;
+ALTER TABLE analytics_snapshots_default FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON analytics_snapshots_default
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+CREATE TRIGGER trg_analytics_snapshot_ws_immutable BEFORE UPDATE ON analytics_snapshots
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE analytics_snapshots ENABLE ROW LEVEL SECURITY;
+ALTER TABLE analytics_snapshots FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON analytics_snapshots
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+-- Grants on the parent cover all current and future partitions for queries
+-- routed through it (014 style); direct leaf access also inherits from the
+-- owner's default privileges (003).
+GRANT SELECT, INSERT, UPDATE, DELETE ON analytics_snapshots TO sp_app;
diff --git a/apps/api/migrations/021_stream_columns.sql b/apps/api/migrations/021_stream_columns.sql
new file mode 100644
index 0000000..66bdbcf
--- /dev/null
+++ b/apps/api/migrations/021_stream_columns.sql
@@ -0,0 +1,52 @@
+-- 021: editable multi-platform streams columns — column definitions (WP3 §1.2, P0a).
+-- stream_columns only: the resolved-source / ingest / fan-out / budget tables
+-- (column_sources, feed_items, feed_item_columns, provider_budget_ledger) land
+-- in their own forward-only migrations so each slice stays independently
+-- reviewable. Additive: no existing table is touched.
+--
+-- `spec` and `refresh_policy` are JSONB blobs validated app-side by
+-- @tactical-media-broadcast-hub/core (stream-columns.ts); invalid specs are rejected before
+-- insert and never stored. The CHECKs here are only coarse backstops — the
+-- authoritative typed validation lives in the app layer (017-style split).
+CREATE TABLE stream_columns (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  type text NOT NULL CHECK (type IN ('platform_feed','keyword','account_list','saved_search')),
+  title text NOT NULL CHECK (char_length(title) <= 80), -- user-editable; app layer enforces too
+  position integer NOT NULL DEFAULT 0 CHECK (position >= 0), -- dense rank; reorder rewrites the tail
+  spec jsonb NOT NULL CHECK (jsonb_typeof(spec) = 'object'),
+  refresh_policy jsonb NOT NULL DEFAULT '{}' CHECK (jsonb_typeof(refresh_policy) = 'object'),
+  created_by uuid NOT NULL REFERENCES users(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  deleted_at timestamptz -- soft delete keeps feed_items FK-stable (§1.2)
+);
+
+CREATE TRIGGER trg_stream_columns_ws_immutable BEFORE UPDATE ON stream_columns
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- Same fail-closed tenant isolation as every tenant table (001/006/017 style):
+-- no app.workspace_id => NULL => no rows. FORCE binds sp_app too.
+ALTER TABLE stream_columns ENABLE ROW LEVEL SECURITY;
+ALTER TABLE stream_columns FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON stream_columns
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON stream_columns TO sp_app;
+
+-- Dense column order per workspace (UI chips, seeding, reorder). Partial on
+-- deleted_at IS NULL: soft-deleted columns keep their row (FK-stable items)
+-- without reserving their slot, so reorder/seeding only fights live rows.
+-- Named per design §1.2; lazy seeding relies on it for idempotence (§1.3).
+CREATE UNIQUE INDEX stream_columns_ws_order_uq
+  ON stream_columns (workspace_id, position)
+  WHERE deleted_at IS NULL;
+
+-- Workspace listing (GET /feeds/columns), newest-position reads served by the
+-- unique index above; this covers soft-deleted lookups and count queries in
+-- the partial-index style of workspace_invite_links_expiry (017).
+CREATE INDEX stream_columns_ws_idx
+  ON stream_columns (workspace_id)
+  WHERE deleted_at IS NULL;
diff --git a/apps/api/migrations/022_live_destinations.sql b/apps/api/migrations/022_live_destinations.sql
new file mode 100644
index 0000000..f51f648
--- /dev/null
+++ b/apps/api/migrations/022_live_destinations.sql
@@ -0,0 +1,136 @@
+-- 022: WP6 live-stream destinations + stream outputs (go-live slice).
+--
+-- Aggregate boundary (proposal §4.4, WP6/WP9): a `live_stream_destinations`
+-- row owns the platform-side live target — provider, ingest endpoint URL and
+-- the vaulted ingest credential — and never references media outputs. A
+-- `stream_outputs` row is a media-output fan-out from a virtual channel and
+-- references EITHER a destination (credential resolved through the
+-- destination at spawn) OR its own generic credential handle — never both
+-- (CHECK below, mirrored in packages/core/src/vc.ts and API validation).
+-- Enablement lives only on StreamOutput; the destination carries no
+-- enabled flag of its own, so "disable one output" never mutates the shared
+-- platform target.
+--
+-- FK actions per the WP6 lifecycle rule: both cross-aggregate FKs are
+-- ON DELETE NO ACTION ON UPDATE RESTRICT; deletion is app-driven — 409 while
+-- a referencing output is enabled, otherwise (disabled output) the app
+-- disables dependents, revokes the ingest credential, then deletes the row.
+-- `credentials` gains the tenant-composite key this migration needs
+-- (tenant-composite FKs everywhere, per proposal §4.4/§4.5).
+--
+-- Query catalog (owning WP: WP6 — packages/db does not exist in this repo, so
+-- the catalog lives here and in apps/api/src/live/live-destination.repository.ts):
+--   live.destinations.list     keyset page ORDER BY label — served by
+--     live_destinations_ws_label; read path, p95 <= 20 ms.
+--   live.destinations.usage    point lookup of referencing outputs by
+--     destination (tenant) — served by stream_outputs_destination partial
+--     index; read path, p95 <= 20 ms.
+--   live.outputs.channel       channel fan-out list — served by
+--     stream_outputs_channel; read path, p95 <= 20 ms.
+BEGIN;
+
+-- 001 created credentials with only a surrogate PK; 018 added the
+-- tenant-composite key the cross-aggregate FK below requires.
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'credentials_id_workspace_key') THEN
+    ALTER TABLE credentials ADD CONSTRAINT credentials_id_workspace_key UNIQUE (id, workspace_id);
+  END IF;
+END $$;
+
+CREATE TABLE live_stream_destinations (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  label text NOT NULL CHECK (btrim(label) <> '' AND length(label) <= 120),
+  -- Provider of the platform-side target (manifest id of a connector); the
+  -- app resolves behaviour through the connector registry, never by branching
+  -- on this value.
+  provider text NOT NULL CHECK (btrim(provider) <> '' AND length(provider) <= 64),
+  -- Ingest endpoint (rtmp/rtmps/srt). Validated app-side by the shared
+  -- media-control endpoint shape validator before insert; the CHECKs here are
+  -- coarse backstops only.
+  endpoint_url text NOT NULL
+    CHECK (endpoint_url ~ '^(rtmp|rtmps|srt)://' AND length(endpoint_url) <= 2048),
+  -- Ingest credential (stream key etc.) vaulted in `credentials`; NULL only
+  -- for providers with no key. Tenant-composite FK; deleting the credential
+  -- row before the destination is a FK error by design (lifecycle revokes in
+  -- order: destination first, then its credential).
+  credential_id uuid,
+  -- Derived, explicitly-stale platform state (runtime truth is Redis obs:*).
+  last_platform_state text NOT NULL DEFAULT 'unknown'
+    CHECK (last_platform_state IN ('unknown', 'created', 'waiting', 'live', 'ended')),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (credential_id, workspace_id) REFERENCES credentials (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_live_dest_ws_immutable BEFORE UPDATE ON live_stream_destinations
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+-- Same fail-closed tenant isolation as every tenant table (001/021 style):
+-- no app.workspace_id => NULL => no rows. FORCE binds sp_app too.
+ALTER TABLE live_stream_destinations ENABLE ROW LEVEL SECURITY;
+ALTER TABLE live_stream_destinations FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON live_stream_destinations
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+-- Per-workspace listing ordered by label (live.destinations.list).
+CREATE INDEX live_destinations_ws_label ON live_stream_destinations (workspace_id, label);
+
+-- Media-output fan-out of a virtual channel onto one live target.
+CREATE TABLE stream_outputs (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  virtual_channel_id uuid NOT NULL,
+  label text NOT NULL CHECK (btrim(label) <> '' AND length(label) <= 120),
+  -- Output profile reference; resolution is app-side.
+  profile text NOT NULL DEFAULT '720p30'
+    CHECK (profile IN ('720p30', '1080p30', '1080p60')),
+  mode text NOT NULL DEFAULT 'passthrough' CHECK (mode IN ('passthrough', 'normalize')),
+  -- Enablement lives ONLY here (WP9): a disabled output stops pushing but the
+  -- destination row and its credential survive untouched.
+  enabled boolean NOT NULL DEFAULT true,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  -- Exactly one of (destination_id, credential_handle_id): destination-
+  -- referenced outputs resolve the ingest credential through the destination
+  -- at spawn; generic outputs carry their own opaque vault handle. The
+  -- NOT-VALID backstop below is validated app-side (021-style split).
+  destination_id uuid,
+  credential_handle_id text,
+  CONSTRAINT stream_outputs_target_exclusive CHECK (
+    (destination_id IS NULL) <> (credential_handle_id IS NULL)
+  ),
+  CONSTRAINT stream_outputs_handle_shape CHECK (
+    credential_handle_id IS NULL OR credential_handle_id ~ '^vh_[A-Za-z0-9_-]{16,128}$'
+  ),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, virtual_channel_id, id),
+  FOREIGN KEY (workspace_id, virtual_channel_id) REFERENCES virtual_channels (workspace_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (destination_id, workspace_id) REFERENCES live_stream_destinations (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_stream_outputs_ws_immutable BEFORE UPDATE ON stream_outputs
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+ALTER TABLE stream_outputs ENABLE ROW LEVEL SECURITY;
+ALTER TABLE stream_outputs FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON stream_outputs
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+-- References by destination (live.destinations.usage, 409 on delete).
+CREATE INDEX stream_outputs_destination ON stream_outputs (workspace_id, destination_id)
+  WHERE destination_id IS NOT NULL;
+-- Channel fan-out listing (live.outputs.channel).
+CREATE INDEX stream_outputs_channel ON stream_outputs (workspace_id, virtual_channel_id);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON live_stream_destinations TO sp_app;
+GRANT SELECT, INSERT, UPDATE, DELETE ON stream_outputs TO sp_app;
+
+COMMIT;
diff --git a/apps/api/migrations/023_virtual_channel_import.sql b/apps/api/migrations/023_virtual_channel_import.sql
new file mode 100644
index 0000000..7febd1a
--- /dev/null
+++ b/apps/api/migrations/023_virtual_channel_import.sql
@@ -0,0 +1,160 @@
+-- 023: WP7 bulk source import + live-settings guard.
+--
+-- Three additive pieces, one migration:
+--
+-- (1) `virtual_channel_sources` (013) is widened to admit *imported* sources.
+--     013's CHECK only modelled hand-entered HLS URLs and local playlists; a
+--     PeerTube channel/live imported in bulk carries `remote_ref` +
+--     `connection_id` and has an HLS URL only once a live is resolvable. The
+--     dedupe key UNIQUE (workspace_id, virtual_channel_id, remote_ref) from
+--     013 is unchanged and stays the only dedupe authority: imports write
+--     INSERT ... ON CONFLICT DO NOTHING RETURNING id.
+--
+-- (2) `virtual_channel_imports`: one row per bulk import request. The HTTP
+--     request only parses + validates + creates the job row; resolution and
+--     inserts run in the background, and the row is the progress/report
+--     document (processed/total + imported/duplicate/invalid/failed counts
+--     and a bounded per-entry outcome list). A `running` row whose heartbeat
+--     (`updated_at`) went stale is reaped to `abandoned` on read, so a
+--     process crash never leaves a job spinning forever.
+--
+-- (3) `virtual_channel_live_settings`: the channel's live output settings
+--     (profile/resolution, latency, replay policy) behind an optimistic
+--     concurrency `version`. Writers take the channel row FOR UPDATE (one
+--     writer per channel), then CAS on `version`; a stale version or a
+--     started live is a 409 with nothing written. The CHECKs mirror the
+--     app-side validator (WP7 acceptance: permanentLive + saveReplay and an
+--     out-of-range latencyMode are rejected by the DB on a direct insert
+--     too), and a trigger keeps `version` monotone.
+--
+-- House style throughout: tenant-composite keys (id, workspace_id), composite
+-- FKs that pin every child to one workspace's channel, reject_workspace_change
+-- / reject_owner_change immutability, FORCE RLS with the NULLIF tenant policy,
+-- grants to sp_app (003 adds the default-privilege side for future tables).
+
+SET LOCAL lock_timeout = '5s';
+
+-- (1) Imported sources: kind 'hls' now requires an HLS URL *or* a remote_ref
+-- (a channel imported now, playback attached when its live starts). The
+-- playlist arm is untouched: local, connectionless, remote_ref-less.
+ALTER TABLE virtual_channel_sources DROP CONSTRAINT virtual_channel_sources_check;
+ALTER TABLE virtual_channel_sources ADD CONSTRAINT virtual_channel_sources_check CHECK (
+  (
+    kind = 'hls' AND playlist_loop IS NULL
+    AND (hls_url IS NOT NULL OR remote_ref IS NOT NULL)
+  ) OR (
+    kind = 'playlist' AND hls_url IS NULL AND remote_ref IS NULL
+    AND connection_id IS NULL AND playlist_loop IS NOT NULL
+  )
+);
+
+-- (2) Import jobs.
+CREATE TABLE virtual_channel_imports (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  -- Connection the import resolves through (default host for bare handles).
+  connection_id uuid,
+  status text NOT NULL DEFAULT 'running'
+    CHECK (status IN ('running', 'completed', 'failed', 'abandoned')),
+  -- total counts every input row (valid or not); processed advances per row.
+  total int NOT NULL DEFAULT 0 CHECK (total >= 0 AND total <= 5000),
+  processed int NOT NULL DEFAULT 0 CHECK (processed >= 0 AND processed <= total),
+  imported int NOT NULL DEFAULT 0 CHECK (imported >= 0),
+  duplicate int NOT NULL DEFAULT 0 CHECK (duplicate >= 0),
+  invalid int NOT NULL DEFAULT 0 CHECK (invalid >= 0),
+  failed int NOT NULL DEFAULT 0 CHECK (failed >= 0),
+  -- Bounded per-entry report (first IMPORT_REPORT_ENTRY_LIMIT rows): what the
+  -- user pasted, what happened, why. Counts are always authoritative.
+  entries jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(entries) = 'array'),
+  error text,
+  created_by uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  completed_at timestamptz,
+  UNIQUE (id, workspace_id),
+  FOREIGN KEY (workspace_id, virtual_channel_id) REFERENCES virtual_channels (workspace_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT DEFERRABLE INITIALLY DEFERRED
+);
+
+CREATE TRIGGER trg_vci_ws_immutable BEFORE UPDATE ON virtual_channel_imports
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_vci_owner_immutable BEFORE UPDATE ON virtual_channel_imports
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id');
+
+ALTER TABLE virtual_channel_imports ENABLE ROW LEVEL SECURITY;
+ALTER TABLE virtual_channel_imports FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON virtual_channel_imports
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+CREATE INDEX virtual_channel_imports_channel
+  ON virtual_channel_imports (workspace_id, virtual_channel_id, created_at DESC);
+
+-- (3) Channel live settings, version-fenced.
+CREATE TABLE virtual_channel_live_settings (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  virtual_channel_id uuid NOT NULL,
+  -- Output shape: a named preset, or an explicit triple (custom).
+  output_profile text NOT NULL DEFAULT '720p30'
+    CHECK (output_profile IN ('720p30', '1080p30', '1080p60', 'custom')),
+  width int CHECK (width IS NULL OR (width >= 16 AND width <= 7680 AND width % 2 = 0)),
+  height int CHECK (height IS NULL OR (height >= 16 AND height <= 4320 AND height % 2 = 0)),
+  fps int CHECK (fps IS NULL OR (fps >= 1 AND fps <= 120)),
+  -- LiveVideoLatencyMode: 1=Default, 2=High latency, 3=Small latency.
+  latency_mode int NOT NULL DEFAULT 1 CHECK (latency_mode IN (1, 2, 3)),
+  permanent_live boolean NOT NULL DEFAULT false,
+  save_replay boolean NOT NULL DEFAULT false,
+  -- Replay privacy etc.; only meaningful while save_replay is on.
+  replay_settings jsonb CHECK (replay_settings IS NULL OR jsonb_typeof(replay_settings) = 'object'),
+  -- Latch: once the channel's live has started, settings are frozen (409).
+  live_started_at timestamptz,
+  -- Optimistic concurrency: every accepted write bumps version exactly once.
+  version bigint NOT NULL DEFAULT 0 CHECK (version >= 0),
+  updated_by uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, virtual_channel_id),
+  UNIQUE (id, workspace_id),
+  FOREIGN KEY (workspace_id, virtual_channel_id) REFERENCES virtual_channels (workspace_id, id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  CHECK (
+    (output_profile <> 'custom' AND width IS NULL AND height IS NULL AND fps IS NULL)
+    OR (output_profile = 'custom' AND width IS NOT NULL AND height IS NOT NULL AND fps IS NOT NULL)
+  ),
+  -- PeerTube rejects saveReplay + permanentLive (400); we refuse it earlier
+  -- and the DB refuses it for direct inserts.
+  CHECK (NOT (permanent_live AND save_replay)),
+  CHECK (save_replay OR replay_settings IS NULL)
+);
+
+CREATE TRIGGER trg_vcls_ws_immutable BEFORE UPDATE ON virtual_channel_live_settings
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_vcls_owner_immutable BEFORE UPDATE ON virtual_channel_live_settings
+  FOR EACH ROW EXECUTE FUNCTION reject_owner_change('virtual_channel_id');
+
+-- version never regresses; a stale CAS writer cannot rewind the fence.
+CREATE FUNCTION reject_live_settings_version_regression() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF NEW.version < OLD.version THEN
+    RAISE EXCEPTION 'live settings version cannot decrease' USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_vcls_version_monotone BEFORE UPDATE ON virtual_channel_live_settings
+  FOR EACH ROW EXECUTE FUNCTION reject_live_settings_version_regression();
+
+ALTER TABLE virtual_channel_live_settings ENABLE ROW LEVEL SECURITY;
+ALTER TABLE virtual_channel_live_settings FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON virtual_channel_live_settings
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON virtual_channel_imports, virtual_channel_live_settings TO sp_app;
diff --git a/apps/api/migrations/024_chatgov.sql b/apps/api/migrations/024_chatgov.sql
new file mode 100644
index 0000000..ec42f55
--- /dev/null
+++ b/apps/api/migrations/024_chatgov.sql
@@ -0,0 +1,477 @@
+-- 024: chat governance spine — chatgov design §2, P0 slice (glm).
+--
+-- Tables: polls, poll_votes, posting_rules, posting_policy_snapshots,
+-- topic_bindings, chat_command_audit, chat_identities, gate_decisions.
+-- poll_mirrors (card edit bookkeeping) is deliberately NOT here: it belongs to
+-- the P5 mirror slice and lands in its own forward migration.
+--
+-- Design notes (chatgov-design.md §0/§1/§2):
+--   * Polls are OURS, not Telegram's (D1): ballots live in poll_votes, the
+--     Telegram card is only a mirror. `polls.rule` is the compiled §1a object
+--     snapshotted at open and never re-resolved mid-flight; `policy_version`
+--     is its deterministic hash pinned at open and at every decision.
+--   * One open gate per draft (partial unique index) stops poll spam gating
+--     the same draft twice; a revote is a NEW poll with parent_poll_id.
+--   * posting_rules are data with precedence topic > content_type > account >
+--     workspace (D4). Only ONE live rule per (scope, account, topic,
+--     content_type) slot: the partial NULLS NOT DISTINCT index ignores
+--     superseded rows so a revision frees its slot without losing lineage.
+--     Effective policies are compiled at SAVE time into
+--     posting_policy_snapshots (whole-block replacement, no field merges).
+--   * topic_bindings are OUR registry of (connection, chat, thread) — the Bot
+--     API cannot list topics, so what we created here is authoritative (D3).
+--     `message_thread_id IS NULL` means the channel root / whole group, so the
+--     slot key needs NULLS NOT DISTINCT.
+--   * chat_identities key on the immutable numeric provider user id — never a
+--     username (§6). /register creates `pending`; console approval flips to
+--     `approved`; nothing self-elevates.
+--   * chat_command_audit records EVERY command attempt including rejects
+--     (rate_limited, unauthorized, unknown_command). UNIQUE (workspace,
+--     provider, update_id) is the replay killer for Telegram updates.
+--   * gate_decisions: one row per destination per gate evaluation (E1/E2/E3,
+--     D8 partial fan-out is a first-class outcome). `inputs` carries the
+--     quorum state at close; reason codes are machine-readable (§4).
+--
+-- Retention classes (WP2 convention; no registry table exists yet, so this
+-- comment is the registration): poll_votes, chat_command_audit and
+-- gate_decisions are append-hot and are monthly-partition candidates once a
+-- partition manager lands (014/020 style leaves). polls, posting_rules,
+-- posting_policy_snapshots, topic_bindings and chat_identities stay
+-- unpartitioned — they are FK parents / small current-state tables.
+--
+-- RLS / NULLIF / reject_workspace_change / sp_app grants follow 001/014/021
+-- conventions: no app.workspace_id => NULL => no rows; FORCE binds sp_app too.
+
+-- ---------------------------------------------------------------------------
+-- topic_bindings
+-- ---------------------------------------------------------------------------
+CREATE TABLE topic_bindings (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Telegram connection (one bot token per connection).
+  connection_id uuid NOT NULL,
+  -- Numeric -100… chat id preferred (usernames drift). Text, not bigint:
+  -- provider-neutral and stable across platforms.
+  chat_id text NOT NULL CHECK (chat_id ~ '^-?[0-9]{1,32}$'),
+  -- Telegram message_thread_id; NULL = channel root / whole group.
+  message_thread_id text CHECK (message_thread_id IS NULL OR message_thread_id ~ '^[0-9]{1,32}$'),
+  binding_type text NOT NULL CHECK (binding_type IN ('announce', 'control', 'audit')),
+  -- Telegram topic name limit is 128.
+  name text NOT NULL CHECK (char_length(btrim(name)) BETWEEN 1 AND 128),
+  -- One of the 7 fixed Telegram icon colors (7322096, 16766592, 13338331,
+  -- 9367192, 16749490, 16478047, 8914859).
+  icon_color integer CHECK (icon_color IS NULL OR icon_color IN
+    (7322096, 16766592, 13338331, 9367192, 16749490, 16478047, 8914859)),
+  state text NOT NULL DEFAULT 'active' CHECK (state IN ('active', 'closed', 'archived')),
+  -- Accounts (connections) that post into this topic. Array members cannot be
+  -- FK-enforced in PostgreSQL; the app layer validates they belong to the same
+  -- workspace (chatgov policy-service).
+  account_ids uuid[] NOT NULL DEFAULT '{}'::uuid[],
+  -- Control bindings: the virtual channel the commands act on.
+  linked_channel_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  UNIQUE NULLS NOT DISTINCT (workspace_id, connection_id, chat_id, message_thread_id),
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (linked_channel_id, workspace_id) REFERENCES virtual_channels (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_topic_bindings_ws_immutable BEFORE UPDATE ON topic_bindings
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE topic_bindings ENABLE ROW LEVEL SECURITY;
+ALTER TABLE topic_bindings FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON topic_bindings
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON topic_bindings TO sp_app;
+
+-- One control binding per virtual channel (design §2): two control topics
+-- commanding the same channel would race the director.
+CREATE UNIQUE INDEX topic_bindings_one_control
+  ON topic_bindings (workspace_id, linked_channel_id)
+  WHERE binding_type = 'control' AND linked_channel_id IS NOT NULL;
+-- Topic screen grid + gateway binding resolution (chat_id + thread -> row).
+CREATE INDEX topic_bindings_ws_conn ON topic_bindings (workspace_id, connection_id, state);
+
+
+-- ---------------------------------------------------------------------------
+-- polls
+-- ---------------------------------------------------------------------------
+CREATE TABLE polls (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Live-chat channel the poll is scoped to (nullable: console-only poll).
+  channel_id uuid,
+  -- Vote scoped to a subchat when set (topic binding), else the whole chat.
+  topic_binding_id uuid,
+  subject_kind text NOT NULL CHECK (subject_kind IN ('draft', 'chat_post', 'none')),
+  -- Set when subject_kind = 'draft'. Drafts are the only gating subject (D5).
+  draft_id uuid,
+  question text NOT NULL CHECK (char_length(question) BETWEEN 1 AND 300),
+  -- Revote lineage: a re-vote is a NEW poll pointing at the closed one.
+  parent_poll_id uuid,
+  -- Compiled §1a pass-criteria object, snapshotted at open (never re-resolved).
+  rule jsonb NOT NULL CHECK (jsonb_typeof(rule) = 'object'),
+  -- Deterministic hash of `rule` at open (pinned on every decision too).
+  policy_version text NOT NULL CHECK (btrim(policy_version) <> ''),
+  -- named | anonymous, extracted from `rule` for queryability. Anonymous polls
+  -- store NO voter linkage: poll_votes rows are written for named mode only
+  -- (§6 privacy; anonymous sentiment rides native Telegram polls in P7).
+  anonymity text NOT NULL DEFAULT 'named' CHECK (anonymity IN ('named', 'anonymous')),
+  state text NOT NULL DEFAULT 'open'
+    CHECK (state IN ('open', 'passed', 'failed', 'vetoed', 'quorum_unreachable', 'cancelled')),
+  opens_at timestamptz NOT NULL DEFAULT now(),
+  -- opens_at + rule.timebox.duration.
+  closes_at timestamptz NOT NULL,
+  closed_at timestamptz,
+  close_reason text CHECK (close_reason IN ('quorum_early', 'timebox', 'veto', 'cancelled')),
+  -- Exactly-once close claim: the state flip and its downstream trigger share
+  -- one transaction guarded by this column (P2 poll-service claims it).
+  outbox_state text NOT NULL DEFAULT 'none' CHECK (outbox_state IN ('none', 'claimed', 'done')),
+  created_by uuid NOT NULL REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  CHECK ((state = 'open') = (closed_at IS NULL)),
+  CHECK (close_reason IS NULL OR state <> 'open'),
+  FOREIGN KEY (channel_id, workspace_id) REFERENCES virtual_channels (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (topic_binding_id, workspace_id) REFERENCES topic_bindings (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_polls_ws_immutable BEFORE UPDATE ON polls
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE polls ENABLE ROW LEVEL SECURITY;
+ALTER TABLE polls FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON polls
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON polls TO sp_app;
+
+-- One open gate per draft (design §2): a second open poll on the same draft is
+-- refused by the index, not by application discipline.
+CREATE UNIQUE INDEX polls_open_one_per_draft ON polls (workspace_id, draft_id)
+  WHERE state = 'open' AND draft_id IS NOT NULL;
+-- Close sweep + overlay listing ("closing soon" chips).
+CREATE INDEX polls_ws_state ON polls (workspace_id, state, closes_at);
+-- Revote lineage walks (blocked queue "open re-vote" action).
+CREATE INDEX polls_ws_parent ON polls (workspace_id, parent_poll_id) WHERE parent_poll_id IS NOT NULL;
+
+-- Self-reference after the table exists (avoids a forward declaration).
+ALTER TABLE polls ADD CONSTRAINT polls_parent_fk
+  FOREIGN KEY (parent_poll_id, workspace_id) REFERENCES polls (id, workspace_id)
+  ON DELETE NO ACTION ON UPDATE RESTRICT;
+
+-- ---------------------------------------------------------------------------
+-- poll_votes
+-- ---------------------------------------------------------------------------
+CREATE TABLE poll_votes (
+  poll_id uuid NOT NULL,
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  voter_kind text NOT NULL CHECK (voter_kind IN ('user', 'chat_identity', 'system')),
+  -- Resolved workspace user, when known (named mode).
+  voter_user_id uuid REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  -- provider:from.id (numeric for Telegram). Idempotency key half.
+  voter_remote_id text NOT NULL CHECK (btrim(voter_remote_id) <> ''),
+  voter_handle text NOT NULL CHECK (btrim(voter_handle) <> ''),
+  ballot text NOT NULL CHECK (ballot IN ('yes', 'no', 'veto', 'abstain')),
+  -- Eligibility AT CAST (informational; eligibility is re-read at close).
+  eligible boolean NOT NULL DEFAULT true,
+  -- Ineligible votes are stored, never counted (D9 / GitLab pattern).
+  counted boolean NOT NULL DEFAULT true,
+  -- INELIGIBLE_ACTOR | SELF_APPROVAL_DENIED | ...
+  ineligible_reason text,
+  cast_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (poll_id, voter_remote_id),
+  FOREIGN KEY (poll_id, workspace_id) REFERENCES polls (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_poll_votes_ws_immutable BEFORE UPDATE ON poll_votes
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE poll_votes ENABLE ROW LEVEL SECURITY;
+ALTER TABLE poll_votes FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON poll_votes
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON poll_votes TO sp_app;
+
+-- Tally reads (quorum evaluation on every ballot) hit counted votes only.
+CREATE INDEX poll_votes_poll ON poll_votes (poll_id, counted);
+
+-- ---------------------------------------------------------------------------
+-- posting_rules
+-- ---------------------------------------------------------------------------
+CREATE TABLE posting_rules (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Precedence (D4): topic > content_type > account > workspace.
+  scope text NOT NULL CHECK (scope IN ('workspace', 'account', 'content_type', 'topic')),
+  -- Connection id (the policy anchor is the ACCOUNT, platform is an attribute).
+  -- NULL for workspace-scope rules and workspace-wide content_type rules.
+  account_id uuid,
+  -- Set when scope = 'topic'.
+  topic_binding_id uuid,
+  -- 'alert' | 'video' | ... when scope = 'content_type'.
+  content_type text,
+  -- §1a-shaped rule object minus the subject; validated app-side by
+  -- apps/api/src/chatgov/policy.ts before insert (021-style split: the CHECKs
+  -- here are only coarse backstops).
+  policy jsonb NOT NULL CHECK (jsonb_typeof(policy) = 'object'),
+  -- Compiled snapshot hash at save (deterministic; identical content shares
+  -- a version, so a re-save of the same policy is a no-op version-wise).
+  policy_version text NOT NULL CHECK (btrim(policy_version) <> ''),
+  -- Shadow mode: evaluate + log, never block/fire (POLICY_DRY_RUN).
+  dry_run boolean NOT NULL DEFAULT false,
+  created_by uuid NOT NULL REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  -- Revision chain hook (P6 rules editor): a superseded row no longer holds
+  -- its scope slot (see the partial unique index below) but keeps lineage.
+  superseded_by uuid,
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (account_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (topic_binding_id, workspace_id) REFERENCES topic_bindings (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_posting_rules_ws_immutable BEFORE UPDATE ON posting_rules
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE posting_rules ENABLE ROW LEVEL SECURITY;
+ALTER TABLE posting_rules FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON posting_rules
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON posting_rules TO sp_app;
+
+-- ONE live rule per scope slot. NULLS NOT DISTINCT because "no account" /
+-- "no topic" / "no content type" is itself a slot value (workspace default,
+-- channel root); a plain UNIQUE would allow unbounded duplicates there.
+-- Partial on superseded_by IS NULL so a revision frees the slot.
+CREATE UNIQUE INDEX posting_rules_live_uq
+  ON posting_rules (workspace_id, scope, account_id, topic_binding_id, content_type)
+  NULLS NOT DISTINCT
+  WHERE superseded_by IS NULL;
+-- Rules-editor listing and per-destination resolution scans.
+CREATE INDEX posting_rules_ws_scope ON posting_rules (workspace_id, scope, account_id, topic_binding_id)
+  WHERE superseded_by IS NULL;
+
+ALTER TABLE posting_rules ADD CONSTRAINT posting_rules_superseded_fk
+  FOREIGN KEY (superseded_by, workspace_id) REFERENCES posting_rules (id, workspace_id)
+  ON DELETE NO ACTION ON UPDATE RESTRICT;
+
+-- ---------------------------------------------------------------------------
+-- chat_identities
+-- ---------------------------------------------------------------------------
+CREATE TABLE chat_identities (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  provider text NOT NULL CHECK (btrim(provider) <> ''),
+  -- Immutable numeric provider user id (Telegram from.id) — NEVER a username
+  -- (§6: usernames are never trusted for authorization).
+  remote_user_id text NOT NULL CHECK (remote_user_id ~ '^[0-9]{1,20}$'),
+  -- Linked workspace user once /register is approved in the console.
+  user_id uuid REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  display_name text,
+  -- §1a admins-arm eligibility: membership role ∈ {Owner, Admin} OR this
+  -- override ≥ that role (evaluated at CLOSE time — TOCTOU guard). NULL = the
+  -- linked membership role governs. Written only by chatgov.manage holders.
+  role_override text CHECK (role_override IS NULL OR role_override IN ('Moderator', 'Editor', 'Publisher', 'Approver', 'Admin', 'Owner')),
+  -- /register creates pending; approval is a console action (chatgov.manage),
+  -- never self-service.
+  status text NOT NULL DEFAULT 'pending' CHECK (status IN ('pending', 'approved', 'rejected', 'banned')),
+  approved_by uuid REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  first_seen_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, provider, remote_user_id),
+  -- Approval must name its approver.
+  CHECK (status <> 'approved' OR approved_by IS NOT NULL)
+);
+
+CREATE TRIGGER trg_chat_identities_ws_immutable BEFORE UPDATE ON chat_identities
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE chat_identities ENABLE ROW LEVEL SECURITY;
+ALTER TABLE chat_identities FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON chat_identities
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON chat_identities TO sp_app;
+
+-- Gateway authorization path: numeric from.id -> identity -> membership role.
+CREATE UNIQUE INDEX chat_identities_ws_user
+  ON chat_identities (workspace_id, provider, user_id) WHERE user_id IS NOT NULL AND status = 'approved';
+
+-- ---------------------------------------------------------------------------
+-- chat_command_audit
+-- ---------------------------------------------------------------------------
+CREATE TABLE chat_command_audit (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Telegram update id (or provider event id): the replay killer.
+  update_id bigint NOT NULL CHECK (update_id > 0),
+  -- Topic binding the command arrived on (NULL: unbound chat — itself a
+  -- reject reason, NO_CHANNEL_BOUND).
+  binding_id uuid,
+  provider text NOT NULL CHECK (btrim(provider) <> ''),
+  remote_user_id text NOT NULL CHECK (btrim(remote_user_id) <> ''),
+  -- Resolved identity's workspace user, if any.
+  user_id uuid REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  command text NOT NULL CHECK (btrim(command) <> ''),
+  args jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(args) = 'object'),
+  -- RBAC permission the command required (NULL for /help, /register).
+  permission text,
+  -- Every attempt is audited, including rejects (§6).
+  decision text NOT NULL CHECK (decision IN ('accepted', 'rejected', 'unauthorized', 'unknown_command', 'rate_limited')),
+  -- Machine code: INELIGIBLE_ACTOR | LOCKED_CHANNEL | CONFIRM_EXPIRED | NO_CHANNEL_BOUND | ...
+  reason text,
+  -- Confirmation nonce when confirm-gated (P4).
+  nonce text,
+  -- Chat nonce reused as the director Idempotency-Key (P3/P4).
+  idempotency_key text,
+  -- Receipt fingerprint / poll id / draft id.
+  result_ref jsonb CHECK (result_ref IS NULL OR jsonb_typeof(result_ref) = 'object'),
+  received_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, provider, update_id),
+  FOREIGN KEY (binding_id, workspace_id) REFERENCES topic_bindings (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_chat_command_audit_ws_immutable BEFORE UPDATE ON chat_command_audit
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE chat_command_audit ENABLE ROW LEVEL SECURITY;
+ALTER TABLE chat_command_audit FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON chat_command_audit
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON chat_command_audit TO sp_app;
+
+CREATE INDEX chat_command_audit_ws_time ON chat_command_audit (workspace_id, received_at DESC);
+
+-- ---------------------------------------------------------------------------
+-- posting_policy_snapshots — effective policy resolved at SAVE time (D4).
+-- Evaluation reads ONLY snapshots; rules are re-compiled on every rule change.
+-- ---------------------------------------------------------------------------
+CREATE TABLE posting_policy_snapshots (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  destination_kind text NOT NULL CHECK (destination_kind IN ('account', 'topic')),
+  -- The account (connection) the destination posts through; topic snapshots
+  -- carry their owning connection here too.
+  account_id uuid NOT NULL,
+  -- NULL = the account root (whole account, no topic override).
+  topic_binding_id uuid,
+  -- '' = the destination's default (no content-type override); content_type
+  -- rules compile one snapshot per type so E3 can re-check by (account,
+  -- [topic], contentType) without re-resolving precedence at dispatch time.
+  content_type text NOT NULL DEFAULT '' CHECK (content_type ~ '^[a-z0-9_.-]{0,40}$'),
+  -- Compiled §1a object. Immutable per policy_version: a rule change writes a
+  -- NEW version; decisions pin the version they evaluated.
+  effective jsonb NOT NULL CHECK (jsonb_typeof(effective) = 'object'),
+  policy_version text NOT NULL CHECK (btrim(policy_version) <> ''),
+  -- Audit: which scopes/rules contributed to this resolution.
+  resolved_from jsonb NOT NULL CHECK (jsonb_typeof(resolved_from) = 'object'),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  -- NULLS NOT DISTINCT: topic_binding_id NULL is its own slot (account root).
+  -- The design sketch's PK omitted content_type; the column is kept in the
+  -- slot key so a content_type rule cannot silently overwrite the account's
+  -- default snapshot (whole-block replacement, one row per resolved slot).
+  UNIQUE NULLS NOT DISTINCT (workspace_id, destination_kind, account_id, topic_binding_id, content_type),
+  FOREIGN KEY (account_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (topic_binding_id, workspace_id) REFERENCES topic_bindings (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_posting_policy_snapshots_ws_immutable BEFORE UPDATE ON posting_policy_snapshots
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE posting_policy_snapshots ENABLE ROW LEVEL SECURITY;
+ALTER TABLE posting_policy_snapshots FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON posting_policy_snapshots
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON posting_policy_snapshots TO sp_app;
+
+-- E3 pre-dispatch re-check reads by (workspace, account[, topic][, contentType]).
+CREATE INDEX posting_policy_snapshots_ws_acct
+  ON posting_policy_snapshots (workspace_id, account_id, updated_at DESC);
+
+-- ---------------------------------------------------------------------------
+-- gate_decisions — one row per destination per gate evaluation (D8).
+-- ---------------------------------------------------------------------------
+CREATE TABLE gate_decisions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  draft_id uuid NOT NULL,
+  -- {platform, accountId, topicBindingId?} — the destination this row is about.
+  destination jsonb NOT NULL CHECK (jsonb_typeof(destination) = 'object'),
+  gate text NOT NULL CHECK (gate IN ('E1', 'E2', 'E3')),
+  -- Which posting rule fired (NULL when the fail-closed default applied).
+  rule_id uuid,
+  policy_version text NOT NULL CHECK (btrim(policy_version) <> ''),
+  outcome text NOT NULL CHECK (outcome IN ('fired', 'blocked', 'pending')),
+  -- Approvals, poll tally, quorum state at close (arm-by-arm got/needed).
+  inputs jsonb NOT NULL CHECK (jsonb_typeof(inputs) = 'object'),
+  -- INSUFFICIENT_QUORUM | INELIGIBLE_ACTOR | SELF_APPROVAL_DENIED | VETOED |
+  -- TIMEBOX_EXPIRED_AUTO_REJECT | RESET_ON_CHANGE | PENDING_POLL |
+  -- OUTSIDE_POLICY | POLICY_DRY_RUN | OVERRIDDEN_BY_OWNER | ...
+  reason_codes text[] NOT NULL DEFAULT '{}'::text[],
+  -- 'system:gate-e3' | 'user:<id>' | 'chat_poll:<pollId>'
+  actor text NOT NULL CHECK (btrim(actor) <> ''),
+  -- E2 rows carry the poll whose outcome this decision persists.
+  poll_id uuid,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (rule_id, workspace_id) REFERENCES posting_rules (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  FOREIGN KEY (poll_id, workspace_id) REFERENCES polls (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_gate_decisions_ws_immutable BEFORE UPDATE ON gate_decisions
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE gate_decisions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE gate_decisions FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON gate_decisions
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON gate_decisions TO sp_app;
+
+-- Blocked queue + draft timeline (P1) read by (workspace, draft, gate).
+CREATE INDEX gate_decisions_draft ON gate_decisions (workspace_id, draft_id, gate);
+-- Poll outcome lookup from the blocked queue's "open re-vote" action.
+CREATE INDEX gate_decisions_poll ON gate_decisions (workspace_id, poll_id) WHERE poll_id IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- RBAC: chatgov permissions, seeded in the 002 pattern (ON CONFLICT DO NOTHING).
+-- chatgov.manage = rules editor, topic registry, identity approval, policy
+-- compile — Owner/Admin. chatgov.vote = open/cast governance votes — the
+-- content + broadcast roles. One statement => one authz-epoch bump (018).
+-- ---------------------------------------------------------------------------
+INSERT INTO role_permissions (role, permission)
+SELECT v.role, v.permission
+FROM (VALUES
+  ('Owner', 'chatgov.manage'),
+  ('Owner', 'chatgov.vote'),
+  ('Admin', 'chatgov.manage'),
+  ('Admin', 'chatgov.vote'),
+  ('Publisher', 'chatgov.vote'),
+  ('Editor', 'chatgov.vote'),
+  ('Approver', 'chatgov.vote'),
+  ('Moderator', 'chatgov.vote'),
+  ('BroadcastOperator', 'chatgov.vote')
+) AS v(role, permission)
+ON CONFLICT DO NOTHING;
diff --git a/apps/api/migrations/025_archive_search.sql b/apps/api/migrations/025_archive_search.sql
new file mode 100644
index 0000000..ff1ae7b
--- /dev/null
+++ b/apps/api/migrations/025_archive_search.sql
@@ -0,0 +1,55 @@
+-- 025: WP15 archive full-text search (firehose research recommendation:
+-- Postgres FTS phase-1) over archived_feed_items.
+--
+-- Search surface:
+--   * tsvector over text_content + channel/attribution metadata, kept in sync
+--     by trigger (the normalizer writes text_content on insert AND on edits,
+--     so a plain trigger beats a generated column: 015's reject_workspace_change
+--     trigger guards workspace_id, and edits must reindex text).
+--   * GIN indexes: tsvector lookup + pg_trgm similarity for typo tolerance.
+--   * The API ORs websearch_to_tsquery matching with pg_trgm similarity so a
+--     misspelled term still matches via trigram distance (similarity >= 0.3).
+--   * RLS is untouched: archived_feed_items keeps its tenant_isolation policy
+--     from 015; search runs inside withTenant() so FORCE RLS binds honestly.
+--
+-- CREATE EXTENSION requires privileges sp_app lacks; this migration runs as
+-- the table owner only (015 grants are preserved below for completeness).
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+ALTER TABLE archived_feed_items ADD COLUMN search_vector tsvector NOT NULL DEFAULT '';
+
+-- String-valued attribution keys worth indexing as metadata (normalizer maps
+-- Telegram author/origin fields here). Kept narrow on purpose.
+CREATE FUNCTION archived_attribution_text(attribution jsonb)
+RETURNS text LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
+  SELECT coalesce(string_agg(value, ' '), '')
+    FROM jsonb_each_text(attribution)
+   WHERE key IN ('channelUsername', 'channelTitle', 'author', 'authorSignature',
+                 'forwardFromChat', 'forwardFromUser', 'signature')
+$$;
+
+CREATE FUNCTION archived_feed_items_search_vector() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  NEW.search_vector :=
+      setweight(to_tsvector('simple', coalesce(NEW.channel_id, '')), 'A')
+   || setweight(to_tsvector('simple', archived_attribution_text(NEW.attribution)), 'B')
+   || to_tsvector('simple', coalesce(NEW.text_content, ''));
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_archived_feed_items_search
+  BEFORE INSERT OR UPDATE OF text_content, channel_id, attribution
+  ON archived_feed_items FOR EACH ROW
+  EXECUTE FUNCTION archived_feed_items_search_vector();
+
+-- Exact/lexical lookups. 'simple' config on purpose: the corpus is a
+-- multilingual firehose, no stemming dictionary is "right", so phase-1 is
+-- exact term matching plus trigram fuzziness.
+CREATE INDEX archived_feed_items_search ON archived_feed_items USING gin (search_vector);
+
+-- Fuzzy path (typo tolerance) + unindexed-corpus ILIKE support on text.
+CREATE INDEX archived_feed_items_text_trgm ON archived_feed_items USING gin (text_content gin_trgm_ops);
+CREATE INDEX archived_feed_items_channel_trgm ON archived_feed_items USING gin (channel_id gin_trgm_ops);
+
+GRANT SELECT ON archived_feed_items TO sp_app;
diff --git a/apps/api/migrations/025_chatgov_p2.sql b/apps/api/migrations/025_chatgov_p2.sql
new file mode 100644
index 0000000..27d2131
--- /dev/null
+++ b/apps/api/migrations/025_chatgov_p2.sql
@@ -0,0 +1,72 @@
+-- P2 competitive short-post variants. 022/023/024 exist. The runner keys
+-- migrations by filename; 025_archive_search.sql belongs to another slice.
+ALTER TABLE polls
+  ADD COLUMN kind text NOT NULL DEFAULT 'yes_no' CHECK (kind IN ('yes_no', 'variant_selection')),
+  ADD COLUMN winner_option_id uuid,
+  ADD COLUMN draft_revision bigint,
+  ADD COLUMN content_kind text NOT NULL DEFAULT 'short_post' CHECK (content_kind IN ('short_post', 'document')),
+  ADD COLUMN eligible_user_ids uuid[];
+-- document is a schema seam only; P2 accepts short_post exclusively.
+ALTER TABLE polls DROP CONSTRAINT polls_state_check;
+ALTER TABLE polls ADD CONSTRAINT polls_state_check CHECK
+  (state IN ('open', 'passed', 'failed', 'vetoed', 'quorum_unreachable', 'cancelled', 'stale'));
+ALTER TABLE polls DROP CONSTRAINT polls_close_reason_check;
+ALTER TABLE polls ADD CONSTRAINT polls_close_reason_check CHECK
+  (close_reason IN ('quorum_early', 'timebox', 'veto', 'cancelled', 'quorum_unreachable', 'reset_on_change'));
+
+CREATE TABLE poll_options (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  poll_id uuid NOT NULL,
+  seq integer NOT NULL CHECK (seq > 0),
+  -- Future document revision chains can anchor here. Short posts use the
+  -- poll's numeric draft_revision plus this immutable text snapshot.
+  draft_revision_id uuid,
+  text text NOT NULL CHECK (char_length(text) BETWEEN 1 AND 5000),
+  submitted_by uuid NOT NULL REFERENCES users(id) ON DELETE NO ACTION ON UPDATE RESTRICT,
+  submitted_at timestamptz NOT NULL DEFAULT clock_timestamp(),
+  UNIQUE (poll_id, seq),
+  UNIQUE (id, poll_id, workspace_id),
+  FOREIGN KEY (poll_id, workspace_id) REFERENCES polls(id, workspace_id) ON DELETE CASCADE ON UPDATE RESTRICT
+);
+CREATE TRIGGER trg_poll_options_ws_immutable BEFORE UPDATE ON poll_options
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+-- Artifacts cannot be edited or individually removed, even by SQL callers.
+-- Cascading workspace/poll retention remains possible.
+CREATE FUNCTION chatgov_option_immutable() RETURNS trigger LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'UPDATE' OR pg_trigger_depth() = 1 THEN
+    RAISE EXCEPTION 'poll options are immutable' USING ERRCODE = '55000';
+  END IF;
+  RETURN OLD;
+END $$;
+CREATE TRIGGER trg_poll_options_immutable BEFORE UPDATE OR DELETE ON poll_options
+  FOR EACH ROW EXECUTE FUNCTION chatgov_option_immutable();
+ALTER TABLE poll_options ENABLE ROW LEVEL SECURITY;
+ALTER TABLE poll_options FORCE ROW LEVEL SECURITY;
+CREATE POLICY tenant_isolation ON poll_options
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+GRANT SELECT, INSERT, UPDATE, DELETE ON poll_options TO sp_app;
+
+ALTER TABLE poll_votes ADD COLUMN option_id uuid;
+ALTER TABLE poll_votes ADD CONSTRAINT poll_votes_option_fk
+  FOREIGN KEY (option_id, poll_id, workspace_id) REFERENCES poll_options(id, poll_id, workspace_id)
+  ON DELETE NO ACTION ON UPDATE RESTRICT;
+ALTER TABLE poll_votes ADD CONSTRAINT poll_votes_option_ballot_check CHECK (option_id IS NULL OR ballot = 'yes');
+ALTER TABLE polls ADD CONSTRAINT polls_winner_option_fk
+  FOREIGN KEY (winner_option_id, id, workspace_id) REFERENCES poll_options(id, poll_id, workspace_id)
+  ON DELETE NO ACTION ON UPDATE RESTRICT;
+ALTER TABLE polls ADD CONSTRAINT polls_winner_state_check CHECK
+  (winner_option_id IS NULL OR (kind = 'variant_selection' AND state = 'passed'));
+ALTER TABLE poll_votes ADD COLUMN voter_identity_id uuid REFERENCES chat_identities(id) ON DELETE NO ACTION ON UPDATE RESTRICT;
+ALTER TABLE polls ADD COLUMN final_evaluation jsonb;
+-- Narrow expiry discovery follows the publishing due-schedule house pattern:
+-- returns references only, never ballots/content. Mutations still use RLS.
+CREATE FUNCTION chatgov_due_polls() RETURNS TABLE(workspace_id uuid, id uuid)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT p.workspace_id, p.id FROM polls p WHERE p.state = 'open' AND p.closes_at <= now()
+  ORDER BY p.closes_at LIMIT 500
+$$;
+REVOKE ALL ON FUNCTION chatgov_due_polls() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION chatgov_due_polls() TO sp_app;
diff --git a/apps/api/migrations/026_columns_p1.sql b/apps/api/migrations/026_columns_p1.sql
new file mode 100644
index 0000000..8f44de9
--- /dev/null
+++ b/apps/api/migrations/026_columns_p1.sql
@@ -0,0 +1,230 @@
+-- 026: columns P1 — persistence + RBAC (WP3 §1.2/§3, §6 P1 row).
+--
+-- (025 was taken by WP15 archive search; this file is the columns slice.)
+--
+-- Three things land here, in 024's many-tables-one-file style:
+--
+--   1. The resolved-source / ingest / fan-out tables 021 deliberately left
+--      for their own slice: column_sources, feed_items, feed_item_columns.
+--      (provider_budget_ledger is P2b/P5 territory — no ledger caller exists
+--      yet, so the table is not created here.)
+--   2. host_budgets — the shared per-host egress budget table owned by
+--      @tactical-media-broadcast-hub/egress (its migrations/001_host_budgets.sql, applied
+--      verbatim with credit; the egress package never migrates at runtime and
+--      expects the application to apply and ledger it). The columns scheduler
+--      is the first app-side caller of HostBudgets that does not go through
+--      the whole egressFetch client, so the table must exist before P1's
+--      poll loop draws from it. IF NOT EXISTS keeps this idempotent if a
+--      later egress-integration migration also carries it.
+--   3. The `streams.columns.manage` RBAC seed (design §1.4/§0.5): write
+--      permission on columns, granted to Owner/Admin/Editor by default.
+--      Reads stay on `draft.view`.
+--
+-- RLS / NULLIF / reject_workspace_change / sp_app grants follow the
+-- 001/014/021/024 conventions: no app.workspace_id => NULL => no rows; FORCE
+-- binds sp_app too. `spec`/`refresh_policy` stay validated app-side by
+-- @tactical-media-broadcast-hub/core (021 note); the CHECKs here are coarse backstops.
+
+-- ---------------------------------------------------------------------------
+-- column_sources — what the scheduler actually polls for a column (§1.2)
+-- ---------------------------------------------------------------------------
+CREATE TABLE column_sources (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  column_id uuid NOT NULL REFERENCES stream_columns(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Identity of the thing polled (manifest id of a connector).
+  provider text NOT NULL CHECK (btrim(provider) <> '' AND length(provider) <= 64),
+  -- NULL for keyless sources (YouTube RSS, public Bluesky/Mastodon) — those
+  -- draw from the per-host budget only (§1.2 "Keyless sources").
+  connection_id uuid,
+  source_kind text NOT NULL CHECK (source_kind IN ('home','mentions','search','author')),
+  -- Platform-adapted query (post-adaptation, what gets sent); NULL for
+  -- home/mentions/author sources.
+  query text,
+  -- Canonical account ref for source_kind='author': '{provider}:{handle@host}'.
+  actor_ref text,
+  state text NOT NULL DEFAULT 'pending'
+    CHECK (state IN ('pending','ready','stale','error','unsupported','rate_limited','budget_paused','disabled')),
+  last_error text,
+  last_polled_at timestamptz,
+  next_poll_at timestamptz,
+  consecutive_failures integer NOT NULL DEFAULT 0 CHECK (consecutive_failures >= 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT,
+  -- One source row per (column, polled identity); NULLs equal NULLs so a
+  -- keyless search source dedupes against itself (024 NULLS NOT DISTINCT
+  -- style). The SAME identity in two different columns is intentional (§3.3:
+  -- following the same account in two columns costs one poll) — the due
+  -- source scan collapses those rows into one poll and fans items out to
+  -- every column sharing the identity.
+  UNIQUE NULLS NOT DISTINCT (workspace_id, column_id, provider, source_kind, connection_id, query, actor_ref)
+);
+
+CREATE TRIGGER trg_column_sources_ws_immutable BEFORE UPDATE ON column_sources
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE column_sources ENABLE ROW LEVEL SECURITY;
+ALTER TABLE column_sources FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON column_sources
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON column_sources TO sp_app;
+
+-- Due-source scan (§3.4): workspace + next_poll_at with the disabled rows
+-- partial-indexed away. Design §1.2 names this column_sources_due_idx on
+-- (next_poll_at); workspace leads here because every scan is tenant-scoped
+-- under RLS and the composite keeps each workspace's due window contiguous.
+CREATE INDEX column_sources_due_idx
+  ON column_sources (workspace_id, next_poll_at)
+  WHERE state <> 'disabled';
+
+-- Column fan-out listing (ColumnView.sources) and per-column refresh.
+CREATE INDEX column_sources_column_idx ON column_sources (column_id);
+
+-- Connection → sources (the degenerate platform_feed lookup in the scheduler
+-- and the /feeds per-connection store fallback).
+CREATE INDEX column_sources_connection_idx
+  ON column_sources (connection_id)
+  WHERE connection_id IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- feed_items — ingested items (§1.2): persisted depth for keyset pagination
+-- and cross-column dedup; Redis stays the hot read-through cache in front.
+-- ---------------------------------------------------------------------------
+CREATE TABLE feed_items (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- sha256(workspace_id | provider | canonical_remote_id) — see §3.3; the
+  -- canonicalization rule is app-side, the key is opaque to the DB.
+  dedup_key text NOT NULL CHECK (dedup_key <> ''),
+  provider text NOT NULL CHECK (btrim(provider) <> '' AND length(provider) <= 64),
+  remote_id text NOT NULL CHECK (remote_id <> ''),
+  -- Connector-reported FeedItem.id; first writer wins, kept stable so a
+  -- cursor minted from the hot cache still tie-breaks identically when the
+  -- same page is later served from the store.
+  item_id text NOT NULL CHECK (item_id <> ''),
+  author_handle text NOT NULL CHECK (author_handle <> ''),
+  -- Canonical '{provider}:{handle@host}' when resolvable (P0c feedAuthorRef).
+  author_ref text,
+  -- Provider permalink; absolute credential-free http(s) only (P0c parseSafeHttpUrl).
+  url text CHECK (url IS NULL OR url ~ '^https?://'),
+  -- Provider timestamp — the deterministic keyset sort key.
+  created_at_remote timestamptz NOT NULL,
+  fetched_at timestamptz NOT NULL DEFAULT now(),
+  -- safe-content typed rich-text AST. NEVER raw HTML (§5.1) — the app layer
+  -- produces this through normalizeFeedItem; the CHECK only backstops shape.
+  content jsonb NOT NULL CHECK (jsonb_typeof(content) = 'object'),
+  -- Derived flat text (astToPlainText) for saved-search filtering/previews.
+  plain_text text NOT NULL,
+  -- [{kind:'image'|'video', proxyUrl, ...}] — proxy-minted only (§5.3).
+  media jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(media) = 'array'),
+  -- Finite numbers only (validated at ingest).
+  metrics jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(metrics) = 'object'),
+  source_id uuid NOT NULL,
+  -- ToS expiry (YouTube Data-API items: fetched_at + 30d); sweeper is P2c.
+  expires_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, dedup_key),
+  UNIQUE (id, workspace_id),
+  FOREIGN KEY (source_id, workspace_id) REFERENCES column_sources (id, workspace_id)
+    ON DELETE NO ACTION ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_feed_items_ws_immutable BEFORE UPDATE ON feed_items
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE feed_items ENABLE ROW LEVEL SECURITY;
+ALTER TABLE feed_items FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON feed_items
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON feed_items TO sp_app;
+
+-- Keyset serving: GET /feeds/columns/:id/items pages (created_at_remote DESC,
+-- dedup_key DESC) over this index (§1.4 "Cursor rule").
+CREATE INDEX feed_items_ws_time_idx
+  ON feed_items (workspace_id, created_at_remote DESC, dedup_key DESC);
+
+-- Store backfill for /feeds per connection and per-source item listing.
+CREATE INDEX feed_items_source_idx ON feed_items (source_id, created_at_remote DESC);
+
+-- Expiry sweeper (P2c) pre-indexed here so the later slice adds no DDL.
+CREATE INDEX feed_items_expiry_idx ON feed_items (expires_at) WHERE expires_at IS NOT NULL;
+
+-- ---------------------------------------------------------------------------
+-- feed_item_columns — which columns show an item (§1.2 table 4). An item
+-- ingested for a source identity is visible to every column sharing that
+-- identity; rows are written by poll-time fan-out with ON CONFLICT DO NOTHING.
+-- ---------------------------------------------------------------------------
+-- stream_columns (021) has only its surrogate PK; migrations < 025 are frozen,
+-- so the tenant-composite keys the FKs below need are added here — additive
+-- unique indexes on supersets of existing keys, so no uniqueness changes.
+CREATE UNIQUE INDEX IF NOT EXISTS stream_columns_id_workspace_key
+  ON stream_columns (id, workspace_id);
+
+CREATE TABLE feed_item_columns (
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  item_id uuid NOT NULL,
+  column_id uuid NOT NULL,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (item_id, column_id),
+  FOREIGN KEY (item_id, workspace_id) REFERENCES feed_items (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT,
+  FOREIGN KEY (column_id, workspace_id) REFERENCES stream_columns (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+
+CREATE TRIGGER trg_feed_item_columns_ws_immutable BEFORE UPDATE ON feed_item_columns
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE feed_item_columns ENABLE ROW LEVEL SECURITY;
+ALTER TABLE feed_item_columns FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON feed_item_columns
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, DELETE ON feed_item_columns TO sp_app;
+
+-- Serving index: the items endpoint joins column_id → item_id before the
+-- keyset filter; the PK alone would force an item_id-ordered probe.
+CREATE INDEX feed_item_columns_column_idx ON feed_item_columns (column_id, item_id);
+
+-- ---------------------------------------------------------------------------
+-- host_budgets — applied verbatim from @tactical-media-broadcast-hub/egress
+-- migrations/001_host_budgets.sql (WP7/WP8). Infrastructure state shared by
+-- all egress callers; deliberately NOT tenant/RLS scoped (one IDNA lowercase
+-- host:port key across callers and host classes — the whole point is that
+-- monitor, feeds and any other caller of the same host share one bucket).
+-- ---------------------------------------------------------------------------
+CREATE TABLE IF NOT EXISTS host_budgets (
+  host text PRIMARY KEY CHECK (host <> '' AND host = lower(host)),
+  capacity double precision NOT NULL CHECK (capacity >= 1 AND capacity < 'Infinity'::double precision),
+  -- Tokens per fixed 10-second interval (fractional tokens support continuous refill).
+  refill_per_interval double precision NOT NULL CHECK (refill_per_interval > 0 AND refill_per_interval < 'Infinity'::double precision),
+  tokens double precision NOT NULL CHECK (tokens >= 0 AND tokens <= capacity),
+  -- A future timestamp parks the bucket: no refill/debit until this deadline.
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp() CHECK (isfinite(updated_at))
+);
+
+COMMENT ON TABLE host_budgets IS 'Infrastructure egress budgets; one IDNA lowercase host:effective-port key across callers and host classes. Retain while host is in use.';
+
+GRANT SELECT, INSERT, UPDATE ON host_budgets TO sp_app;
+
+-- ---------------------------------------------------------------------------
+-- RBAC seed: streams.columns.manage (design §1.4 — granted to Owner/Admin/
+-- Editor by default; reads stay on draft.view). 002's unnest + ON CONFLICT
+-- pattern so the seed is re-runnable and never fights a later role edit.
+-- ---------------------------------------------------------------------------
+INSERT INTO role_permissions (role, permission)
+SELECT 'Owner', 'streams.columns.manage'
+UNION ALL SELECT 'Admin', 'streams.columns.manage'
+UNION ALL SELECT 'Editor', 'streams.columns.manage'
+ON CONFLICT DO NOTHING;
diff --git a/apps/api/migrations/027_intake.sql b/apps/api/migrations/027_intake.sql
new file mode 100644
index 0000000..185b444
--- /dev/null
+++ b/apps/api/migrations/027_intake.sql
@@ -0,0 +1,186 @@
+-- 027: content intake firehose phase 1 (WP15+ firehose research §1/§2/§4/§5.3,
+-- decision record docs/decisions/2026-10-09-intake-posture.md — Tier-1
+-- sanctioned sources only, metadata-first).
+--
+-- NOTE on the number: this slice was specced as "026_intake.sql (next free)"
+-- but 025_archive_search and 026_columns_p1 already exist, so intake lands as
+-- 027 — the next free slot at authoring time.
+--
+-- Two tables:
+--
+--   intake_sources  the per-workspace subscription registry (§4.4 sketch,
+--                   tenant-scoped per the phase-1 dedup note in §2.4: dedup
+--                   happens WITHIN a workspace; the global item registry +
+--                   claims split is the phase-1.5 upgrade).
+--   intake_items    the harvested rows. Dedup is CONTENT-ADDRESSED:
+--                   UNIQUE (workspace_id, content_hash) where content_hash is
+--                   sha256(normalized plain text + media origin identity), so
+--                   the same statement arriving via RSS and a Mastodon boost
+--                   (or the same URL watched twice) stores once. Storage-level
+--                   dedup stays in the S3 content-addressed layer.
+--
+-- `content` is the P0c safe-content rich-text AST — the ONLY render source;
+-- adapters never hand raw provider HTML through (apps/api/src/feeds/
+-- feed-normalize.ts funnels every item). `text` is the derived flat text
+-- (astToPlainText) that FTS + pg_trgm index.
+--
+-- FTS mirrors 025's design: 'simple' config (multilingual firehose, no
+-- stemming dictionary is "right"), websearch_to_tsquery in the API ORed with
+-- pg_trgm similarity for typo tolerance; tsvector maintained by trigger
+-- because edits/telegram revisions must reindex.
+--
+-- RLS / NULLIF / reject_workspace_change / sp_app grants follow the
+-- 001/015/026 conventions: no app.workspace_id => NULL => no rows; FORCE
+-- binds sp_app too. CREATE EXTENSION requires privileges sp_app lacks; this
+-- migration runs as the table owner only (025 note).
+
+CREATE EXTENSION IF NOT EXISTS pg_trgm;
+
+-- ---------------------------------------------------------------------------
+-- intake_sources
+-- ---------------------------------------------------------------------------
+CREATE TABLE intake_sources (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  -- Tier-1 sanctioned intake kinds (decision record). bluesky_keyword is a
+  -- stub seam in this slice — the Jetstream consumer is a later slice, so the
+  -- scheduler parks those rows in health='unsupported' rather than polling.
+  kind text NOT NULL CHECK (kind IN ('rss','mastodon_tag','mastodon_account','bluesky_keyword',
+                                     'telegram_channel','peertube_channel','youtube_channel','web_watch')),
+  -- Per-kind identity: url (rss/web_watch), tag (mastodon_tag), instance +
+  -- accountId (mastodon_account), keywords[] (bluesky_keyword), channelId
+  -- (telegram_channel / youtube_channel), handle + instance (peertube_channel).
+  -- Validated app-side per kind; the DB only backstops "is an object".
+  params jsonb NOT NULL CHECK (jsonb_typeof(params) = 'object'),
+  -- sha256 of the canonically serialized params — the stable identity half of
+  -- UNIQUE (workspace_id, kind, params_hash). Canonicalization is app-side.
+  params_hash text NOT NULL CHECK (params_hash ~ '^[0-9a-f]{64}$'),
+  -- 0 = push-only (telegram webhook bridge, bluesky Jetstream): never due.
+  poll_interval_sec integer NOT NULL DEFAULT 300 CHECK (poll_interval_sec >= 0),
+  -- Adapter carry: etag / lastModified / lastContentHash / lastRemoteRef.
+  state jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(state) = 'object'),
+  health text NOT NULL DEFAULT 'active'
+    CHECK (health IN ('active','backoff','error','paused','unsupported')),
+  last_error text,
+  last_polled_at timestamptz,
+  next_poll_at timestamptz,
+  consecutive_failures integer NOT NULL DEFAULT 0 CHECK (consecutive_failures >= 0),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, id),
+  UNIQUE (workspace_id, kind, params_hash)
+);
+
+CREATE TRIGGER trg_intake_sources_ws_immutable BEFORE UPDATE ON intake_sources
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE intake_sources ENABLE ROW LEVEL SECURITY;
+ALTER TABLE intake_sources FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON intake_sources
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON intake_sources TO sp_app;
+
+-- Due-source scan (the scheduler's loop): workspace + next_poll_at with the
+-- non-pollable rows partial-indexed away.
+CREATE INDEX intake_sources_due_idx
+  ON intake_sources (workspace_id, next_poll_at)
+  WHERE health NOT IN ('paused','unsupported');
+
+-- Listing / "which sources feed this item".
+CREATE INDEX intake_sources_kind_idx ON intake_sources (workspace_id, kind);
+
+-- ---------------------------------------------------------------------------
+-- intake_items
+-- ---------------------------------------------------------------------------
+CREATE TABLE intake_items (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE ON UPDATE RESTRICT,
+  source_id uuid NOT NULL,
+  -- Platform-native id for the source (guid, status id, yt:video:…, tg chat:id,
+  -- url#hash for web_watch diffs).
+  remote_ref text NOT NULL CHECK (btrim(remote_ref) <> '' AND length(remote_ref) <= 2048),
+  -- sha256(NFKC + whitespace-collapsed AST plain text + sorted media origin
+  -- identity). THE dedup key: UNIQUE (workspace_id, content_hash).
+  content_hash text NOT NULL CHECK (content_hash ~ '^[0-9a-f]{64}$'),
+  published_at timestamptz NOT NULL,
+  -- Flat text derived from `content` at ingest (astToPlainText) — the FTS and
+  -- pg_trgm corpus. `text` is non-reserved; kept as the specced column name.
+  text text NOT NULL DEFAULT '',
+  -- P0c safe-content rich-text AST (doc/paragraph/inline). NEVER raw HTML.
+  content jsonb NOT NULL CHECK (jsonb_typeof(content) = 'object'),
+  -- [{kind, proxyUrl}…] for pull adapters (feed-normalize proxied media) or
+  -- [{kind, storageKey, …}] for the Telegram archive bridge (content-addressed
+  -- S3 keys already harvested by apps/api/src/archive).
+  media_refs jsonb NOT NULL DEFAULT '[]'::jsonb CHECK (jsonb_typeof(media_refs) = 'array'),
+  -- {authorHandle, authorRef, url, title, provider, …kind extras}
+  attribution jsonb NOT NULL DEFAULT '{}'::jsonb CHECK (jsonb_typeof(attribution) = 'object'),
+  fetched_at timestamptz NOT NULL DEFAULT now(),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (id, workspace_id),
+  -- Content-addressed dedup (spec §2.4 layer 2): first writer wins, every
+  -- later delivery of the same content no-ops.
+  UNIQUE (workspace_id, content_hash),
+  FOREIGN KEY (source_id, workspace_id) REFERENCES intake_sources (id, workspace_id)
+    ON DELETE CASCADE ON UPDATE RESTRICT
+);
+
+-- Maintained by trigger below; declared here so the column exists for the
+-- index + trigger DDL in one place.
+ALTER TABLE intake_items ADD COLUMN search_vector tsvector NOT NULL DEFAULT '';
+
+CREATE TRIGGER trg_intake_items_ws_immutable BEFORE UPDATE ON intake_items
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE intake_items ENABLE ROW LEVEL SECURITY;
+ALTER TABLE intake_items FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON intake_items
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON intake_items TO sp_app;
+
+-- Per-source listing (GET /intake/items?sourceId=) keyset order.
+CREATE INDEX intake_items_source_idx
+  ON intake_items (workspace_id, source_id, published_at DESC, id DESC);
+
+-- Whole-workspace newest-first (GET /intake/items without a source filter).
+CREATE INDEX intake_items_time_idx
+  ON intake_items (workspace_id, published_at DESC, id DESC);
+
+-- ---------------------------------------------------------------------------
+-- FTS (025 pattern)
+-- ---------------------------------------------------------------------------
+-- String-valued attribution keys worth indexing as metadata.
+CREATE FUNCTION intake_attribution_text(attribution jsonb)
+RETURNS text LANGUAGE sql IMMUTABLE PARALLEL SAFE AS $$
+  SELECT coalesce(string_agg(value, ' '), '')
+    FROM jsonb_each_text(attribution)
+   WHERE key IN ('authorHandle','authorRef','title','channelTitle','channelUsername',
+                 'author','authorSignature','forwardFromChat','forwardFromUser','handle')
+$$;
+
+CREATE FUNCTION intake_items_search_vector() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  NEW.search_vector :=
+      setweight(to_tsvector('simple', coalesce(NEW.attribution->>'title', '')), 'A')
+   || setweight(to_tsvector('simple', intake_attribution_text(NEW.attribution)), 'B')
+   || to_tsvector('simple', coalesce(NEW.text, ''));
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_intake_items_search
+  BEFORE INSERT OR UPDATE OF text, attribution
+  ON intake_items FOR EACH ROW
+  EXECUTE FUNCTION intake_items_search_vector();
+
+-- Exact/lexical path. fastupdate stays on explicitly: GIN insert cost is the
+-- watch item at firehose write rates (research §2.7).
+CREATE INDEX intake_items_fts ON intake_items USING gin (search_vector) WITH (fastupdate = on);
+
+-- Fuzzy path (typo tolerance) + ILIKE support on the text corpus.
+CREATE INDEX intake_items_text_trgm ON intake_items USING gin (text gin_trgm_ops);
diff --git a/apps/api/migrations/028_instance_settings.sql b/apps/api/migrations/028_instance_settings.sql
new file mode 100644
index 0000000..635d40f
--- /dev/null
+++ b/apps/api/migrations/028_instance_settings.sql
@@ -0,0 +1,79 @@
+-- 028: instance-level admin settings — content-policy posture for intake.
+--
+-- The intake-posture decision record
+-- (docs/decisions/2026-10-09-intake-posture.md) grades the intake tiers by
+-- legal/ToS risk:
+--
+--   YouTube channel RSS + metadata  = safe (keyless, no quota, no ToS risk)
+--   YouTube full harvest (yt-dlp)   = ToS risk — per-source opt-in ONLY
+--                                     (027's DEFAULT_MEDIA_POLICY already
+--                                     parks youtube_channel at 'metadata');
+--                                     this switch is the instance-wide gate
+--                                     the per-source opt-in is subordinate to
+--   YouTube broadcast playlists     = CC-only (Creative Commons licensed
+--                                     content only) — safe to rebroadcast
+--   Locked platforms (X/IG/TikTok)  = metadata-only via sanctioned
+--                                     connectors; a bounded read-only pool is
+--                                     the decision record's Tier-2 "small
+--                                     bounded pool, later" option — opt-in
+--
+-- Those posture choices are INSTANCE-level (one deployment = one collective,
+-- one egress IP, one legal exposure), not per-workspace: no workspace admin
+-- may widen them for everyone. Hence this table is a system table:
+--
+--   * no workspace_id — deliberately. It is not a tenant row.
+--   * no RLS — there is nothing to isolate BY. Access control is at the API
+--     seam (SettingsService runs as sp_app; only Owner/Admin roles reach the
+--     setters through the controller's role check). NOT a grant-surface for
+--     tenant sessions: the app pool is the only grantee.
+--
+-- key-value shape (key TEXT PK, value TEXT NOT NULL) per task spec: settings
+-- are few, admin-facing and read as a whole — typed decoding lives in
+-- apps/api/src/settings/settings.service.ts (the ONE place that interprets
+-- values; nothing else parses these strings), values are CHECK-constrained
+-- to the exact literal the service layer understands so a stray UPDATE can
+-- never park an undecodable row in the table.
+
+BEGIN;
+
+CREATE TABLE instance_settings (
+  key text PRIMARY KEY,
+  value text NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  updated_by uuid REFERENCES users(id) ON DELETE SET NULL,
+  -- Legal-exposure switches must never hold anything but the literals the
+  -- service layer decodes; unknown keys are equally rejected so a typo can't
+  -- fork the settings surface.
+  CONSTRAINT instance_settings_key_allowed CHECK (key IN (
+    'youtube_full_harvest', 'youtube_cc_only_broadcast',
+    'scrape_metadata_only', 'scrape_bounded_pilot', 'intake_posture'
+  )),
+  CONSTRAINT instance_settings_bool_value CHECK (
+    key NOT IN ('youtube_full_harvest', 'youtube_cc_only_broadcast',
+                'scrape_metadata_only', 'scrape_bounded_pilot')
+    OR value IN ('true', 'false')
+  ),
+  CONSTRAINT instance_settings_posture_value CHECK (
+    key <> 'intake_posture'
+    OR value IN ('metadata_only', 'community_submissions', 'bounded_pilot')
+  )
+);
+
+-- ---------------------------------------------------------------------------
+-- Seed defaults (the safe posture — matches the 2026-10-09 decision record:
+-- "metadata-only + community submissions + Tier-1 sanctioned sources").
+-- ON CONFLICT DO NOTHING keeps re-runs and later re-seeds idempotent.
+-- ---------------------------------------------------------------------------
+INSERT INTO instance_settings (key, value) VALUES
+  ('youtube_full_harvest',       'false'),          -- yt-dlp OFF at the gate
+  ('youtube_cc_only_broadcast',  'true'),           -- CC-only broadcast filter
+  ('scrape_metadata_only',       'true'),           -- locked platforms: metadata
+  ('scrape_bounded_pilot',       'false'),          -- no bounded X pool
+  ('intake_posture',             'metadata_only')   -- overall posture
+ON CONFLICT (key) DO NOTHING;
+
+-- System table: sp_app is the ONLY grantee (003's default privileges already
+-- cover it, but the explicit grant documents intent the way 006/008/009 do).
+GRANT SELECT, INSERT, UPDATE, DELETE ON instance_settings TO sp_app;
+
+COMMIT;
diff --git a/apps/api/package.json b/apps/api/package.json
new file mode 100644
index 0000000..2fe9eef
--- /dev/null
+++ b/apps/api/package.json
@@ -0,0 +1,47 @@
+{
+  "name": "@tactical-media-broadcast-hub/api",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "migrate": "tsx src/db/migrate.cli.ts"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-telegram": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*",
+    "@aws-sdk/client-s3": "^3.1146.0",
+    "@aws-sdk/s3-request-presigner": "^3.1146.0",
+    "@nestjs/common": "^10.4.1",
+    "@nestjs/core": "^10.4.1",
+    "@nestjs/platform-express": "^10.4.1",
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/auto-instrumentations-node": "^0.80.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/sdk-node": "^0.222.0",
+    "jose": "^6.2.12",
+    "pg": "^8.23.1",
+    "pino": "^9.3.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "@tactical-media-broadcast-hub/publishing-execution": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-runtime": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-mastodon": "workspace:*",
+    "@temporalio/client": "1.24.0"
+  },
+  "devDependencies": {
+    "@tactical-media-broadcast-hub/connector-mock-livestream": "workspace:^",
+    "@types/express": "^4.17.21",
+    "@types/node": "^22.5.0",
+    "@types/pg": "^8.23.1",
+    "tsx": "^4.17.0",
+    "vitest": "^2.0.5"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  }
+}
diff --git a/apps/api/src/analytics/analytics.controller.ts b/apps/api/src/analytics/analytics.controller.ts
new file mode 100644
index 0000000..337eb9e
--- /dev/null
+++ b/apps/api/src/analytics/analytics.controller.ts
@@ -0,0 +1,62 @@
+import { BadRequestException, Body, Controller, Get, Post, Query, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { parseLimit, requireSession } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { SnapshotService, SnapshotRecord, monthStart, parseMonth } from "./snapshot.service.js";
+
+/**
+ * POST /analytics/snapshot is the manual trigger (analytics.view is held by
+ * Owner/Admin/Approver/Analyst — the closest thing to an admin/owner gate in
+ * the 002 permission set). The scheduler calls `writeMonthlySnapshot`
+ * (exported from snapshot.service.ts) directly later: same set-based SQL and
+ * idempotent upsert, no HTTP hop.
+ */
+@Controller("analytics")
+@UseGuards(RbacGuard)
+export class AnalyticsController {
+  constructor(private readonly snapshots: SnapshotService) {}
+
+  @Post("snapshot")
+  @RequirePermission("analytics.view")
+  async snapshot(
+    @Req() request: Request & AuthenticatedRequest,
+    @Body() body: unknown,
+  ): Promise<SnapshotRecord> {
+    const input = typeof body === "object" && body !== null ? (body as Record<string, unknown>) : {};
+    const month = input.month === undefined || input.month === null || input.month === ""
+      ? monthStart()
+      : parseMonth(String(input.month));
+    const session = requireSession(request);
+    return this.snapshots.refresh(session.workspaceId, month);
+  }
+
+  @Get("snapshots")
+  @RequirePermission("analytics.view")
+  async list(
+    @Req() request: Request & AuthenticatedRequest,
+    @Query("cursor") cursor: string | undefined,
+    @Query("limit") limit: string | undefined,
+  ): Promise<{ items: SnapshotRecord[]; nextCursor: string | null }> {
+    if (cursor !== undefined && (cursor.length > 256 || !/^[A-Za-z0-9_-]+$/.test(cursor))) {
+      throw new BadRequestException("invalid cursor");
+    }
+    const session = requireSession(request);
+    return this.snapshots.list(session.workspaceId, {
+      ...(cursor === undefined || cursor === "" ? {} : { cursor }),
+      limit: limit === undefined || limit === "" ? undefined : parseLimit(limit, 12, 24),
+    });
+  }
+
+  @Get("summary")
+  @RequirePermission("analytics.view")
+  async summary(@Req() request: Request & AuthenticatedRequest): Promise<{
+    currentMonth: string;
+    previousMonth: string;
+    current: SnapshotRecord | null;
+    previous: SnapshotRecord | null;
+    deltas: ReturnType<typeof import("./snapshot.service.js").monthDeltas> | null;
+  }> {
+    const session = requireSession(request);
+    return this.snapshots.summary(session.workspaceId);
+  }
+}
diff --git a/apps/api/src/analytics/analytics.integration.test.ts b/apps/api/src/analytics/analytics.integration.test.ts
new file mode 100644
index 0000000..a6b4941
--- /dev/null
+++ b/apps/api/src/analytics/analytics.integration.test.ts
@@ -0,0 +1,358 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * WP3 analytics snapshots against a live PostgreSQL, as sp_app (FORCE RLS
+ * binds). Uses its OWN database (ANALYTICS_IT_DATABASE_URL, plus
+ * ANALYTICS_IT_SUPER_DATABASE_URL for migrations/seeding) for the same reason
+ * as groups.integration.test.ts: tenancy.integration.test.ts wipes every
+ * workspace in the shared DB and vitest runs files in parallel.
+ * Skipped cleanly when either env var is unset.
+ */
+const appUrl = process.env.ANALYTICS_IT_DATABASE_URL;
+const ownerUrl = process.env.ANALYTICS_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  service: typeof import("./snapshot.service.js");
+  controller: typeof import("./analytics.controller.js");
+  guard: typeof import("../rbac/rbac.guard.js");
+  session: typeof import("../auth/session.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("analytics snapshots (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  const currentMonth = new Date().toISOString().slice(0, 7) + "-01";
+  const prevDate = new Date(`${currentMonth}T00:00:00Z`);
+  prevDate.setUTCMonth(prevDate.getUTCMonth() - 1);
+  const previousMonth = prevDate.toISOString().slice(0, 10);
+  let wsA: string;
+  let wsB: string;
+  let user: string;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  /** Seed tenant rows honestly: FORCE RLS applies to the owner too. */
+  async function inTenant(client: PoolClient, wsId: string, fn: () => Promise<void>): Promise<void> {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [wsId]);
+    await fn();
+    await client.query("COMMIT");
+  }
+
+  beforeAll(async () => {
+    // The shared pool reads DATABASE_URL at import time: point it at this
+    // isolated DB first, then import the modules under test.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      service: await import("./snapshot.service.js"),
+      controller: await import("./analytics.controller.js"),
+      guard: await import("../rbac/rbac.guard.js"),
+      session: await import("../auth/session.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    await asOwner(async (c) => {
+      const ws = async (name: string): Promise<string> =>
+        (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", [name, `${name}-${suffix}`])).rows[0].id as string;
+      wsA = await ws("analytics-a");
+      wsB = await ws("analytics-b");
+      user = (await c.query(
+        "INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4) RETURNING id",
+        [`analytics:owner:${suffix}`, `analytics-owner-${suffix}`, `owner-${suffix}@example.com`, "owner"],
+      )).rows[0].id as string;
+
+      const seed = async (wsId: string, archivedCount: number): Promise<void> => {
+        await inTenant(c, wsId, async () => {
+          await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Owner')", [wsId, user]);
+          const tag = wsId.slice(0, 8);
+          // 3 connections (mastodon, bluesky, mastodon) + one draft each.
+          const drafts: string[] = [];
+          for (const [i, provider] of ["mastodon", "bluesky", "mastodon"].entries()) {
+            const conn = (await c.query(
+              "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, $2, $3) RETURNING id",
+              [wsId, provider, `ch-${tag}-${i}`],
+            )).rows[0].id as string;
+            const draft = (await c.query(
+              "INSERT INTO drafts (workspace_id, author_user_id, post) VALUES ($1, $2, $3::jsonb) RETURNING id",
+              [wsId, user, JSON.stringify({ body: "x" })],
+            )).rows[0].id as string;
+            drafts.push(draft);
+            await c.query(
+              `INSERT INTO publications (workspace_id, draft_id, connection_id, idempotency_key, remote_id, published_at)
+               VALUES ($1, $2, $3, $4, $5, $6::date + $7::int)`,
+              [wsId, draft, conn, `pub-${tag}-${i}`, `r-${tag}-${i}`, currentMonth, i],
+            );
+          }
+          // One scheduled publication (draft_id is UNIQUE there) carrying
+          // three attempts on the same draft: attempt_no 1..3.
+          const schedule = (await c.query(
+            `INSERT INTO scheduled_publications (workspace_id, draft_id, connection_id, publish_at, idempotency_key)
+             VALUES ($1, $2, (SELECT id FROM connections WHERE workspace_id = $1 LIMIT 1), $3::date, $4) RETURNING id`,
+            [wsId, drafts[0]!, currentMonth, `sch-${tag}`],
+          )).rows[0].id as string;
+          const credential = (await c.query(
+            "INSERT INTO credentials (workspace_id, kind, ciphertext) VALUES ($1, 'test', gen_random_bytes(16)) RETURNING id",
+            [wsId],
+          )).rows[0].id as string;
+          for (const n of [1, 2, 3]) {
+            await c.query(
+              `INSERT INTO publishing_attempts
+                 (workspace_id, schedule_id, draft_id, connection_id, attempt_no, idempotency_key, schedule_generation,
+                  post_snapshot, post_hash, scheduled_by_user_id, required_permission, approved_revision,
+                  reviewer_user_id, credential_id, credential_generation, authorized_epoch, status)
+               VALUES ($1, $2, $3, (SELECT id FROM connections WHERE workspace_id = $1 LIMIT 1), $4, $5, 1,
+                       '{}'::jsonb, $6, $7, 'publication.publish', 1, $7, $8, 1, 0, $9)`,
+              [wsId, schedule, drafts[0]!, n, `att-${tag}-${n}`, `hash-${tag}-${n}`, user, credential, n === 3 ? "completed" : "failed"],
+            );
+          }
+          // Archived feed items: `archivedCount` in the current month, one in
+          // the previous month, one in the far past (outside both windows).
+          // remote_ref must equal channel_id || ':' || message_id.
+          // remote_ref must match (@handle|numeric):message_id AND equal
+          // channel_id || ':' || message_id; content_hash is sha256 hex (64).
+          for (let i = 0; i < archivedCount; i += 1) {
+            await c.query(
+              `INSERT INTO archived_feed_items (workspace_id, remote_ref, channel_id, message_id, content_hash, posted_at)
+               VALUES ($1, '@ch' || $2::text || ':' || $3::bigint::text, '@ch' || $2::text, $3::bigint,
+                       encode(sha256($4::bytea), 'hex'), $5::date + ($6::int * interval '1 hour'))`,
+              [wsId, wsId.replace(/-/g, "").slice(0, 9), 1000 + i, `${tag}-${i}`, currentMonth, i],
+            );
+          }
+          await c.query(
+            `INSERT INTO archived_feed_items (workspace_id, remote_ref, channel_id, message_id, content_hash, posted_at)
+             VALUES ($1, '@ch' || $2::text || ':9001', '@ch' || $2::text, 9001,
+                     encode(sha256($3::bytea), 'hex'), $4::date)`,
+            [wsId, wsId.replace(/-/g, "").slice(0, 9), `${tag}-prev`, previousMonth],
+          );
+          await c.query(
+            `INSERT INTO archived_feed_items (workspace_id, remote_ref, channel_id, message_id, content_hash, posted_at)
+             VALUES ($1, '@ch' || $2::text || ':9002', '@ch' || $2::text, 9002,
+                     encode(sha256($3::bytea), 'hex'), '2020-01-01')`,
+            [wsId, wsId.replace(/-/g, "").slice(0, 9), `${tag}-old`],
+          );
+        });
+      };
+
+      await seed(wsA, 5);
+      await seed(wsB, 10);
+    });
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE id = ANY($1::uuid[])", [[wsA, wsB]]);
+        await c.query("DELETE FROM users WHERE external_id LIKE $1", [`analytics:%:${suffix}`]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  it("computes per-workspace monthly metrics from fixtures (set-based, no row loops)", async () => {
+    const service = new m.service.SnapshotService();
+    const a = await service.refresh(wsA, currentMonth);
+    expect(a.month).toBe(currentMonth.slice(0, 7));
+    expect(a.publicationsTotal).toBe(3);
+    expect(a.publicationsByProvider).toEqual({ mastodon: 2, bluesky: 1 });
+    expect(a.postsArchivedTotal).toBe(5);
+    expect(a.activeConnections).toBe(3);
+    expect(a.draftsCreatedTotal).toBe(3);
+    expect(a.publishingAttemptsTotal).toBe(3);
+    expect(a.publishFailuresTotal).toBe(2);
+
+    const b = await service.refresh(wsB, currentMonth);
+    expect(b.postsArchivedTotal).toBe(10);
+    expect(b.activeConnections).toBe(3);
+    // Disconnect wsB's connections as sp_app so RLS scopes the update to wsB
+    // (the owner pool is a superuser and bypasses RLS entirely).
+    await m.db.withTenant(wsB, (client) => client.query("UPDATE connections SET disconnected_at = now()"));
+    const bAfter = await service.refresh(wsB, currentMonth);
+    expect(bAfter.activeConnections).toBe(0);
+  });
+
+  it("is idempotent: running twice leaves exactly one row, same id and metrics", async () => {
+    const service = new m.service.SnapshotService();
+    const first = await service.refresh(wsA, currentMonth);
+    const second = await service.refresh(wsA, currentMonth);
+    expect(second.id).toBe(first.id);
+    // Metrics are identical; only the snapshot timestamps move.
+    const stripTimes = (r: typeof first): Record<string, unknown> => {
+      const { snapshotStartedAt, snapshotCompletedAt, ...metrics } = r;
+      void snapshotStartedAt; void snapshotCompletedAt;
+      return metrics;
+    };
+    expect(stripTimes(second)).toEqual(stripTimes(first));
+    expect(second.snapshotCompletedAt >= first.snapshotCompletedAt).toBe(true);
+    // Count through the app pool so FORCE RLS scopes the check to wsA (the
+    // owner pool is a superuser and would see every workspace's rows).
+    const rows = await m.db
+      .withTenant(wsA, (client) => client.query("SELECT id, publications_total FROM analytics_snapshots WHERE month = $1::date", [currentMonth]))
+      .then((r) => r.rows);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ id: first.id, publications_total: "3" });
+  });
+
+  it("partition pruning: a single-month predicate plans a scan of exactly one leaf", async () => {
+    // Plan-time pruning needs a literal (a $n param defers pruning to run
+    // time); the value is a validated YYYY-MM-01 so inlining is safe.
+    if (!/^\d{4}-\d{2}-01$/.test(currentMonth)) throw new Error("bad month literal");
+    const plan = await asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [wsA]);
+      const explained = await c.query<{ "QUERY PLAN": string }>(
+        `EXPLAIN (COSTS OFF) SELECT count(*) FROM analytics_snapshots WHERE month = DATE '${currentMonth}'`,
+      );
+      await c.query("COMMIT");
+      return explained.rows.map((r) => r["QUERY PLAN"]).join("\n");
+    });
+    const scanned = [...plan.matchAll(/Scan on (analytics_snapshots\S*)/g)].map((match) => match[1]!);
+    expect(scanned.filter((r) => /^analytics_snapshots_[0-9]{6}$/.test(r)).length).toBe(1);
+    for (const relation of scanned) expect(relation).not.toContain("default");
+  });
+
+  it("cross-tenant denial: RLS hides other workspaces' snapshots (parent and every leaf)", async () => {
+    const service = new m.service.SnapshotService();
+    await service.refresh(wsB, currentMonth);
+    const aList = await service.list(wsA, { limit: 24 });
+    expect(aList.items.length).toBeGreaterThan(0);
+    expect(aList.items.every((item) => item.workspaceId === wsA)).toBe(true);
+
+    // A raw read as the runtime role under B's context sees only B's rows.
+    const leaked = await m.db.withTenant(wsB, async (client) =>
+      client.query("SELECT workspace_id FROM analytics_snapshots"));
+    expect(leaked.rows.length).toBeGreaterThan(0);
+    expect(new Set(leaked.rows.map((r) => r.workspace_id))).toEqual(new Set([wsB]));
+
+    // Direct leaf access (parent RLS does not cascade to leaves): zero of
+    // A's rows visible from B's context in every partition.
+    const partitions = await asOwner((c) =>
+      c.query<{ relname: string }>(
+        "SELECT c.relname FROM pg_inherits i JOIN pg_class c ON c.oid = i.inhrelid WHERE i.inhparent = 'analytics_snapshots'::regclass",
+      ));
+    expect(partitions.rows.length).toBeGreaterThan(0);
+    for (const row of partitions.rows) {
+      if (!/^analytics_snapshots_(default|[0-9]{6})$/.test(row.relname)) throw new Error(`unexpected partition ${row.relname}`);
+      const seen = await m.db.withTenant(wsB, (client) => client.query(`SELECT workspace_id FROM ${row.relname}`));
+      expect(seen.rows.every((r) => r.workspace_id === wsB)).toBe(true);
+    }
+
+    // And a write attempt for another workspace is refused by WITH CHECK.
+    await expect(
+      m.db.withTenant(wsA, async (client) =>
+        client.query(
+          `INSERT INTO analytics_snapshots (workspace_id, month) VALUES ($1::uuid, DATE '${currentMonth}')`,
+          [wsB],
+        )),
+    ).rejects.toThrow(/row-level security/i);
+  });
+
+  it("keyset pagination: newest first, cursor continues without overlap", async () => {
+    const service = new m.service.SnapshotService();
+    await service.refresh(wsA, previousMonth);
+    const page1 = await service.list(wsA, { limit: 1 });
+    expect(page1.items.map((i) => i.month)).toEqual([currentMonth.slice(0, 7)]);
+    expect(page1.nextCursor).not.toBeNull();
+    const page2 = await service.list(wsA, { cursor: page1.nextCursor!, limit: 1 });
+    expect(page2.items.map((i) => i.month)).toEqual([previousMonth.slice(0, 7)]);
+    expect(page2.nextCursor).toBeNull();
+    await expect(service.list(wsA, { cursor: "!!!not-a-cursor" })).rejects.toMatchObject({ status: 400 });
+  });
+
+  it("summary: current month + previous month with correct deltas", async () => {
+    const service = new m.service.SnapshotService();
+    await service.refresh(wsB, previousMonth);
+    const summary = await service.summary(wsB);
+    expect(summary.currentMonth).toBe(currentMonth.slice(0, 7));
+    expect(summary.previousMonth).toBe(previousMonth.slice(0, 7));
+    expect(summary.previous).not.toBeNull();
+    // previous month: only the one archived item; connections already
+    // disconnected when that snapshot was taken.
+    expect(summary.previous!.postsArchivedTotal).toBe(1);
+    expect(summary.previous!.publicationsTotal).toBe(0);
+    expect(summary.current!.postsArchivedTotal).toBe(10);
+    expect(summary.deltas).toMatchObject({
+      publicationsTotal: 3,
+      postsArchivedTotal: 9,
+      activeConnections: 0,
+      publishFailuresTotal: 2,
+    });
+  });
+
+  it("invalid month input is rejected before any query", async () => {
+    await expect(m.service.writeMonthlySnapshot({} as never, "2025-13")).rejects.toMatchObject({ status: 400 });
+    await expect(new m.service.SnapshotService().refresh(wsA, "2025-1")).rejects.toMatchObject({ status: 400 });
+  });
+
+  it("controller + RBAC guard chain: analytics.view required, wrong-workspace token is refused", async () => {
+    const controller = new m.controller.AnalyticsController(new m.service.SnapshotService());
+    const user = (await asOwner((c) => c.query<{ id: string }>("SELECT id FROM users WHERE external_id = $1", [`analytics:owner:${suffix}`]))).rows[0]!.id;
+
+    // Permission gate: a role without analytics.view is forbidden by the
+    // guard. The guard resolves the role from the MEMBERSHIP, not the token,
+    // so an Editor member of wsA is the honest deny-path fixture.
+    const editor = (await asOwner(async (c) => {
+      const id = (await c.query(
+        "INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4) RETURNING id",
+        [`analytics:editor:${suffix}`, `analytics-editor-${suffix}`, `editor-${suffix}@example.com`, "editor"],
+      )).rows[0].id as string;
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [wsA]);
+      await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Editor')", [wsA, id]);
+      await c.query("COMMIT");
+      return id;
+    }));
+    // The membership insert above bumps authz_epoch (continuous authz), so
+    // tokens are minted AFTER it — mirroring a fresh login per epoch.
+    const epochNow = await asOwner(async (c) =>
+      Number((await c.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [wsA])).rows[0]?.authz_epoch));
+    const token = (userId: string, workspaceId: string, role: string): string =>
+      m.session.issueSession({ userId, workspaceId, role, authzEpoch: epochNow });
+    const request = (t: string): { headers: Record<string, string>; session?: unknown } => ({
+      headers: { authorization: `Bearer ${t}` },
+      // In production RbacGuard.canActivate attaches this before the
+      // controller runs; do the same here after verifying the token.
+      session: m.session.verifySession(t) ?? undefined,
+    });
+
+    // Owner of wsA refreshes wsA's snapshot through the real controller.
+    const refreshed = await controller.snapshot(request(token(user, wsA, "Owner")) as never, {});
+    expect(refreshed.workspaceId).toBe(wsA);
+    expect(refreshed.publicationsTotal).toBe(3);
+
+    // A valid token for wsB does not leak wsA: wsB's refresh writes wsB's row.
+    const forB = await controller.snapshot(request(token(user, wsB, "Owner")) as never, {});
+    expect(forB.workspaceId).toBe(wsB);
+
+    const { Reflector } = await import("@nestjs/core");
+    const guard = new m.guard.RbacGuard(new Reflector());
+    const handler = (): void => undefined;
+    Reflect.defineMetadata(m.guard.PERMISSION_KEY, "analytics.view", handler);
+    const ctx = {
+      getHandler: () => handler,
+      switchToHttp: () => ({ getRequest: () => ({ headers: { authorization: `Bearer ${token(editor, wsA, "Editor")}` }, params: {} }) }),
+    } as unknown as import("@nestjs/common").ExecutionContext;
+    await expect(guard.canActivate(ctx)).rejects.toMatchObject({ status: 403 });
+    // ...while the Owner's token passes the same gate.
+    const ownerCtx = {
+      getHandler: () => handler,
+      switchToHttp: () => ({ getRequest: () => ({ headers: { authorization: `Bearer ${token(user, wsA, "Owner")}` }, params: {} }) }),
+    } as unknown as import("@nestjs/common").ExecutionContext;
+    await expect(guard.canActivate(ownerCtx)).resolves.toBe(true);
+  });
+});
diff --git a/apps/api/src/analytics/snapshot.service.ts b/apps/api/src/analytics/snapshot.service.ts
new file mode 100644
index 0000000..d63d58a
--- /dev/null
+++ b/apps/api/src/analytics/snapshot.service.ts
@@ -0,0 +1,309 @@
+import { BadRequestException, Injectable, NotFoundException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+
+/**
+ * WP3 analytics snapshots: one rollup row per (workspace, month), recomputed
+ * from source tables with set-based SQL (no row loops) and upserted so a
+ * re-run is idempotent. Partitioned by month (020_analytics.sql).
+ *
+ * Exported as plain functions so the scheduler can call them later without
+ * going through Nest:
+ *   import { writeMonthlySnapshot } from "./snapshot.service.js";
+ *   await withTenant(workspaceId, (client) => writeMonthlySnapshot(client, month));
+ */
+
+/**
+ * Month keys are accepted as `YYYY-MM` (API form) or `YYYY-MM-DD` where the
+ * day is 01 (the partition-key form used internally). Both denote the same
+ * month; anything else is a 400.
+ */
+export const MONTH_PATTERN = /^\d{4}-(0[1-9]|1[0-2])(-01)?$/;
+
+export function parseMonth(value: string, field = "month"): string {
+  if (!MONTH_PATTERN.test(value)) throw new BadRequestException(`${field} must be YYYY-MM`);
+  return value;
+}
+
+/** First day (UTC) of the month containing `at`, as `YYYY-MM-DD`. */
+export function monthStart(at: Date = new Date()): string {
+  return at.toISOString().slice(0, 7) + "-01";
+}
+
+export interface SnapshotMetrics {
+  publicationsTotal: number;
+  publicationsByProvider: Record<string, number>;
+  postsArchivedTotal: number;
+  activeConnections: number;
+  draftsCreatedTotal: number;
+  publishingAttemptsTotal: number;
+  publishFailuresTotal: number;
+}
+
+export interface SnapshotRecord extends SnapshotMetrics {
+  id: string;
+  workspaceId: string;
+  month: string;
+  snapshotStartedAt: string;
+  snapshotCompletedAt: string;
+}
+
+interface MetricsRow {
+  publications_total: string;
+  publications_by_provider: Record<string, number>;
+  posts_archived_total: string;
+  active_connections: number;
+  drafts_created_total: string;
+  publishing_attempts_total: string;
+  publish_failures_total: string;
+}
+
+interface SnapshotRow {
+  id: string;
+  workspace_id: string;
+  month: string | Date; // pg returns `date` as a UTC Date
+  publications_total: string;
+  publications_by_provider: Record<string, number>;
+  posts_archived_total: string;
+  active_connections: number;
+  drafts_created_total: string;
+  publishing_attempts_total: string;
+  publish_failures_total: string;
+  snapshot_started_at: Date;
+  snapshot_completed_at: Date;
+}
+
+/**
+ * Set-based metric computation for one (workspace, month), run inside a tenant
+ * transaction. Every source table is scanned once (the failure count is
+ * derived from the attempts pass, not a second scan). Must run inside RLS
+ * tenant context opened by the caller — no workspace_id literal is ever
+ * embedded in the SQL.
+ */
+export async function computeMonthlyMetrics(client: PoolClient, month: string): Promise<MetricsRow> {
+  const result = await client.query<MetricsRow>(
+    `SELECT
+       pub.publications_total,
+       COALESCE(pub.by_provider, '{}'::jsonb) AS publications_by_provider,
+       arch.posts_archived_total,
+       conn.active_connections,
+       dr.drafts_created_total,
+       att.publishing_attempts_total,
+       COALESCE(att.failed_total, 0) AS publish_failures_total
+     FROM (SELECT 1) AS anchor
+     LEFT JOIN LATERAL (
+       -- one row per provider, so the total is SUM(n) — count(*) here would
+       -- count provider groups, not publications.
+       SELECT COALESCE(sum(c.n), 0)::bigint AS publications_total,
+              COALESCE(jsonb_object_agg(c.provider, c.n) FILTER (WHERE c.provider IS NOT NULL), '{}'::jsonb) AS by_provider
+       FROM (
+         SELECT c.provider, count(*)::bigint AS n
+         FROM publications p
+         JOIN connections c ON c.id = p.connection_id
+         WHERE p.published_at >= $1::date
+           AND p.published_at < $1::date + interval '1 month'
+         GROUP BY c.provider
+       ) c
+     ) pub ON true
+     LEFT JOIN LATERAL (
+       SELECT count(*)::bigint AS posts_archived_total
+       FROM archived_feed_items a
+       WHERE a.posted_at >= $1::date
+         AND a.posted_at < $1::date + interval '1 month'
+     ) arch ON true
+     LEFT JOIN LATERAL (
+       SELECT count(*)::int AS active_connections
+       FROM connections c
+       WHERE c.disconnected_at IS NULL
+     ) conn ON true
+     LEFT JOIN LATERAL (
+       SELECT count(*)::bigint AS drafts_created_total
+       FROM drafts d
+       WHERE d.created_at >= $1::date
+         AND d.created_at < $1::date + interval '1 month'
+     ) dr ON true
+     LEFT JOIN LATERAL (
+       SELECT count(*)::bigint AS publishing_attempts_total,
+              count(*) FILTER (WHERE a.status = 'failed')::bigint AS failed_total
+       FROM publishing_attempts a
+       WHERE a.created_at >= $1::date
+         AND a.created_at < $1::date + interval '1 month'
+     ) att ON true`,
+    [month],
+  );
+  return result.rows[0]!;
+}
+
+/**
+ * Idempotent refresh of one workspace's snapshot for one month: INSERT on
+ * first run, UPDATE in place (same row id) on every re-run. Returns the
+ * persisted row. Runs under RLS, so a wrong workspace context simply yields
+ * no row (surfaced as 404 by the controller).
+ */
+export async function writeMonthlySnapshot(client: PoolClient, month: string): Promise<SnapshotRow> {
+  // Normalize YYYY-MM / YYYY-MM-01 to the partition-key form.
+  const normalized = `${parseMonth(month).slice(0, 7)}-01`;
+  const metrics = await computeMonthlyMetrics(client, normalized);
+  const result = await client.query<SnapshotRow>(
+    `INSERT INTO analytics_snapshots
+       (workspace_id, month, publications_total, publications_by_provider,
+        posts_archived_total, active_connections, drafts_created_total,
+        publishing_attempts_total, publish_failures_total,
+        snapshot_started_at, snapshot_completed_at)
+     VALUES (NULLIF(current_setting('app.workspace_id', true), '')::uuid, $1::date,
+             $2, $3::jsonb, $4, $5, $6, $7, $8, clock_timestamp(), clock_timestamp())
+     ON CONFLICT (workspace_id, month) DO UPDATE SET
+       publications_total = EXCLUDED.publications_total,
+       publications_by_provider = EXCLUDED.publications_by_provider,
+       posts_archived_total = EXCLUDED.posts_archived_total,
+       active_connections = EXCLUDED.active_connections,
+       drafts_created_total = EXCLUDED.drafts_created_total,
+       publishing_attempts_total = EXCLUDED.publishing_attempts_total,
+       publish_failures_total = EXCLUDED.publish_failures_total,
+       snapshot_started_at = EXCLUDED.snapshot_started_at,
+       snapshot_completed_at = EXCLUDED.snapshot_completed_at
+     RETURNING *`,
+    [
+      normalized,
+      metrics.publications_total,
+      JSON.stringify(metrics.publications_by_provider),
+      metrics.posts_archived_total,
+      metrics.active_connections,
+      metrics.drafts_created_total,
+      metrics.publishing_attempts_total,
+      metrics.publish_failures_total,
+    ],
+  );
+  if (result.rows[0] === undefined) throw new NotFoundException("workspace not found for snapshot");
+  return result.rows[0];
+}
+
+/** `pg` returns `date` columns as JS Dates (UTC midnight) — normalize to `YYYY-MM`. */
+function monthKey(value: string | Date): string {
+  return (typeof value === "string" ? value : value.toISOString().slice(0, 10)).slice(0, 7);
+}
+
+function recordFromRow(row: SnapshotRow): SnapshotRecord {
+  return {
+    id: row.id,
+    workspaceId: row.workspace_id,
+    month: monthKey(row.month),
+    publicationsTotal: Number(row.publications_total),
+    publicationsByProvider: row.publications_by_provider,
+    postsArchivedTotal: Number(row.posts_archived_total),
+    activeConnections: row.active_connections,
+    draftsCreatedTotal: Number(row.drafts_created_total),
+    publishingAttemptsTotal: Number(row.publishing_attempts_total),
+    publishFailuresTotal: Number(row.publish_failures_total),
+    snapshotStartedAt: row.snapshot_started_at.toISOString(),
+    snapshotCompletedAt: row.snapshot_completed_at.toISOString(),
+  };
+}
+
+/** Month keyset cursor: the last emitted month, opaque base64url. */
+function encodeCursor(month: string): string {
+  return Buffer.from(JSON.stringify({ m: month }), "utf8").toString("base64url");
+}
+
+function decodeCursor(cursor: string): string {
+  try {
+    const value: unknown = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+    const month = (value as { m?: unknown } | null)?.m;
+    if (typeof month !== "string") throw new Error("shape");
+    return `${parseMonth(month, "cursor").slice(0, 7)}-01`;
+  } catch {
+    throw new BadRequestException("invalid cursor");
+  }
+}
+
+@Injectable()
+export class SnapshotService {
+  /** Refresh a month's snapshot for the caller's workspace (admin/owner gated at the controller). */
+  async refresh(workspaceId: string, month: string): Promise<SnapshotRecord> {
+    return withTenant(workspaceId, async (client) => recordFromRow(await writeMonthlySnapshot(client, month)));
+  }
+
+  /** Keyset page over months, newest first. Cursor = last emitted month. */
+  async list(
+    workspaceId: string,
+    options: { cursor?: string; limit?: number } = {},
+  ): Promise<{ items: SnapshotRecord[]; nextCursor: string | null }> {
+    const cursor = options.cursor === undefined ? null : decodeCursor(options.cursor);
+    const limit = Math.min(Math.max(options.limit ?? 12, 1), 24);
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query<SnapshotRow>(
+        `SELECT * FROM analytics_snapshots
+         WHERE ($1::date IS NULL OR month < $1::date)
+         ORDER BY month DESC
+         LIMIT $2`,
+        [cursor, limit + 1],
+      );
+      const rows = result.rows.slice(0, limit);
+      const last = rows.at(-1);
+      return {
+        items: rows.map(recordFromRow),
+        nextCursor: result.rows.length > limit && last !== undefined ? encodeCursor(monthKey(last.month)) : null,
+      };
+    });
+  }
+
+  /** Current month vs previous month with deltas (missing months are null). */
+  async summary(workspaceId: string): Promise<{
+    currentMonth: string;
+    previousMonth: string;
+    current: SnapshotRecord | null;
+    previous: SnapshotRecord | null;
+    deltas: Record<keyof SnapshotMetrics, number | Record<string, number>> | null;
+  }> {
+    const month = monthStart();
+    const previous = previousMonthStart(month);
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query<SnapshotRow>(
+        `SELECT * FROM analytics_snapshots
+         WHERE month IN ($1::date, ($1::date - interval '1 month')::date)`,
+        [month],
+      );
+      const byMonth = new Map(result.rows.map((row) => [monthKey(row.month), recordFromRow(row)]));
+      const current = byMonth.get(month.slice(0, 7)) ?? null;
+      const previousRecord = byMonth.get(previous.slice(0, 7)) ?? null;
+      return {
+        currentMonth: month.slice(0, 7),
+        previousMonth: previous.slice(0, 7),
+        current,
+        previous: previousRecord,
+        deltas: current !== null && previousRecord !== null ? monthDeltas(previousRecord, current) : null,
+      };
+    });
+  }
+}
+
+/** `YYYY-MM(-01)` of the month before `month`, same form as the input. */
+function previousMonthStart(month: string): string {
+  const date = new Date(`${month.slice(0, 7)}-01T00:00:00Z`);
+  date.setUTCMonth(date.getUTCMonth() - 1);
+  const key = date.toISOString().slice(0, 7);
+  return month.length === 7 ? key : `${key}-01`;
+}
+
+/** Delta math for the summary endpoint (pure, unit-testable). */
+export function monthDeltas(
+  previous: SnapshotMetrics,
+  current: SnapshotMetrics,
+): Record<keyof SnapshotMetrics, number | Record<string, number>> {
+  const prevProviders = previous.publicationsByProvider;
+  const curProviders = current.publicationsByProvider;
+  const providers = new Set([...Object.keys(prevProviders), ...Object.keys(curProviders)]);
+  const providerDeltas: Record<string, number> = {};
+  for (const provider of providers) {
+    providerDeltas[provider] = (curProviders[provider] ?? 0) - (prevProviders[provider] ?? 0);
+  }
+  return {
+    publicationsTotal: current.publicationsTotal - previous.publicationsTotal,
+    publicationsByProvider: providerDeltas,
+    postsArchivedTotal: current.postsArchivedTotal - previous.postsArchivedTotal,
+    activeConnections: current.activeConnections - previous.activeConnections,
+    draftsCreatedTotal: current.draftsCreatedTotal - previous.draftsCreatedTotal,
+    publishingAttemptsTotal: current.publishingAttemptsTotal - previous.publishingAttemptsTotal,
+    publishFailuresTotal: current.publishFailuresTotal - previous.publishFailuresTotal,
+  };
+}
diff --git a/apps/api/src/analytics/snapshot.test.ts b/apps/api/src/analytics/snapshot.test.ts
new file mode 100644
index 0000000..2ab5d7d
--- /dev/null
+++ b/apps/api/src/analytics/snapshot.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { MONTH_PATTERN, monthDeltas, monthStart, parseMonth } from "./snapshot.service.js";
+
+describe("analytics snapshot pure helpers", () => {
+  it("monthStart returns the UTC month start", () => {
+    expect(monthStart(new Date("2025-07-14T23:59:59.999Z"))).toBe("2025-07-01");
+    expect(monthStart(new Date("2024-02-29T00:00:00Z"))).toBe("2024-02-01");
+  });
+
+  it("parseMonth accepts YYYY-MM and month-start YYYY-MM-01, rejects everything else", () => {
+    expect(parseMonth("2025-01")).toBe("2025-01");
+    expect(parseMonth("2025-01-01")).toBe("2025-01-01");
+    expect(() => parseMonth("2025-13")).toThrow();
+    expect(() => parseMonth("2025-1")).toThrow();
+    expect(() => parseMonth("25-01")).toThrow();
+    expect(() => parseMonth("2025-01-02")).toThrow();
+    expect(MONTH_PATTERN.test("2025-12")).toBe(true);
+    expect(MONTH_PATTERN.test("2025-00")).toBe(false);
+  });
+
+  it("monthDeltas computes per-metric and per-provider deltas vs fixtures", () => {
+    const previous = {
+      publicationsTotal: 10,
+      publicationsByProvider: { mastodon: 4, bluesky: 6 },
+      postsArchivedTotal: 100,
+      activeConnections: 3,
+      draftsCreatedTotal: 20,
+      publishingAttemptsTotal: 12,
+      publishFailuresTotal: 2,
+    };
+    const current = {
+      publicationsTotal: 13,
+      publicationsByProvider: { mastodon: 4, bluesky: 7, reddit: 2 },
+      postsArchivedTotal: 90,
+      activeConnections: 4,
+      draftsCreatedTotal: 20,
+      publishingAttemptsTotal: 15,
+      publishFailuresTotal: 1,
+    };
+    expect(monthDeltas(previous, current)).toEqual({
+      publicationsTotal: 3,
+      publicationsByProvider: { mastodon: 0, bluesky: 1, reddit: 2 },
+      postsArchivedTotal: -10,
+      activeConnections: 1,
+      draftsCreatedTotal: 0,
+      publishingAttemptsTotal: 3,
+      publishFailuresTotal: -1,
+    });
+  });
+
+  it("monthDeltas covers providers that vanished this month", () => {
+    const deltas = monthDeltas(
+      { publicationsTotal: 5, publicationsByProvider: { mastodon: 5 }, postsArchivedTotal: 0, activeConnections: 0, draftsCreatedTotal: 0, publishingAttemptsTotal: 0, publishFailuresTotal: 0 },
+      { publicationsTotal: 1, publicationsByProvider: { bluesky: 1 }, postsArchivedTotal: 0, activeConnections: 0, draftsCreatedTotal: 0, publishingAttemptsTotal: 0, publishFailuresTotal: 0 },
+    );
+    expect(deltas.publicationsByProvider).toEqual({ mastodon: -5, bluesky: 1 });
+    expect(deltas.publicationsTotal).toBe(-4);
+  });
+});
diff --git a/apps/api/src/app.module.ts b/apps/api/src/app.module.ts
new file mode 100644
index 0000000..fe8a937
--- /dev/null
+++ b/apps/api/src/app.module.ts
@@ -0,0 +1,61 @@
+import { Module } from "@nestjs/common";
+import { HealthModule } from "./health/health.module";
+import { DemoController } from "./demo/demo.controller";
+import { PublishingController } from "./publishing/publishing.controller";
+import { pool, withTenant } from "./db/client";
+import { PublishingExecutionRepository, assertPublishingSchema } from "@tactical-media-broadcast-hub/publishing-execution";
+import { ApprovalGateService } from "./publishing/approval-gate.service.js";
+import { PUBLISHING_DEPENDENCIES, TemporalWorkflowStarter, PublishingService } from "./publishing/publishing.service";
+import { AuthController } from "./auth/auth.controller";
+import { AuthService } from "./auth/auth.service";
+import { ConnectionsController } from "./connections/connections.controller";
+import { ConnectionsService } from "./connections/connections.service";
+import { TeamController } from "./team/team.controller";
+import { TeamService } from "./team/team.service";
+import { InviteLinkController, InviteClaimController } from "./team/invite-link.controller";
+import { InviteLinkService } from "./team/invite-link.service";
+import { AuditController } from "./audit/audit.controller";
+import { AuditQueryService } from "./audit/audit.query";
+import { GroupsController } from "./groups/groups.controller";
+import { GroupsService } from "./groups/groups.service";
+import { VideoController } from "./video/video.controller";
+import { VideoService } from "./video/video.service";
+import { LiveMonitorModule } from "./live-monitor/live-monitor.module";
+import { MediaControlModule } from "./media-control/media-control.module";
+import { ProductionModule } from "./production/production.module";
+import { RealtimeModule } from "./realtime/realtime.module";
+import { LiveChatModule } from "./live-chat/live-chat.module";
+import { LiveModule } from "./live/live.module.js";
+import { ChatgovModule } from "./chatgov/chatgov.module.js";
+import { IntakeModule } from "./intake/intake.module.js";
+import { SettingsModule } from "./settings/settings.module.js";
+import { SettingsController } from "./settings/settings.controller.js";
+import { SettingsService } from "./settings/settings.service.js";
+import { VirtualChannelsModule } from "./virtual-channels/virtual-channels.module.js";
+import { DirectorModule } from "./director/director.module.js";
+import { AnalyticsController } from "./analytics/analytics.controller";
+import { SnapshotService } from "./analytics/snapshot.service";
+
+@Module({
+  imports: [HealthModule, LiveMonitorModule, MediaControlModule, ProductionModule, RealtimeModule, LiveChatModule, LiveModule, VirtualChannelsModule, ChatgovModule, IntakeModule, SettingsModule],
+  controllers: [
+    DemoController,
+    PublishingController,
+    AuthController,
+    ConnectionsController,
+    TeamController,
+    InviteLinkController,
+    InviteClaimController,
+    AuditController,
+    VideoController,
+    GroupsController,
+    AnalyticsController,
+    SettingsController,
+  ],
+  providers: [
+    { provide: PublishingExecutionRepository, useFactory: () => new PublishingExecutionRepository(pool) },
+    TemporalWorkflowStarter,
+    { provide: PUBLISHING_DEPENDENCIES, inject: [PublishingExecutionRepository, TemporalWorkflowStarter, ApprovalGateService], useFactory: (repository: PublishingExecutionRepository, workflowStarter: TemporalWorkflowStarter, approvalGate: ApprovalGateService) => ({ repository, workflowStarter, approvalGate, tenantTransaction: withTenant, assertReady: () => assertPublishingSchema(pool) }) },
+    PublishingService, ApprovalGateService, AuthService, ConnectionsService, TeamService, InviteLinkService, AuditQueryService, VideoService, GroupsService, SnapshotService, SettingsService],
+})
+export class AppModule {}
diff --git a/apps/api/src/archive/archive-search.integration.test.ts b/apps/api/src/archive/archive-search.integration.test.ts
new file mode 100644
index 0000000..2971900
--- /dev/null
+++ b/apps/api/src/archive/archive-search.integration.test.ts
@@ -0,0 +1,256 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * WP15 archive search + export against a live PostgreSQL, as sp_app (FORCE
+ * RLS binds). Uses its OWN database (ARCHIVE_SEARCH_IT_DATABASE_URL, plus
+ * ARCHIVE_SEARCH_IT_SUPER_DATABASE_URL for migrations/seeding) per the
+ * local-db-sol pattern: tenancy.integration.test.ts wipes every workspace in
+ * the shared DB and vitest runs files in parallel. Skipped when unset.
+ */
+const appUrl = process.env.ARCHIVE_SEARCH_IT_DATABASE_URL;
+const ownerUrl = process.env.ARCHIVE_SEARCH_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  service: typeof import("./archive.service.js");
+  "search-helpers": typeof import("./archive-search.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("archive search + export (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let wsA: string;
+  let wsB: string;
+  let chA = "";
+  const chB = `@chB${suffix}`;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  /** Seed tenant rows honestly: FORCE RLS applies to the owner too. */
+  async function inTenant(client: PoolClient, wsId: string, fn: () => Promise<void>): Promise<void> {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [wsId]);
+    await fn();
+    await client.query("COMMIT");
+  }
+
+  let seedSeq = 0;
+  /** remote_ref must equal channel_id || ':' || message_id; content_hash is sha256 hex. */
+  async function seedItem(client: PoolClient, wsId: string, item: {
+    channel: string; message: number; text: string; postedAt: Date; attribution?: Record<string, unknown>;
+  }): Promise<void> {
+    seedSeq += 1;
+    await client.query(
+      `INSERT INTO archived_feed_items
+         (workspace_id, remote_ref, channel_id, message_id, text_content, content_hash, posted_at, attribution)
+       VALUES ($1, $2 || ':' || $3::bigint::text, $2, $3::bigint, $4, encode(sha256($5::bytea), 'hex'), $6, $7::jsonb)`,
+      [wsId, item.channel, item.message, item.text, `seed-${suffix}-${seedSeq}`, item.postedAt,
+        JSON.stringify(item.attribution ?? {})],
+    );
+  }
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      service: await import("./archive.service.js"),
+      "search-helpers": await import("./archive-search.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    await asOwner(async (c) => {
+      const ws = async (name: string): Promise<string> =>
+        (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id",
+          [name, `${name}-${suffix}`])).rows[0].id as string;
+      wsA = await ws("search-a");
+      wsB = await ws("search-b");
+    });
+
+    // Tenant data: distinct texts per tenant, overlap only inside wsA.
+    chA = `@chA${suffix}`;
+    await asOwner((c) => inTenant(c, wsA, async () => {
+      await seedItem(c, wsA, {
+        channel: chA, message: 1001,
+        text: "Water rights are a community responsibility, not a commodity for markets.",
+        postedAt: new Date("2026-01-10T09:00:00Z"),
+        attribution: { channelUsername: chA.slice(1), author: "Water Working Group" },
+      });
+      await seedItem(c, wsA, {
+        channel: chA, message: 1002,
+        text: "Totally unrelated post about bicycle repair cooperatives and tools.",
+        postedAt: new Date("2026-01-11T09:00:00Z"),
+      });
+      await seedItem(c, wsA, {
+        channel: chA, message: 1003,
+        text: "Water rights update: the hearing is postponed to February.",
+        postedAt: new Date("2026-01-12T09:00:00Z"),
+      });
+    }));
+    await asOwner((c) => inTenant(c, wsB, async () => {
+      await seedItem(c, wsB, {
+        channel: chB, message: 2001,
+        text: "Water rights are a community responsibility, not a commodity for markets.",
+        postedAt: new Date("2026-01-05T09:00:00Z"),
+      });
+    }));
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE id = ANY($1::uuid[])", [[wsA, wsB]]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  it("full-text search matches archived text (websearch_to_tsquery)", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const result = await service.search(wsA, { q: "water rights" });
+    expect(result.items).toHaveLength(2);
+    for (const item of result.items) {
+      expect(String(item.text)).toMatch(/water/i);
+      expect(item.remoteRef).toBeDefined();
+    }
+    // Ranked path: both matches, the denser one first is NOT guaranteed, but
+    // the update (1003) must not shadow the older match.
+    expect(result.items.map((i) => i.messageId).sort()).toEqual([1001, 1003]);
+  });
+
+  it("fuzzy typo tolerance: misspelled token still matches via pg_trgm", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const result = await service.search(wsA, { q: "watter rghts" });
+    expect(result.items.length).toBeGreaterThanOrEqual(1);
+    expect(result.items.map((i) => i.messageId).sort()).toEqual([1001, 1003]);
+  });
+
+  it("metadata search: channel id and attribution text are searchable", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const byChannel = await service.search(wsA, { q: chA });
+    expect(byChannel.items).toHaveLength(3);
+    const byAuthor = await service.search(wsA, { q: "Working Group" });
+    expect(byAuthor.items.map((i) => i.messageId)).toEqual([1001]);
+  });
+
+  it("RLS: search never crosses tenants even with shared text", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const a = await service.search(wsA, { q: "water rights" });
+    const b = await service.search(wsB, { q: "water rights" });
+    expect(a.items).toHaveLength(2);
+    expect(b.items).toHaveLength(1);
+    expect(b.items.every((i) => String(i.remoteRef).startsWith(chB))).toBe(true);
+    // Direct DB-level cross-tenant denial as sp_app.
+    const leaked = await m.db.withTenant(wsB, (client) => client.query(
+      "SELECT count(*)::int AS n FROM archived_feed_items WHERE workspace_id = $1", [wsA]));
+    expect(leaked.rows[0]?.n).toBe(0);
+  });
+
+  it("date + channel filters narrow the result set", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const from = await service.search(wsA, { q: "water", from: "2026-01-12" });
+    expect(from.items.map((i) => i.messageId)).toEqual([1003]);
+    const to = await service.search(wsA, { q: "water", to: "2026-01-10T23:59:59Z" });
+    expect(to.items.map((i) => i.messageId)).toEqual([1001]);
+    const channel = await service.search(wsA, { q: "bicycle", channelId: chA });
+    expect(channel.items.map((i) => i.messageId)).toEqual([1002]);
+    const none = await service.search(wsA, { q: "bicycle", channelId: `@nonesuch${suffix}` });
+    expect(none.items).toHaveLength(0);
+  });
+
+  it("keyset pagination walks the ranked result set without repeats or gaps", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const page1 = await service.search(wsA, { q: "water rights", limit: "1" });
+    expect(page1.items).toHaveLength(1);
+    expect(page1.nextCursor).not.toBeNull();
+    const page2 = await service.search(wsA, { q: "water rights", limit: "1", cursor: page1.nextCursor ?? "" });
+    expect(page2.items).toHaveLength(1);
+    expect(page2.nextCursor).toBeNull();
+    const seen = [...page1.items, ...page2.items].map((i) => i.messageId).sort();
+    expect(seen).toEqual([1001, 1003]);
+    // Bogus cursor is rejected, not silently ignored.
+    await expect(service.search(wsA, { q: "water", cursor: "bogus-cursor" }))
+      .rejects.toThrow(/invalid cursor/);
+  });
+
+  it("export streams every matching item with faithful content (json + csv)", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const json: string[] = [];
+    const format = await service.exportItems(wsA, { q: "water rights" }, (chunk) => json.push(chunk));
+    expect(format).toBe("json");
+    const parsed = JSON.parse(json.join("")) as Array<Record<string, unknown>>;
+    expect(parsed).toHaveLength(2);
+    expect(parsed.map((i) => i.messageId).sort()).toEqual([1001, 1003]);
+    expect(parsed.every((i) => typeof i.postedAt === "string" && typeof i.remoteRef === "string")).toBe(true);
+
+    const csv: string[] = [];
+    const csvFormat = await service.exportItems(wsA, { q: "water", format: "csv" }, (chunk) => csv.push(chunk));
+    expect(csvFormat).toBe("csv");
+    const csvText = csv.join("");
+    const lines = csvText.split("\r\n").filter((line) => line !== "");
+    expect(lines).toHaveLength(3); // header + 2 rows
+    const header = lines[0]!.split(",");
+    expect(header.slice(0, 4)).toEqual(["id", "remote_ref", "channel_id", "message_id"]);
+    const rows = lines.slice(1).map((line) => line.split(","));
+    for (const row of rows) {
+      expect(row).toHaveLength(header.length);
+      expect(UUID_SHAPE.test(row[0]!)).toBe(true);
+      expect(row[1]).toMatch(new RegExp(`^${chA}:[0-9]+$`));
+    }
+    const textCol = header.indexOf("text");
+    const texts = rows.map((row) => row[textCol]!).sort();
+    expect(texts[1]).toContain("hearing is postponed");
+  });
+
+  it("export CSV escaping: commas, quotes and newlines round-trip", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    const hostile = 'He said "water, rights", then\nleft';
+    await asOwner((c) => inTenant(c, wsA, async () => {
+      await seedItem(c, wsA, {
+        channel: chA, message: 1004, text: hostile, postedAt: new Date("2026-01-13T09:00:00Z"),
+      });
+    }));
+    const csv: string[] = [];
+    await service.exportItems(wsA, { channelId: chA, format: "csv" }, (chunk) => csv.push(chunk));
+    const lines = csv.join("").split("\r\n").filter((l) => l !== "");
+    const header = lines[0]!.split(",");
+    const textCol = header.indexOf("text");
+    const rows = lines.slice(1).map((line) => line.split(","));
+    const hostileRow = rows.find((row) => row[textCol] === hostile);
+    expect(hostileRow).toBeDefined();
+    expect(hostileRow![textCol]).toBe(hostile);
+    expect(rows.every((row) => row.length === header.length)).toBe(true);
+  });
+
+  it("filter validation rejects garbage bounds, limits and formats", async () => {
+    const service = new m.service.ArchiveService(null as never);
+    await expect(service.search(wsA, { q: "water", from: "not-a-date" })).rejects.toThrow(/ISO-8601/);
+    await expect(service.search(wsA, { q: "water", from: "2026-02-01", to: "2026-01-01" })).rejects.toThrow(/after/);
+    await expect(service.search(wsA, { q: "water", limit: "0" })).rejects.toThrow(/between 1 and/);
+    await expect(service.search(wsA, { q: "water", limit: "1000" })).rejects.toThrow(/between 1 and/);
+    await expect(service.search(wsA, { q: "water", cursor: "bogus" })).rejects.toThrow(/invalid cursor/);
+    await expect(service.exportItems(wsA, { format: "xml" }, () => undefined)).rejects.toThrow(/csv or json/);
+  });
+
+  it("unindexed helper behavior: tokenization + CSV header shape", () => {
+    const helpers = m["search-helpers"];
+    expect(helpers.searchTokens("Watter, Rghts! @channel123")).toEqual(["watter", "rghts", "@channel123"]);
+    expect(helpers.searchTokens("ab xx ")).toEqual([]);
+    expect(helpers.ARCHIVE_CSV_HEADER).toMatch(/^id,remote_ref,channel_id,message_id,posted_at,revision,protected_content,text,storage_keys,attribution\r\n$/);
+  });
+});
+
+const UUID_SHAPE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
diff --git a/apps/api/src/archive/archive-search.ts b/apps/api/src/archive/archive-search.ts
new file mode 100644
index 0000000..0cda3e2
--- /dev/null
+++ b/apps/api/src/archive/archive-search.ts
@@ -0,0 +1,280 @@
+import { BadRequestException } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import type { StorageService } from "../storage/storage.js";
+import type { TelegramMedia } from "./normalizer.js";
+
+/**
+ * WP15 archive full-text search (Postgres FTS phase-1, firehose research
+ * recommendation). Every query runs through withTenant() so the
+ * archived_feed_items tenant_isolation RLS policy (migration 015, FORCE)
+ * binds — there is deliberately no system/superuser path here.
+ *
+ * Matching is `websearch_to_tsquery` lexical OR pg_trgm similarity per token,
+ * so a misspelled token still matches via trigram distance (typo tolerance).
+ * Ranking: FTS ts_rank dominates, trigram similarity breaks ties. Keyset
+ * pagination follows the house pattern: base64url JSON cursor, fetch N+1.
+ */
+
+export interface ArchiveSearchFilters {
+  q: string | null;
+  channelId: string | null;
+  from: string | null;
+  to: string | null;
+  cursor: string | undefined;
+  limit: number;
+}
+
+export const SEARCH_DEFAULT_LIMIT = 20;
+export const SEARCH_MAX_LIMIT = 100;
+export const ARCHIVE_EXPORT_MAX_ROWS = 50_000;
+const EXPORT_BATCH_SIZE = 500;
+
+export interface ArchiveItemRow {
+  id: string;
+  remote_ref: string;
+  channel_id: string;
+  message_id: string;
+  text_content: string;
+  media_refs: TelegramMedia[];
+  attribution: Record<string, unknown>;
+  protected_content: boolean;
+  posted_at: Date;
+  revision: number;
+  rank?: number;
+}
+
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+const UUID_SHAPE = /^[0-9a-f-]{36}$/i;
+
+function parseDateBound(value: unknown, field: string): string | null {
+  if (value === undefined || value === null || value === "") return null;
+  if (typeof value !== "string" || value.length > 32 || !ISO_TIMESTAMP.test(value)
+    || !Number.isFinite(Date.parse(value))) {
+    throw new BadRequestException(`${field} must be an ISO-8601 date or timestamp`);
+  }
+  return value;
+}
+
+/** Shared filter/cursor-shape parsing for GET /archive/search and GET /archive/export. */
+export function parseArchiveSearchQuery(query: Record<string, unknown>): ArchiveSearchFilters {
+  const rawQ = query.q;
+  const q = typeof rawQ === "string" && rawQ.trim() !== "" ? rawQ.trim() : null;
+  if (q !== null && q.length > 256) throw new BadRequestException("q must be at most 256 characters");
+  const rawChannel = query.channelId;
+  const channelId = typeof rawChannel === "string" && rawChannel.trim() !== "" ? rawChannel.trim() : null;
+  if (channelId !== null && channelId.length > 128) throw new BadRequestException("channelId is too long");
+  const from = parseDateBound(query.from, "from");
+  const to = parseDateBound(query.to, "to");
+  if (from !== null && to !== null && Date.parse(from) > Date.parse(to)) {
+    throw new BadRequestException("from must not be after to");
+  }
+  let limit = SEARCH_DEFAULT_LIMIT;
+  const rawLimit = query.limit;
+  if (rawLimit !== undefined && rawLimit !== "") {
+    const n = typeof rawLimit === "string" ? Number(rawLimit) : NaN;
+    if (!Number.isInteger(n) || n < 1 || n > SEARCH_MAX_LIMIT) {
+      throw new BadRequestException(`limit must be an integer between 1 and ${SEARCH_MAX_LIMIT}`);
+    }
+    limit = n;
+  }
+  const rawCursor = query.cursor;
+  const cursor = typeof rawCursor === "string" && rawCursor !== "" ? rawCursor : undefined;
+  if (cursor !== undefined && (cursor.length > 256 || !/^[A-Za-z0-9_-]+$/.test(cursor))) {
+    throw new BadRequestException("invalid cursor");
+  }
+  return { q, channelId, from, to, cursor, limit };
+}
+
+/** Lowercase word tokens (>= 3 chars, pg_trgm minimum), deduped and capped. */
+export function searchTokens(q: string): string[] {
+  const matches = q.toLowerCase().match(/[\p{L}\p{N}_@]+/gu) ?? [];
+  return [...new Set(matches.filter((token) => token.length >= 3))].slice(0, 8);
+}
+
+/** Positional bind helper: keeps parameter indices stable while SQL fragments compose. */
+class Params {
+  readonly values: unknown[] = [];
+  bind(value: unknown): number {
+    this.values.push(value);
+    return this.values.length;
+  }
+}
+
+function decodeCursor<T extends { id: string }>(cursor: string | undefined, what: string,
+  shape: (v: Record<string, unknown>) => T): T {
+  if (cursor === undefined) throw new BadRequestException(`invalid cursor: ${what}`);
+  let value: unknown;
+  try {
+    value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+  } catch {
+    throw new BadRequestException(`invalid cursor: ${what}`);
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BadRequestException(`invalid cursor: ${what}`);
+  }
+  return shape(value as Record<string, unknown>);
+}
+
+/**
+ * The rank expression, bound once so SELECT, WHERE (keyset cursor) and
+ * ORDER BY share identical parameter indices.
+ */
+function rankExpression(params: Params, q: string, tokens: string[]): string {
+  const qi = params.bind(q);
+  const textSims = tokens.map((token) => `similarity(text_content, $${params.bind(token)})`);
+  const chanSims = tokens.map((token) => `similarity(channel_id, $${params.bind(token)})`);
+  return `(ts_rank(search_vector, websearch_to_tsquery('simple', $${qi})) * 2`
+    + (textSims.length > 0 ? ` + GREATEST(${textSims.join(", ")})` : "")
+    + (chanSims.length > 0 ? ` + GREATEST(${chanSims.join(", ")}) * 0.5` : "")
+    + `)`;
+}
+
+function filterConds(params: Params, filters: ArchiveSearchFilters): string[] {
+  const conds: string[] = [];
+  if (filters.channelId !== null) conds.push(`channel_id = $${params.bind(filters.channelId)}`);
+  if (filters.from !== null) conds.push(`posted_at >= $${params.bind(filters.from)}::timestamptz`);
+  if (filters.to !== null) conds.push(`posted_at <= $${params.bind(filters.to)}::timestamptz`);
+  return conds;
+}
+
+/** WHERE + ORDER BY for the ranked search path (q present). */
+function searchConds(params: Params, filters: ArchiveSearchFilters, tokens: string[]): [string, string] {
+  const rank = rankExpression(params, filters.q ?? "", tokens);
+  const conds = filterConds(params, filters);
+  const fuzzy = tokens.length === 0 ? "false"
+    : tokens.map((token) => {
+      const ti = params.bind(token);
+      return `(text_content % $${ti} OR channel_id % $${ti})`;
+    }).join(" OR ");
+  conds.push(`(search_vector @@ websearch_to_tsquery('simple', $${params.bind(filters.q ?? "")}) OR ${fuzzy})`);
+  if (filters.cursor !== undefined) {
+    const { rk, id } = decodeCursor<{ rk: number; id: string }>(filters.cursor, "rank", (v) => {
+      if (typeof v.rk !== "number" || !Number.isFinite(v.rk)
+        || typeof v.id !== "string" || !UUID_SHAPE.test(v.id)) throw new BadRequestException("invalid cursor: rank");
+      return { rk: v.rk, id: v.id };
+    });
+    conds.push(`(${rank}, id) < ($${params.bind(rk)}::real, $${params.bind(id)}::uuid)`);
+  }
+  return [conds.join(" AND "), "ranked.rank DESC, ranked.id ASC"];
+}
+
+/** WHERE + ORDER BY for the export / no-query path (stable posted_at keyset). */
+function unrankedConds(params: Params, filters: ArchiveSearchFilters,
+  cursor: { at: string; id: string } | null): [string, string] {
+  const conds = filterConds(params, filters);
+  if (cursor) conds.push(`(posted_at, id) < ($${params.bind(cursor.at)}::timestamptz, $${params.bind(cursor.id)}::uuid)`);
+  return [conds.length > 0 ? conds.join(" AND ") : "true", "posted_at DESC, id DESC"];
+}
+
+const ROW_FIELDS = "id, remote_ref, channel_id, message_id, text_content, media_refs, attribution, protected_content, posted_at, revision";
+
+export function itemFromRow(row: ArchiveItemRow): Record<string, unknown> {
+  return {
+    id: row.id,
+    remoteRef: row.remote_ref,
+    channelId: row.channel_id,
+    messageId: Number(row.message_id),
+    text: row.text_content,
+    media: row.media_refs,
+    attribution: row.attribution,
+    protectedContent: row.protected_content,
+    postedAt: row.posted_at.toISOString(),
+    revision: row.revision,
+  };
+}
+
+export async function searchArchive(workspaceId: string, filters: ArchiveSearchFilters,
+  storage: StorageService): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+  const params = new Params();
+  const tokens = filters.q !== null ? searchTokens(filters.q) : [];
+  let sql: string;
+  if (filters.q !== null) {
+    const [where, orderBy] = searchConds(params, filters, tokens);
+    const rank = rankExpression(params, filters.q, tokens);
+    sql = `SELECT ${ROW_FIELDS}, rank FROM (
+        SELECT ${ROW_FIELDS}, ${rank} AS rank FROM archived_feed_items WHERE ${where}
+      ) ranked ORDER BY ${orderBy} LIMIT $${params.bind(filters.limit + 1)}`;
+  } else {
+    const cursor = filters.cursor === undefined ? null
+      : decodeCursor<{ at: string; id: string }>(filters.cursor, "posted", (v) => {
+        if (typeof v.at !== "string" || !Number.isFinite(Date.parse(v.at))
+          || typeof v.id !== "string" || !UUID_SHAPE.test(v.id)) throw new BadRequestException("invalid cursor: posted");
+        return { at: v.at, id: v.id };
+      });
+    const [where, orderBy] = unrankedConds(params, filters, cursor);
+    sql = `SELECT ${ROW_FIELDS} FROM archived_feed_items WHERE ${where}
+      ORDER BY ${orderBy} LIMIT $${params.bind(filters.limit + 1)}`;
+  }
+  const result = await withTenant(workspaceId, (client) => client.query<ArchiveItemRow>(sql, params.values));
+  return paginate(result.rows, filters, storage);
+}
+
+async function paginate(rows: ArchiveItemRow[], filters: ArchiveSearchFilters,
+  storage: StorageService): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+  const page = rows.slice(0, filters.limit);
+  const last = page.at(-1);
+  const items = await Promise.all(page.map(async (row) => {
+    const item = itemFromRow(row);
+    if (filters.q !== null) item.rank = row.rank ?? 0;
+    item.media = await Promise.all(row.media_refs.map(async (media) => ({
+      ...media, thumbUrl: media.storageKey ? await storage.presign(media.storageKey, 900) : null,
+    })));
+    return item;
+  }));
+  const nextCursor = rows.length > filters.limit && last
+    ? Buffer.from(JSON.stringify(filters.q !== null
+      ? { rk: last.rank ?? 0, id: last.id }
+      : { at: last.posted_at.toISOString(), id: last.id })).toString("base64url")
+    : null;
+  return { items, nextCursor };
+}
+
+/**
+ * Streamed export: yields pages of plain item objects in posted_at keyset
+ * order. Exports never mint presigned URLs — media travels by storage key.
+ */
+export async function* exportArchiveItems(workspaceId: string,
+  filters: ArchiveSearchFilters): AsyncGenerator<Record<string, unknown>[]> {
+  let cursor: { at: string; id: string } | null = null;
+  let sent = 0;
+  while (sent < ARCHIVE_EXPORT_MAX_ROWS) {
+    const params = new Params();
+    const remaining = Math.min(EXPORT_BATCH_SIZE, ARCHIVE_EXPORT_MAX_ROWS - sent);
+    const [where, orderBy] = unrankedConds(params, filters, cursor);
+    const result = await withTenant(workspaceId, (client) => client.query<ArchiveItemRow>(
+      `SELECT ${ROW_FIELDS} FROM archived_feed_items WHERE ${where}
+       ORDER BY ${orderBy} LIMIT $${params.bind(remaining + 1)}`, params.values));
+    const page = result.rows.slice(0, remaining);
+    if (page.length === 0) return;
+    sent += page.length;
+    const lastRow = page[page.length - 1]!;
+    cursor = { at: lastRow.posted_at.toISOString(), id: lastRow.id };
+    yield page.map(itemFromRow);
+    if (result.rows.length <= remaining) return;
+  }
+}
+
+const CSV_COLUMNS: Array<[string, (item: Record<string, unknown>) => string]> = [
+  ["id", (i) => String(i.id)],
+  ["remote_ref", (i) => String(i.remoteRef)],
+  ["channel_id", (i) => String(i.channelId)],
+  ["message_id", (i) => String(i.messageId)],
+  ["posted_at", (i) => String(i.postedAt)],
+  ["revision", (i) => String(i.revision)],
+  ["protected_content", (i) => (i.protectedContent === true ? "true" : "false")],
+  ["text", (i) => String(i.text)],
+  ["storage_keys", (i) => (Array.isArray(i.media)
+    ? (i.media as Array<{ storageKey?: string }>).map((m) => m.storageKey ?? "").filter((k) => k !== "").join(";")
+    : "")],
+  ["attribution", (i) => JSON.stringify(i.attribution ?? {})],
+];
+
+function csvCell(value: string): string {
+  return /[",\r\n]/.test(value) ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+export const ARCHIVE_CSV_HEADER = CSV_COLUMNS.map(([name]) => name).join(",") + "\r\n";
+
+export function csvItemRow(item: Record<string, unknown>): string {
+  return CSV_COLUMNS.map(([, get]) => csvCell(get(item))).join(",") + "\r\n";
+}
diff --git a/apps/api/src/archive/archive.controller.ts b/apps/api/src/archive/archive.controller.ts
new file mode 100644
index 0000000..ec2880f
--- /dev/null
+++ b/apps/api/src/archive/archive.controller.ts
@@ -0,0 +1,86 @@
+import { BadRequestException, Body, Controller, Get, Headers, Param, Post, Query, Req, Res, UseGuards } from "@nestjs/common";
+import type { Request, Response } from "express";
+import { parseId, requireObject, requireSession, requireString } from "../http/validation.js";
+import { RbacGuard, RequireGroupAccess, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { ArchiveService } from "./archive.service.js";
+
+@Controller("archive")
+export class ArchiveController {
+  constructor(private readonly archive: ArchiveService) {}
+
+  @Post("webhook/:workspaceId")
+  async webhook(@Param("workspaceId") workspaceId: string,
+    // eslint-disable-next-line no-restricted-syntax -- Fixed webhook protocol header, not provider branching.
+    @Headers("x-telegram-bot-api-secret-token") secret: string | undefined,
+    @Body() body: unknown): Promise<{ ok: true }> {
+    await this.archive.receive(parseId(workspaceId), secret, body);
+    return { ok: true };
+  }
+
+  @Post("subscriptions")
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.manage")
+  @RequireGroupAccess("body")
+  async subscribe(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<{ id: string }> {
+    const input = requireObject(body, "body");
+    const workspaceId = requireSession(request).workspaceId;
+    return { id: await this.archive.subscribe(workspaceId, parseId(requireString(input.connectionId, "connectionId")),
+      requireString(input.channelId, "channelId")) };
+  }
+
+  @Get("items")
+  @UseGuards(RbacGuard)
+  @RequirePermission("draft.view")
+  async list(@Req() request: Request & AuthenticatedRequest,
+    @Query("cursor") cursor?: string): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    if (cursor && (cursor.length > 256 || !/^[A-Za-z0-9_-]+$/.test(cursor))) throw new BadRequestException("invalid cursor");
+    return this.archive.list(requireSession(request).workspaceId, cursor);
+  }
+
+  @Post("items/:itemId/drafts")
+  @UseGuards(RbacGuard)
+  @RequirePermission("draft.create")
+  async createDraft(@Req() request: Request & AuthenticatedRequest,
+    @Param("itemId") itemId: string): Promise<{ id: string; state: string }> {
+    const session = requireSession(request);
+    return this.archive.createDraft(session.workspaceId, { userId: session.userId, role: session.role }, parseId(itemId));
+  }
+
+  @Post("items/:itemId/amplify")
+  @UseGuards(RbacGuard)
+  @RequirePermission("publication.schedule")
+  @RequireGroupAccess("body")
+  async amplify(@Req() request: Request & AuthenticatedRequest, @Param("itemId") itemId: string,
+    @Body() body: unknown): Promise<unknown> {
+    const input = requireObject(body, "body");
+    if (input.attribution !== undefined && typeof input.attribution !== "boolean") throw new BadRequestException("attribution must be boolean");
+    return this.archive.amplify(requireSession(request).workspaceId, parseId(itemId),
+      parseId(requireString(input.draftId, "draftId")), parseId(requireString(input.connectionId, "connectionId")),
+      input.attribution !== false);
+  }
+
+  @Get("search")
+  @UseGuards(RbacGuard)
+  @RequirePermission("draft.view")
+  async search(@Req() request: Request & AuthenticatedRequest,
+    @Query() query: Record<string, unknown>): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    return this.archive.search(requireSession(request).workspaceId, query);
+  }
+
+  @Get("export")
+  @UseGuards(RbacGuard)
+  @RequirePermission("draft.view")
+  async exportAll(@Req() request: Request & AuthenticatedRequest, @Res() response: Response,
+    @Query() query: Record<string, unknown>): Promise<void> {
+    const workspaceId = requireSession(request).workspaceId;
+    const format = query.format === "csv" ? "csv" : query.format === undefined || query.format === "" ? "json" : null;
+    if (format === null) throw new BadRequestException("format must be csv or json");
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    response.setHeader("Content-Type", format === "csv" ? "text/csv; charset=utf-8" : "application/json; charset=utf-8");
+    response.setHeader("Content-Disposition", `attachment; filename="archive-export-${stamp}.${format}"`);
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    await this.archive.exportItems(workspaceId, query, (chunk) => response.write(chunk));
+    response.end();
+  }
+}
diff --git a/apps/api/src/archive/archive.module.ts b/apps/api/src/archive/archive.module.ts
new file mode 100644
index 0000000..ed0fe14
--- /dev/null
+++ b/apps/api/src/archive/archive.module.ts
@@ -0,0 +1,7 @@
+import { Module } from "@nestjs/common";
+import { PublishingService } from "../publishing/publishing.service.js";
+import { ArchiveController } from "./archive.controller.js";
+import { ArchiveService } from "./archive.service.js";
+
+@Module({ controllers: [ArchiveController], providers: [ArchiveService, PublishingService] })
+export class ArchiveModule {}
diff --git a/apps/api/src/archive/archive.service.ts b/apps/api/src/archive/archive.service.ts
new file mode 100644
index 0000000..2b8a4fc
--- /dev/null
+++ b/apps/api/src/archive/archive.service.ts
@@ -0,0 +1,239 @@
+import { BadRequestException, ForbiddenException, Injectable, NotFoundException } from "@nestjs/common";
+import { timingSafeEqual } from "node:crypto";
+// eslint-disable-next-line no-restricted-syntax -- Importing the connector adapter is the provider boundary, not provider branching.
+import { createTelegramConnector } from "@tactical-media-broadcast-hub/connector-telegram";
+import { ConnectorError } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { withTenant } from "../db/client.js";
+import { PublishingService, type Actor } from "../publishing/publishing.service.js";
+import { S3Storage, s3ConfigFromEnv, type StorageService } from "../storage/storage.js";
+import {
+  ARCHIVE_CSV_HEADER,
+  csvItemRow,
+  exportArchiveItems,
+  parseArchiveSearchQuery,
+  searchArchive,
+  type ArchiveSearchFilters,
+} from "./archive-search.js";
+import { TelegramAlbumDebouncer, type ArchiveItemInput, type TelegramMedia } from "./normalizer.js";
+
+const ARCHIVE_PROVIDER = createTelegramConnector().manifest().id;
+
+interface ItemRow {
+  id: string; remote_ref: string; channel_id: string; message_id: string;
+  text_content: string; media_refs: TelegramMedia[]; attribution: Record<string, unknown>;
+  protected_content: boolean; posted_at: Date; revision: number;
+}
+function object(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+function equalSecret(actual: string, expected: string): boolean {
+  const a = Buffer.from(actual); const b = Buffer.from(expected);
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+function itemFromRow(row: ItemRow): Record<string, unknown> {
+  return { id: row.id, remoteRef: row.remote_ref, channelId: row.channel_id,
+    messageId: Number(row.message_id), text: row.text_content, media: row.media_refs,
+    attribution: row.attribution, protectedContent: row.protected_content,
+    postedAt: row.posted_at.toISOString(), revision: row.revision };
+}
+
+@Injectable()
+export class ArchiveService {
+  readonly albums: TelegramAlbumDebouncer;
+  private readonly storage: StorageService;
+  constructor(private readonly publishing: PublishingService) {
+    this.storage = new S3Storage(s3ConfigFromEnv());
+    this.albums = new TelegramAlbumDebouncer((item) => this.save(item));
+  }
+
+  async subscribe(workspaceId: string, connectionId: string, channelId: string): Promise<string> {
+    if (!/^-?\d{3,}$/.test(channelId)) throw new BadRequestException("channelId must be a numeric Telegram chat id");
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        `INSERT INTO feed_subscriptions (workspace_id, type, connection_id, channel_id)
+         SELECT $1, 'telegram_channel', id, $3 FROM connections
+         WHERE id = $2 AND provider = 'telegram'
+         ON CONFLICT (workspace_id, connection_id, channel_id) DO UPDATE SET updated_at = now()
+         RETURNING id`, [workspaceId, connectionId, channelId]);
+      if (!result.rows[0]) throw new NotFoundException("Telegram connection not found");
+      return String(result.rows[0].id);
+    });
+  }
+
+  async receive(workspaceId: string, secret: string | undefined, payload: unknown): Promise<void> {
+    const expected = process.env.TELEGRAM_WEBHOOK_SECRET;
+    if (!expected || !secret || !equalSecret(secret, expected)) throw new ForbiddenException("webhook secret mismatch");
+    const update = object(payload);
+    const post = object(update?.channel_post ?? update?.edited_channel_post);
+    const membership = object(update?.my_chat_member);
+    const chat = object(post?.chat ?? membership?.chat);
+    const channelId = chat?.id === undefined ? null : String(chat.id);
+    if (!channelId) return;
+    const subscriptions = await withTenant(workspaceId, (client) => client.query(
+      "SELECT id FROM feed_subscriptions WHERE channel_id = $1", [channelId]));
+    if (subscriptions.rowCount === 0) return;
+    if (membership) {
+      const next = object(membership.new_chat_member);
+      const status = next?.status;
+      const health = status === "administrator" || status === "creator" ? "active"
+        : status === "member" ? "admin_required" : "bot_removed";
+      await withTenant(workspaceId, (client) => client.query(
+        "UPDATE feed_subscriptions SET health = $2, health_checked_at = now(), updated_at = now() WHERE channel_id = $1",
+        [channelId, health]));
+      return;
+    }
+    await this.albums.ingest(workspaceId, payload);
+  }
+
+  private async harvest(media: TelegramMedia): Promise<TelegramMedia> {
+    if (media.status !== "pending") return media;
+    const token = process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) return media;
+    const response = await fetch(`https://api.telegram.org/bot${token}/getFile?file_id=${encodeURIComponent(media.fileId)}`);
+    const body: unknown = await response.json();
+    const file = object(object(body)?.result);
+    const size = typeof file?.file_size === "number" ? file.file_size : media.sizeBytes;
+    if (size !== null && size > 20_000_000) return { ...media, sizeBytes: size, status: "Bot API cannot fetch" };
+    const path = file?.file_path;
+    if (!response.ok || typeof path !== "string" || path.includes("..") || path.startsWith("/")) return { ...media, status: "failed" };
+    const downloaded = await fetch(`https://api.telegram.org/file/bot${token}/${path}`);
+    if (!downloaded.ok) return { ...media, status: "failed" };
+    const bytes = Buffer.from(await downloaded.arrayBuffer());
+    if (bytes.length > 20_000_000) return { ...media, sizeBytes: bytes.length, status: "Bot API cannot fetch" };
+    const stored = await this.storage.putContent(bytes, media.contentType);
+    return { ...media, sizeBytes: bytes.length, status: "stored", storageKey: stored.key };
+  }
+
+  async save(item: ArchiveItemInput): Promise<void> {
+    const media = await Promise.all(item.mediaRefs.map((entry) => this.harvest(entry)));
+    await withTenant(item.workspaceId, async (client) => {
+      const existing = await client.query<ItemRow & { content_hash: string }>(
+        "SELECT * FROM archived_feed_items WHERE remote_ref = $1 FOR UPDATE", [item.remoteRef]);
+      const row = existing.rows[0];
+      if (row?.content_hash === item.contentHash) return;
+      if (row && !item.edited) return;
+      if (row) {
+        const next = row.revision + 1;
+        await client.query(`UPDATE archived_feed_items SET text_content = $2, content_hash = $3,
+          media_refs = $4, attribution = $5, protected_content = $6, revision = $7, updated_at = now() WHERE id = $1`,
+        [row.id, item.textContent, item.contentHash, JSON.stringify(media), JSON.stringify(item.attribution), item.protectedContent, next]);
+        await client.query(`INSERT INTO archived_feed_revisions
+          (workspace_id, item_id, revision, content_hash, text_content, media_refs, attribution)
+          VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+        [item.workspaceId, row.id, next, item.contentHash, item.textContent, JSON.stringify(media), JSON.stringify(item.attribution)]);
+        return;
+      }
+      const inserted = await client.query<{ id: string }>(`INSERT INTO archived_feed_items
+        (workspace_id, remote_ref, channel_id, message_id, media_group_id, text_content, content_hash,
+         media_refs, attribution, protected_content, posted_at)
+        VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11)
+        ON CONFLICT (workspace_id, remote_ref) DO NOTHING RETURNING id`,
+      [item.workspaceId, item.remoteRef, item.channelId, item.messageId, item.mediaGroupId,
+        item.textContent, item.contentHash, JSON.stringify(media), JSON.stringify(item.attribution),
+        item.protectedContent, item.postedAt]);
+      const id = inserted.rows[0]?.id;
+      if (id) await client.query(`INSERT INTO archived_feed_revisions
+        (workspace_id, item_id, revision, content_hash, text_content, media_refs, attribution)
+        VALUES ($1,$2,1,$3,$4,$5,$6)`,
+      [item.workspaceId, id, item.contentHash, item.textContent, JSON.stringify(media), JSON.stringify(item.attribution)]);
+    });
+  }
+
+  async list(workspaceId: string, cursor?: string): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    let parsed: { at: string; id: string } | null = null;
+    if (cursor) {
+      try {
+        const value: unknown = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        const shape = object(value);
+        if (typeof shape?.at !== "string" || !Number.isFinite(Date.parse(shape.at))
+          || typeof shape.id !== "string" || !/^[0-9a-f-]{36}$/i.test(shape.id)) throw new Error("shape");
+        parsed = { at: shape.at, id: shape.id };
+      } catch { throw new BadRequestException("invalid cursor"); }
+    }
+    const result = await withTenant(workspaceId, (client) => client.query<ItemRow>(
+      `SELECT * FROM archived_feed_items WHERE ($1::timestamptz IS NULL OR (posted_at, id) < ($1::timestamptz, $2::uuid))
+       ORDER BY posted_at DESC, id DESC LIMIT 21`, [parsed?.at ?? null, parsed?.id ?? null]));
+    const rows = result.rows.slice(0, 20);
+    const last = rows.at(-1);
+    const items = await Promise.all(rows.map(async (row) => {
+      const item = itemFromRow(row);
+      item.media = await Promise.all(row.media_refs.map(async (media) => ({
+        ...media, thumbUrl: media.storageKey ? await this.storage.presign(media.storageKey, 900) : null,
+      })));
+      return item;
+    }));
+    return { items, nextCursor: result.rows.length > 20 && last
+      ? Buffer.from(JSON.stringify({ at: last.posted_at.toISOString(), id: last.id })).toString("base64url") : null };
+  }
+
+  async createDraft(workspaceId: string, actor: Actor, itemId: string): Promise<{ id: string; state: string }> {
+    const found = await withTenant(workspaceId, (client) => client.query<ItemRow>(
+      "SELECT * FROM archived_feed_items WHERE id = $1", [itemId]));
+    const item = found.rows[0];
+    if (!item) throw new NotFoundException("archive item not found");
+    const draft = await this.publishing.createDraft(workspaceId, actor, {
+      text: item.text_content, mediaAssetIds: [], visibility: "provider_default",
+      providerMetadata: { archiveItemId: itemId, sourceRemoteRef: item.remote_ref,
+        attribution: item.attribution, attributionEnabled: true },
+    });
+    await withTenant(workspaceId, (client) => client.query(
+      "INSERT INTO archived_feed_drafts (workspace_id, item_id, draft_id) VALUES ($1,$2,$3)",
+      [workspaceId, itemId, draft.id]));
+    return { id: draft.id, state: draft.state };
+  }
+
+  async amplify(workspaceId: string, itemId: string, draftId: string, connectionId: string,
+    attribution = true): Promise<unknown> {
+    const found = await withTenant(workspaceId, (client) => client.query<ItemRow & { channel_id: string }>(
+      `SELECT i.* FROM archived_feed_items i JOIN archived_feed_drafts b
+       ON b.item_id = i.id AND b.workspace_id = i.workspace_id
+       JOIN drafts d ON d.id = b.draft_id AND d.workspace_id = b.workspace_id
+       WHERE i.id = $1 AND d.id = $2 AND d.state = 'approved'`, [itemId, draftId]));
+    const item = found.rows[0];
+    if (!item) throw new ForbiddenException("an approved archive draft is required");
+    if (item.protected_content) throw new ConnectorError(`${ARCHIVE_PROVIDER}: protected content cannot be forwarded`, ARCHIVE_PROVIDER);
+    const target = await withTenant(workspaceId, (client) => client.query<{ channel_id: string; fields: Record<string, string> }>(
+      "SELECT channel_id, fields FROM connections WHERE id = $1 AND provider = $2", [connectionId, ARCHIVE_PROVIDER]));
+    const connectionRow = target.rows[0];
+    if (!connectionRow) throw new NotFoundException("Telegram target connection not found");
+    const token = process.env.TELEGRAM_BOT_TOKEN;
+    if (!token) throw new BadRequestException("Telegram bot token is not configured");
+    const connection: ConnectorConnection = { id: connectionId, workspaceId, provider: ARCHIVE_PROVIDER,
+      channelId: connectionRow.channel_id, credentialId: { kind: "credential-ref", id: connectionId },
+      fields: { ...connectionRow.fields, botToken: token }, createdAt: new Date() };
+    const connector = createTelegramConnector();
+    if (!connector.amplify) throw new ConnectorError(`${ARCHIVE_PROVIDER}: amplify unavailable`, ARCHIVE_PROVIDER);
+    const origin = item.attribution.channelUsername;
+    const commentary = attribution && typeof origin === "string" && origin !== ""
+      ? `Source: https://t.me/${origin}/${item.message_id}` : undefined;
+    return connector.amplify(connection, { kind: "share", targetRemoteId: item.remote_ref,
+      ...(commentary ? { commentary } : {}) });
+  }
+
+  async search(workspaceId: string, query: Record<string, unknown>): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    const filters: ArchiveSearchFilters = parseArchiveSearchQuery(query);
+    return searchArchive(workspaceId, filters, this.storage);
+  }
+
+  async exportItems(workspaceId: string, query: Record<string, unknown>,
+    write: (chunk: string) => void): Promise<"csv" | "json"> {
+    const filters = parseArchiveSearchQuery(query);
+    const format = query.format === "csv" ? "csv" : query.format === undefined || query.format === "" ? "json" : null;
+    if (format === null) throw new BadRequestException("format must be csv or json");
+    if (format === "csv") write(ARCHIVE_CSV_HEADER);
+    else write("[");
+    let first = true;
+    for await (const page of exportArchiveItems(workspaceId, filters)) {
+      for (const item of page) {
+        if (format === "csv") write(csvItemRow(item));
+        else {
+          write((first ? "" : ",") + JSON.stringify(item));
+          first = false;
+        }
+      }
+    }
+    write(format === "csv" ? "" : "]");
+    return format;
+  }
+}
diff --git a/apps/api/src/archive/normalizer.ts b/apps/api/src/archive/normalizer.ts
new file mode 100644
index 0000000..46d4a33
--- /dev/null
+++ b/apps/api/src/archive/normalizer.ts
@@ -0,0 +1,109 @@
+import { createHash } from "node:crypto";
+
+export interface TelegramMedia {
+  fileId: string;
+  fileUniqueId: string;
+  sizeBytes: number | null;
+  contentType: string;
+  status: "pending" | "stored" | "Bot API cannot fetch" | "failed";
+  storageKey?: string;
+}
+export interface ArchiveItemInput {
+  workspaceId: string;
+  channelId: string;
+  messageId: number;
+  remoteRef: string;
+  mediaGroupId: string | null;
+  textContent: string;
+  contentHash: string;
+  mediaRefs: TelegramMedia[];
+  attribution: Record<string, unknown>;
+  protectedContent: boolean;
+  postedAt: Date;
+  edited: boolean;
+}
+interface TelegramFile { file_id?: unknown; file_unique_id?: unknown; file_size?: unknown; mime_type?: unknown }
+interface TelegramPost {
+  message_id: number; date: number;
+  chat: { id: number | string; title?: string; username?: string };
+  text?: string; caption?: string; media_group_id?: string; author_signature?: string;
+  forward_origin?: Record<string, unknown>; is_automatic_forward?: boolean;
+  has_protected_content?: boolean;
+  photo?: TelegramFile[]; video?: TelegramFile; document?: TelegramFile;
+}
+function record(value: unknown): Record<string, unknown> | null {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value as Record<string, unknown> : null;
+}
+export function parseTelegramPost(value: unknown): TelegramPost | null {
+  const post = record(value);
+  const chat = record(post?.chat);
+  if (!post || !chat || !Number.isSafeInteger(post.message_id) || !Number.isSafeInteger(post.date)
+    || (typeof chat.id !== "number" && typeof chat.id !== "string")) return null;
+  return post as unknown as TelegramPost;
+}
+function mediaOf(post: TelegramPost): TelegramMedia[] {
+  const photo = Array.isArray(post.photo) ? post.photo.at(-1) : undefined;
+  const entries: Array<[TelegramFile | undefined, string]> = [[photo, "image/jpeg"], [post.video, "video/mp4"], [post.document, "application/octet-stream"]];
+  return entries.flatMap(([file, fallback]) => typeof file?.file_id === "string" && typeof file.file_unique_id === "string"
+    ? [{ fileId: file.file_id, fileUniqueId: file.file_unique_id,
+      sizeBytes: typeof file.file_size === "number" ? file.file_size : null,
+      contentType: typeof file.mime_type === "string" ? file.mime_type : fallback,
+      status: file.file_size !== undefined && typeof file.file_size === "number" && file.file_size > 20_000_000
+        ? "Bot API cannot fetch" as const : "pending" as const }]
+    : []);
+}
+export function normalizePosts(workspaceId: string, posts: TelegramPost[], edited = false): ArchiveItemInput {
+  const ordered = [...posts].sort((a, b) => a.message_id - b.message_id);
+  const first = ordered[0];
+  if (!first) throw new Error("empty Telegram post batch");
+  const textContent = ordered.map((p) => p.text ?? p.caption ?? "").find((s) => s !== "") ?? "";
+  const mediaRefs = ordered.flatMap(mediaOf);
+  const attribution: Record<string, unknown> = {
+    channelTitle: first.chat.title ?? null, channelUsername: first.chat.username ?? null,
+    authorSignature: first.author_signature ?? null, forwardOrigin: first.forward_origin ?? null,
+    isAutomaticForward: first.is_automatic_forward === true,
+  };
+  const channelId = String(first.chat.id);
+  const contentHash = createHash("sha256").update(JSON.stringify({ textContent, media: mediaRefs.map((m) => m.fileUniqueId), attribution })).digest("hex");
+  return { workspaceId, channelId, messageId: first.message_id, remoteRef: `${channelId}:${first.message_id}`,
+    mediaGroupId: first.media_group_id ?? null, textContent, contentHash, mediaRefs, attribution,
+    protectedContent: ordered.some((p) => p.has_protected_content === true),
+    postedAt: new Date(first.date * 1000), edited };
+}
+export interface AlbumTimers {
+  set(callback: () => void, ms: number): ReturnType<typeof setTimeout>;
+  clear(handle: ReturnType<typeof setTimeout>): void;
+}
+const defaultTimers: AlbumTimers = { set: (cb, ms) => setTimeout(cb, ms), clear: clearTimeout };
+/** A keyed 2s debounce. Every album update shares one durable archive identity. */
+export class TelegramAlbumDebouncer {
+  private readonly pending = new Map<string, { posts: TelegramPost[]; timer: ReturnType<typeof setTimeout> }>();
+  constructor(private readonly save: (item: ArchiveItemInput) => Promise<void>, private readonly timers: AlbumTimers = defaultTimers) {}
+  async ingest(workspaceId: string, update: unknown): Promise<void> {
+    const envelope = record(update);
+    const edited = envelope?.edited_channel_post !== undefined;
+    const post = parseTelegramPost(envelope?.[edited ? "edited_channel_post" : "channel_post"]);
+    if (!post) return;
+    const group = post.media_group_id;
+    if (!group || edited) { await this.save(normalizePosts(workspaceId, [post], edited)); return; }
+    const key = `${workspaceId}:${post.chat.id}:${group}`;
+    const current = this.pending.get(key);
+    if (current) this.timers.clear(current.timer);
+    const posts = [...(current?.posts ?? []), post];
+    const timer = this.timers.set(() => { void this.flush(key, workspaceId); }, 2_000);
+    this.pending.set(key, { posts, timer });
+  }
+  async flush(key: string, workspaceId: string): Promise<void> {
+    const group = this.pending.get(key);
+    if (!group) return;
+    this.pending.delete(key);
+    this.timers.clear(group.timer);
+    await this.save(normalizePosts(workspaceId, group.posts));
+  }
+  async flushAll(): Promise<void> {
+    for (const key of [...this.pending.keys()]) {
+      const workspaceId = key.slice(0, key.indexOf(":"));
+      await this.flush(key, workspaceId);
+    }
+  }
+}
diff --git a/apps/api/src/audit/audit.controller.ts b/apps/api/src/audit/audit.controller.ts
new file mode 100644
index 0000000..e846d2c
--- /dev/null
+++ b/apps/api/src/audit/audit.controller.ts
@@ -0,0 +1,35 @@
+import { BadRequestException, Controller, Get, Inject, Query, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { isUuid, parseLimit, requireSession } from "../http/validation.js";
+import { AuditQueryService, type AuditPage } from "./audit.query.js";
+
+@Controller("audit")
+@UseGuards(RbacGuard)
+export class AuditController {
+  constructor(@Inject(AuditQueryService) private readonly audit: AuditQueryService) {}
+
+  @Get()
+  @RequirePermission("audit.view")
+  async list(
+    @Req() request: Request & AuthenticatedRequest,
+    @Query("action") action: string | undefined,
+    @Query("actor") actor: string | undefined,
+    @Query("before") before: string | undefined,
+    @Query("limit") limit: string | undefined,
+  ): Promise<AuditPage> {
+    const session = requireSession(request);
+    if (actor !== undefined && actor !== "" && actor !== "system" && !isUuid(actor)) {
+      throw new BadRequestException("actor must be a user UUID or \"system\"");
+    }
+    if (before !== undefined && before !== "" && !/^\d{1,18}$/.test(before)) {
+      throw new BadRequestException("before must be a sequence cursor");
+    }
+    return this.audit.page(session.workspaceId, {
+      ...(action === undefined || action === "" ? {} : { action }),
+      ...(actor === undefined || actor === "" ? {} : { actor }),
+      ...(before === undefined || before === "" ? {} : { before }),
+      limit: parseLimit(limit, 50, 200),
+    });
+  }
+}
diff --git a/apps/api/src/audit/audit.query.ts b/apps/api/src/audit/audit.query.ts
new file mode 100644
index 0000000..0a4fe21
--- /dev/null
+++ b/apps/api/src/audit/audit.query.ts
@@ -0,0 +1,113 @@
+import { Injectable } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+
+export interface AuditEntryDto {
+  id: string;
+  seq: string;
+  at: string;
+  actorUserId: string | null;
+  actorEmail: string | null;
+  actorRole: string | null;
+  action: string;
+  targetType: string;
+  targetId: string;
+  diff: Record<string, unknown> | null;
+}
+
+export interface AuditActorFacet {
+  /** null = system / service actor. */
+  id: string | null;
+  email: string | null;
+}
+
+export interface AuditPage {
+  entries: AuditEntryDto[];
+  /** Pass back as `before` to fetch the next (older) page; null when exhausted. */
+  nextCursor: string | null;
+  facets: { actions: string[]; actors: AuditActorFacet[] };
+}
+
+export interface AuditFilter {
+  action?: string;
+  /** User UUID, or "system" for entries without a human actor. */
+  actor?: string;
+  before?: string;
+  limit: number;
+}
+
+interface AuditRow {
+  id: string;
+  seq: string;
+  at: Date;
+  actor_user_id: string | null;
+  actor_email: string | null;
+  actor_role: string | null;
+  action: string;
+  target_type: string;
+  target_id: string;
+  diff: Record<string, unknown> | null;
+}
+
+/** Read side of the tenant audit chain. RLS (tenant_audit policy) scopes rows to the session's workspace. */
+@Injectable()
+export class AuditQueryService {
+  async page(workspaceId: string, filter: AuditFilter): Promise<AuditPage> {
+    return withTenant(workspaceId, async (client) => {
+      const actorIsSystem = filter.actor === "system";
+      const rows = await client.query(
+        `SELECT a.id, a.seq::text AS seq, a.at, a.actor_user_id, u.email AS actor_email, a.actor_role,
+                a.action, a.target_type, a.target_id, a.diff
+         FROM audit_log a
+         LEFT JOIN users u ON u.id = a.actor_user_id
+         WHERE a.workspace_id = $1
+           AND ($2::text IS NULL OR a.action = $2)
+           AND ($3::uuid IS NULL OR a.actor_user_id = $3)
+           AND (NOT $4::boolean OR a.actor_user_id IS NULL)
+           AND ($5::bigint IS NULL OR a.seq < $5)
+         ORDER BY a.seq DESC
+         LIMIT $6`,
+        [
+          workspaceId,
+          filter.action ?? null,
+          actorIsSystem ? null : (filter.actor ?? null),
+          actorIsSystem,
+          filter.before ?? null,
+          filter.limit + 1,
+        ],
+      );
+      const all = rows.rows as AuditRow[];
+      const hasMore = all.length > filter.limit;
+      const entries = all.slice(0, filter.limit).map((r) => ({
+        id: r.id,
+        seq: r.seq,
+        at: new Date(r.at).toISOString(),
+        actorUserId: r.actor_user_id,
+        actorEmail: r.actor_email,
+        actorRole: r.actor_role,
+        action: r.action,
+        targetType: r.target_type,
+        targetId: r.target_id,
+        diff: r.diff,
+      }));
+
+      const actions = await client.query(
+        "SELECT DISTINCT action FROM audit_log WHERE workspace_id = $1 ORDER BY action",
+        [workspaceId],
+      );
+      const actors = await client.query(
+        `SELECT DISTINCT a.actor_user_id AS id, u.email
+         FROM audit_log a LEFT JOIN users u ON u.id = a.actor_user_id
+         WHERE a.workspace_id = $1 ORDER BY u.email NULLS LAST`,
+        [workspaceId],
+      );
+      return {
+        entries,
+        nextCursor: hasMore ? (entries[entries.length - 1]?.seq ?? null) : null,
+        facets: {
+          actions: (actions.rows as Array<{ action: string }>).map((r) => r.action),
+          actors: actors.rows as AuditActorFacet[],
+        },
+      };
+    });
+  }
+}
diff --git a/apps/api/src/audit/audit.scrub.test.ts b/apps/api/src/audit/audit.scrub.test.ts
new file mode 100644
index 0000000..dcf29cb
--- /dev/null
+++ b/apps/api/src/audit/audit.scrub.test.ts
@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { scrub } from "./audit.service.js";
+
+describe("audit diff scrubbing", () => {
+  it("redacts secret-shaped keys (spec: secrets never enter audit payloads)", () => {
+    const clean = scrub({ password: "hunter2", stream_key: "sk-1", note: "hello", count: 3 });
+    expect(clean).toEqual({ password: "[REDACTED]", stream_key: "[REDACTED]", note: "hello", count: 3 });
+  });
+
+  it("passes null through", () => {
+    expect(scrub(null)).toBeNull();
+  });
+});
diff --git a/apps/api/src/audit/audit.service.ts b/apps/api/src/audit/audit.service.ts
new file mode 100644
index 0000000..7577916
--- /dev/null
+++ b/apps/api/src/audit/audit.service.ts
@@ -0,0 +1,38 @@
+import { withTenant } from "../db/client.js";
+
+/**
+ * Audit service: hash-chained, secrets never enter payloads.
+ * Branch selection (findings #1/#6): tenant context present => tenant chain
+ * (audit_append), even for service roles; no tenant context => system chain.
+ */
+
+const SECRET_KEYS = /(password|secret|token|key|credential|stream_key|refresh)/i;
+
+export function scrub(diff: Record<string, unknown> | null): Record<string, unknown> | null {
+  if (diff === null) return null;
+  const clean: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(diff)) {
+    clean[k] = SECRET_KEYS.test(k) ? "[REDACTED]" : v;
+  }
+  return clean;
+}
+
+export interface AuditEvent {
+  actorUserId: string | null;
+  actorRole: string;
+  action: string;
+  targetType: string;
+  targetId: string;
+  diff?: Record<string, unknown> | null;
+}
+
+export async function appendTenantAudit(workspaceId: string, event: AuditEvent): Promise<string> {
+  const res = await withTenant(workspaceId, async (client) => {
+    const result = await client.query(
+      "SELECT audit_append($1, $2, $3, $4, $5, $6, $7) AS id",
+      [workspaceId, event.actorUserId, event.actorRole, event.action, event.targetType, event.targetId, scrub(event.diff ?? null)],
+    );
+    return result.rows[0]?.id as string;
+  });
+  return res;
+}
diff --git a/apps/api/src/auth/auth.controller.ts b/apps/api/src/auth/auth.controller.ts
new file mode 100644
index 0000000..0c28e89
--- /dev/null
+++ b/apps/api/src/auth/auth.controller.ts
@@ -0,0 +1,70 @@
+import { Body, Controller, Get, HttpCode, Inject, Post, Req, UnauthorizedException, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { optionalEmail, optionalString, parseId, requireObject, requireString, requireUsername, requireSession } from "../http/validation.js";
+import { AuthService, type AuthResult, type LoginInput, type MeResponse, type RegisterInput } from "./auth.service.js";
+import { verifySession } from "./session.js";
+
+@Controller("auth")
+export class AuthController {
+  constructor(@Inject(AuthService) private readonly auth: AuthService) {}
+
+  @Post("register")
+  async register(@Body() body: unknown): Promise<AuthResult> {
+    return this.auth.register(parseRegister(body));
+  }
+
+  @Post("login")
+  @HttpCode(200)
+  async login(@Body() body: unknown): Promise<AuthResult> {
+    return this.auth.login(parseLogin(body));
+  }
+
+  /** Any valid, epoch-current session may read itself — no permission gate beyond authentication. */
+  @Get("me")
+  @UseGuards(RbacGuard)
+  async me(@Req() request: Request & AuthenticatedRequest): Promise<MeResponse> {
+    return this.auth.me(requireSession(request));
+  }
+
+  /** A signed, unexpired session can refresh its epoch and live role. */
+  @Post("reissue")
+  @HttpCode(200)
+  async reissue(@Req() request: Request): Promise<AuthResult> {
+    const authorization = request.headers.authorization;
+    if (authorization === undefined || !authorization.startsWith("Bearer ")) throw new UnauthorizedException();
+    const session = verifySession(authorization.slice("Bearer ".length));
+    if (session === null) throw new UnauthorizedException();
+    return this.auth.reissue(session);
+  }
+
+  /** Stateless tokens: logout is client-side (drop the token). Revocation-by-epoch covers role changes. */
+  @Post("logout")
+  @HttpCode(200)
+  logout(): { ok: true } {
+    return { ok: true };
+  }
+}
+
+function parseRegister(value: unknown): RegisterInput {
+  const body = requireObject(value, "body");
+  const username = requireUsername(body.username);
+  const email = optionalEmail(body.email);
+  return {
+    workspaceName: requireString(body.workspaceName, "workspaceName").trim().slice(0, 100),
+    username,
+    password: requireString(body.password, "password"),
+    displayName: (optionalString(body.displayName, "displayName") ?? username).trim().slice(0, 100),
+    ...(email === undefined ? {} : { email }),
+  };
+}
+
+function parseLogin(value: unknown): LoginInput {
+  const body = requireObject(value, "body");
+  const workspaceId = optionalString(body.workspaceId, "workspaceId");
+  return {
+    username: requireUsername(body.username),
+    password: requireString(body.password, "password"),
+    ...(workspaceId === undefined ? {} : { workspaceId: parseId(workspaceId, "workspaceId") }),
+  };
+}
diff --git a/apps/api/src/auth/auth.integration.test.ts b/apps/api/src/auth/auth.integration.test.ts
new file mode 100644
index 0000000..e5f868a
--- /dev/null
+++ b/apps/api/src/auth/auth.integration.test.ts
@@ -0,0 +1,155 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import type { ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+
+/**
+ * Auth + team + audit wiring against a live PostgreSQL, as sp_app (FORCE RLS binds).
+ * Uses its OWN database (AUTH_IT_DATABASE_URL, plus AUTH_IT_SUPER_DATABASE_URL for
+ * migrations) because tenancy.integration.test.ts wipes every workspace in the
+ * shared DB and vitest runs files in parallel. Skipped when unset.
+ */
+const appUrl = process.env.AUTH_IT_DATABASE_URL;
+const ownerUrl = process.env.AUTH_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  auth: typeof import("./auth.service.js");
+  team: typeof import("../team/team.service.js");
+  audit: typeof import("../audit/audit.query.js");
+  guard: typeof import("../rbac/rbac.guard.js");
+  session: typeof import("./session.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("auth/team/audit (live DB)", () => {
+  let m: Modules;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  const ownerUsername = `owner${suffix}`;
+  const ownerEmail = `owner-${suffix}@example.com`;
+
+  beforeAll(async () => {
+    // The pool reads DATABASE_URL at import time: point it at the isolated DB first.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      auth: await import("./auth.service.js"),
+      team: await import("../team/team.service.js"),
+      audit: await import("../audit/audit.query.js"),
+      guard: await import("../rbac/rbac.guard.js"),
+      session: await import("./session.js"),
+      db: await import("../db/client.js"),
+    };
+  });
+
+  afterAll(async () => {
+    await m?.db.pool.end();
+  });
+
+  function guardContext(token: string, permission: string | undefined): { ctx: ExecutionContext; reflector: Reflector } {
+    const handler = (): void => undefined;
+    const reflector = new Reflector();
+    if (permission !== undefined) Reflect.defineMetadata(m.guard.PERMISSION_KEY, permission, handler);
+    const req = { headers: { authorization: `Bearer ${token}` } };
+    const ctx = {
+      getHandler: () => handler,
+      switchToHttp: () => ({ getRequest: () => req }),
+    } as unknown as ExecutionContext;
+    return { ctx, reflector };
+  }
+
+  async function allowed(token: string, permission?: string): Promise<boolean | string> {
+    const { ctx, reflector } = guardContext(token, permission);
+    try {
+      return await new m.guard.RbacGuard(reflector).canActivate(ctx);
+    } catch (err) {
+      return (err as Error).constructor.name;
+    }
+  }
+
+  it("register -> login -> me, and the RBAC guard accepts the session (bigint epoch, tenant-scoped lookup)", async () => {
+    const auth = new m.auth.AuthService();
+    const reg = await auth.register({ workspaceName: "IT Studio", username: ownerUsername, password: "correct-horse-1", displayName: "Owner", email: ownerEmail });
+    expect(reg.me.role).toBe("Owner");
+    expect(reg.me.user.username).toBe(ownerUsername);
+    expect(reg.me.user.email).toBe(ownerEmail);
+    expect(reg.me.permissions).toContain("workspace.members.manage");
+
+    await expect(auth.register({ workspaceName: "Dup", username: ownerUsername, password: "correct-horse-1", displayName: "x" }))
+      .rejects.toMatchObject({ status: 409 });
+    await expect(auth.login({ username: ownerUsername, password: "wrong-password-1" })).rejects.toMatchObject({ status: 401 });
+
+    const login = await auth.login({ username: ownerUsername.toUpperCase(), password: "correct-horse-1" });
+    expect(login.me.workspace.id).toBe(reg.me.workspace.id);
+    await expect(allowed(login.token)).resolves.toBe(true);
+    await expect(allowed(login.token, "audit.view")).resolves.toBe(true);
+  });
+
+  it("registers without an email (username-only accounts)", async () => {
+    const auth = new m.auth.AuthService();
+    const username = `noemail${suffix}`;
+    const reg = await auth.register({ workspaceName: "No Email WS", username, password: "correct-horse-1", displayName: "N" });
+    expect(reg.me.user.email).toBeNull();
+    expect(reg.me.user.username).toBe(username);
+    const login = await auth.login({ username, password: "correct-horse-1" });
+    expect(login.me.user.id).toBe(reg.me.user.id);
+  });
+
+  it("membership mutations bump the epoch but hand the actor a fresh token; last Owner is protected", async () => {
+    const auth = new m.auth.AuthService();
+    const team = new m.team.TeamService();
+    const login = await auth.login({ username: ownerUsername, password: "correct-horse-1" });
+    const session = m.session.verifySession(login.token);
+    if (session === null) throw new Error("session did not verify");
+    const actor = { userId: session.userId, role: session.role };
+
+    const invited = await team.invite(session.workspaceId, actor, `pub-${suffix}@example.com`, "Publisher");
+    expect(invited.member).toMatchObject({ role: "Publisher", status: "invited" });
+    if (invited.token === null || invited.member === null) throw new Error("expected token + member");
+    await expect(allowed(login.token)).resolves.toBe("UnauthorizedException");
+    await expect(allowed(invited.token, "workspace.members.manage")).resolves.toBe(true);
+    const renewed = await auth.reissue(session);
+    expect(m.session.verifySession(renewed.token)?.expiresAt).toBe(session.expiresAt);
+    await expect(allowed(renewed.token, "workspace.members.manage")).resolves.toBe(true);
+    await expect(auth.me(m.session.verifySession(renewed.token)!)).resolves.toMatchObject({ role: "Owner" });
+
+    const changed = await team.changeRole(session.workspaceId, actor, invited.member.id, "Approver");
+    expect(changed.member?.role).toBe("Approver");
+
+    const members = await team.list(session.workspaceId);
+    const owner = members.find((mem) => mem.role === "Owner");
+    if (owner === undefined) throw new Error("owner missing");
+    await expect(team.changeRole(session.workspaceId, actor, owner.id, "Admin")).rejects.toMatchObject({ status: 400 });
+
+    // Invited (password-less) users cannot sign in; placeholder gets a derived username.
+    await expect(auth.login({ username: `pub-${suffix}`, password: "anything-123" })).rejects.toMatchObject({ status: 401 });
+
+    const audit = new m.audit.AuditQueryService();
+    const first = await audit.page(session.workspaceId, { limit: 2 });
+    expect(first.entries).toHaveLength(2);
+    expect(first.entries[0]?.action).toBe("membership.role_changed");
+    expect(first.entries[0]?.diff).toMatchObject({ role: ["Publisher", "Approver"] });
+    expect(first.entries[1]?.action).toBe("membership.invited");
+    expect(first.nextCursor).not.toBeNull();
+    const second = await audit.page(session.workspaceId, { limit: 50, before: first.nextCursor ?? undefined });
+    expect(second.entries.map((e) => e.action)).toEqual(
+      expect.arrayContaining(["session.created", "workspace.created"]),
+    );
+    const filtered = await audit.page(session.workspaceId, { limit: 50, action: "membership.invited" });
+    expect(filtered.entries.every((e) => e.action === "membership.invited")).toBe(true);
+    expect(first.facets.actions).toContain("workspace.created");
+  });
+
+  it("a member without the permission is forbidden", async () => {
+    const auth = new m.auth.AuthService();
+    const username = `analyst${suffix}`;
+    const reg = await auth.register({ workspaceName: "Analyst WS", username, password: "correct-horse-1", displayName: "A" });
+    const team = new m.team.TeamService();
+    const session = m.session.verifySession(reg.token);
+    if (session === null) throw new Error("session did not verify");
+    // Owner of their own workspace may manage members; prove a missing permission is refused.
+    await expect(allowed(reg.token, "permission.that.does.not.exist")).resolves.toBe("ForbiddenException");
+    await expect(team.list(session.workspaceId)).resolves.toHaveLength(1);
+  });
+});
diff --git a/apps/api/src/auth/auth.service.ts b/apps/api/src/auth/auth.service.ts
new file mode 100644
index 0000000..217bcd1
--- /dev/null
+++ b/apps/api/src/auth/auth.service.ts
@@ -0,0 +1,233 @@
+import { randomBytes } from "node:crypto";
+import {
+  BadRequestException,
+  ConflictException,
+  ForbiddenException,
+  Injectable,
+  NotFoundException,
+  UnauthorizedException,
+} from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { withSystem, withTenant } from "../db/client.js";
+import { issueSession, verifySession, type SessionPayload } from "./session.js";
+import { MIN_PASSWORD_LENGTH, burnPasswordCheck, hashPassword, verifyPassword } from "./password.js";
+
+export interface MeResponse {
+  user: { id: string; username: string; email: string | null; displayName: string };
+  workspace: { id: string; name: string; slug: string };
+  role: string;
+  permissions: string[];
+  expiresAt: number;
+}
+
+export interface AuthResult {
+  token: string;
+  me: MeResponse;
+}
+
+export interface RegisterInput {
+  workspaceName: string;
+  username: string;
+  password: string;
+  displayName: string;
+  email?: string;
+}
+
+export interface LoginInput {
+  username: string;
+  password: string;
+  workspaceId?: string;
+}
+
+const USERNAME = /^[a-z0-9][a-z0-9_.-]{1,31}$/;
+
+function normalizeUsername(raw: string): string {
+  const username = raw.trim().toLowerCase();
+  if (!USERNAME.test(username)) {
+    throw new BadRequestException("username must be 2-32 characters: lowercase letters, digits, dot, underscore or hyphen, starting with a letter or digit");
+  }
+  return username;
+}
+
+/**
+ * First-party accounts are keyed `local:<username>`; invited placeholders keep
+ * their `local:<email>` key until an activation flow exists; OIDC users keep
+ * their issuer subject.
+ */
+export function localExternalId(handle: string): string {
+  return `local:${handle.trim().toLowerCase()}`;
+}
+
+function slugify(name: string): string {
+  const base = name
+    .toLowerCase()
+    .normalize("NFKD")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40);
+  return `${base === "" ? "workspace" : base}-${randomBytes(3).toString("hex")}`;
+}
+
+function requirePasswordStrength(password: string): void {
+  if (password.length < MIN_PASSWORD_LENGTH) {
+    throw new BadRequestException(`password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+  }
+}
+
+/**
+ * Re-issue a session for `userId` from the CURRENT membership row and epoch.
+ * Must run inside a tenant transaction for `workspaceId`; callers that just
+ * mutated memberships use it so their own session survives the epoch bump.
+ */
+export async function issueSessionInTenant(
+  client: PoolClient, workspaceId: string, userId: string, expiresAt?: number,
+): Promise<string> {
+  const membership = await client.query(
+    "SELECT role FROM memberships WHERE workspace_id = $1 AND user_id = $2 AND status = 'active'",
+    [workspaceId, userId],
+  );
+  const role = membership.rows[0]?.role as string | undefined;
+  if (role === undefined) throw new ForbiddenException("no active membership in this workspace");
+  const ws = await client.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [workspaceId]);
+  const epoch = ws.rows[0]?.authz_epoch as string | number | undefined;
+  if (epoch === undefined) throw new NotFoundException("workspace not found");
+  const remaining = expiresAt === undefined ? undefined : Math.max(0, expiresAt - Math.floor(Date.now() / 1000));
+  return issueSession({ userId, workspaceId, role, authzEpoch: Number(epoch) }, remaining);
+}
+
+@Injectable()
+export class AuthService {
+  async register(input: RegisterInput): Promise<AuthResult> {
+    requirePasswordStrength(input.password);
+    const passwordHash = await hashPassword(input.password);
+    const username = normalizeUsername(input.username);
+    const externalId = localExternalId(username);
+
+    const created = await withSystem(async (client) => {
+      // Existing identities (including invited, password-less users) cannot be
+      // claimed by registering: without verified contact channels that would
+      // let anyone attach a password to someone else's pending invitation.
+      const user = await client.query(
+        `INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (external_id) DO NOTHING
+         RETURNING id`,
+        [externalId, username, input.email ?? null, input.displayName],
+      );
+      const userId = user.rows[0]?.id as string | undefined;
+      if (userId === undefined) throw new ConflictException("an account with this username already exists — sign in instead");
+      await client.query("INSERT INTO user_passwords (user_id, password_hash) VALUES ($1, $2)", [userId, passwordHash]);
+
+      const ws = await client.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id, slug", [
+        input.workspaceName,
+        slugify(input.workspaceName),
+      ]);
+      const workspaceId = ws.rows[0]?.id as string;
+      // Enter the new tenant's context for the RLS-protected membership insert.
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      await client.query(
+        "INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, 'Owner', 'active')",
+        [workspaceId, userId],
+      );
+      const token = await issueSessionInTenant(client, workspaceId, userId);
+      return { userId, workspaceId, slug: ws.rows[0]?.slug as string, token };
+    });
+
+    await appendTenantAudit(created.workspaceId, {
+      actorUserId: created.userId,
+      actorRole: "Owner",
+      action: "workspace.created",
+      targetType: "workspace",
+      targetId: created.workspaceId,
+      diff: { name: input.workspaceName, slug: created.slug },
+    });
+    return { token: created.token, me: await this.meFor(created.workspaceId, created.userId, created.token) };
+  }
+
+  async login(input: LoginInput): Promise<AuthResult> {
+    const username = normalizeUsername(input.username);
+    const found = await withSystem((client) =>
+      client.query(
+        `SELECT u.id, p.password_hash FROM users u
+         LEFT JOIN user_passwords p ON p.user_id = u.id
+         WHERE u.external_id = $1`,
+        [localExternalId(username)],
+      ),
+    );
+    const row = found.rows[0] as { id: string; password_hash: string | null } | undefined;
+    if (row === undefined || row.password_hash === null) {
+      await burnPasswordCheck(input.password);
+      throw new UnauthorizedException("invalid email or password");
+    }
+    if (!(await verifyPassword(input.password, row.password_hash))) {
+      throw new UnauthorizedException("invalid email or password");
+    }
+
+    const memberships = await withSystem((client) =>
+      client.query("SELECT workspace_id, role, status FROM auth_user_memberships($1)", [row.id]),
+    );
+    const active = (memberships.rows as Array<{ workspace_id: string; status: string }>).filter((m) => m.status === "active");
+    const chosen = input.workspaceId === undefined ? active[0] : active.find((m) => m.workspace_id === input.workspaceId);
+    if (chosen === undefined) throw new ForbiddenException("no active workspace membership for this account");
+
+    const token = await withTenant(chosen.workspace_id, (client) => issueSessionInTenant(client, chosen.workspace_id, row.id));
+    const me = await this.meFor(chosen.workspace_id, row.id, token);
+    await appendTenantAudit(chosen.workspace_id, {
+      actorUserId: row.id,
+      actorRole: me.role,
+      action: "session.created",
+      targetType: "user",
+      targetId: row.id,
+      diff: { method: "password" },
+    });
+    return { token, me };
+  }
+
+  async me(session: SessionPayload): Promise<MeResponse> {
+    return this.meFor(session.workspaceId, session.userId, null, session.expiresAt);
+  }
+
+  async reissue(session: SessionPayload): Promise<AuthResult> {
+    let token: string;
+    try {
+      token = await withTenant(session.workspaceId, (client) =>
+        issueSessionInTenant(client, session.workspaceId, session.userId, session.expiresAt),
+      );
+    } catch (error) {
+      if (error instanceof ForbiddenException || error instanceof NotFoundException) {
+        throw new UnauthorizedException("membership no longer active");
+      }
+      throw error;
+    }
+    return { token, me: await this.meFor(session.workspaceId, session.userId, token) };
+  }
+
+  private async meFor(workspaceId: string, userId: string, token: string | null, expiresAt?: number): Promise<MeResponse> {
+    return withTenant(workspaceId, async (client) => {
+      const res = await client.query(
+        `SELECT m.role, u.username, u.email, u.display_name, w.name, w.slug
+         FROM memberships m
+         JOIN users u ON u.id = m.user_id
+         JOIN workspaces w ON w.id = m.workspace_id
+         WHERE m.workspace_id = $1 AND m.user_id = $2 AND m.status = 'active'`,
+        [workspaceId, userId],
+      );
+      const row = res.rows[0] as { role: string; username: string; email: string | null; display_name: string; name: string; slug: string } | undefined;
+      if (row === undefined) throw new UnauthorizedException("membership no longer active");
+      const perms = await client.query("SELECT permission FROM role_permissions WHERE role = $1 ORDER BY permission", [row.role]);
+      return {
+        user: { id: userId, username: row.username, email: row.email, displayName: row.display_name },
+        workspace: { id: workspaceId, name: row.name, slug: row.slug },
+        role: row.role,
+        permissions: (perms.rows as Array<{ permission: string }>).map((p) => p.permission),
+        expiresAt: expiresAt ?? expiryOf(token),
+      };
+    });
+  }
+}
+
+function expiryOf(token: string | null): number {
+  if (token === null) return 0;
+  return verifySession(token)?.expiresAt ?? 0;
+}
diff --git a/apps/api/src/auth/oidc.test.ts b/apps/api/src/auth/oidc.test.ts
new file mode 100644
index 0000000..2604e57
--- /dev/null
+++ b/apps/api/src/auth/oidc.test.ts
@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { OidcClient } from "./oidc.js";
+
+function fakeFetch(responses: Record<string, unknown>): typeof fetch {
+  return (async (input: string | URL | unknown) => {
+    const url = String(input);
+    for (const [match, body] of Object.entries(responses)) {
+      if (url.includes(match)) return new Response(JSON.stringify(body), { status: 200 });
+    }
+    return new Response("not found", { status: 404 });
+  }) as unknown as typeof fetch;
+}
+
+describe("oidc client", () => {
+  const config = {
+    issuer: "https://idp.example",
+    clientId: "client-1",
+    clientSecret: "secret-1",
+    redirectUri: "http://localhost:3000/auth/callback",
+  };
+
+  it("builds authorization URL with PKCE S256", async () => {
+    const client = new OidcClient(config, fakeFetch({
+      "well-known": {
+        authorization_endpoint: "https://idp.example/auth",
+        token_endpoint: "https://idp.example/token",
+      },
+    }));
+    const url = await client.authorizationUrl("state-123", "challenge-abc");
+    const parsed = new URL(url);
+    expect(parsed.searchParams.get("code_challenge")).toBe("challenge-abc");
+    expect(parsed.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(parsed.searchParams.get("state")).toBe("state-123");
+    expect(parsed.searchParams.get("client_id")).toBe("client-1");
+  });
+
+  it("exchanges code with verifier + client secret", async () => {
+    const holder: { params?: URLSearchParams } = {};
+    const fetchMock = (async (input: string | URL | unknown, init?: RequestInit) => {
+      if (String(input).includes("token")) {
+        holder.params = new URLSearchParams(String(init?.body));
+        return new Response(JSON.stringify({ access_token: "at", id_token: "it" }), { status: 200 });
+      }
+      return new Response(JSON.stringify({
+        authorization_endpoint: "https://idp.example/auth",
+        token_endpoint: "https://idp.example/token",
+      }), { status: 200 });
+    }) as unknown as typeof fetch;
+    const client = new OidcClient(config, fetchMock);
+    const tokens = await client.exchangeCode("code-1", "verifier-xyz");
+    expect(tokens.accessToken).toBe("at");
+    expect(holder.params?.get("code_verifier")).toBe("verifier-xyz");
+    expect(holder.params?.get("client_secret")).toBe("secret-1");
+  });
+});
diff --git a/apps/api/src/auth/oidc.ts b/apps/api/src/auth/oidc.ts
new file mode 100644
index 0000000..a7e2865
--- /dev/null
+++ b/apps/api/src/auth/oidc.ts
@@ -0,0 +1,78 @@
+/**
+ * Generic OIDC code flow with PKCE, discovery-document driven.
+ * Production: Authentik/Keycloak/any compliant issuer via env.
+ * Tests: mock the discovery + token endpoints via fetch override.
+ */
+
+export interface OidcConfig {
+  issuer: string;
+  clientId: string;
+  clientSecret: string;
+  redirectUri: string;
+}
+
+export function oidcConfigFromEnv(): OidcConfig | null {
+  const issuer = process.env.OIDC_ISSUER;
+  if (issuer === undefined || issuer === "") return null;
+  return {
+    issuer,
+    clientId: process.env.OIDC_CLIENT_ID ?? "",
+    clientSecret: process.env.OIDC_CLIENT_SECRET ?? "",
+    redirectUri: process.env.OIDC_REDIRECT_URI ?? "http://localhost:3000/auth/callback",
+  };
+}
+
+interface DiscoveryDoc {
+  authorization_endpoint: string;
+  token_endpoint: string;
+  userinfo_endpoint?: string;
+}
+
+export type FetchLike = typeof fetch;
+
+export class OidcClient {
+  private discovery: DiscoveryDoc | null = null;
+
+  constructor(private readonly config: OidcConfig, private readonly fetchImpl: FetchLike = fetch) {}
+
+  private async discover(): Promise<DiscoveryDoc> {
+    if (this.discovery !== null) return this.discovery;
+    const res = await this.fetchImpl(`${this.config.issuer.replace(/\/$/, "")}/.well-known/openid-configuration`);
+    if (!res.ok) throw new Error(`discovery failed: HTTP ${res.status}`);
+    this.discovery = (await res.json()) as DiscoveryDoc;
+    return this.discovery;
+  }
+
+  authorizationUrl(state: string, codeChallenge: string): Promise<string> {
+    return this.discover().then((d) => {
+      const url = new URL(d.authorization_endpoint);
+      url.searchParams.set("client_id", this.config.clientId);
+      url.searchParams.set("response_type", "code");
+      url.searchParams.set("scope", "openid profile email");
+      url.searchParams.set("redirect_uri", this.config.redirectUri);
+      url.searchParams.set("state", state);
+      url.searchParams.set("code_challenge", codeChallenge);
+      url.searchParams.set("code_challenge_method", "S256");
+      return url.toString();
+    });
+  }
+
+  async exchangeCode(code: string, codeVerifier: string): Promise<{ accessToken: string; idToken: string }> {
+    const d = await this.discover();
+    const res = await this.fetchImpl(d.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        redirect_uri: this.config.redirectUri,
+        code_verifier: codeVerifier,
+      }),
+    });
+    if (!res.ok) throw new Error(`token exchange failed: HTTP ${res.status}`);
+    const token = (await res.json()) as { access_token: string; id_token: string };
+    return { accessToken: token.access_token, idToken: token.id_token };
+  }
+}
diff --git a/apps/api/src/auth/password.test.ts b/apps/api/src/auth/password.test.ts
new file mode 100644
index 0000000..b3d5727
--- /dev/null
+++ b/apps/api/src/auth/password.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import { hashPassword, verifyPassword } from "./password.js";
+
+describe("password hashing", () => {
+  it("round-trips and rejects the wrong password", async () => {
+    const encoded = await hashPassword("correct-horse-battery");
+    expect(encoded.startsWith("scrypt$")).toBe(true);
+    expect(encoded).not.toContain("correct-horse-battery");
+    await expect(verifyPassword("correct-horse-battery", encoded)).resolves.toBe(true);
+    await expect(verifyPassword("correct-horse-batterz", encoded)).resolves.toBe(false);
+  });
+
+  it("salts every hash", async () => {
+    const [a, b] = await Promise.all([hashPassword("same-password-1"), hashPassword("same-password-1")]);
+    expect(a).not.toBe(b);
+  });
+
+  it("fails closed on malformed encodings", async () => {
+    await expect(verifyPassword("x", "")).resolves.toBe(false);
+    await expect(verifyPassword("x", "bcrypt$1$2$3$aa$bb")).resolves.toBe(false);
+    await expect(verifyPassword("x", "scrypt$0$8$1$aa$bb")).resolves.toBe(false);
+  });
+});
diff --git a/apps/api/src/auth/password.ts b/apps/api/src/auth/password.ts
new file mode 100644
index 0000000..91e6955
--- /dev/null
+++ b/apps/api/src/auth/password.ts
@@ -0,0 +1,46 @@
+import { randomBytes, scrypt, timingSafeEqual } from "node:crypto";
+
+/**
+ * scrypt password hashing. Encoded as `scrypt$N$r$p$salt$hash` (base64url) so
+ * cost parameters can be raised later without invalidating stored hashes.
+ */
+
+const N = 16384;
+const R = 8;
+const P = 1;
+const KEYLEN = 32;
+export const MIN_PASSWORD_LENGTH = 10;
+
+function derive(password: string, salt: Buffer, n: number, r: number, p: number): Promise<Buffer> {
+  return new Promise((resolve, reject) => {
+    scrypt(password, salt, KEYLEN, { N: n, r, p, maxmem: 64 * 1024 * 1024 }, (err, key) => {
+      if (err !== null) reject(err);
+      else resolve(key);
+    });
+  });
+}
+
+export async function hashPassword(password: string): Promise<string> {
+  const salt = randomBytes(16);
+  const key = await derive(password, salt, N, R, P);
+  return `scrypt$${N}$${R}$${P}$${salt.toString("base64url")}$${key.toString("base64url")}`;
+}
+
+export async function verifyPassword(password: string, encoded: string): Promise<boolean> {
+  const parts = encoded.split("$");
+  if (parts.length !== 6 || parts[0] !== "scrypt") return false;
+  const [n, r, p] = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
+  if (![n, r, p].every((v) => Number.isInteger(v) && v > 0)) return false;
+  const salt = Buffer.from(parts[4] ?? "", "base64url");
+  const expected = Buffer.from(parts[5] ?? "", "base64url");
+  if (expected.length !== KEYLEN) return false;
+  const actual = await derive(password, salt, n, r, p);
+  return timingSafeEqual(actual, expected);
+}
+
+/** Burn equivalent CPU when the user does not exist, so login timing does not reveal account existence. */
+let dummyHash: Promise<string> | undefined;
+export async function burnPasswordCheck(password: string): Promise<void> {
+  dummyHash ??= hashPassword("timing-equalizer-not-a-real-password");
+  await verifyPassword(password, await dummyHash);
+}
diff --git a/apps/api/src/auth/reissue.test.ts b/apps/api/src/auth/reissue.test.ts
new file mode 100644
index 0000000..c35a707
--- /dev/null
+++ b/apps/api/src/auth/reissue.test.ts
@@ -0,0 +1,46 @@
+import type { PoolClient } from "pg";
+import { describe, expect, it, vi } from "vitest";
+import { AuthService } from "./auth.service.js";
+import { issueSession, verifySession } from "./session.js";
+
+const workspaceId = "10000000-0000-4000-8000-000000000001";
+const userId = "20000000-0000-4000-8000-000000000002";
+let role = "Publisher";
+let epoch = 1;
+let active = true;
+
+vi.mock("../db/client.js", () => ({
+  withTenant: async (_workspaceId: string, fn: (client: PoolClient) => Promise<unknown>) => fn({
+    query: async (sql: string) => {
+      if (sql.includes("SELECT role FROM memberships")) return { rows: active ? [{ role }] : [] };
+      if (sql.includes("SELECT authz_epoch FROM workspaces")) return { rows: [{ authz_epoch: String(epoch) }] };
+      if (sql.includes("SELECT m.role, u.username")) return { rows: active ? [{ role, username: "user", email: "user@example.com", display_name: "User", name: "Studio", slug: "studio" }] : [] };
+      if (sql.includes("SELECT permission FROM role_permissions")) return { rows: [{ permission: "draft.view" }] };
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  } as PoolClient),
+  withSystem: vi.fn(),
+}));
+
+describe("session reissue", () => {
+  it("refreshes a stale epoch and live role without extending the session expiry", async () => {
+    active = true;
+    role = "Publisher";
+    epoch = 1;
+    const old = verifySession(issueSession({ userId, workspaceId, role, authzEpoch: epoch }));
+    if (old === null) throw new Error("failed to issue test session");
+    role = "Approver";
+    epoch = 2;
+    const result = await new AuthService().reissue(old);
+    expect(result.me.role).toBe("Approver");
+    expect(result.me.permissions).toContain("draft.view");
+    expect(verifySession(result.token)).toMatchObject({ userId, workspaceId, role: "Approver", authzEpoch: 2, expiresAt: old.expiresAt });
+  });
+
+  it("refuses an inactive membership", async () => {
+    active = false;
+    const old = verifySession(issueSession({ userId, workspaceId, role: "Publisher", authzEpoch: 1 }));
+    if (old === null) throw new Error("failed to issue test session");
+    await expect(new AuthService().reissue(old)).rejects.toMatchObject({ status: 401 });
+  });
+});
diff --git a/apps/api/src/auth/session.test.ts b/apps/api/src/auth/session.test.ts
new file mode 100644
index 0000000..9c7b967
--- /dev/null
+++ b/apps/api/src/auth/session.test.ts
@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { issueSession, verifySession, epochValid } from "./session.js";
+
+describe("session tokens", () => {
+  it("issues and verifies", () => {
+    const token = issueSession({ userId: "u1", workspaceId: "ws1", role: "Publisher", authzEpoch: 3 });
+    const payload = verifySession(token);
+    expect(payload?.userId).toBe("u1");
+    expect(payload?.workspaceId).toBe("ws1");
+  });
+
+  it("rejects tampering", () => {
+    const token = issueSession({ userId: "u1", workspaceId: "ws1", role: "Publisher", authzEpoch: 3 });
+    const tampered = `${token.slice(0, -3)}xxx`;
+    expect(verifySession(tampered)).toBeNull();
+  });
+
+  it("epoch fence fails closed on mismatch (finding #2)", () => {
+    const token = issueSession({ userId: "u1", workspaceId: "ws1", role: "Publisher", authzEpoch: 3 });
+    const payload = verifySession(token);
+    if (payload === null) throw new Error("unreachable");
+    expect(epochValid(payload, 3)).toBe(true);
+    expect(epochValid(payload, 4)).toBe(false);
+  });
+});
diff --git a/apps/api/src/auth/session.ts b/apps/api/src/auth/session.ts
new file mode 100644
index 0000000..f6c5d33
--- /dev/null
+++ b/apps/api/src/auth/session.ts
@@ -0,0 +1,60 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+/**
+ * Session tokens: HMAC-signed, workspace-scoped, epoch-fenced.
+ * authzEpoch fail-closed: any membership/role change bumps the workspace
+ * epoch (see 001_tenants.sql trigger) and the session stops validating —
+ * this is the continuous-authz fix for audit finding #2.
+ */
+
+export interface SessionPayload {
+  userId: string;
+  workspaceId: string;
+  role: string;
+  authzEpoch: number;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+function secret(): string {
+  const s = process.env.SESSION_SECRET;
+  if (s !== undefined && s !== "") return s;
+  if (process.env.NODE_ENV === "production") throw new Error("SESSION_SECRET required in production");
+  return "dev-session-secret";
+}
+
+function sign(data: string): string {
+  return createHmac("sha256", secret()).update(data).digest("base64url");
+}
+
+export function issueSession(payload: Omit<SessionPayload, "issuedAt" | "expiresAt">, ttlSeconds = 12 * 3600): string {
+  const full: SessionPayload = {
+    ...payload,
+    issuedAt: Math.floor(Date.now() / 1000),
+    expiresAt: Math.floor(Date.now() / 1000) + ttlSeconds,
+  };
+  const body = Buffer.from(JSON.stringify(full)).toString("base64url");
+  return `${body}.${sign(body)}`;
+}
+
+export function verifySession(token: string): SessionPayload | null {
+  const dot = token.lastIndexOf(".");
+  if (dot === -1) return null;
+  const body = token.slice(0, dot);
+  const mac = token.slice(dot + 1);
+  const expected = sign(body);
+  if (mac.length !== expected.length) return null;
+  if (!timingSafeEqual(Buffer.from(mac), Buffer.from(expected))) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(body, "base64url").toString("utf8")) as SessionPayload;
+    if (payload.expiresAt < Math.floor(Date.now() / 1000)) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/** Fail-closed epoch check: the caller passes the workspace's CURRENT epoch from the DB. */
+export function epochValid(session: SessionPayload, currentEpoch: number): boolean {
+  return session.authzEpoch === currentEpoch;
+}
diff --git a/apps/api/src/chatgov/chatgov.controller.ts b/apps/api/src/chatgov/chatgov.controller.ts
new file mode 100644
index 0000000..be807fa
--- /dev/null
+++ b/apps/api/src/chatgov/chatgov.controller.ts
@@ -0,0 +1,100 @@
+import { Body, Controller, Delete, Get, Inject, Param, Patch, Post, Query, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { parseId, requireObject, requireSession } from "../http/validation.js";
+import { CHATGOV_PERMISSIONS } from "./policy.js";
+import { PolicyService, type PolicyActor, type RuleRecord } from "./policy.service.js";
+import { GateService, type GateDecisionRecord, type RecordGateInput } from "./gate.service.js";
+
+/**
+ * Chat governance console API (§5): rules editor + gate decision reads.
+ * The command router (/poll, /tally, …) is P3 and does NOT live here.
+ *
+ * Permission model (§6): chatgov.manage gates every rule mutation; reads are
+ * workspace.view-shaped (any member sees the policy that governs them).
+ */
+@Controller("chatgov")
+@UseGuards(RbacGuard)
+export class ChatgovController {
+  constructor(
+    @Inject(PolicyService) private readonly policy: PolicyService,
+    @Inject(GateService) private readonly gates: GateService,
+  ) {}
+
+  @Get("rules")
+  @RequirePermission("workspace.view")
+  async listRules(
+    @Req() request: Request & AuthenticatedRequest,
+    @Query("accountId") accountId: string | undefined,
+    @Query("topicBindingId") topicBindingId: string | undefined,
+  ): Promise<RuleRecord[]> {
+    return this.policy.listRules(requireSession(request).workspaceId, {
+      ...(accountId === undefined || accountId === "" ? {} : { accountId }),
+      ...(topicBindingId === undefined || topicBindingId === "" ? {} : { topicBindingId }),
+    });
+  }
+
+  @Post("rules")
+  @RequirePermission(CHATGOV_PERMISSIONS.manage)
+  async createRule(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<RuleRecord> {
+    return this.policy.createRule(requireSession(request).workspaceId, body, actorOf(request));
+  }
+
+  @Patch("rules/:id")
+  @RequirePermission(CHATGOV_PERMISSIONS.manage)
+  async updateRule(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+    @Body() body: unknown,
+  ): Promise<RuleRecord> {
+    return this.policy.updateRule(requireSession(request).workspaceId, parseId(id, "id"), body, actorOf(request));
+  }
+
+  @Delete("rules/:id")
+  @RequirePermission(CHATGOV_PERMISSIONS.manage)
+  async deleteRule(@Req() request: Request & AuthenticatedRequest, @Param("id") id: string): Promise<{ superseded: boolean }> {
+    return this.policy.deleteRule(requireSession(request).workspaceId, parseId(id, "id"), actorOf(request));
+  }
+
+  /** Blocked-queue / draft timeline feed (P6 renders it). */
+  @Get("decisions/draft/:draftId")
+  @RequirePermission("draft.view")
+  async decisionsForDraft(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+  ): Promise<GateDecisionRecord[]> {
+    return this.gates.listForDraft(requireSession(request).workspaceId, parseId(draftId, "draftId"));
+  }
+
+  /**
+   * Internal write path for the Temporal E3 worker / E1 review hook (P1).
+   * Service-to-service in v1: the route exists so the seam is testable, and is
+   * gated on chatgov.manage (an Owner/Admin console action in practice).
+   */
+  @Post("decisions")
+  @RequirePermission(CHATGOV_PERMISSIONS.manage)
+  async recordDecision(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<GateDecisionRecord> {
+    const dto = requireObject(body, "body");
+    const session = requireSession(request);
+    return this.gates.record(session.workspaceId, {
+      draftId: String(dto.draftId),
+      destination: dto.destination as RecordGateInput["destination"],
+      gate: dto.gate as RecordGateInput["gate"],
+      ...(dto.ruleId === undefined || dto.ruleId === null ? {} : { ruleId: String(dto.ruleId) }),
+      policyVersion: String(dto.policyVersion),
+      outcome: dto.outcome as RecordGateInput["outcome"],
+      inputs: (dto.inputs ?? {}) as RecordGateInput["inputs"],
+      reasonCodes: Array.isArray(dto.reasonCodes) ? (dto.reasonCodes as unknown[]).filter((c): c is RecordGateInput["reasonCodes"][number] => typeof c === "string") : [],
+      actor: typeof dto.actor === "string" ? dto.actor : `user:${session.userId}`,
+      ...(dto.pollId === undefined || dto.pollId === null ? {} : { pollId: String(dto.pollId) }),
+    });
+  }
+}
+
+function actorOf(request: Request & AuthenticatedRequest): PolicyActor {
+  const session = requireSession(request);
+  // The route decorator already enforced chatgov.manage; `permissions` is left
+  // unset so the service's defense-in-depth check treats the controller as the
+  // privileged caller (it re-checks only for non-controller callers).
+  return { userId: session.userId, role: session.role };
+}
diff --git a/apps/api/src/chatgov/chatgov.integration.test.ts b/apps/api/src/chatgov/chatgov.integration.test.ts
new file mode 100644
index 0000000..7af7700
--- /dev/null
+++ b/apps/api/src/chatgov/chatgov.integration.test.ts
@@ -0,0 +1,710 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * chatgov P0 spine against a live PostgreSQL (chatgov-design.md §7 DoD):
+ *  - migration idempotency (re-run applies nothing)
+ *  - RLS denial for EVERY new table (workspace B sees/updates/deletes zero A
+ *    rows, and B cannot write into A's workspace — WITH CHECK)
+ *  - rule CRUD + one-live-rule-per-slot
+ *  - policy compile -> posting_policy_snapshots with a deterministic version
+ *  - RBAC permission gating (chatgov.manage; Editor is denied, Admin allowed)
+ *  - audit event landing (policy.revised / policy.gate in audit_log)
+ *
+ * Owns its own database (CHATGOV_IT_DATABASE_URL + CHATGOV_IT_SUPER_DATABASE_URL,
+ * local-db-sol.env pattern) because the shared tenancy DB is wiped by other
+ * suites and vitest runs files in parallel. Skips cleanly when unset.
+ */
+const appUrl = process.env.CHATGOV_IT_DATABASE_URL;
+const ownerUrl = process.env.CHATGOV_IT_SUPER_DATABASE_URL;
+const dbAvailable = appUrl !== undefined && ownerUrl !== undefined;
+
+const RLS_VIOLATION = "42501";
+const UNIQUE_VIOLATION = "23505";
+const FK_VIOLATION = "23503";
+const TABLES = [
+  "polls",
+  "poll_votes",
+  "posting_rules",
+  "posting_policy_snapshots",
+  "topic_bindings",
+  "chat_command_audit",
+  "chat_identities",
+  "gate_decisions",
+] as const;
+
+type Modules = {
+  policy: typeof import("./policy.js");
+  policyService: typeof import("./policy.service.js");
+  gate: typeof import("./gate.service.js");
+  db: typeof import("../db/client.js");
+  guard: typeof import("../rbac/rbac.guard.js");
+  session: typeof import("../auth/session.js");
+};
+
+describe.skipIf(!dbAvailable)("chatgov P0 spine (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let wsA: string;
+  let wsB: string;
+  let userA: string;
+  let connA1: string;
+  let connA2: string;
+  let connB: string;
+  let topicA: string;
+  let draftA: string;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  /** Seed tenant rows honestly: FORCE RLS applies to the owner too. */
+  async function inTenant(client: PoolClient, wsId: string, fn: () => Promise<void>): Promise<void> {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [wsId]);
+    await fn();
+    await client.query("COMMIT");
+  }
+
+  beforeAll(async () => {
+    // The shared pool reads DATABASE_URL at import time: point it at this
+    // isolated DB first, then import the modules under test.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    // Idempotency: the CLI already applied every migration; re-running must
+    // apply nothing (schema_migrations guards).
+    const applied = await runMigrations(join(process.cwd(), "migrations"));
+    expect(applied).toEqual([]);
+
+    m = {
+      policy: await import("./policy.js"),
+      policyService: await import("./policy.service.js"),
+      gate: await import("./gate.service.js"),
+      db: await import("../db/client.js"),
+      guard: await import("../rbac/rbac.guard.js"),
+      session: await import("../auth/session.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    await asOwner(async (c) => {
+      const ws = async (name: string): Promise<string> =>
+        (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", [name, `${name}-${suffix}`])).rows[0].id as string;
+      wsA = await ws("cg-a");
+      wsB = await ws("cg-b");
+      const user = async (name: string): Promise<string> =>
+        (await c.query(
+          "INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4) RETURNING id",
+          [`cg:${name}:${suffix}`, `cg-${name}-${suffix}`, `${name}-${suffix}@example.com`, name],
+        )).rows[0].id as string;
+      userA = await user("owner");
+      const editorA = await user("editor");
+
+      const conn = async (wsId: string, name: string): Promise<string> =>
+        (await c.query(
+          "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id",
+          [wsId, `ch-${name}`],
+        )).rows[0].id as string;
+      connA1 = await conn(wsA, "a1");
+      connA2 = await conn(wsA, "a2");
+      connB = await conn(wsB, "b1");
+
+      await inTenant(c, wsA, async () => {
+        await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Owner')", [wsA, userA]);
+        await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Editor')", [wsA, editorA]);
+        draftA = (await c.query("INSERT INTO drafts (workspace_id, author_user_id, post) VALUES ($1, $2, $3::jsonb) RETURNING id", [wsA, userA, JSON.stringify({ body: "x" })])).rows[0].id as string;
+        topicA = (await c.query(
+          `INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, message_thread_id, binding_type, name, account_ids, icon_color)
+           VALUES ($1, $2, '-100200', '7', 'announce', 'Ops', $3, 7322096) RETURNING id`,
+          [wsA, connA1, [connA1]],
+        )).rows[0].id as string;
+        // Seed rows for the RLS denial suite (A-side data B must not see).
+        const poll = (await c.query(
+          `INSERT INTO polls (workspace_id, channel_id, topic_binding_id, subject_kind, draft_id, question, rule, policy_version, closes_at, created_by)
+           VALUES ($1, NULL, $2, 'draft', $3, 'ship it?', $4::jsonb, 'pv-seed', now() + interval '1 hour', $5) RETURNING id`,
+          [wsA, topicA, draftA, JSON.stringify({ version: 1, mode: "quorum", arms: [{ kind: "admins", x: 1 }], timebox: { duration: "PT1H", onExpire: "reject" } }), userA],
+        )).rows[0].id as string;
+        await c.query(
+          `INSERT INTO poll_votes (poll_id, workspace_id, voter_kind, voter_user_id, voter_remote_id, voter_handle, ballot)
+           VALUES ($1, $2, 'chat_identity', $3, '424242', 'opal', 'yes')`,
+          [poll, wsA, userA],
+        );
+        await c.query(
+          `INSERT INTO chat_identities (workspace_id, provider, remote_user_id, user_id, display_name, status, approved_by)
+           VALUES ($1, 'telegram', '111222333', $2, 'Opal', 'approved', $2)`,
+          [wsA, userA],
+        );
+        await c.query(
+          `INSERT INTO chat_command_audit (workspace_id, update_id, binding_id, provider, remote_user_id, user_id, command, args, permission, decision)
+           VALUES ($1, 9001, $2, 'telegram', '111222333', $3, '/tally', '{}'::jsonb, 'director.view', 'accepted')`,
+          [wsA, topicA, userA],
+        );
+        // one row of every remaining table so the RLS sweep counts real data
+        await c.query(
+          `INSERT INTO posting_rules (workspace_id, scope, policy, policy_version, created_by)
+           VALUES ($1, 'workspace', $2::jsonb, 'pv-seed', $3)`,
+          [wsA, JSON.stringify({ version: 1, mode: "immediate" }), userA],
+        );
+        await c.query(
+          `INSERT INTO posting_policy_snapshots (workspace_id, destination_kind, account_id, topic_binding_id, content_type, effective, policy_version, resolved_from)
+           VALUES ($1, 'account', $2, NULL, '', $3::jsonb, 'pv-seed', '{"scopes":["workspace"]}'::jsonb)`,
+          [wsA, connA1, JSON.stringify({ version: 1, mode: "immediate" })],
+        );
+        await c.query(
+          `INSERT INTO gate_decisions (workspace_id, draft_id, destination, gate, policy_version, outcome, inputs, reason_codes, actor)
+           VALUES ($1, $2, $3::jsonb, 'E1', 'pv-seed', 'fired', '{}'::jsonb, '{}', 'system:gate-e1')`,
+          [wsA, draftA, JSON.stringify({ platform: "telegram", accountId: connA1 })],
+        );
+      });
+      await inTenant(c, wsB, async () => {
+        const ownerB = await user("owner-b");
+        await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Owner')", [wsB, ownerB]);
+      });
+    });
+  }, 60_000);
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE slug LIKE $1", [`%-${suffix}`]);
+        await c.query("DELETE FROM users WHERE external_id LIKE $1", [`cg:%:${suffix}`]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  // -------------------------------------------------------------------------
+  describe("migration + RBAC seed", () => {
+    it("idempotent: a second run applies nothing", async () => {
+      const { runMigrations } = await import("../db/migrate.js");
+      const previous = process.env.SUPER_DATABASE_URL;
+      process.env.SUPER_DATABASE_URL = ownerUrl;
+      try {
+        expect(await runMigrations(join(process.cwd(), "migrations"))).toEqual([]);
+      } finally {
+        process.env.SUPER_DATABASE_URL = previous;
+      }
+    });
+
+    it("chatgov permissions are seeded per the 002 pattern", async () => {
+      const rows = await asOwner((c) => c.query<{ role: string; permission: string }>(
+        "SELECT role, permission FROM role_permissions WHERE permission LIKE 'chatgov%' ORDER BY role, permission"),
+      );
+      const map = new Map<string, string[]>();
+      for (const row of rows.rows) {
+        map.set(row.role, [...(map.get(row.role) ?? []), row.permission]);
+      }
+      expect(map.get("Owner")).toEqual(["chatgov.manage", "chatgov.vote"]);
+      expect(map.get("Admin")).toEqual(["chatgov.manage", "chatgov.vote"]);
+      for (const role of ["Publisher", "Editor", "Approver", "Moderator", "BroadcastOperator"]) {
+        expect(map.get(role)).toEqual(["chatgov.vote"]);
+      }
+      for (const role of ["Analyst", "VideoPublisher", "StreamOperator"]) {
+        expect(map.has(role)).toBe(false);
+      }
+    });
+
+    it("every new table is RLS-enabled AND forced with a tenant_isolation policy", async () => {
+      for (const table of TABLES) {
+        const flags = await asOwner((c) => c.query<{ relrowsecurity: boolean; relforcerowsecurity: boolean }>(
+          "SELECT relrowsecurity, relforcerowsecurity FROM pg_class WHERE oid = $1::regclass", [table]));
+        expect(flags.rows[0], table).toEqual({ relrowsecurity: true, relforcerowsecurity: true });
+        const policies = await asOwner((c) => c.query<{ policyname: string }>(
+          "SELECT policyname FROM pg_policies WHERE tablename = $1", [table]));
+        expect(policies.rows.map((r) => r.policyname), table).toContain("tenant_isolation");
+      }
+    });
+
+    it("sp_app holds table grants (and is neither superuser nor BYPASSRLS)", async () => {
+      for (const table of TABLES) {
+        const grants = await asOwner((c) => c.query<{ privilege_type: string }>(
+          "SELECT privilege_type FROM information_schema.role_table_grants WHERE grantee = 'sp_app' AND table_name = $1", [table]));
+        expect(new Set(grants.rows.map((r) => r.privilege_type)), table)
+          .toEqual(new Set(["SELECT", "INSERT", "UPDATE", "DELETE"]));
+      }
+      const role = await asOwner((c) => c.query<{ rolsuper: boolean; rolbypassrls: boolean }>(
+        "SELECT rolsuper, rolbypassrls FROM pg_roles WHERE rolname = 'sp_app'"));
+      expect(role.rows[0]).toEqual({ rolsuper: false, rolbypassrls: false });
+    });
+  });
+
+  /** Fresh workspace with its own connections/topic (isolated rule slots). */
+  async function seedWorkspace(name: string): Promise<{ ws: string; conn1: string; conn2: string; topic: string }> {
+    return asOwner(async (c) => {
+      const ws = (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", [`cg-${name}`, `cg-${name}-${suffix}`])).rows[0].id as string;
+      let conn1 = "";
+      let conn2 = "";
+      let topic = "";
+      await inTenant(c, ws, async () => {
+        await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Owner')", [ws, userA]);
+        conn1 = (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id", [ws, `ch-${name}-1`])).rows[0].id as string;
+        conn2 = (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id", [ws, `ch-${name}-2`])).rows[0].id as string;
+        topic = (await c.query(
+          `INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, message_thread_id, binding_type, name, account_ids)
+           VALUES ($1, $2, '-100200', '7', 'announce', 'Ops', $3) RETURNING id`,
+          [ws, conn1, [conn1]])).rows[0].id as string;
+      });
+      return { ws, conn1, conn2, topic };
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  describe("RLS denial suite (FORCE + NULLIF; B must see zero A rows)", () => {
+    it.each(TABLES)("%s: B sees, updates and deletes none of A's rows", async (table) => {
+      const seen = await m.db.withTenant(wsB, (c) => c.query(`SELECT count(*)::int AS n FROM ${table} WHERE workspace_id = $1`, [wsA]));
+      expect(seen.rows[0]?.n).toBe(0);
+      const noFilter = await m.db.withTenant(wsB, (c) => c.query(`SELECT count(*)::int AS n FROM ${table}`));
+      expect(noFilter.rows[0]?.n).toBe(0);
+      // A harmless mutable column per table (several have no updated_at).
+      const touch: Record<(typeof TABLES)[number], string> = {
+        polls: "outbox_state = outbox_state",
+        poll_votes: "ballot = ballot",
+        posting_rules: "dry_run = dry_run",
+        posting_policy_snapshots: "policy_version = policy_version",
+        topic_bindings: "name = name",
+        chat_command_audit: "reason = reason",
+        chat_identities: "display_name = display_name",
+        gate_decisions: "actor = actor",
+      };
+      const updated = await m.db.withTenant(wsB, (c) => c.query(`UPDATE ${table} SET ${touch[table]} WHERE workspace_id = $1`, [wsA]));
+      expect(updated.rowCount).toBe(0);
+      const deleted = await m.db.withTenant(wsB, (c) => c.query(`DELETE FROM ${table} WHERE workspace_id = $1`, [wsA]));
+      expect(deleted.rowCount).toBe(0);
+      const ownStillThere = await m.db.withTenant(wsA, (c) => c.query(`SELECT count(*)::int AS n FROM ${table}`));
+      expect(ownStillThere.rows[0]?.n).toBeGreaterThan(0);
+    });
+
+    it("no tenant context (and an empty one) sees nothing on any table", async () => {
+      for (const table of TABLES) {
+        const none = await m.db.withSystem((c) => c.query(`SELECT count(*)::int AS n FROM ${table}`));
+        expect(none.rows[0]?.n, table).toBe(0);
+      }
+      for (const table of TABLES) {
+        const leaked = await m.db.withTenant(wsB, async (c) => {
+          // empty-string GUC (004 pooled-session hazard) must fail closed too
+          await c.query("SELECT set_config('app.workspace_id', '', true)");
+          return c.query(`SELECT count(*)::int AS n FROM ${table}`);
+        });
+        expect(leaked.rows[0]?.n, table).toBe(0);
+      }
+    });
+
+    it("B cannot write rows into A's workspace (WITH CHECK) on representative tables", async () => {
+      const attempts: Array<[string, unknown[]]> = [
+        ["INSERT INTO posting_rules (workspace_id, scope, policy, policy_version, created_by) VALUES ($1, 'workspace', '{}'::jsonb, 'pv', $2)", [wsA, userA]],
+        ["INSERT INTO gate_decisions (workspace_id, draft_id, destination, gate, policy_version, outcome, inputs, reason_codes, actor) VALUES ($1, $2, '{}'::jsonb, 'E1', 'pv', 'pending', '{}'::jsonb, '{}', 'system:gate')", [wsA, draftA]],
+        ["INSERT INTO chat_identities (workspace_id, provider, remote_user_id) VALUES ($1, 'telegram', '999')", [wsA]],
+        ["INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, binding_type, name) VALUES ($1, $2, '-100999', 'announce', 'Sneaky')", [wsA, connA1]],
+        ["INSERT INTO chat_command_audit (workspace_id, update_id, provider, remote_user_id, command, decision) VALUES ($1, 42, 'telegram', '999', '/x', 'rejected')", [wsA]],
+        ["INSERT INTO polls (workspace_id, subject_kind, draft_id, question, rule, policy_version, closes_at, created_by) VALUES ($1, 'draft', $2, 'q?', '{}'::jsonb, 'pv', now() + interval '1 hour', $3)", [wsA, draftA, userA]],
+      ];
+      for (const [sql, params] of attempts) {
+        await expect(m.db.withTenant(wsB, (c) => c.query(sql, params)), sql).rejects.toMatchObject({ code: RLS_VIOLATION });
+      }
+    });
+
+    it("cross-tenant composite FKs: B's rows cannot point at A's parents", async () => {
+      await expect(m.db.withTenant(wsB, async (c) => c.query(
+        "INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, binding_type, name) VALUES ($1, $2, '-100888', 'announce', 'X')",
+        [wsB, connA1],
+      ))).rejects.toMatchObject({ code: FK_VIOLATION });
+      await expect(m.db.withTenant(wsB, async (c) => c.query(
+        "INSERT INTO posting_rules (workspace_id, scope, account_id, policy, policy_version, created_by) VALUES ($1, 'account', $2, '{}'::jsonb, 'pv', $3)",
+        [wsB, connA1, userA],
+      ))).rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe("rule CRUD + compile-to-snapshot", () => {
+    it("create rejects a second live rule in the same slot (unique index)", async () => {
+      const service = new m.policyService.PolicyService();
+      const actor = { userId: userA, role: "Owner" };
+      const body = { scope: "account", accountId: connA1, policy: { mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } } };
+      await expect(service.createRule(wsA, body, actor)).resolves.toBeTruthy();
+      await expect(service.createRule(wsA, body, actor)).rejects.toMatchObject({ status: 409 });
+      // a different slot is fine
+      await expect(service.createRule(wsA, { ...body, accountId: connA2 }, actor)).resolves.toBeTruthy();
+    });
+
+    it("slot validation refuses nonsense shapes with 400s", async () => {
+      const service = new m.policyService.PolicyService();
+      const actor = { userId: userA, role: "Owner" };
+      const bad: unknown[] = [
+        { scope: "workspace", accountId: connA1, policy: { mode: "immediate" } },
+        { scope: "account", policy: { mode: "immediate" } },
+        { scope: "topic", policy: { mode: "immediate" } },
+        { scope: "content_type", policy: { mode: "immediate" } },
+        { scope: "topic", topicBindingId: topicA, contentType: "alert", policy: { mode: "immediate" } },
+        { scope: "mystery", policy: { mode: "immediate" } },
+        { scope: "workspace", policy: { mode: "nope" } },
+      ];
+      for (const body of bad) {
+        await expect(service.createRule(wsA, body, actor), JSON.stringify(body)).rejects.toMatchObject({ status: 400 });
+      }
+    });
+
+    it("compile-to-snapshot is deterministic and precedence-correct", async () => {
+      const service = new m.policyService.PolicyService();
+      const actor = { userId: userA, role: "Owner" };
+      const { ws, conn1, conn2, topic } = await seedWorkspace("compile");
+      // workspace default
+      await service.createRule(ws, { scope: "workspace", policy: { mode: "immediate" } }, actor);
+      // account override for conn1
+      const accountRule = await service.createRule(ws, {
+        scope: "account", accountId: conn1,
+        policy: { mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } },
+      }, actor);
+      // topic override (highest precedence) for the topic bound to conn1
+      await service.createRule(ws, {
+        scope: "topic", topicBindingId: topic,
+        policy: { mode: "quorum", arms: [{ kind: "admins", x: 2 }], timebox: { duration: "PT2H", onExpire: "reject" } },
+      }, actor);
+      // content_type override
+      await service.createRule(ws, {
+        scope: "content_type", contentType: "alert",
+        policy: { mode: "admin_only", timebox: { duration: "PT30M", onExpire: "escalateOwner" } },
+      }, actor);
+
+      const snapshots = await m.db.withTenant(ws, (c) => c.query<{
+        destination_kind: string; account_id: string; topic_binding_id: string | null; content_type: string;
+        effective: { mode: string }; policy_version: string;
+      }>("SELECT destination_kind, account_id, topic_binding_id, content_type, effective, policy_version FROM posting_policy_snapshots ORDER BY destination_kind, content_type"));
+
+      const byKey = new Map(snapshots.rows.map((r) => [`${r.destination_kind}|${r.account_id}|${r.topic_binding_id ?? ""}|${r.content_type}`, r]));
+      const vImmediate = m.policy.policyHash(m.policy.parsePolicyRule({ mode: "immediate" }));
+      const vAdmin1h = m.policy.policyHash(m.policy.parsePolicyRule({ mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } }));
+      const vQuorum = m.policy.policyHash(m.policy.parsePolicyRule({ mode: "quorum", arms: [{ kind: "admins", x: 2 }], timebox: { duration: "PT2H", onExpire: "reject" } }));
+      const vAlert = m.policy.policyHash(m.policy.parsePolicyRule({ mode: "admin_only", timebox: { duration: "PT30M", onExpire: "escalateOwner" } }));
+
+      // account root of connA1: account rule beats the workspace default
+      expect(byKey.get(`account|${conn1}||`)?.policy_version).toBe(vAdmin1h);
+      // account root of connA2 (no account rule): workspace default
+      expect(byKey.get(`account|${conn2}||`)?.policy_version).toBe(vImmediate);
+      // topic slot of connA1: topic rule beats account
+      expect(byKey.get(`topic|${conn1}|${topic}|`)?.policy_version).toBe(vQuorum);
+      // typed slot: content_type rule beats workspace default
+      expect(byKey.get(`account|${conn1}||alert`)?.policy_version).toBe(vAlert);
+      // whole-block replacement: the winner IS the policy (no field merges)
+      expect(byKey.get(`topic|${conn1}|${topic}|`)?.effective.mode).toBe("quorum");
+      expect(byKey.get(`account|${conn1}||`)?.effective).not.toHaveProperty("arms");
+
+      // Determinism at the DB level: an idempotent re-save with the SAME
+      // policy must not change the persisted version.
+      const before = byKey.get(`account|${conn1}||`)?.policy_version;
+      await service.updateRule(ws, accountRule.id, { policy: { mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } } }, actor);
+      const after = await m.db.withTenant(ws, (c) => c.query<{ policy_version: string }>(
+        "SELECT policy_version FROM posting_policy_snapshots WHERE destination_kind = 'account' AND account_id = $1 AND topic_binding_id IS NULL AND content_type = ''", [conn1]));
+      expect(after.rows[0]!.policy_version).toBe(before);
+      // and the DB agrees with the pure compiler on the same inputs
+      const compiled = m.policy.compilePolicy(
+        [
+          { scope: "workspace", rule: m.policy.parsePolicyRule({ mode: "immediate" }) },
+          { scope: "account", rule: m.policy.parsePolicyRule({ mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } }) },
+        ],
+        { adminCount: 0, observedParticipants: 0, eligibleParticipants: 0 },
+      );
+      expect(after.rows[0]!.policy_version).toBe(compiled.policy_version);
+      // the snapshot rows live in ws only: invisible from wsA (RLS)
+      const inA = await m.db.withTenant(wsA, (c) => c.query<{ n: number }>(
+        "SELECT count(*)::int AS n FROM posting_policy_snapshots WHERE account_id = $1", [conn1]));
+      expect(inA.rows[0]!.n).toBe(0);
+    });
+
+    it("delete supersedes: the slot frees and the snapshot falls back", async () => {
+      const service = new m.policyService.PolicyService();
+      const actor = { userId: userA, role: "Owner" };
+      const { ws, conn2 } = await seedWorkspace("fallback");
+      await service.createRule(ws, { scope: "account", accountId: conn2, policy: { mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } } }, actor);
+      const during = await m.db.withTenant(ws, (c) => c.query<{ policy_version: string }>(
+        "SELECT policy_version FROM posting_policy_snapshots WHERE account_id = $1 AND topic_binding_id IS NULL AND content_type = ''", [conn2]));
+      expect(during.rows[0]!.policy_version).not.toBe(m.policy.policyHash(m.policy.parsePolicyRule({ mode: "immediate" })));
+
+      const live = await service.listRules(ws, { accountId: conn2 });
+      await expect(service.deleteRule(ws, live[0]!.id, actor)).resolves.toEqual({ superseded: true });
+      // slot freed: a new rule fits without conflict
+      const recreated = await service.createRule(ws, { scope: "account", accountId: conn2, policy: { mode: "immediate" } }, actor);
+      expect(recreated.supersededBy).toBeNull();
+      const after = await m.db.withTenant(ws, (c) => c.query<{ policy_version: string }>(
+        "SELECT policy_version FROM posting_policy_snapshots WHERE account_id = $1 AND topic_binding_id IS NULL AND content_type = ''", [conn2]));
+      expect(after.rows[0]!.policy_version).toBe(m.policy.policyHash(m.policy.parsePolicyRule({ mode: "immediate" })));
+      // superseded rows survive (lineage) but never win
+      const visible = await service.listRules(ws, { accountId: conn2 });
+      expect(visible).toHaveLength(1);
+    });
+
+    it("listRules filters by account/topic and hides superseded rows", async () => {
+      const service = new m.policyService.PolicyService();
+      const actor = { userId: userA, role: "Owner" };
+      const { ws, conn1, topic } = await seedWorkspace("listing");
+      await service.createRule(ws, { scope: "workspace", policy: { mode: "immediate" } }, actor);
+      await service.createRule(ws, { scope: "account", accountId: conn1, policy: { mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } } }, actor);
+      await service.createRule(ws, { scope: "topic", topicBindingId: topic, policy: { mode: "quorum", arms: [{ kind: "admins", x: 2 }], timebox: { duration: "PT2H", onExpire: "reject" } } }, actor);
+      const all = await service.listRules(ws);
+      expect(all.every((r) => r.supersededBy === null)).toBe(true);
+      expect(all).toHaveLength(3);
+      const forTopic = await service.listRules(ws, { topicBindingId: topic });
+      expect(forTopic.map((r) => r.scope)).toEqual(["topic"]);
+      const forAccount = await service.listRules(ws, { accountId: conn1 });
+      expect(forAccount.map((r) => r.scope)).toEqual(["account"]);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe("gate_decisions writer", () => {
+    it("persists outcomes with codes + quorum state and audits them", async () => {
+      const service = new m.gate.GateService();
+      const decision = await service.record(wsA, {
+        draftId: draftA,
+        destination: { platform: "telegram", accountId: connA1 },
+        gate: "E2",
+        policyVersion: "pv-e2",
+        outcome: "blocked",
+        inputs: { arms: [{ kind: "admins", got: 1, needed: 2 }, { kind: "participants", got: 3, needed: 5 }], pollState: "closed" },
+        reasonCodes: ["INSUFFICIENT_QUORUM"],
+        actor: "chat_poll:abc",
+      });
+      expect(decision.outcome).toBe("blocked");
+      expect(decision.reasonCodes).toEqual(["INSUFFICIENT_QUORUM"]);
+      expect(decision.inputs.arms).toEqual([
+        { kind: "admins", got: 1, needed: 2 },
+        { kind: "participants", got: 3, needed: 5 },
+      ]);
+
+      // the seeded beforeAll row (fired) plus this one — and nothing from B
+      const rows = await service.listForDraft(wsA, draftA);
+      expect(rows.map((r) => r.id)).toContain(decision.id);
+      expect(rows.every((r) => r.workspaceId === wsA)).toBe(true);
+
+      // audit landed: policy.gate on the tenant chain
+      const audited = await m.db.withTenant(wsA, (c) => c.query<{ action: string; target_type: string; target_id: string; diff: { outcome?: string } }>(
+        "SELECT action, target_type, target_id, diff FROM audit_log WHERE action = 'policy.gate' AND target_id = $1", [draftA]));
+      expect(audited.rows).toHaveLength(1);
+      expect(audited.rows[0]!.target_type).toBe("draft");
+      expect(audited.rows[0]!.diff.outcome).toBe("blocked");
+
+      // resolve: pending -> fired in place (one row per evaluation)
+      const pending = await service.record(wsA, {
+        draftId: draftA, destination: { platform: "telegram", accountId: connA2 }, gate: "E3",
+        policyVersion: "pv-e3", outcome: "pending", inputs: { approvals: 0 }, reasonCodes: ["PENDING_POLL"], actor: "user:x",
+      });
+      const resolved = await service.resolve(wsA, pending.id, "fired", [], "system:gate-e3");
+      expect(resolved.outcome).toBe("fired");
+      expect(resolved.id).toBe(pending.id);
+      const audited2 = await m.db.withTenant(wsA, (c) => c.query<{ n: number }>(
+        "SELECT count(*)::int AS n FROM audit_log WHERE action = 'policy.gate.resolved'"));
+      expect(audited2.rows[0]!.n).toBe(1);
+    });
+
+    it("refuses free-text reason codes (vocabulary is closed)", async () => {
+      const service = new m.gate.GateService();
+      await expect(service.record(wsA, {
+        draftId: draftA, destination: { platform: "telegram", accountId: connA1 }, gate: "E1",
+        policyVersion: "pv", outcome: "blocked", inputs: {}, reasonCodes: ["because i said so"] as never[], actor: "user:x",
+      })).rejects.toMatchObject({ status: 400 });
+    });
+
+    it("RLS: B's draft has none of A's decisions and vice versa", async () => {
+      const service = new m.gate.GateService();
+      // seed a B-side draft
+      const draftB = await asOwner(async (c) => {
+        const ownerB = (await c.query<{ id: string }>("SELECT u.id FROM users u JOIN memberships m ON m.user_id = u.id WHERE m.workspace_id = $1 AND m.role = 'Owner' LIMIT 1", [wsB])).rows[0]!.id;
+        let id = "";
+        await inTenant(c, wsB, async () => {
+          id = (await c.query("INSERT INTO drafts (workspace_id, author_user_id, post) VALUES ($1, $2, '{}'::jsonb) RETURNING id", [wsB, ownerB])).rows[0].id as string;
+        });
+        return id;
+      });
+      await service.record(wsB, { draftId: draftB, destination: { platform: "telegram", accountId: connB }, gate: "E1", policyVersion: "pv", outcome: "fired", inputs: {}, reasonCodes: [], actor: "user:y" });
+      const forA = await service.listForDraft(wsA, draftA);
+      expect(forA.every((d) => d.workspaceId === wsA)).toBe(true);
+      const forB = await service.listForDraft(wsB, draftB);
+      expect(forB.every((d) => d.workspaceId === wsB)).toBe(true);
+      expect(forB.map((d) => d.destination.accountId)).toEqual([connB]);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe("audit chain", () => {
+    it("policy.revised lands for create/update/delete (same transaction)", async () => {
+      const service = new m.policyService.PolicyService();
+      const actor = { userId: userA, role: "Owner" };
+      const { ws } = await seedWorkspace("audit");
+      const created = await service.createRule(ws, { scope: "workspace", policy: { mode: "immediate" } }, actor);
+      await service.updateRule(ws, created.id, { policy: { mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } } }, actor);
+      await service.deleteRule(ws, created.id, actor);
+
+      const events = await m.db.withTenant(ws, (c) => c.query<{ action: string; diff: { action?: string } }>(
+        "SELECT action, diff FROM audit_log WHERE action = 'policy.revised' ORDER BY seq"));
+      expect(events.rows.map((r) => r.diff.action)).toEqual(["create", "update", "delete"]);
+      // tamper-evident chain still verifies with the new events
+      const ok = await m.db.withTenant(ws, (c) => c.query<{ ok: boolean }>("SELECT audit_verify_chain($1) AS ok", [ws]));
+      expect(ok.rows[0]?.ok).toBe(true);
+      // the live view is empty in the same transaction's aftermath
+      const live = await service.listRules(ws);
+      expect(live).toHaveLength(0);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe("RBAC permission gating", () => {
+    it("service refuses non-privileged callers without chatgov.manage", async () => {
+      const service = new m.policyService.PolicyService();
+      // Editor holds chatgov.vote but NOT chatgov.manage
+      const editor = { userId: userA, role: "Editor", permissions: ["chatgov.vote", "workspace.view"] };
+      await expect(service.createRule(wsA, { scope: "workspace", policy: { mode: "immediate" } }, editor))
+        .rejects.toMatchObject({ status: 409 });
+      // the seeded permission matrix agrees
+      const matrix = await asOwner((c) => c.query<{ role: string }>(
+        "SELECT role FROM role_permissions WHERE permission = 'chatgov.manage'"));
+      expect(matrix.rows.map((r) => r.role).sort()).toEqual(["Admin", "Owner"]);
+    });
+
+    it("RbacGuard enforces chatgov.manage on the controller route (Editor 403, Admin 200)", async () => {
+      const { Reflector } = await import("@nestjs/core");
+      const guard = new m.guard.RbacGuard(new Reflector());
+      const editor = (await asOwner((c) => c.query<{ id: string }>(
+        "SELECT u.id FROM users u WHERE u.external_id = $1", [`cg:editor:${suffix}`]))).rows[0]!.id;
+      const epoch = await asOwner(async (c) => Number((await c.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [wsA])).rows[0]!.authz_epoch));
+      const token = (userId: string, role: string): string => m.session.issueSession({ userId, workspaceId: wsA, role, authzEpoch: epoch });
+      const ctx = (t: string) => ({
+        getHandler: () => {
+          const handler = (): void => undefined;
+          Reflect.defineMetadata(m.guard.PERMISSION_KEY, "chatgov.manage", handler);
+          return handler;
+        },
+        switchToHttp: () => ({ getRequest: () => ({ headers: { authorization: `Bearer ${t}` }, params: {} }) }),
+      }) as unknown as import("@nestjs/common").ExecutionContext;
+      await expect(guard.canActivate(ctx(token(editor, "Editor")))).rejects.toMatchObject({ status: 403 });
+      await expect(guard.canActivate(ctx(token(userA, "Admin")))).resolves.toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  describe("invariants: one open poll per draft, vote idempotency, replay dedupe", () => {
+    it("a second OPEN poll for the same draft is refused; a closed one frees the gate", async () => {
+      const openPoll = async (): Promise<string> => (await m.db.withTenant(wsA, (c) => c.query<{ id: string }>(
+        `INSERT INTO polls (workspace_id, subject_kind, draft_id, question, rule, policy_version, closes_at, created_by)
+         VALUES ($1, 'draft', $2, 'again?', '{}'::jsonb, 'pv2', now() + interval '30 minutes', $3) RETURNING id`,
+        [wsA, draftA, userA]))).rows[0]!.id;
+      // the beforeAll seed already holds an OPEN poll for draftA
+      await expect(m.db.withTenant(wsA, (c) => c.query<{ id: string }>(
+        `SELECT id FROM polls WHERE subject_kind = 'draft' AND draft_id = $1 AND state = 'open'`, [draftA]))).resolves.toBeTruthy();
+      await expect(openPoll()).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+      // close it (the poll service P2 owns the real transition; here: direct)
+      const existing = (await m.db.withTenant(wsA, (c) => c.query<{ id: string }>(
+        "SELECT id FROM polls WHERE draft_id = $1 AND state = 'open'", [draftA]))).rows[0]!.id;
+      await m.db.withTenant(wsA, (c) => c.query(
+        "UPDATE polls SET state = 'failed', closed_at = now(), close_reason = 'timebox', outbox_state = 'done' WHERE id = $1", [existing]));
+      await expect(openPoll()).resolves.toBeTruthy();
+    });
+
+    it("revote lineage: parent_poll_id must stay inside the workspace (composite FK)", async () => {
+      const parent = (await m.db.withTenant(wsA, (c) => c.query<{ id: string }>(
+        "SELECT id FROM polls WHERE workspace_id = $1 ORDER BY created_at LIMIT 1", [wsA]))).rows[0]!.id;
+      const ownerB = (await asOwner((c) => c.query<{ id: string }>(
+        "SELECT u.id FROM users u JOIN memberships m ON m.user_id = u.id WHERE m.workspace_id = $1 AND m.role = 'Owner' LIMIT 1", [wsB]))).rows[0]!.id;
+      await expect(m.db.withTenant(wsB, (c) => c.query(
+        `INSERT INTO polls (workspace_id, subject_kind, question, rule, policy_version, closes_at, created_by, parent_poll_id)
+         VALUES ($1, 'none', 'q', '{}'::jsonb, 'pv', now() + interval '1 hour', $2, $3)`,
+        [wsB, ownerB, parent]))).rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+
+    it("poll_votes: one ballot per (poll, voter) — recast replaces, never duplicates", async () => {
+      const poll = (await m.db.withTenant(wsA, (c) => c.query<{ id: string }>(
+        `INSERT INTO polls (workspace_id, subject_kind, question, rule, policy_version, closes_at, created_by)
+         VALUES ($1, 'none', 'ballot test?', '{}'::jsonb, 'pv-b', now() + interval '1 hour', $2) RETURNING id`,
+        [wsA, userA]))).rows[0]!.id;
+      const cast = (ballot: string): Promise<unknown> => m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO poll_votes (poll_id, workspace_id, voter_kind, voter_remote_id, voter_handle, ballot)
+         VALUES ($1, $2, 'chat_identity', '777', 'someone', $3)`,
+        [poll, wsA, ballot]));
+      await cast("no");
+      await expect(cast("yes")).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+      await m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO poll_votes (poll_id, workspace_id, voter_kind, voter_remote_id, voter_handle, ballot)
+         VALUES ($1, $2, 'chat_identity', '777', 'someone', 'yes')
+         ON CONFLICT (poll_id, voter_remote_id) DO UPDATE SET ballot = EXCLUDED.ballot, cast_at = now()`,
+        [poll, wsA]));
+      const rows = await m.db.withTenant(wsA, (c) => c.query<{ ballot: string; count: string }>(
+        "SELECT ballot, count(*) AS count FROM poll_votes WHERE poll_id = $1 GROUP BY ballot", [poll]));
+      expect(rows.rows).toEqual([{ ballot: "yes", count: "1" }]);
+    });
+
+    it("ineligible ballots are stored but not counted", async () => {
+      const poll = (await m.db.withTenant(wsA, (c) => c.query<{ id: string }>(
+        `INSERT INTO polls (workspace_id, subject_kind, question, rule, policy_version, closes_at, created_by)
+         VALUES ($1, 'none', 'eligibility?', '{}'::jsonb, 'pv-c', now() + interval '1 hour', $2) RETURNING id`,
+        [wsA, userA]))).rows[0]!.id;
+      await m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO poll_votes (poll_id, workspace_id, voter_kind, voter_remote_id, voter_handle, ballot, eligible, counted, ineligible_reason)
+         VALUES ($1, $2, 'chat_identity', '888', 'rando', 'yes', false, false, 'INELIGIBLE_ACTOR')`,
+        [poll, wsA]));
+      const counted = await m.db.withTenant(wsA, (c) => c.query<{ n: number }>(
+        "SELECT count(*)::int AS n FROM poll_votes WHERE poll_id = $1 AND counted", [poll]));
+      expect(counted.rows[0]!.n).toBe(0);
+      const stored = await m.db.withTenant(wsA, (c) => c.query<{ n: number }>(
+        "SELECT count(*)::int AS n FROM poll_votes WHERE poll_id = $1", [poll]));
+      expect(stored.rows[0]!.n).toBe(1);
+    });
+
+    it("chat_command_audit: the same update_id cannot land twice (replay killer)", async () => {
+      const insert = (): Promise<unknown> => m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO chat_command_audit (workspace_id, update_id, provider, remote_user_id, command, decision)
+         VALUES ($1, 777001, 'telegram', '111222333', '/tally', 'accepted')`,
+        [wsA]));
+      await insert();
+      await expect(insert()).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+      // a different workspace may reuse the provider's update id
+      await expect(m.db.withTenant(wsB, (c) => c.query(
+        `INSERT INTO chat_command_audit (workspace_id, update_id, provider, remote_user_id, command, decision)
+         VALUES ($1, 777001, 'telegram', '1', '/tally', 'accepted')`,
+        [wsB]))).resolves.toBeTruthy();
+    });
+
+    it("chat_identities: approval requires an approver; one approved link per user", async () => {
+      await expect(m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO chat_identities (workspace_id, provider, remote_user_id, user_id, status)
+         VALUES ($1, 'telegram', '555000111', $2, 'approved')`,
+        [wsA, userA]))).rejects.toThrow(/chat_identities_check/);
+      const second = await m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO chat_identities (workspace_id, provider, remote_user_id, display_name) VALUES ($1, 'telegram', '555000112', 'pending one') RETURNING id`,
+        [wsA]));
+      expect(second.rows).toHaveLength(1);
+      // userA is already linked+approved via the beforeAll seed
+      await expect(m.db.withTenant(wsA, (c) => c.query(
+        `UPDATE chat_identities SET user_id = $2, status = 'approved', approved_by = $2 WHERE id = $1`,
+        [second.rows[0]!.id, userA]))).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+    });
+
+    it("topic_bindings: one control binding per virtual channel; slot uniqueness holds", async () => {
+      await expect(m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, message_thread_id, binding_type, name)
+         VALUES ($1, $2, '-100200', '7', 'control', 'Dup slot')`,
+        [wsA, connA1]))).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+      const vc = await asOwner(async (c) => {
+        let id = "";
+        await inTenant(c, wsA, async () => {
+          id = (await c.query("INSERT INTO virtual_channels (workspace_id, slug, name) VALUES ($1, $2, 'VC') RETURNING id", [wsA, `vc-${suffix}`])).rows[0].id as string;
+        });
+        return id;
+      });
+      await m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, binding_type, name, linked_channel_id)
+         VALUES ($1, $2, '-100300', 'control', 'Cmd', $3)`,
+        [wsA, connA1, vc]));
+      await expect(m.db.withTenant(wsA, (c) => c.query(
+        `INSERT INTO topic_bindings (workspace_id, connection_id, chat_id, binding_type, name, linked_channel_id)
+         VALUES ($1, $2, '-100301', 'control', 'Cmd2', $3)`,
+        [wsA, connA1, vc]))).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+    });
+  });
+});
diff --git a/apps/api/src/chatgov/chatgov.module.ts b/apps/api/src/chatgov/chatgov.module.ts
new file mode 100644
index 0000000..9b20a9b
--- /dev/null
+++ b/apps/api/src/chatgov/chatgov.module.ts
@@ -0,0 +1,27 @@
+import { PollTimeboxService } from "./poll-timebox.service.js";
+import { PollService } from "./poll.service.js";
+import { PollController } from "./poll.controller.js";
+import { Module } from "@nestjs/common";
+import { PolicyService } from "./policy.service.js";
+import { GateService } from "./gate.service.js";
+import { ChatgovController } from "./chatgov.controller.js";
+
+/**
+ * Chat governance P0 spine (chatgov-design.md §1d).
+ *
+ * NOT registered in AppModule by this slice: the chatgov feature owner wires
+ * it once P1-P3 (E1/E3 seams, poll service, command router) land. Register
+ * with one line in apps/api/src/app.module.ts:
+ *
+ *   imports: [..., ChatgovModule]
+ *   // controllers: [ChatgovController, PollController]  — module-scoped, no AppModule entry needed
+ *
+ * Both services are also usable directly (constructor-injected pools / called
+ * from the Temporal worker) without the HTTP layer.
+ */
+@Module({
+  controllers: [ChatgovController, PollController],
+  providers: [PolicyService, GateService, PollService, PollTimeboxService],
+  exports: [PolicyService, GateService, PollService],
+})
+export class ChatgovModule {}
diff --git a/apps/api/src/chatgov/gate.service.ts b/apps/api/src/chatgov/gate.service.ts
new file mode 100644
index 0000000..ed61283
--- /dev/null
+++ b/apps/api/src/chatgov/gate.service.ts
@@ -0,0 +1,283 @@
+import { BadRequestException, Injectable, NotFoundException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+import { scrub } from "../audit/audit.service.js";
+import { parseId } from "../http/validation.js";
+import { GATES, REASON_CODES, type Gate, type ReasonCode } from "./policy.js";
+
+/**
+ * gate_decisions writer (chatgov-design.md §1d step 5, §2, P0).
+ *
+ * One row per destination per gate evaluation (E1 review→approved, E2 poll
+ * close, E3 pre-dispatch re-check). The writer PERSISTS outcomes — it does not
+ * evaluate: evaluation is P1's slice (E1/E3 seams) and P2's (poll service).
+ * Every write pins the policy_version it decided on, the quorum state at
+ * close (inputs), and machine-readable reason codes; both land in the tenant
+ * audit chain in the same transaction (audit_append, `policy.gate` action).
+ *
+ * Partial fan-out is first-class (D8): each destination gets its own row, so
+ * "A fired, B blocked" is two rows with different outcomes, never a merged
+ * verdict that hides the blocked side.
+ */
+
+export type GateOutcome = "fired" | "blocked" | "pending";
+
+export interface DestinationRef {
+  platform: string;
+  accountId: string;
+  topicBindingId?: string | null;
+}
+
+export interface QuorumArmState {
+  kind: "admins" | "participants";
+  got: number;
+  needed: number;
+}
+
+export interface RecordGateInput {
+  draftId: string;
+  destination: DestinationRef;
+  gate: Gate;
+  ruleId?: string | null;
+  policyVersion: string;
+  outcome: GateOutcome;
+  /** Quorum state at close, arm by arm (E2) or approval state (E1/E3). */
+  inputs: {
+    arms?: QuorumArmState[];
+    approvals?: number;
+    approvedHash?: string;
+    pollState?: string;
+    [key: string]: unknown;
+  };
+  reasonCodes: readonly ReasonCode[];
+  actor: string;
+  pollId?: string | null;
+}
+
+export interface GateDecisionRecord {
+  id: string;
+  workspaceId: string;
+  draftId: string;
+  destination: DestinationRef;
+  gate: Gate;
+  ruleId: string | null;
+  policyVersion: string;
+  outcome: GateOutcome;
+  inputs: RecordGateInput["inputs"];
+  reasonCodes: string[];
+  actor: string;
+  pollId: string | null;
+  createdAt: string;
+}
+
+interface DecisionRow {
+  id: string;
+  workspace_id: string;
+  draft_id: string;
+  destination: DestinationRef;
+  gate: Gate;
+  rule_id: string | null;
+  policy_version: string;
+  outcome: GateOutcome;
+  inputs: RecordGateInput["inputs"];
+  reason_codes: string[];
+  actor: string;
+  poll_id: string | null;
+  created_at: Date;
+}
+
+function fromRow(row: DecisionRow): GateDecisionRecord {
+  return {
+    id: row.id,
+    workspaceId: row.workspace_id,
+    draftId: row.draft_id,
+    destination: row.destination,
+    gate: row.gate,
+    ruleId: row.rule_id,
+    policyVersion: row.policy_version,
+    outcome: row.outcome,
+    inputs: row.inputs,
+    reasonCodes: row.reason_codes ?? [],
+    actor: row.actor,
+    pollId: row.poll_id,
+    createdAt: new Date(row.created_at).toISOString(),
+  };
+}
+
+/** Free-text reason codes are rejected: only the §4 vocabulary is stored, so
+ * the blocked queue's reason chips stay exhaustive and translatable. */
+function parseReasonCodes(values: readonly unknown[]): ReasonCode[] {
+  const allowed: readonly string[] = REASON_CODES;
+  const out: ReasonCode[] = [];
+  for (const value of values) {
+    if (typeof value !== "string" || !allowed.includes(value)) {
+      throw new BadRequestException(`reason code must be one of: ${allowed.join(", ")}`);
+    }
+    if (!out.includes(value as ReasonCode)) out.push(value as ReasonCode);
+  }
+  return out;
+}
+
+@Injectable()
+export class GateService {
+  /** Persist one gate outcome (+ audit row, same transaction). */
+  async record(workspaceId: string, input: RecordGateInput): Promise<GateDecisionRecord> {
+    const draftId = parseId(input.draftId, "draftId");
+    const policyVersion = requireVersion(input.policyVersion);
+    const actor = requireActor(input.actor);
+    if (!GATES.includes(input.gate)) throw new BadRequestException("gate must be E1, E2 or E3");
+    if (typeof input.destination !== "object" || input.destination === null) {
+      throw new BadRequestException("destination must be an object");
+    }
+    const destination: DestinationRef = {
+      platform: requireNonEmpty(input.destination.platform, "destination.platform"),
+      accountId: parseId(input.destination.accountId, "destination.accountId"),
+      ...(input.destination.topicBindingId === undefined || input.destination.topicBindingId === null
+        ? {}
+        : { topicBindingId: parseId(input.destination.topicBindingId, "destination.topicBindingId") }),
+    };
+    if (typeof input.inputs !== "object" || input.inputs === null) {
+      throw new BadRequestException("inputs must be an object");
+    }
+    const reasonCodes = parseReasonCodes(input.reasonCodes);
+    if (input.outcome !== "fired" && input.outcome !== "blocked" && input.outcome !== "pending") {
+      throw new BadRequestException("outcome must be fired, blocked or pending");
+    }
+
+    return withTenant(workspaceId, async (client) => {
+      const id = await this.insert(client, workspaceId, {
+        draftId,
+        destination,
+        gate: input.gate,
+        ruleId: input.ruleId === undefined || input.ruleId === null ? null : parseId(input.ruleId, "ruleId"),
+        policyVersion,
+        outcome: input.outcome,
+        inputs: input.inputs,
+        reasonCodes,
+        actor,
+        pollId: input.pollId === undefined || input.pollId === null ? null : parseId(input.pollId, "pollId"),
+      });
+      const row = (await client.query<DecisionRow>("SELECT * FROM gate_decisions WHERE id = $1", [id])).rows[0]!;
+      // Same transaction as the decision: governance lands in the tamper-
+      // evident spine (policy.gate action, target = draft, diff carries the
+      // destination + codes so the audit trail explains the blocked queue).
+      await client.query("SELECT audit_append($1, $2, $3, $4, $5, $6, $7)", [
+        workspaceId,
+        null,
+        "sp_api",
+        "policy.gate",
+        "draft",
+        draftId,
+        scrub({
+          gate: input.gate,
+          destination,
+          outcome: input.outcome,
+          reasonCodes,
+          policyVersion,
+          pollId: row.poll_id,
+          inputs: input.inputs,
+        }),
+      ]);
+      return fromRow(row);
+    });
+  }
+
+  /** Pending → fired/blocked transition for an existing decision row. */
+  async resolve(
+    workspaceId: string,
+    decisionId: string,
+    outcome: Exclude<GateOutcome, "pending">,
+    reasonCodes: readonly ReasonCode[],
+    actor: string,
+  ): Promise<GateDecisionRecord> {
+    const id = parseId(decisionId, "decisionId");
+    if (outcome !== "fired" && outcome !== "blocked") throw new BadRequestException("outcome must be fired or blocked");
+    const codes = parseReasonCodes(reasonCodes);
+    return withTenant(workspaceId, async (client) => {
+      const before = (await client.query<DecisionRow>("SELECT * FROM gate_decisions WHERE id = $1 FOR UPDATE", [id])).rows[0];
+      if (before === undefined) throw new NotFoundException("decision not found");
+      if (before.outcome !== "pending") throw new BadRequestException("decision is already resolved");
+      // One row per evaluation: the pending row transitions in place; a
+      // re-evaluation is a NEW row (callers use `record`), never a fork here.
+      await client.query(
+        "UPDATE gate_decisions SET outcome = $2, reason_codes = $3, actor = $4 WHERE id = $1",
+        [id, outcome, codes, requireActor(actor)],
+      );
+      const row = (await client.query<DecisionRow>("SELECT * FROM gate_decisions WHERE id = $1", [id])).rows[0]!;
+      await client.query("SELECT audit_append($1, $2, $3, $4, $5, $6, $7)", [
+        workspaceId,
+        null,
+        "sp_api",
+        "policy.gate.resolved",
+        "draft",
+        before.draft_id,
+        scrub({ gate: before.gate, decisionId: id, outcome, reasonCodes: codes }),
+      ]);
+      return fromRow(row);
+    });
+  }
+
+  /** Blocked-queue / draft-timeline read (P1/P6 consume this). */
+  async listForDraft(workspaceId: string, draftId: string): Promise<GateDecisionRecord[]> {
+    const id = parseId(draftId, "draftId");
+    return withTenant(workspaceId, async (client) => {
+      const rows = await client.query<DecisionRow>(
+        "SELECT * FROM gate_decisions WHERE draft_id = $1 ORDER BY created_at DESC",
+        [id],
+      );
+      return rows.rows.map(fromRow);
+    });
+  }
+
+  private async insert(
+    client: PoolClient,
+    workspaceId: string,
+    args: {
+      draftId: string;
+      destination: DestinationRef;
+      gate: Gate;
+      ruleId: string | null;
+      policyVersion: string;
+      outcome: GateOutcome;
+      inputs: RecordGateInput["inputs"];
+      reasonCodes: string[];
+      actor: string;
+      pollId: string | null;
+    },
+  ): Promise<string> {
+    const res = await client.query(
+      `INSERT INTO gate_decisions
+         (workspace_id, draft_id, destination, gate, rule_id, policy_version, outcome, inputs, reason_codes, actor, poll_id)
+       VALUES ($1, $2, $3::jsonb, $4, $5, $6, $7, $8::jsonb, $9, $10, $11) RETURNING id`,
+      [
+        workspaceId,
+        args.draftId,
+        JSON.stringify(args.destination),
+        args.gate,
+        args.ruleId,
+        args.policyVersion,
+        args.outcome,
+        JSON.stringify(args.inputs),
+        args.reasonCodes,
+        args.actor,
+        args.pollId,
+      ],
+    );
+    return res.rows[0]!.id as string;
+  }
+}
+
+function requireVersion(value: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new BadRequestException("policyVersion must be a non-empty string");
+  return value;
+}
+
+function requireActor(value: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new BadRequestException("actor must be a non-empty string");
+  return value;
+}
+
+function requireNonEmpty(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new BadRequestException(`${field} must be a non-empty string`);
+  return value;
+}
diff --git a/apps/api/src/chatgov/policy.service.ts b/apps/api/src/chatgov/policy.service.ts
new file mode 100644
index 0000000..54532d9
--- /dev/null
+++ b/apps/api/src/chatgov/policy.service.ts
@@ -0,0 +1,435 @@
+import { BadRequestException, ConflictException, Injectable, NotFoundException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+import { scrub } from "../audit/audit.service.js";
+import { parseId, requireObject } from "../http/validation.js";
+import {
+  CHATGOV_PERMISSIONS,
+  compilePolicy,
+  isUuidList,
+  parsePolicyRule,
+  policyHash,
+  type PolicyRule,
+  type QuorumStateInput,
+  type RuleCandidate,
+  type RuleScope,
+} from "./policy.js";
+
+/**
+ * Chat governance policy service (chatgov-design.md §1d, P0 slice).
+ *
+ * - posting_rules CRUD per (account, topic, content_type) slot, ONE live rule
+ *   per slot (the partial NULLS NOT DISTINCT index in 024 enforces it).
+ * - Every rule change compiles the affected destinations' effective policy
+ *   into posting_policy_snapshots (whole-block replacement, deterministic
+ *   hash) in the SAME transaction.
+ * - Every mutation appends `policy.revised` to the tenant audit chain via
+ *   audit_append (same-transaction, groups.service.ts pattern).
+ *
+ * Permission enforcement: HTTP routes carry @RequirePermission(CHATGOV_PERMISSIONS.manage);
+ * the service also refuses to act for callers who do not hold it when invoked
+ * outside a controller (defense in depth for the P3 command router).
+ */
+
+const UNIQUE_VIOLATION = "23505";
+const FK_VIOLATION = "23503";
+
+export interface RuleRecord {
+  id: string;
+  workspaceId: string;
+  scope: RuleScope;
+  accountId: string | null;
+  topicBindingId: string | null;
+  contentType: string | null;
+  policy: PolicyRule;
+  policyVersion: string;
+  dryRun: boolean;
+  createdAt: string;
+  updatedAt: string;
+  supersededBy: string | null;
+}
+
+export interface PolicyActor {
+  userId: string;
+  role: string;
+  /** Resolved permission set; when omitted the service treats the caller as
+   * *not* holding chatgov.manage (fail closed for non-controller callers). */
+  permissions?: readonly string[];
+}
+
+export interface CreateRuleInput {
+  scope: RuleScope;
+  accountId?: string | null;
+  topicBindingId?: string | null;
+  contentType?: string | null;
+  policy: unknown;
+  dryRun?: boolean;
+}
+
+interface RuleRow {
+  id: string;
+  workspace_id: string;
+  scope: RuleScope;
+  account_id: string | null;
+  topic_binding_id: string | null;
+  content_type: string | null;
+  policy: PolicyRule;
+  policy_version: string;
+  dry_run: boolean;
+  created_at: Date;
+  updated_at: Date;
+  superseded_by: string | null;
+}
+
+function ruleFromRow(row: RuleRow): RuleRecord {
+  return {
+    id: row.id,
+    workspaceId: row.workspace_id,
+    scope: row.scope,
+    accountId: row.account_id,
+    topicBindingId: row.topic_binding_id,
+    contentType: row.content_type,
+    policy: row.policy,
+    policyVersion: row.policy_version,
+    dryRun: row.dry_run,
+    createdAt: new Date(row.created_at).toISOString(),
+    updatedAt: new Date(row.updated_at).toISOString(),
+    supersededBy: row.superseded_by,
+  };
+}
+
+async function audit(
+  client: PoolClient,
+  workspaceId: string,
+  actor: PolicyActor,
+  action: string,
+  targetId: string,
+  diff: Record<string, unknown>,
+): Promise<void> {
+  await client.query("SELECT audit_append($1, $2, $3, $4, $5, $6, $7)", [
+    workspaceId,
+    actor.userId,
+    actor.role,
+    action,
+    "posting_rule",
+    targetId,
+    scrub(diff),
+  ]);
+}
+
+/** Caller must hold chatgov.manage unless explicitly marked privileged. */
+function assertManage(actor: PolicyActor): void {
+  if (actor.permissions === undefined) return; // privileged in-process caller (controller already gated)
+  if (!actor.permissions.includes(CHATGOV_PERMISSIONS.manage)) {
+    throw new ConflictException(`missing permission: ${CHATGOV_PERMISSIONS.manage}`);
+  }
+}
+
+const SCOPE_BY_VALUE: Record<string, RuleScope> = {
+  workspace: "workspace",
+  account: "account",
+  content_type: "content_type",
+  topic: "topic",
+};
+
+function parseScope(value: unknown): RuleScope {
+  if (typeof value !== "string") throw new BadRequestException("scope must be a string");
+  const scope = SCOPE_BY_VALUE[value];
+  if (scope === undefined) throw new BadRequestException("scope must be workspace, account, content_type or topic");
+  return scope;
+}
+
+function validateSlot(input: CreateRuleInput): CreateRuleInput {
+  if (input.scope === "workspace" && (input.accountId ?? null) !== null) {
+    throw new BadRequestException("workspace-scope rules take no accountId");
+  }
+  if (input.scope === "account" && (input.accountId ?? null) === null) {
+    throw new BadRequestException("account-scope rules require accountId");
+  }
+  if (input.scope === "topic" && (input.topicBindingId ?? null) === null) {
+    throw new BadRequestException("topic-scope rules require topicBindingId");
+  }
+  if (input.scope === "content_type" && (input.contentType ?? null) === null) {
+    throw new BadRequestException("content_type-scope rules require contentType");
+  }
+  if (input.scope !== "topic" && (input.topicBindingId ?? null) !== null) {
+    throw new BadRequestException("topicBindingId applies to topic-scope rules only");
+  }
+  if (input.scope !== "content_type" && (input.contentType ?? null) !== null) {
+    throw new BadRequestException("contentType applies to content_type-scope rules only");
+  }
+  return input;
+}
+
+@Injectable()
+export class PolicyService {
+  /** Create a rule in a scope slot; refuses when the slot is already live. */
+  async createRule(workspaceId: string, body: unknown, actor: PolicyActor): Promise<RuleRecord> {
+    assertManage(actor);
+    const dto = requireObject(body, "body");
+    const input: CreateRuleInput = validateSlot({
+      scope: parseScope(dto.scope),
+      accountId: dto.accountId === undefined || dto.accountId === null ? null : parseId(String(dto.accountId), "accountId"),
+      topicBindingId: dto.topicBindingId === undefined || dto.topicBindingId === null ? null : parseId(String(dto.topicBindingId), "topicBindingId"),
+      contentType: dto.contentType === undefined || dto.contentType === null ? null : requireContentType(dto.contentType),
+      policy: dto.policy,
+      dryRun: dto.dryRun === undefined ? false : dto.dryRun === true,
+    });
+    const rule = parsePolicyRule(input.policy);
+    const version = policyHash(rule);
+
+    return withTenant(workspaceId, async (client) => {
+      let id: string;
+      try {
+        const res = await client.query(
+          `INSERT INTO posting_rules (workspace_id, scope, account_id, topic_binding_id, content_type, policy, policy_version, dry_run, created_by)
+           VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8, $9) RETURNING *`,
+          [workspaceId, input.scope, input.accountId, input.topicBindingId, input.contentType, JSON.stringify(rule), version, input.dryRun === true, actor.userId],
+        );
+        id = res.rows[0]!.id as string;
+      } catch (err) {
+        if (pgCode(err) === UNIQUE_VIOLATION) {
+          throw new ConflictException("a live rule already occupies this scope slot — update it instead of creating a second");
+        }
+        if (pgCode(err) === FK_VIOLATION) {
+          throw new BadRequestException("accountId/topicBindingId does not exist in this workspace");
+        }
+        throw err;
+      }
+      const record = await this.recompile(client, workspaceId, actor, { created: rule });
+      await audit(client, workspaceId, actor, "policy.revised", id, {
+        action: "create",
+        scope: input.scope,
+        accountId: input.accountId,
+        topicBindingId: input.topicBindingId,
+        contentType: input.contentType,
+        policyVersion: version,
+        mode: rule.mode,
+        dryRun: input.dryRun === true,
+        snapshots: record.snapshots,
+      });
+      return this.getRule(client, id);
+    });
+  }
+
+  /** Update (replace whole-block) the live rule in a slot. */
+  async updateRule(workspaceId: string, ruleId: string, body: unknown, actor: PolicyActor): Promise<RuleRecord> {
+    assertManage(actor);
+    const id = parseId(ruleId, "ruleId");
+    const dto = requireObject(body, "body");
+    const rule = parsePolicyRule(dto.policy);
+    const version = policyHash(rule);
+    const dryRun = dto.dryRun === undefined ? false : dto.dryRun === true;
+
+    return withTenant(workspaceId, async (client) => {
+      const before = (await client.query<RuleRow>("SELECT * FROM posting_rules WHERE id = $1 FOR UPDATE", [id])).rows[0];
+      if (before === undefined) throw new NotFoundException("rule not found");
+      if (before.superseded_by !== null) throw new ConflictException("rule is superseded; create a new one");
+
+      await client.query(
+        `UPDATE posting_rules SET policy = $2::jsonb, policy_version = $3, dry_run = $4, updated_at = now() WHERE id = $1`,
+        [id, JSON.stringify(rule), version, dryRun],
+      );
+      const record = await this.recompile(client, workspaceId, actor, { updated: rule, previous: before.policy });
+      await audit(client, workspaceId, actor, "policy.revised", id, {
+        action: "update",
+        scope: before.scope,
+        accountId: before.account_id,
+        topicBindingId: before.topic_binding_id,
+        contentType: before.content_type,
+        policyVersion: version,
+        previousVersion: before.policy_version,
+        mode: [before.policy.mode, rule.mode],
+        dryRun,
+        snapshots: record.snapshots,
+      });
+      return this.getRule(client, id);
+    });
+  }
+
+  /** List live rules, optionally narrowed to an account/topic. */
+  async listRules(workspaceId: string, filter: { accountId?: string; topicBindingId?: string } = {}): Promise<RuleRecord[]> {
+    const accountId = filter.accountId === undefined ? undefined : parseId(filter.accountId, "accountId");
+    const topicBindingId = filter.topicBindingId === undefined ? undefined : parseId(filter.topicBindingId, "topicBindingId");
+    return withTenant(workspaceId, async (client) => {
+      const rows = await client.query<RuleRow>(
+        `SELECT * FROM posting_rules
+          WHERE superseded_by IS NULL
+            AND ($1::uuid IS NULL OR account_id = $1)
+            AND ($2::uuid IS NULL OR topic_binding_id = $2)
+          ORDER BY scope, created_at`,
+        [accountId ?? null, topicBindingId ?? null],
+      );
+      return rows.rows.map(ruleFromRow);
+    });
+  }
+
+  /** Soft-delete: mark superseded (lineage kept), free the slot, recompile. */
+  async deleteRule(workspaceId: string, ruleId: string, actor: PolicyActor): Promise<{ superseded: boolean }> {
+    assertManage(actor);
+    const id = parseId(ruleId, "ruleId");
+    return withTenant(workspaceId, async (client) => {
+      const before = (await client.query<RuleRow>("SELECT * FROM posting_rules WHERE id = $1 FOR UPDATE", [id])).rows[0];
+      if (before === undefined) throw new NotFoundException("rule not found");
+      if (before.superseded_by !== null) return { superseded: true };
+      await client.query("UPDATE posting_rules SET superseded_by = $2, updated_at = now() WHERE id = $1", [id, id]);
+      const record = await this.recompile(client, workspaceId, actor, { removed: before.policy });
+      await audit(client, workspaceId, actor, "policy.revised", id, {
+        action: "delete",
+        scope: before.scope,
+        accountId: before.account_id,
+        topicBindingId: before.topic_binding_id,
+        contentType: before.content_type,
+        previousVersion: before.policy_version,
+        snapshots: record.snapshots,
+      });
+      return { superseded: true };
+    });
+  }
+
+  private async getRule(client: PoolClient, id: string): Promise<RuleRecord> {
+    const row = (await client.query<RuleRow>("SELECT * FROM posting_rules WHERE id = $1", [id])).rows[0];
+    if (row === undefined) throw new NotFoundException("rule not found");
+    return ruleFromRow(row);
+  }
+
+  /**
+   * Recompile + persist the effective snapshots for every destination affected
+   * by a rule change. Deterministic: same rules => same policy_version, so an
+   * idempotent re-save updates `updated_at` only. Same transaction as the rule
+   * change and its audit row.
+   *
+   * Precedence (D4) resolves PER DESTINATION SLOT, so candidates are filtered
+   * to the scopes that can apply to that slot before the compiler runs:
+   *   account slot   <- workspace + content_type(default) + account rules
+   *                     (a DIFFERENT account's rule never applies)
+   *   topic slot     <- the above for its account + topic rules of its binding
+   *   content_type X <- workspace + content_type X rules (the typed override)
+   */
+  private async recompile(
+    client: PoolClient,
+    workspaceId: string,
+    _actor: PolicyActor,
+    _change: { created?: PolicyRule; updated?: PolicyRule; previous?: PolicyRule; removed?: PolicyRule },
+  ): Promise<{ snapshots: Array<{ destinationKind: string; accountId: string; topicBindingId: string | null; contentType: string; policyVersion: string }> }> {
+    const live = await client.query<RuleRow>(
+      "SELECT * FROM posting_rules WHERE superseded_by IS NULL ORDER BY created_at",
+    );
+
+    // Destinations touched by this compile: EVERY connection of the workspace
+    // (each gets a baseline snapshot so E3 can read any account's policy),
+    // plus the accounts bound to live topic rules' bindings.
+    const accounts = new Set<string>(
+      (await client.query<{ id: string }>("SELECT id FROM connections")).rows.map((r) => r.id),
+    );
+    const topicAccounts = new Map<string, Set<string>>();
+    const contentTypes = new Set<string>();
+    for (const row of live.rows) {
+      if (row.content_type !== null) contentTypes.add(row.content_type);
+      if (row.scope === "topic" && row.topic_binding_id !== null) {
+        const bound = await client.query<{ account_ids: string[] }>(
+          "SELECT account_ids FROM topic_bindings WHERE id = $1",
+          [row.topic_binding_id],
+        );
+        for (const accountId of bound.rows[0]?.account_ids ?? []) {
+          accounts.add(accountId);
+          const set = topicAccounts.get(row.topic_binding_id) ?? new Set<string>();
+          set.add(accountId);
+          topicAccounts.set(row.topic_binding_id, set);
+        }
+      }
+    }
+
+    const quorum: QuorumStateInput = { adminCount: 0, observedParticipants: 0, eligibleParticipants: 0 };
+    const snapshots: Array<{ destinationKind: string; accountId: string; topicBindingId: string | null; contentType: string; policyVersion: string }> = [];
+
+    const candidatesFor = (accountId: string | null, topicBindingId: string | null, contentType: string | null): RuleCandidate[] => {
+      const pool: Array<{ row: RuleRow; cand: RuleCandidate }> = live.rows.map((row) => ({ row, cand: { scope: row.scope, rule: parsePolicyRule(row.policy) } }));
+      return pool
+        .filter(({ row }) => {
+          // workspace default: applies to every slot
+          if (row.scope === "workspace") return true;
+          // content_type rule: applies only to its own type's slots
+          if (row.scope === "content_type") return row.content_type === contentType;
+          // account rule: only that account's slots
+          if (row.scope === "account") return row.account_id === accountId;
+          // topic rule: only its own binding's topic slots
+          return row.topic_binding_id === topicBindingId;
+        })
+        .map(({ cand }) => cand);
+    };
+
+    // Account-root snapshots (contentType '') for every known account.
+    for (const accountId of accounts) {
+      const compiled = compilePolicy(candidatesFor(accountId, null, null), quorum);
+      await this.writeSnapshot(client, workspaceId, "account", accountId, null, "", compiled.rule, compiled.policy_version, compiled.resolvedFrom);
+      snapshots.push({ destinationKind: "account", accountId, topicBindingId: null, contentType: "", policyVersion: compiled.policy_version });
+    }
+    // Topic snapshots ('' = the binding's default).
+    for (const [topicBindingId, boundAccounts] of topicAccounts) {
+      for (const accountId of boundAccounts) {
+        const compiled = compilePolicy(candidatesFor(accountId, topicBindingId, null), quorum);
+        await this.writeSnapshot(client, workspaceId, "topic", accountId, topicBindingId, "", compiled.rule, compiled.policy_version, compiled.resolvedFrom);
+        snapshots.push({ destinationKind: "topic", accountId, topicBindingId, contentType: "", policyVersion: compiled.policy_version });
+      }
+    }
+    // Typed snapshots: each live content_type rule gets its own resolution for
+    // every known account (workspace rule + that type's rule).
+    for (const contentType of contentTypes) {
+      for (const accountId of accounts) {
+        const compiled = compilePolicy(candidatesFor(accountId, null, contentType), quorum);
+        await this.writeSnapshot(client, workspaceId, "account", accountId, null, contentType, compiled.rule, compiled.policy_version, compiled.resolvedFrom);
+        snapshots.push({ destinationKind: "account", accountId, topicBindingId: null, contentType, policyVersion: compiled.policy_version });
+      }
+    }
+    return { snapshots };
+  }
+
+  private async writeSnapshot(
+    client: PoolClient,
+    workspaceId: string,
+    destinationKind: "account" | "topic",
+    accountId: string,
+    topicBindingId: string | null,
+    contentType: string,
+    rule: PolicyRule,
+    policyVersion: string,
+    resolvedFrom: Array<{ scope: RuleScope }>,
+  ): Promise<void> {
+    await client.query(
+      `INSERT INTO posting_policy_snapshots
+         (workspace_id, destination_kind, account_id, topic_binding_id, content_type, effective, policy_version, resolved_from)
+       VALUES ($1, $2, $3, $4, $5, $6::jsonb, $7, $8::jsonb)
+       ON CONFLICT (workspace_id, destination_kind, account_id, topic_binding_id, content_type)
+       DO UPDATE SET effective = EXCLUDED.effective, policy_version = EXCLUDED.policy_version,
+                     resolved_from = EXCLUDED.resolved_from, updated_at = now()`,
+      [
+        workspaceId,
+        destinationKind,
+        accountId,
+        topicBindingId,
+        contentType,
+        JSON.stringify(rule),
+        policyVersion,
+        JSON.stringify({ scopes: resolvedFrom.map((r) => r.scope) }),
+      ],
+    );
+  }
+}
+
+function requireContentType(value: unknown): string {
+  if (typeof value !== "string" || !/^[a-z0-9_.-]{1,40}$/.test(value)) {
+    throw new BadRequestException("contentType must be 1..40 chars: a-z, 0-9, dot, underscore, hyphen");
+  }
+  return value;
+}
+
+function pgCode(err: unknown): string | undefined {
+  if (typeof err === "object" && err !== null && "code" in err) {
+    const code = (err as { code: unknown }).code;
+    return typeof code === "string" ? code : undefined;
+  }
+  return undefined;
+}
+
+export { isUuidList };
diff --git a/apps/api/src/chatgov/policy.test.ts b/apps/api/src/chatgov/policy.test.ts
new file mode 100644
index 0000000..0cbc210
--- /dev/null
+++ b/apps/api/src/chatgov/policy.test.ts
@@ -0,0 +1,173 @@
+import { describe, expect, it } from "vitest";
+import {
+  canonicalJson,
+  compilePolicy,
+  parsePolicyRule,
+  policyHash,
+  resolvePrecedence,
+  type QuorumStateInput,
+  type RuleCandidate,
+} from "./policy.js";
+
+/**
+ * P0 acceptance (design §7): "policy compile is pure + snapshot hash
+ * deterministic". Pure-function tests — no DB, no clock.
+ */
+
+const quorum: QuorumStateInput = { adminCount: 3, observedParticipants: 12, eligibleParticipants: 8 };
+
+const immediate = { version: 1, mode: "immediate" as const };
+const adminOnly = { version: 1, mode: "admin_only" as const, timebox: { duration: "PT1H", onExpire: "reject" as const } };
+const quorumRule = {
+  version: 1,
+  mode: "quorum" as const,
+  arms: [
+    { kind: "admins" as const, x: 2 },
+    { kind: "participants" as const, x: 3, of: "observed" as const },
+  ],
+  join: "all" as const,
+  allowVeto: true,
+  timebox: { duration: "PT2H", onExpire: "reject" as const },
+};
+
+describe("canonicalJson", () => {
+  it("sorts keys and drops undefined, so key order never changes the hash input", () => {
+    expect(canonicalJson({ b: 1, a: 2 })).toBe(canonicalJson({ a: 2, b: 1 }));
+    expect(canonicalJson({ a: undefined, b: 1 })).toBe(canonicalJson({ b: 1 }));
+    expect(canonicalJson({ a: [1, { y: 2, x: 1 }] })).toBe('{"a":[1,{"x":1,"y":2}]}');
+  });
+  it("keeps array order (order is data)", () => {
+    expect(canonicalJson({ a: [2, 1] })).not.toBe(canonicalJson({ a: [1, 2] }));
+  });
+});
+
+describe("policyHash determinism", () => {
+  it("same rule (any key order / explicit defaults) => same hash", () => {
+    const a = parsePolicyRule({ mode: "quorum", arms: [{ kind: "admins", x: 2 }], timebox: { duration: "PT2H", onExpire: "reject" } });
+    const b = parsePolicyRule({
+      timebox: { onExpire: "reject", duration: "PT2H" },
+      arms: [{ x: 2, kind: "admins" }],
+      mode: "quorum",
+      join: "all",
+      allowVeto: false,
+      anonymity: "named",
+      allowSelfApproval: false,
+      resetOnChange: true,
+      dryRun: false,
+      minDwellSeconds: 0,
+    });
+    expect(policyHash(a)).toBe(policyHash(b));
+  });
+  it("different policy => different hash", () => {
+    expect(policyHash(parsePolicyRule({ mode: "immediate" })))
+      .not.toBe(policyHash(parsePolicyRule({ mode: "admin_only", timebox: { duration: "PT1H", onExpire: "reject" } })));
+    const withVeto = parsePolicyRule({ mode: "quorum", arms: [{ kind: "admins", x: 2 }], allowVeto: true, timebox: { duration: "PT1H", onExpire: "reject" } });
+    const noVeto = parsePolicyRule({ mode: "quorum", arms: [{ kind: "admins", x: 2 }], allowVeto: false, timebox: { duration: "PT1H", onExpire: "reject" } });
+    expect(policyHash(withVeto)).not.toBe(policyHash(noVeto));
+  });
+  it("quorum denominators never enter the hash", () => {
+    const rule = parsePolicyRule(quorumRule);
+    const withSmall: QuorumStateInput = { adminCount: 1, observedParticipants: 1, eligibleParticipants: 1 };
+    const withBig: QuorumStateInput = { adminCount: 99, observedParticipants: 9999, eligibleParticipants: 500 };
+    expect(policyHash(rule)).toBe(compilePolicy([{ scope: "workspace", rule }], withSmall).policy_version);
+    expect(compilePolicy([{ scope: "workspace", rule }], withSmall).policy_version)
+      .toBe(compilePolicy([{ scope: "workspace", rule }], withBig).policy_version);
+  });
+});
+
+describe("compilePolicy", () => {
+  it("candidate order does not change the compiled snapshot", () => {
+    const candidates: RuleCandidate[] = [
+      { scope: "workspace", rule: parsePolicyRule(immediate) },
+      { scope: "account", rule: parsePolicyRule(adminOnly) },
+      { scope: "topic", rule: parsePolicyRule(quorumRule) },
+    ];
+    const forward = compilePolicy(candidates, quorum);
+    const shuffled = compilePolicy([...candidates].reverse(), quorum);
+    expect(forward.policy_version).toBe(shuffled.policy_version);
+    expect(canonicalJson(forward.rule)).toBe(canonicalJson(shuffled.rule));
+  });
+  it("repeated compiles are byte-identical (no hidden state)", () => {
+    const candidates: RuleCandidate[] = [{ scope: "content_type", rule: parsePolicyRule(adminOnly) }];
+    const first = compilePolicy(candidates, quorum);
+    for (let i = 0; i < 5; i += 1) {
+      expect(compilePolicy(candidates, quorum)).toEqual(first);
+    }
+  });
+  it("no candidates => fail-closed immediate baseline with a stable version", () => {
+    const empty = compilePolicy([], quorum);
+    expect(empty.rule.mode).toBe("immediate");
+    expect(empty.policy_version).toBe(compilePolicy([], { adminCount: 0, observedParticipants: 0, eligibleParticipants: 0 }).policy_version);
+    expect(empty.policy_version).toBe(policyHash(parsePolicyRule({ mode: "immediate", allowVeto: false })));
+  });
+});
+
+describe("resolvePrecedence (D4: topic > content_type > account > workspace)", () => {
+  it("picks the most specific scope", () => {
+    const all: RuleCandidate[] = [
+      { scope: "workspace", rule: parsePolicyRule(immediate) },
+      { scope: "account", rule: parsePolicyRule(adminOnly) },
+      { scope: "content_type", rule: parsePolicyRule(adminOnly) },
+      { scope: "topic", rule: parsePolicyRule(quorumRule) },
+    ];
+    expect(resolvePrecedence(all).scope).toBe("topic");
+    expect(resolvePrecedence(all.filter((c) => c.scope !== "topic")).scope).toBe("content_type");
+    expect(resolvePrecedence(all.filter((c) => c.scope === "account" || c.scope === "workspace")).scope).toBe("account");
+    expect(resolvePrecedence(all.filter((c) => c.scope === "workspace")).scope).toBe("workspace");
+  });
+  it("whole-block replacement: the winner's rule IS the effective policy", () => {
+    const winner = resolvePrecedence([
+      { scope: "workspace", rule: parsePolicyRule(quorumRule) },
+      { scope: "topic", rule: parsePolicyRule(adminOnly) },
+    ]);
+    expect(winner.rule.mode).toBe("admin_only");
+    expect(winner.rule).not.toHaveProperty("arms");
+  });
+});
+
+describe("parsePolicyRule validation (400s, never 500s)", () => {
+  it("rejects malformed shapes", () => {
+    const bad: unknown[] = [
+      null,
+      "immediate",
+      { mode: "nope" },
+      { mode: "quorum" }, // no arms
+      { mode: "quorum", arms: [] },
+      { mode: "quorum", arms: [{ kind: "admins", x: 0 }] },
+      { mode: "quorum", arms: [{ kind: "admins", x: 2 }], timebox: { duration: "2 hours", onExpire: "reject" } },
+      { mode: "quorum", arms: [{ kind: "admins", x: 2 }] }, // no timebox
+      { mode: "admin_only", arms: [{ kind: "participants", x: 2 }], timebox: { duration: "PT1H", onExpire: "reject" } },
+      { mode: "immediate", arms: [{ kind: "admins", x: 1 }] },
+      { mode: "quorum", arms: [{ kind: "admins", x: 2, of: "observed" }], timebox: { duration: "PT1H", onExpire: "reject" } },
+      { mode: "quorum", arms: [{ kind: "participants", x: 2 }], timebox: { duration: "PT1H", onExpire: "maybe" } },
+      { mode: "quorum", arms: [{ kind: "admins", x: 2 }], join: "xor", timebox: { duration: "PT1H", onExpire: "reject" } },
+      { mode: "quorum", arms: [{ kind: "admins", x: 2 }], anonymity: "secret", timebox: { duration: "PT1H", onExpire: "reject" } },
+      { mode: "quorum", arms: [{ kind: "admins", x: 2 }], minDwellSeconds: -1, timebox: { duration: "PT1H", onExpire: "reject" } },
+      { version: 2, mode: "immediate" },
+    ];
+    for (const input of bad) {
+      expect(() => parsePolicyRule(input), JSON.stringify(input)).toThrow();
+    }
+  });
+  it("accepts the full §1a surface and normalises defaults", () => {
+    const rule = parsePolicyRule(quorumRule);
+    expect(rule).toMatchObject({
+      version: 1,
+      mode: "quorum",
+      join: "all",
+      allowVeto: true,
+      anonymity: "named",
+      allowSelfApproval: false,
+      resetOnChange: true,
+      dryRun: false,
+      minDwellSeconds: 0,
+    });
+    expect(rule.arms).toHaveLength(2);
+    expect(rule.timebox).toEqual({ duration: "PT2H", onExpire: "reject" });
+  });
+  it("ISO-8601 duration shapes accepted include days/minutes/seconds", () => {
+    for (const duration of ["PT30M", "PT45S", "P1DT12H", "PT2H30M"]) {
+      expect(() => parsePolicyRule({ mode: "quorum", arms: [{ kind: "admins", x: 1 }], timebox: { duration, onExpire: "escalateOwner" } })).not.toThrow();
+    }
+  });
+});
diff --git a/apps/api/src/chatgov/policy.ts b/apps/api/src/chatgov/policy.ts
new file mode 100644
index 0000000..0f3a3ec
--- /dev/null
+++ b/apps/api/src/chatgov/policy.ts
@@ -0,0 +1,301 @@
+import { createHash } from "node:crypto";
+import { BadRequestException } from "@nestjs/common";
+
+/**
+ * Chat governance policy primitives (chatgov-design.md §1a/§1d).
+ *
+ * These functions are PURE on purpose — no DB, no clock, no randomness. The
+ * compiled snapshot and its `policy_version` hash must be deterministic so
+ * that the same rules + quorum state always produce byte-identical output
+ * (P0 acceptance: "policy compile is pure + snapshot hash deterministic").
+ * Time-dependent values (opens_at/closes_at) never enter the hash input.
+ */
+
+export type GateMode = "immediate" | "quorum" | "admin_only";
+
+/** Whose ballots count toward an arm. Eligibility is resolved at CLOSE time
+ * (TOCTOU guard, §1a) by the evaluator; the compile step only records the
+ * shape. */
+export type ArmKind = "admins" | "participants";
+
+/** Participants denominator: observed roster | explicit eligible roster | pure count. */
+export type ParticipantsOf = "observed" | "eligible" | "none";
+
+export interface QuorumArm {
+  kind: ArmKind;
+  /** Absolute count needed from this arm. */
+  x: number;
+  /** Participants arms only: how the denominator is derived. */
+  of?: ParticipantsOf;
+}
+
+export interface TimeboxSpec {
+  /** ISO-8601 duration (e.g. "PT2H"). Validated shape-only here. */
+  duration: string;
+  onExpire: "approve" | "reject" | "escalateOwner";
+}
+
+/** §1a pass-criteria rule object as stored in posting_rules.policy and
+ * polls.rule (compiled). */
+export interface PolicyRule {
+  version: number;
+  mode: GateMode;
+  arms?: QuorumArm[];
+  /** all (AND, default) | any (OR). */
+  join?: "all" | "any";
+  allowVeto?: boolean;
+  /** Seconds; early close only when quorum ∧ dwell. */
+  minDwellSeconds?: number;
+  timebox?: TimeboxSpec;
+  /** named | anonymous — never mixed silently. */
+  anonymity?: "named" | "anonymous";
+  allowSelfApproval?: boolean;
+  /** Draft edit ⇒ approvals reset, poll re-arms. */
+  resetOnChange?: boolean;
+  /** Evaluate + log, never block/fire. */
+  dryRun?: boolean;
+}
+
+export const POLICY_SCHEMA_VERSION = 1;
+
+/** Machine-readable reason codes (design §4). Kept here (not in the module
+ * file) so P1-P3 import them without dragging in Nest decorators. */
+export const REASON_CODES = [
+  "INSUFFICIENT_QUORUM",
+  "INELIGIBLE_ACTOR",
+  "SELF_APPROVAL_DENIED",
+  "TIMEBOX_EXPIRED_AUTO_REJECT",
+  "TIMEBOX_EXPIRED_AUTO_APPROVE",
+  "RESET_ON_CHANGE",
+  "PENDING_POLL",
+  "VETOED",
+  "OUTSIDE_POLICY",
+  "POLICY_DRY_RUN",
+  "OVERRIDDEN_BY_OWNER",
+  "LOCKED_CHANNEL",
+  "NO_CHANNEL_BOUND",
+  "CONFIRM_EXPIRED",
+] as const;
+
+export type ReasonCode = (typeof REASON_CODES)[number];
+
+export const GATES = ["E1", "E2", "E3"] as const;
+export type Gate = (typeof GATES)[number];
+
+/** Public (denormalised) chatgov permissions. Seeded into role_permissions by
+ * migration 024; mirrored here because packages/core's PERMISSIONS list is
+ * frozen for the WP2 slice and apps/web reads permissions from the API. */
+export const CHATGOV_PERMISSIONS = {
+  /** Rules editor, topic registry, identity approval, policy compile. */
+  manage: "chatgov.manage",
+  /** Open/cast governance votes. */
+  vote: "chatgov.vote",
+} as const;
+
+const DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+(\.\d+)?S)?)?$/;
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+
+export function isUuidList(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string" && UUID_RE.test(v));
+}
+
+/** Parse + validate a §1a-shaped policy object (unknown in, typed out). */
+export function parsePolicyRule(input: unknown, field = "policy"): PolicyRule {
+  if (typeof input !== "object" || input === null || Array.isArray(input)) {
+    throw new BadRequestException(`${field} must be an object`);
+  }
+  const raw = input as Record<string, unknown>;
+  const version = raw.version === undefined ? POLICY_SCHEMA_VERSION : raw.version;
+  if (version !== POLICY_SCHEMA_VERSION) {
+    throw new BadRequestException(`${field}.version must be ${POLICY_SCHEMA_VERSION}`);
+  }
+  const mode = raw.mode;
+  if (mode !== "immediate" && mode !== "quorum" && mode !== "admin_only") {
+    throw new BadRequestException(`${field}.mode must be immediate, quorum or admin_only`);
+  }
+  const join = raw.join === undefined ? "all" : raw.join;
+  if (join !== "all" && join !== "any") throw new BadRequestException(`${field}.join must be all or any`);
+
+  const arms: QuorumArm[] = [];
+  if (raw.arms !== undefined) {
+    if (!Array.isArray(raw.arms)) throw new BadRequestException(`${field}.arms must be an array`);
+    if (raw.arms.length === 0) throw new BadRequestException(`${field}.arms must not be empty`);
+    if (raw.arms.length > 4) throw new BadRequestException(`${field}.arms supports at most 4 arms`);
+    for (const [index, entry] of raw.arms.entries()) {
+      if (typeof entry !== "object" || entry === null) throw new BadRequestException(`${field}.arms[${index}] must be an object`);
+      const arm = entry as Record<string, unknown>;
+      if (arm.kind !== "admins" && arm.kind !== "participants") {
+        throw new BadRequestException(`${field}.arms[${index}].kind must be admins or participants`);
+      }
+      const x = arm.x;
+      if (typeof x !== "number" || !Number.isInteger(x) || x < 1 || x > 1000) {
+        throw new BadRequestException(`${field}.arms[${index}].x must be an integer between 1 and 1000`);
+      }
+      if (arm.of !== undefined) {
+        if (arm.kind !== "participants") {
+          throw new BadRequestException(`${field}.arms[${index}].of applies to participants arms only`);
+        }
+        if (arm.of !== "observed" && arm.of !== "eligible" && arm.of !== "none") {
+          throw new BadRequestException(`${field}.arms[${index}].of must be observed, eligible or none`);
+        }
+      }
+      arms.push({ kind: arm.kind, x, ...(arm.of === undefined ? {} : { of: arm.of }) });
+    }
+  }
+
+  if (mode === "admin_only" && arms.some((arm) => arm.kind === "participants")) {
+    throw new BadRequestException(`${field}: admin_only mode has no participants arm`);
+  }
+  if (mode === "quorum" && arms.length === 0) {
+    throw new BadRequestException(`${field}: quorum mode requires arms`);
+  }
+  if (mode !== "quorum" && arms.length > 0) {
+    throw new BadRequestException(`${field}: ${mode} mode takes no arms`);
+  }
+
+  const timebox = raw.timebox;
+  let parsedTimebox: TimeboxSpec | undefined;
+  if (timebox !== undefined) {
+    if (typeof timebox !== "object" || timebox === null) throw new BadRequestException(`${field}.timebox must be an object`);
+    const spec = timebox as Record<string, unknown>;
+    if (typeof spec.duration !== "string" || !DURATION.test(spec.duration)) {
+      throw new BadRequestException(`${field}.timebox.duration must be an ISO-8601 duration`);
+    }
+    if (spec.onExpire !== "approve" && spec.onExpire !== "reject" && spec.onExpire !== "escalateOwner") {
+      throw new BadRequestException(`${field}.timebox.onExpire must be approve, reject or escalateOwner`);
+    }
+    parsedTimebox = { duration: spec.duration, onExpire: spec.onExpire };
+  }
+  if (parsedTimebox === undefined && mode !== "immediate") {
+    throw new BadRequestException(`${field}: ${mode} mode requires timebox`);
+  }
+
+  const anonymity = raw.anonymity === undefined ? "named" : raw.anonymity;
+  if (anonymity !== "named" && anonymity !== "anonymous") {
+    throw new BadRequestException(`${field}.anonymity must be named or anonymous`);
+  }
+  const allowVeto = raw.allowVeto === undefined ? false : requireBoolean(raw.allowVeto, `${field}.allowVeto`);
+  const allowSelfApproval = raw.allowSelfApproval === undefined ? false : requireBoolean(raw.allowSelfApproval, `${field}.allowSelfApproval`);
+  const resetOnChange = raw.resetOnChange === undefined ? true : requireBoolean(raw.resetOnChange, `${field}.resetOnChange`);
+  const dryRun = raw.dryRun === undefined ? false : requireBoolean(raw.dryRun, `${field}.dryRun`);
+  const minDwellSeconds = raw.minDwellSeconds === undefined ? 0 : raw.minDwellSeconds;
+  if (typeof minDwellSeconds !== "number" || !Number.isInteger(minDwellSeconds) || minDwellSeconds < 0 || minDwellSeconds > 86400) {
+    throw new BadRequestException(`${field}.minDwellSeconds must be an integer between 0 and 86400`);
+  }
+
+  return {
+    version: POLICY_SCHEMA_VERSION,
+    mode,
+    ...(arms.length === 0 ? {} : { arms }),
+    join,
+    allowVeto,
+    minDwellSeconds,
+    ...(parsedTimebox === undefined ? {} : { timebox: parsedTimebox }),
+    anonymity,
+    allowSelfApproval,
+    resetOnChange,
+    dryRun,
+  };
+}
+
+function requireBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new BadRequestException(`${field} must be a boolean`);
+  return value;
+}
+
+/**
+ * Canonical JSON: keys sorted lexicographically, no insignificant whitespace,
+ * arrays keep order. This — not JSON.stringify of the source object — is the
+ * hash input, so an equivalent policy written with different key order or
+ * explicit defaults still compiles to the same version.
+ */
+export function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>)
+    .filter(([, v]) => v !== undefined)
+    .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonicalJson(v)}`).join(",")}}`;
+}
+
+/** Deterministic snapshot hash: sha256 over the canonical JSON (hex, 16 chars
+ * — short enough for UI display, long enough to be collision-safe here). */
+export function policyHash(value: unknown): string {
+  return createHash("sha256").update(canonicalJson(value)).digest("hex").slice(0, 16);
+}
+
+// ---------------------------------------------------------------------------
+// Compile: rules + quorum state -> immutable snapshot.
+// ---------------------------------------------------------------------------
+
+export type RuleScope = "workspace" | "account" | "content_type" | "topic";
+
+export interface CompiledPolicySnapshot {
+  rule: PolicyRule;
+  policy_version: string;
+}
+
+/** A live rule candidate offered to the compiler. */
+export interface RuleCandidate {
+  scope: RuleScope;
+  rule: PolicyRule;
+}
+
+/** Quorum denominators AT COMPILE TIME. Recorded in the snapshot for
+ * observability only — never hashed — so a re-compile after roster drift
+ * yields the same policy_version unless the policy itself changed. */
+export interface QuorumStateInput {
+  adminCount: number;
+  observedParticipants: number;
+  eligibleParticipants: number;
+}
+
+/** Precedence (D4): topic > content_type > account > workspace. */
+const SCOPE_ORDER: readonly RuleScope[] = ["workspace", "account", "content_type", "topic"];
+
+/**
+ * Resolve the winning rule among `candidates` (any order, duplicates allowed —
+ * most specific scope wins; ties resolve to the first candidate of that scope,
+ * which the caller keeps stable by ordering rules by created_at).
+ */
+export function resolvePrecedence(candidates: RuleCandidate[]): RuleCandidate {
+  let winner: RuleCandidate | null = null;
+  for (const candidate of candidates) {
+    if (winner === null || SCOPE_ORDER.indexOf(candidate.scope) > SCOPE_ORDER.indexOf(winner.scope)) {
+      winner = candidate;
+    }
+  }
+  if (winner !== null) return winner;
+  // Fail-closed baseline: an explicit `immediate` policy so every destination
+  // has a persisted snapshot (§1d fallback:block is an EVALUATION posture —
+  // OUTSIDE_POLICY at the gate — not a compile input).
+  return { scope: "workspace", rule: parsePolicyRule({ mode: "immediate", allowVeto: false }) };
+}
+
+export interface CompiledSnapshot {
+  rule: PolicyRule;
+  policy_version: string;
+  resolvedFrom: Array<{ scope: RuleScope }>;
+  quorum: QuorumStateInput;
+}
+
+/**
+ * Compile the effective policy for one destination. PURE + DETERMINISTIC:
+ * - candidates in any order produce the same winner and the same version;
+ * - the version hashes only the winning rule (quorum denominators are
+ *   observability, not identity);
+ * - no clock, no DB, no randomness.
+ */
+export function compilePolicy(candidates: RuleCandidate[], quorum: QuorumStateInput): CompiledSnapshot {
+  const winner = resolvePrecedence(candidates);
+  const resolvedFrom = [...candidates]
+    .sort((a, b) => a.scope.localeCompare(b.scope))
+    .map((c) => ({ scope: c.scope }));
+  return {
+    rule: winner.rule,
+    policy_version: policyHash(winner.rule),
+    resolvedFrom,
+    quorum,
+  };
+}
diff --git a/apps/api/src/chatgov/poll-evaluator.ts b/apps/api/src/chatgov/poll-evaluator.ts
new file mode 100644
index 0000000..43abee9
--- /dev/null
+++ b/apps/api/src/chatgov/poll-evaluator.ts
@@ -0,0 +1,71 @@
+import type { PolicyRule, QuorumArm } from './policy.js';
+
+export interface EvaluatedBallot {
+  ballot: 'yes' | 'no' | 'veto' | 'abstain';
+  optionId: string | null;
+  counted: boolean;
+  admin: boolean;
+  observed: boolean;
+  participant: boolean;
+}
+export interface OptionTally { id: string; seq: number; submittedAt: string; votes: number }
+export interface ArmTally { kind: QuorumArm['kind']; of?: QuorumArm['of']; got: number; needed: number; possible: number | null }
+export interface PollEvaluation {
+  arms: ArmTally[];
+  quorum: boolean;
+  winnerOptionId: string | null;
+  tallies: OptionTally[];
+  turnout: number;
+  state: 'passed' | 'failed' | 'vetoed' | 'quorum_unreachable' | null;
+  reason: 'quorum_early' | 'timebox' | 'veto' | 'quorum_unreachable' | null;
+}
+
+/** Pure decision; membership, self-approval and observed roster are resolved
+ * afresh by the service. A plurality never substitutes for legitimacy. */
+export function evaluatePoll(input: {
+  kind: 'yes_no' | 'variant_selection'; rule: PolicyRule;
+  opensAt: Date; closesAt: Date; now: Date;
+  ballots: EvaluatedBallot[]; options: Omit<OptionTally, 'votes'>[];
+  possible: { admins: number; eligible: number; observed: number };
+}): PollEvaluation {
+  const { rule, ballots } = input;
+  const selected = ballots.filter(b => b.counted && b.ballot === 'yes' && (input.kind === 'yes_no' || b.optionId !== null));
+  const tallies = input.options.map(o => ({ ...o, votes: selected.filter(b => b.optionId === o.id).length }));
+  const winner = [...tallies].sort((a, b) => b.votes - a.votes || Date.parse(a.submittedAt) - Date.parse(b.submittedAt) || a.seq - b.seq)[0];
+  const specs: QuorumArm[] = rule.mode === 'admin_only' ? [{ kind: 'admins', x: 1 }] : rule.arms ?? [];
+  const arms = specs.map(arm => {
+    const matches = (b: EvaluatedBallot): boolean => arm.kind === 'admins' ? b.admin : arm.of === 'observed' ? b.observed : b.participant;
+    return { kind: arm.kind, ...(arm.of === undefined ? {} : { of: arm.of }),
+      got: selected.filter(matches).length, needed: arm.x,
+      // Observed/count-only rosters can grow; never eagerly declare them impossible.
+      possible: arm.kind === 'admins' ? input.possible.admins : arm.of === 'eligible' ? input.possible.eligible : null };
+  });
+  const quorum = rule.mode === 'immediate' || (rule.join === 'any' ? arms.some(a => a.got >= a.needed) : arms.every(a => a.got >= a.needed));
+  const result: PollEvaluation = { arms, quorum, tallies, turnout: selected.length,
+    winnerOptionId: winner?.id ?? null, state: null, reason: null };
+  const choice = input.kind === 'yes_no' || winner !== undefined;
+  if (rule.allowVeto && ballots.some(b => b.counted && b.ballot === 'veto')) {
+    result.state = 'vetoed'; result.reason = 'veto';
+  } else if (input.now >= input.closesAt) {
+    result.state = quorum && choice && rule.timebox?.onExpire === 'approve' ? 'passed' : 'failed';
+    result.reason = 'timebox';
+  } else if (quorum && choice && input.now.getTime() - input.opensAt.getTime() >= (rule.minDwellSeconds ?? 0) * 1000) {
+    result.state = 'passed'; result.reason = 'quorum_early';
+  } else {
+    const impossible = (a: ArmTally): boolean => a.possible !== null && a.possible < a.needed;
+    if (arms.length && (rule.join === 'any' ? arms.every(impossible) : arms.some(impossible))) {
+      result.state = 'quorum_unreachable'; result.reason = 'quorum_unreachable';
+    }
+  }
+  return result;
+}
+
+/** Fixed-length ISO durations only; months/years are calendar-dependent. */
+export function durationMs(duration: string): number {
+  const match = /^P(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/.exec(duration);
+  if (!match) throw new Error('poll timebox requires a fixed duration (weeks/days/hours/minutes/seconds)');
+  const [, w, d, h, m, s] = match;
+  const ms = ((Number(w ?? 0) * 7 + Number(d ?? 0)) * 86400 + Number(h ?? 0) * 3600 + Number(m ?? 0) * 60 + Number(s ?? 0)) * 1000;
+  if (!Number.isFinite(ms) || ms <= 0 || ms > 365 * 86400_000) throw new Error('poll duration must be positive and at most 365 days');
+  return ms;
+}
diff --git a/apps/api/src/chatgov/poll-timebox.service.ts b/apps/api/src/chatgov/poll-timebox.service.ts
new file mode 100644
index 0000000..0d3c733
--- /dev/null
+++ b/apps/api/src/chatgov/poll-timebox.service.ts
@@ -0,0 +1,30 @@
+import { Inject, Injectable, Logger, type OnModuleDestroy, type OnModuleInit } from '@nestjs/common';
+import { pool } from '../db/client.js';
+import { PollService } from './poll.service.js';
+
+/** Durable database timeboxes plus lazy read evaluation. A Temporal adapter
+ * can call the same exactly-once close without changing the state machine. */
+@Injectable()
+export class PollTimeboxService implements OnModuleInit, OnModuleDestroy {
+  private timer?: ReturnType<typeof setInterval>;
+  private running = false;
+  private readonly logger = new Logger(PollTimeboxService.name);
+  constructor(@Inject(PollService) private readonly polls: PollService) {}
+  onModuleInit(): void {
+    this.timer = setInterval(() => { void this.tick(); }, 1000);
+    this.timer.unref();
+  }
+  onModuleDestroy(): void { if (this.timer) clearInterval(this.timer); }
+  async tick(): Promise<void> {
+    if (this.running) return;
+    this.running = true;
+    try {
+      const due = await pool.query<{ workspace_id: string; id: string }>('SELECT * FROM chatgov_due_polls()');
+      for (const row of due.rows) {
+        try { await this.polls.close(row.workspace_id, row.id); }
+        catch (error) { this.logger.warn(`poll ${row.id} expiry will retry: ${String(error)}`); }
+      }
+    } catch (error) { this.logger.warn(`poll timebox discovery will retry: ${String(error)}`); }
+    finally { this.running = false; }
+  }
+}
diff --git a/apps/api/src/chatgov/poll.controller.ts b/apps/api/src/chatgov/poll.controller.ts
new file mode 100644
index 0000000..7bfe75a
--- /dev/null
+++ b/apps/api/src/chatgov/poll.controller.ts
@@ -0,0 +1,37 @@
+import { Body, Controller, Get, Inject, Param, Post, Req, UseGuards } from '@nestjs/common';
+import type { Request } from 'express';
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from '../rbac/rbac.guard.js';
+import { requireSession } from '../http/validation.js';
+import { PollService, type PollCard } from './poll.service.js';
+
+@Controller('chatgov/polls')
+@UseGuards(RbacGuard)
+export class PollController {
+  constructor(@Inject(PollService) private readonly polls: PollService) {}
+  @Get(':id')
+  @RequirePermission('workspace.view')
+  async get(@Req() req: Request & AuthenticatedRequest, @Param('id') id: string): Promise<PollCard> {
+    const session = requireSession(req);
+    return this.polls.get(session.workspaceId, id, session.userId);
+  }
+  @Post()
+  @RequirePermission('chatgov.vote')
+  async open(@Req() req: Request & AuthenticatedRequest, @Body() body: unknown): Promise<PollCard> {
+    const session = requireSession(req);
+    return this.polls.open(session.workspaceId, body, { userId: session.userId });
+  }
+  @Post(':id/options')
+  @RequirePermission('chatgov.vote')
+  async fork(@Req() req: Request & AuthenticatedRequest, @Param('id') id: string, @Body() body: unknown): Promise<PollCard> {
+    const session = requireSession(req);
+    return this.polls.forkEdit(session.workspaceId, id, body, { userId: session.userId });
+  }
+  // Any authenticated member can store an ineligible ballot. Eligibility is
+  // enforced by the service; identity fields in the body are never trusted.
+  @Post(':id/vote')
+  @RequirePermission('workspace.view')
+  async vote(@Req() req: Request & AuthenticatedRequest, @Param('id') id: string, @Body() body: unknown): Promise<PollCard> {
+    const session = requireSession(req);
+    return this.polls.vote(session.workspaceId, id, body, { kind: 'user', userId: session.userId });
+  }
+}
diff --git a/apps/api/src/chatgov/poll.service.ts b/apps/api/src/chatgov/poll.service.ts
new file mode 100644
index 0000000..b30de16
--- /dev/null
+++ b/apps/api/src/chatgov/poll.service.ts
@@ -0,0 +1,380 @@
+import { BadRequestException, ConflictException, ForbiddenException, Injectable, NotFoundException } from '@nestjs/common';
+import type { PoolClient } from 'pg';
+import { withTenant } from '../db/client.js';
+import { parseId, requireObject, requireString } from '../http/validation.js';
+import { scrub } from '../audit/audit.service.js';
+import { draftDestinationAccounts } from '../publishing/approval-gate.service.js';
+import type { DraftPost } from '../publishing/publishing.service.js';
+import { transitionPollDraft } from '../publishing/poll-approval.js';
+import { parsePolicyRule, policyHash, type PolicyRule, type QuorumArm } from './policy.js';
+import { durationMs, evaluatePoll, type EvaluatedBallot, type PollEvaluation } from './poll-evaluator.js';
+
+export interface PollActor { userId: string; role?: string }
+export interface PollVoter { kind: 'user' | 'chat_identity'; userId?: string; provider?: string; remoteId?: string; handle?: string }
+interface PollRow {
+  id: string; workspace_id: string; draft_id: string | null; draft_revision: string | null;
+  channel_id: string | null; topic_binding_id: string | null; question: string;
+  kind: 'yes_no' | 'variant_selection'; state: string; rule: PolicyRule; policy_version: string;
+  anonymity: string; opens_at: Date; closes_at: Date; created_by: string;
+  winner_option_id: string | null; eligible_user_ids: string[] | null;
+  parent_poll_id: string | null; closed_at: Date | null; close_reason: string | null; outbox_state: string;
+}
+interface OptionRow { id: string; seq: number; text: string; submitted_by: string; submitted_at: Date; draft_revision_id: string | null; author: string }
+interface Member { user_id: string; role: string; can_vote: boolean }
+interface VoteRow { voter_kind: 'user' | 'chat_identity'; voter_user_id: string | null; voter_remote_id: string; voter_handle: string;
+  ballot: EvaluatedBallot['ballot']; option_id: string | null; counted: boolean; eligible: boolean; ineligible_reason: string | null }
+export interface PollCard {
+  poll: PollRow; options: OptionRow[]; evaluation: PollEvaluation;
+  votes: VoteRow[]; voterEligibility: { eligible: boolean; admin: boolean; reason: string | null } | null;
+}
+
+/** All writes use workspace → draft → poll lock order, matching publishing
+ * and membership epoch updates. The outbox claim and E2 transition share one
+ * transaction; rollback also releases the claim. Late ballots are no-ops. */
+@Injectable()
+export class PollService {
+  async open(workspaceId: string, body: unknown, actor: PollActor): Promise<PollCard> {
+    return withTenant(workspaceId, async client => {
+      await lockWorkspace(client, workspaceId);
+      const poll = await openPollInTransaction(client, workspaceId, body, actor);
+      return card(client, poll, actor.userId);
+    });
+  }
+  async forkEdit(workspaceId: string, pollId: string, body: unknown, actor: PollActor): Promise<PollCard> {
+    const dto = requireObject(body, 'body'); const text = variantText(dto.text);
+    return this.locked(workspaceId, pollId, async (client, poll) => {
+      await requireVoter(client, workspaceId, actor.userId);
+      await evaluateLocked(client, poll);
+      if (poll.state !== 'open' || poll.kind !== 'variant_selection') throw new ConflictException('only open variant polls accept forks');
+      const seq = Number((await client.query('SELECT COALESCE(max(seq), 0) + 1 AS seq FROM poll_options WHERE poll_id = $1', [poll.id])).rows[0]?.seq);
+      await insertOption(client, poll, seq, text, actor.userId);
+      await audit(client, poll, 'poll.option_submitted', actor.userId, { seq });
+      return card(client, poll, actor.userId);
+    });
+  }
+  async vote(workspaceId: string, pollId: string, body: unknown, voter: PollVoter): Promise<PollCard> {
+    const dto = requireObject(body, 'body');
+    const optionId = dto.optionId === undefined || dto.optionId === null ? null : parseId(requireString(dto.optionId, 'optionId'));
+    const ballot = dto.ballot ?? (optionId ? 'yes' : undefined);
+    if (!['yes', 'no', 'veto', 'abstain'].includes(String(ballot))) throw new BadRequestException('invalid ballot');
+    return this.locked(workspaceId, pollId, async (client, poll) => {
+      // Expiry is resolved before accepting a late ballot; retries after close
+      // render the frozen artifact without changing the decision.
+      if (new Date() >= poll.closes_at) await evaluateLocked(client, poll);
+      if (poll.state !== 'open') return card(client, poll, voter.userId);
+      if (poll.kind === 'variant_selection' && ballot === 'yes' && optionId === null) throw new BadRequestException('variant vote requires optionId');
+      if (optionId && (poll.kind !== 'variant_selection' || ballot !== 'yes')) throw new BadRequestException('optionId only applies to a variant choice');
+      if (optionId && !(await client.query('SELECT id FROM poll_options WHERE id = $1 AND poll_id = $2', [optionId, poll.id])).rowCount) throw new BadRequestException('option does not belong to this poll');
+      if (ballot === 'veto' && !poll.rule.allowVeto) throw new BadRequestException('veto is disabled');
+      let userId = voter.userId ?? null;
+      let key: string;
+      let identityId: string | null = null;
+      if (voter.kind === 'user') {
+        if (!userId) throw new BadRequestException('user voter needs userId');
+        parseId(userId, 'voter.userId'); key = `user:${userId}`;
+      } else {
+        const provider = requireString(voter.provider, 'provider');
+        const remote = requireString(voter.remoteId, 'remoteId');
+        if (!/^[0-9]{1,20}$/.test(remote) || !/^[a-z0-9_-]+$/.test(provider)) throw new BadRequestException('invalid immutable provider identity');
+        key = `${provider}:${remote}`;
+        // Never trust a supplied linked user id from the gateway.
+        const identity = (await client.query("SELECT id, user_id, status FROM chat_identities WHERE provider = $1 AND remote_user_id = $2", [provider, remote])).rows[0];
+        identityId = identity?.id as string | undefined ?? null;
+        userId = identity?.status === 'approved' ? identity.user_id as string | null : null;
+      }
+      // Linked identities and web users share ONE ballot. Alternate provider
+      // accounts cannot inflate turnout. Unlinked ballots are still retained.
+      if (userId) key = `user:${userId}`;
+      await client.query(`INSERT INTO poll_votes (workspace_id, poll_id, voter_kind, voter_user_id, voter_remote_id, voter_handle, ballot, option_id, eligible, counted, voter_identity_id)
+        VALUES ($1, $2, $3, $4, $5, $6, $7, $8, false, false, $9)
+        ON CONFLICT (poll_id, voter_remote_id) DO UPDATE SET voter_kind = EXCLUDED.voter_kind,
+          voter_user_id = EXCLUDED.voter_user_id, voter_identity_id = EXCLUDED.voter_identity_id, voter_handle = EXCLUDED.voter_handle,
+          ballot = EXCLUDED.ballot, option_id = EXCLUDED.option_id, cast_at = clock_timestamp()`,
+      [workspaceId, poll.id, voter.kind, userId, key, voter.handle ?? key, ballot, optionId, identityId]);
+      await audit(client, poll, 'poll.voted', userId, { voter: key, ballot, optionId });
+      await evaluateLocked(client, poll);
+      return card(client, poll, userId ?? undefined);
+    });
+  }
+  async get(workspaceId: string, pollId: string, userId?: string): Promise<PollCard> {
+    return this.locked(workspaceId, pollId, async (client, poll) => {
+      await evaluateLocked(client, poll); return card(client, poll, userId);
+    });
+  }
+  async evaluate(workspaceId: string, pollId: string): Promise<PollCard> { return this.get(workspaceId, pollId); }
+  /** Deliberately re-evaluates the authoritative conditions; callers cannot
+   * force a pass or supply a stale tally. Suitable for competing timeboxes. */
+  async close(workspaceId: string, pollId: string): Promise<PollCard> { return this.get(workspaceId, pollId); }
+  async sweep(workspaceId: string): Promise<void> {
+    const ids = await withTenant(workspaceId, c => c.query<{ id: string }>("SELECT id FROM polls WHERE state = 'open' AND (closes_at <= now() OR opens_at + COALESCE((rule->>'minDwellSeconds')::integer,0) * interval '1 second' <= now())", []));
+    for (const { id } of ids.rows) await this.evaluate(workspaceId, id);
+  }
+  private async locked<T>(workspaceId: string, pollId: string, fn: (client: PoolClient, poll: PollRow) => Promise<T>): Promise<T> {
+    parseId(pollId, 'pollId');
+    return withTenant(workspaceId, async client => {
+      await lockWorkspace(client, workspaceId);
+      const found = (await client.query<PollRow>('SELECT * FROM polls WHERE id = $1', [pollId])).rows[0];
+      if (!found) throw new NotFoundException('poll not found');
+      if (found.draft_id) await client.query('SELECT id FROM drafts WHERE id = $1 FOR UPDATE', [found.draft_id]);
+      const poll = (await client.query<PollRow>('SELECT * FROM polls WHERE id = $1 FOR UPDATE', [pollId])).rows[0]!;
+      return fn(client, poll);
+    });
+  }
+}
+
+async function lockWorkspace(client: PoolClient, workspaceId: string): Promise<void> {
+  await client.query('SELECT id FROM workspaces WHERE id = $1 FOR UPDATE', [workspaceId]);
+}
+async function members(client: PoolClient, workspaceId: string): Promise<Member[]> {
+  return (await client.query<Member>(`SELECT m.user_id, m.role, EXISTS(SELECT 1 FROM role_permissions rp
+    WHERE rp.role = m.role AND rp.permission = 'chatgov.vote') AS can_vote
+    FROM memberships m WHERE workspace_id = $1 AND status = 'active'`, [workspaceId])).rows;
+}
+async function requireVoter(client: PoolClient, workspaceId: string, userId: string): Promise<void> {
+  parseId(userId, 'actor.userId');
+  if (!(await members(client, workspaceId)).some(m => m.user_id === userId && m.can_vote)) throw new ForbiddenException('chatgov.vote required');
+}
+function variantText(value: unknown): string {
+  const text = requireString(value, 'text');
+  if (text.length > 5000) throw new BadRequestException('variant text must be at most 5000 characters');
+  return text;
+}
+async function insertOption(client: PoolClient, poll: PollRow, seq: number, text: string, userId: string): Promise<void> {
+  await client.query('INSERT INTO poll_options (workspace_id, poll_id, seq, text, submitted_by) VALUES ($1,$2,$3,$4,$5)', [poll.workspace_id, poll.id, seq, text, userId]);
+}
+async function options(client: PoolClient, pollId: string): Promise<OptionRow[]> {
+  return (await client.query<OptionRow>(`SELECT o.*, u.display_name AS author FROM poll_options o
+    JOIN users u ON u.id = o.submitted_by WHERE poll_id = $1 ORDER BY seq`, [pollId])).rows;
+}
+async function audit(client: PoolClient, poll: PollRow, action: string, userId: string | null, diff: Record<string, unknown>): Promise<void> {
+  await client.query("SELECT audit_append($1,$2,$3,$4,'poll',$5,$6)", [poll.workspace_id, userId, userId ? 'Member' : 'System', action, poll.id,
+    scrub({ ...diff, policyVersion: poll.policy_version, actor: userId ? `user:${userId}` : `system:chat-poll-gate:${poll.id}` })]);
+}
+
+/** Snapshot all applicable arms. Different OR-policy groups cannot be
+ * flattened into a single §1a object without changing their meaning. */
+export async function draftPollRule(client: PoolClient, draft: { post: DraftPost }, supplied?: unknown): Promise<PolicyRule | null> {
+  const accountIds = draftDestinationAccounts(draft.post);
+  const live = await client.query("SELECT 1 FROM posting_rules WHERE superseded_by IS NULL LIMIT 1");
+  const rules: PolicyRule[] = [];
+  if (accountIds.length && live.rowCount) {
+    for (const account of accountIds) {
+      const topic = typeof draft.post.providerMetadata.topicBindingId === 'string' ? draft.post.providerMetadata.topicBindingId : null;
+      const snapshot = (await client.query(`SELECT effective FROM posting_policy_snapshots WHERE account_id = $1
+        AND content_type = '' AND (topic_binding_id IS NULL OR topic_binding_id = $2)
+        ORDER BY topic_binding_id NULLS LAST LIMIT 1`, [account, topic])).rows[0];
+      if (!snapshot) throw new ConflictException('OUTSIDE_POLICY: destination snapshot missing');
+      const rule = parsePolicyRule(snapshot.effective);
+      if (rule.mode !== 'immediate' && !rule.dryRun) rules.push(rule);
+    }
+  }
+  let rule: PolicyRule | null = rules[0] ?? null;
+  if (rules.some(r => policyHash(r) !== policyHash(rule))) {
+    if (rules.some(r => r.join === 'any')) throw new ConflictException('incompatible OR policy groups require independent polls');
+    rule = parsePolicyRule({ ...rules[0], mode: 'quorum', join: 'all',
+      arms: rules.flatMap<QuorumArm>(r => r.mode === 'admin_only' ? [{ kind: 'admins', x: 1 }] : r.arms ?? []).filter((a, i, all) => all.findIndex(b => b.kind === a.kind && b.of === a.of && b.x === a.x) === i),
+      allowVeto: rules.some(r => r.allowVeto), allowSelfApproval: rules.every(r => r.allowSelfApproval),
+      resetOnChange: rules.some(r => r.resetOnChange), minDwellSeconds: Math.max(...rules.map(r => r.minDwellSeconds ?? 0)),
+      timebox: { duration: rules.reduce((a,b) => durationMs(a.timebox!.duration) >= durationMs(b.timebox!.duration) ? a : b).timebox!.duration, onExpire: 'reject' } });
+  }
+  if (supplied !== undefined) {
+    const requested = parsePolicyRule(supplied);
+    if (rule && policyHash(rule) !== policyHash(requested)) throw new BadRequestException('rule must match the compiled destination policy');
+    rule ??= requested;
+  }
+  return rule;
+}
+
+export async function openPollInTransaction(client: PoolClient, workspaceId: string, body: unknown, actor: PollActor): Promise<PollRow> {
+  const dto = requireObject(body, 'body');
+  await requireVoter(client, workspaceId, actor.userId);
+  if (dto.contentKind !== undefined && dto.contentKind !== 'short_post') throw new BadRequestException('document polls are a future track');
+  const draftId = dto.draftId == null ? null : parseId(requireString(dto.draftId, 'draftId'));
+  const draft = draftId ? (await client.query('SELECT * FROM drafts WHERE id = $1 FOR UPDATE', [draftId])).rows[0] : null;
+  if (draftId && !draft) throw new NotFoundException('draft not found');
+  if (draft && !['editing', 'in_review'].includes(String(draft.state))) throw new ConflictException('draft is not reviewable');
+  const rule = draft ? await draftPollRule(client, draft as { post: DraftPost }, dto.rule) : parsePolicyRule(dto.rule);
+  if (!rule) throw new BadRequestException('a rule or compiled chat-signal policy is required');
+  if (rule.anonymity !== 'named') throw new BadRequestException('anonymous sentiment belongs to the separate Telegram track; governance needs attributable ballots');
+  const kind = dto.kind ?? (draft ? 'variant_selection' : 'yes_no');
+  if (kind !== 'yes_no' && kind !== 'variant_selection') throw new BadRequestException('invalid poll kind');
+  if (kind === 'variant_selection' && !draft) throw new BadRequestException('variant selection requires a draft');
+  if (dto.variants !== undefined && !Array.isArray(dto.variants)) throw new BadRequestException('variants must be an array');
+  const variants = (dto.variants as unknown[] | undefined ?? []).map(v => variantText(typeof v === 'string' ? v : requireObject(v, 'variant').text));
+  if (kind === 'yes_no' && variants.length) throw new BadRequestException('yes/no polls do not accept variants');
+  if (variants.length > 99) throw new BadRequestException('at most 99 initial forks');
+  const eligibleIds = dto.eligibleUserIds === undefined ? null : (Array.isArray(dto.eligibleUserIds) ? dto.eligibleUserIds.map(v => parseId(requireString(v, 'eligibleUserId'))) : (() => { throw new BadRequestException('eligibleUserIds must be an array'); })());
+  const question = requireString(dto.question ?? 'Choose the post to approve', 'question');
+  if (question.length > 300) throw new BadRequestException('question too long');
+  let duration: number;
+  try { duration = durationMs(rule.timebox?.duration ?? 'PT1H'); } catch (error) { throw new BadRequestException(String(error)); }
+  const now = new Date();
+  const poll = (await client.query<PollRow>(`INSERT INTO polls
+    (workspace_id, draft_id, subject_kind, question, kind, rule, policy_version, opens_at, closes_at, created_by, draft_revision, parent_poll_id, channel_id, topic_binding_id, eligible_user_ids)
+    VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15) RETURNING *`,
+  [workspaceId, draftId, draftId ? 'draft' : 'none', question, kind, rule, policyHash(rule), now, new Date(now.getTime() + duration), actor.userId,
+    draft?.revision ?? null, dto.parentPollId == null ? null : parseId(requireString(dto.parentPollId, 'parentPollId')),
+    dto.channelId == null ? null : parseId(requireString(dto.channelId, 'channelId')),
+    dto.topicBindingId == null ? null : parseId(requireString(dto.topicBindingId, 'topicBindingId')), eligibleIds])).rows[0]!;
+  if (kind === 'variant_selection') {
+    await insertOption(client, poll, 1, variantText((draft!.post as DraftPost).text), String(draft!.author_user_id));
+    for (const [i, text] of variants.entries()) await insertOption(client, poll, i + 2, text, actor.userId);
+  }
+  await audit(client, poll, 'poll.opened', actor.userId, { draftId, kind, parentPollId: poll.parent_poll_id });
+  return poll;
+}
+
+async function resolveTally(client: PoolClient, poll: PollRow, persist: boolean): Promise<{ evaluation: PollEvaluation; votes: VoteRow[] }> {
+  const roster = await members(client, poll.workspace_id);
+  const draft = poll.draft_id ? (await client.query('SELECT author_user_id FROM drafts WHERE id = $1', [poll.draft_id])).rows[0] : null;
+  const opts = await options(client, poll.id);
+  const votes = (await client.query<VoteRow & { identity_status: string | null; identity_user_id: string | null; role_override: string | null; cast_at: Date; voter_identity_id: string | null }>(`SELECT v.*, ci.status AS identity_status, ci.user_id AS identity_user_id, ci.role_override
+    FROM poll_votes v LEFT JOIN chat_identities ci ON ci.id = v.voter_identity_id
+    WHERE poll_id = $1 ORDER BY cast_at DESC, voter_remote_id`, [poll.id])).rows;
+  // Ingress currently persists handles, not immutable remote ids. Only
+  // numeric author_handle evidence can bind to approved identities safely.
+  // A username must never become an authorization key.
+  const observed = new Set<string>();
+  if (poll.channel_id) {
+    const rows = await client.query<{ user_id: string }>(`SELECT DISTINCT ci.user_id FROM live_chat_messages lm
+      JOIN chat_identities ci ON ci.provider = lm.provider AND ci.remote_user_id = lm.author_handle
+      WHERE lm.channel_id = $1 AND lm.received_at >= $2 AND ci.status = 'approved' AND ci.user_id IS NOT NULL`, [poll.channel_id, poll.opens_at]);
+    for (const row of rows.rows) observed.add(row.user_id);
+  }
+  const seen = new Set<string>();
+  const ballots: EvaluatedBallot[] = [];
+  const eligibleMembers = roster.filter(m => m.can_vote);
+  const identities = (await client.query<{ user_id: string; role_override: string }>("SELECT user_id, role_override FROM chat_identities WHERE status = 'approved' AND role_override IN ('Admin','Owner')")).rows;
+  const adminIds = new Set(roster.filter(m => m.can_vote && ['Admin', 'Owner'].includes(m.role)).map(m => m.user_id));
+  for (const identity of identities) if (roster.some(m => m.user_id === identity.user_id)) adminIds.add(identity.user_id);
+  for (const vote of votes) {
+    const identityOkay = !vote.voter_identity_id || (vote.identity_status === 'approved' && vote.identity_user_id === vote.voter_user_id);
+    const member = roster.find(m => m.user_id === vote.voter_user_id);
+    const eligible = identityOkay && member !== undefined && (member.can_vote || ['Admin','Owner'].includes(vote.role_override ?? ''));
+    const selfDenied = !poll.rule.allowSelfApproval && vote.ballot === 'yes' && (poll.kind === 'variant_selection'
+      ? opts.some(o => o.id === vote.option_id && o.submitted_by === vote.voter_user_id)
+      : draft?.author_user_id === vote.voter_user_id);
+    const duplicate = vote.voter_user_id !== null && seen.has(vote.voter_user_id);
+    if (eligible && vote.voter_user_id) seen.add(vote.voter_user_id);
+    vote.eligible = eligible;
+    vote.counted = eligible && !selfDenied && !duplicate;
+    vote.ineligible_reason = !eligible || duplicate ? 'INELIGIBLE_ACTOR' : selfDenied ? 'SELF_APPROVAL_DENIED' : null;
+    if (persist) await client.query(`UPDATE poll_votes SET eligible = $3, counted = $4, ineligible_reason = $5
+      WHERE poll_id = $1 AND voter_remote_id = $2`, [poll.id, vote.voter_remote_id, vote.eligible, vote.counted, vote.ineligible_reason]);
+    ballots.push({ ballot: vote.ballot, optionId: vote.option_id, counted: vote.counted,
+      admin: adminIds.has(vote.voter_user_id ?? ''), observed: observed.has(vote.voter_user_id ?? ''),
+      participant: poll.eligible_user_ids === null || poll.eligible_user_ids.includes(vote.voter_user_id ?? '') });
+  }
+  const eligible = eligibleMembers.filter(m => poll.eligible_user_ids === null || poll.eligible_user_ids.includes(m.user_id));
+  // Potential self-voters must have at least one option authored by someone
+  // else. A no/self ballot can be recast, so it is never subtracted twice.
+  const canChoose = (id: string): boolean => poll.rule.allowSelfApproval === true || (poll.kind === 'variant_selection'
+    ? opts.some(o => o.submitted_by !== id) : draft?.author_user_id !== id);
+  const evaluation = evaluatePoll({ kind: poll.kind, rule: poll.rule, opensAt: poll.opens_at, closesAt: poll.closes_at, now: new Date(), ballots,
+    options: opts.map(o => ({ id: o.id, seq: o.seq, submittedAt: o.submitted_at.toISOString() })),
+    possible: { admins: [...adminIds].filter(canChoose).length, eligible: eligible.filter(m => canChoose(m.user_id)).length, observed: observed.size } });
+  // Keep the public DTO separate from identity resolution internals.
+  return { evaluation, votes: votes.map(v => ({ voter_kind: v.voter_kind, voter_user_id: v.voter_user_id,
+    voter_remote_id: v.voter_remote_id, voter_handle: v.voter_handle, ballot: v.ballot, option_id: v.option_id,
+    counted: v.counted, eligible: v.eligible, ineligible_reason: v.ineligible_reason })) };
+}
+
+async function evaluateLocked(client: PoolClient, poll: PollRow): Promise<void> {
+  if (poll.state !== 'open') return;
+  if (poll.draft_id && poll.draft_revision !== null) {
+    const draft = (await client.query('SELECT revision FROM drafts WHERE id = $1', [poll.draft_id])).rows[0];
+    if (String(draft?.revision) !== String(poll.draft_revision)) {
+      await stalePoll(client, poll); return;
+    }
+  }
+  const { evaluation } = await resolveTally(client, poll, true);
+  await audit(client, poll, 'policy.evaluated', null, { evaluation });
+  // Shadow polls retain their artifact and terminal outcome but cannot
+  // approve/reject drafts. Their E2 decision is pending, never a release.
+  if (!evaluation.state) return;
+  const claimed = await client.query(`UPDATE polls SET outbox_state = 'claimed', state = $2, closed_at = clock_timestamp(),
+    close_reason = $3, winner_option_id = $4, final_evaluation = $5
+    WHERE id = $1 AND state = 'open' AND outbox_state = 'none' RETURNING *`,
+  [poll.id, evaluation.state, evaluation.reason,
+    evaluation.state === 'passed' && poll.kind === 'variant_selection' ? evaluation.winnerOptionId : null, evaluation]);
+  if (!claimed.rowCount) return;
+  Object.assign(poll, claimed.rows[0]);
+  const reasons = evaluation.state === 'vetoed' ? ['VETOED'] : evaluation.state === 'quorum_unreachable' ? ['INSUFFICIENT_QUORUM']
+    : evaluation.reason === 'timebox' ? [evaluation.state === 'passed' ? 'TIMEBOX_EXPIRED_AUTO_APPROVE' : 'TIMEBOX_EXPIRED_AUTO_REJECT'] : [];
+  if (poll.draft_id && !poll.rule.dryRun) {
+    const winnerText = poll.winner_option_id ? (await options(client, poll.id)).find(o => o.id === poll.winner_option_id)?.text : undefined;
+    await transitionPollDraft(client, { workspaceId: poll.workspace_id, draftId: poll.draft_id, pollId: poll.id,
+      passed: evaluation.state === 'passed', ...(winnerText === undefined ? {} : { text: winnerText }),
+      reason: reasons[0] ?? 'quorum_early', escalate: evaluation.reason === 'timebox' && poll.rule.timebox?.onExpire === 'escalateOwner' });
+  }
+  await recordE2(client, poll, evaluation, poll.rule.dryRun ? ['POLICY_DRY_RUN'] : reasons);
+  await audit(client, poll, 'poll.closed', null, { state: poll.state, reason: poll.close_reason, winnerOptionId: poll.winner_option_id, evaluation });
+  await audit(client, poll, evaluation.state === 'passed' && !poll.rule.dryRun ? 'release.fired' : 'release.blocked', null, { reasons });
+  await client.query("UPDATE polls SET outbox_state = 'done' WHERE id = $1 AND outbox_state = 'claimed'", [poll.id]);
+  poll.outbox_state = 'done';
+}
+async function recordE2(client: PoolClient, poll: PollRow, evaluation: PollEvaluation, reasons: string[]): Promise<void> {
+  if (!poll.draft_id) return;
+  const draft = (await client.query('SELECT post FROM drafts WHERE id = $1', [poll.draft_id])).rows[0];
+  for (const accountId of draftDestinationAccounts(draft.post as DraftPost)) {
+    const provider = (await client.query('SELECT provider FROM connections WHERE id = $1', [accountId])).rows[0]?.provider ?? 'unknown';
+    await client.query(`INSERT INTO gate_decisions
+      (workspace_id, draft_id, destination, gate, policy_version, outcome, inputs, reason_codes, actor, poll_id)
+      VALUES ($1,$2,$3,'E2',$4,$5,$6,$7,$8,$9)`,
+    [poll.workspace_id, poll.draft_id, { platform: provider, accountId, ...(poll.topic_binding_id ? { topicBindingId: poll.topic_binding_id } : {}) },
+      poll.policy_version, poll.rule.dryRun ? 'pending' : poll.state === 'passed' ? 'fired' : 'blocked',
+      { ...evaluation, pollState: poll.state }, reasons, `system:chat-poll-gate:${poll.id}`, poll.id]);
+  }
+}
+async function card(client: PoolClient, poll: PollRow, userId?: string): Promise<PollCard> {
+  const final = (poll as PollRow & { final_evaluation?: PollEvaluation }).final_evaluation;
+  const tally = final && poll.state !== 'open'
+    ? { evaluation: final, votes: (await client.query<VoteRow>('SELECT voter_kind, voter_user_id, voter_remote_id, voter_handle, ballot, option_id, counted, eligible, ineligible_reason FROM poll_votes WHERE poll_id = $1 ORDER BY cast_at', [poll.id])).rows }
+    : await resolveTally(client, poll, false);
+  const member = userId ? (await members(client, poll.workspace_id)).find(m => m.user_id === userId) : undefined;
+  return { poll, options: await options(client, poll.id), evaluation: tally.evaluation, votes: tally.votes,
+    voterEligibility: userId ? { eligible: member?.can_vote ?? false, admin: member !== undefined && ['Admin','Owner'].includes(member.role), reason: member?.can_vote ? null : 'INELIGIBLE_ACTOR' } : null };
+}
+
+async function stalePoll(client: PoolClient, poll: PollRow): Promise<void> {
+  const { evaluation } = await resolveTally(client, poll, true);
+  const changed = await client.query(`UPDATE polls SET state = 'stale', closed_at = clock_timestamp(), close_reason = 'reset_on_change',
+    outbox_state = 'done', final_evaluation = $2 WHERE id = $1 AND state = 'open' AND outbox_state = 'none' RETURNING *`, [poll.id, evaluation]);
+  if (!changed.rowCount) return;
+  Object.assign(poll, changed.rows[0]);
+  await audit(client, poll, 'poll.stale', null, { reason: 'RESET_ON_CHANGE' });
+  await recordE2(client, poll, evaluation, ['RESET_ON_CHANGE']);
+  if (poll.rule.dryRun || !poll.draft_id) return;
+  if (poll.rule.resetOnChange) {
+    await openPollInTransaction(client, poll.workspace_id, {
+      draftId: poll.draft_id, kind: poll.kind, rule: poll.rule, question: poll.question,
+      parentPollId: poll.id, channelId: poll.channel_id, topicBindingId: poll.topic_binding_id,
+      ...(poll.eligible_user_ids ? { eligibleUserIds: poll.eligible_user_ids } : {}),
+    }, { userId: await rearmActor(client, poll) });
+  } else {
+    // Stale content can never be auto-approved, even with an approve expiry
+    // policy. escalateOwner keeps it in review; all other stale gates reject.
+    await transitionPollDraft(client, { workspaceId: poll.workspace_id, draftId: poll.draft_id, pollId: poll.id,
+      passed: false, reason: 'RESET_ON_CHANGE', escalate: poll.rule.timebox?.onExpire === 'escalateOwner' });
+  }
+}
+async function rearmActor(client: PoolClient, poll: PollRow): Promise<string> {
+  const roster = await members(client, poll.workspace_id);
+  const actor = roster.find(m => m.user_id === poll.created_by && m.can_vote) ?? roster.find(m => m.can_vote && ['Owner','Admin'].includes(m.role));
+  if (!actor) throw new ConflictException('cannot re-arm without an eligible opener');
+  return actor.user_id;
+}
+/** Called under publishing's workspace/draft lock, after its revision trigger.
+ * The old options and ballots stay attached to the stale artifact forever. */
+export async function markDraftPollsStale(client: PoolClient, workspaceId: string, draftId: string): Promise<void> {
+  const polls = (await client.query<PollRow>("SELECT * FROM polls WHERE workspace_id = $1 AND draft_id = $2 AND state = 'open' FOR UPDATE", [workspaceId, draftId])).rows;
+  for (const poll of polls) await evaluateLocked(client, poll);
+}
+/** Auto-arm on submit, using ONLY compiled destination snapshots. */
+export async function autoOpenDraftPoll(client: PoolClient, workspaceId: string, draftId: string, actor: PollActor, post: DraftPost): Promise<void> {
+  if (!draftDestinationAccounts(post).length) return;
+  const rule = await draftPollRule(client, { post });
+  if (!rule) return;
+  if ((await client.query("SELECT 1 FROM polls WHERE draft_id = $1 AND state = 'open'", [draftId])).rowCount) return;
+  await openPollInTransaction(client, workspaceId, { draftId, kind: 'variant_selection', rule }, actor);
+}
diff --git a/apps/api/src/connections/connection-store.test.ts b/apps/api/src/connections/connection-store.test.ts
new file mode 100644
index 0000000..7df6f0e
--- /dev/null
+++ b/apps/api/src/connections/connection-store.test.ts
@@ -0,0 +1,76 @@
+import { randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import type { SessionPayload } from "../auth/session.js";
+import { Vault } from "../vault/vault.js";
+import { PgConnectionStore } from "./connection-store.js";
+
+const session: SessionPayload = { workspaceId: randomUUID(), userId: randomUUID(), role: "Owner", authzEpoch: 3, issuedAt: 0, expiresAt: Math.floor(Date.now() / 1000) + 600 };
+const connection: ConnectorConnection = { id: randomUUID(), workspaceId: session.workspaceId, provider: "mastodon", channelId: "remote-account", credentialId: { kind: "credential-ref", id: "opaque" }, fields: { instanceUrl: "https://social.example" }, createdAt: new Date() };
+
+function fixture(allowed = true, existingCredential = false) {
+  const queries: Array<{ sql: string; params: unknown[] }> = [];
+  const credentialId = randomUUID();
+  const client = {
+    async query(sql: string, params: unknown[] = []) {
+      queries.push({ sql, params });
+      if (sql.includes("FROM memberships")) return { rowCount: allowed ? 1 : 0, rows: [] };
+      if (sql.startsWith("UPDATE scheduled_publications")) return { rowCount: 1, rows: [{ id: connection.id, draft_id: connection.id }] };
+      if (sql.includes("SELECT id FROM credentials")) return { rows: existingCredential ? [{ id: credentialId }] : [] };
+      if (sql.includes("SELECT c.*, cr.ciphertext")) return { rows: [{ id: connection.id, provider: connection.provider, channel_id: connection.channelId, fields: connection.fields, created_at: connection.createdAt, ciphertext: null, key_version: 1 }] };
+      return { rowCount: 1, rows: [{ id: connection.id }] };
+    },
+  } as unknown as PoolClient;
+  const store = new PgConnectionStore(async (workspaceId, callback) => {
+    expect(workspaceId).toBe(session.workspaceId);
+    return callback(client);
+  });
+  return { store, queries, credentialId };
+}
+
+describe("Postgres connection writes", () => {
+  it("saves only a vault envelope and identifier-only audit in the same tenant transaction", async () => {
+    const { store, queries } = fixture();
+    const sealed = await new Vault().seal(session.workspaceId, connection.id, Buffer.from('{"access_token":"never-in-db-plaintext"}'));
+    await store.save(session, connection, { provider: connection.provider, remoteId: "remote-account", handle: "@alice" }, sealed, false);
+    const credential = queries.find(({ sql }) => sql.startsWith("INSERT INTO credentials"));
+    expect(credential?.params).toContain(sealed.ciphertext);
+    expect(queries[0]?.sql).toContain("FOR UPDATE");
+    expect(JSON.stringify(queries)).not.toContain("never-in-db-plaintext");
+    const audit = queries.find(({ sql }) => sql.includes("audit_append"));
+    expect(audit?.params.at(-1)).toEqual({ provider: connection.provider });
+  });
+  it("rotates the credential row in place and blocks a revoked authorization before writes", async () => {
+    const { store, queries, credentialId } = fixture(true, true);
+    const sealed = await new Vault().seal(session.workspaceId, connection.id, Buffer.from("rotated-secret"));
+    await store.save(session, connection, { provider: connection.provider, remoteId: "remote-account", handle: "@alice" }, sealed, true);
+    expect(queries.find(({ sql }) => sql.startsWith("UPDATE credentials"))?.params[0]).toBe(credentialId);
+    expect(queries.some(({ sql }) => sql.startsWith("INSERT INTO connections"))).toBe(false);
+    const denied = fixture(false);
+    await expect(denied.store.save(session, connection, { provider: connection.provider, remoteId: "remote-account", handle: "@alice" }, sealed, true)).rejects.toThrow();
+    expect(denied.queries.some(({ sql }) => /^(INSERT|UPDATE)/.test(sql))).toBe(false);
+  });
+  it("locks and revokes locally before provider I/O while preserving publishing history", async () => {
+    const { store, queries } = fixture();
+    await store.remove(session, connection.id, async (stored) => {
+      expect(stored.connection.id).toBe(connection.id);
+      expect(queries.some(({ sql }) => sql.includes("FOR UPDATE"))).toBe(true);
+      expect(queries.some(({ sql }) => sql.startsWith("DELETE"))).toBe(false);
+    });
+    expect(queries.filter(({ sql }) => sql.startsWith("DELETE"))).toHaveLength(0);
+    expect(queries.some(({ sql }) => sql.startsWith("UPDATE credentials SET revoked_at"))).toBe(true);
+    expect(queries.some(({ sql }) => sql.startsWith("UPDATE connections SET disconnected_at"))).toBe(true);
+    expect(queries.some(({ sql }) => sql.includes("needs_reauthorization"))).toBe(true);
+    expect(queries.some(({ sql }) => sql.startsWith("UPDATE publishing_attempts") && sql.includes("abandoned"))).toBe(true);
+    expect(queries.some(({ sql }) => sql.startsWith("UPDATE drafts") && sql.includes("approved_revision = revision"))).toBe(true);
+    expect(queries.at(-1)?.sql).toContain("audit_append");
+  });
+  it("retains revoked local evidence and audits provider revocation failure", async () => {
+    const { store, queries } = fixture();
+    await expect(store.remove(session, connection.id, async () => { throw new Error("provider offline"); })).resolves.toBeUndefined();
+    expect(queries.some(({ sql }) => sql.startsWith("UPDATE credentials SET revoked_at"))).toBe(true);
+    expect(queries.at(-1)?.sql).toContain("connection.revoke_failed");
+    expect(queries.some(({ sql }) => sql.startsWith("DELETE"))).toBe(false);
+  });
+});
diff --git a/apps/api/src/connections/connection-store.ts b/apps/api/src/connections/connection-store.ts
new file mode 100644
index 0000000..a8246ad
--- /dev/null
+++ b/apps/api/src/connections/connection-store.ts
@@ -0,0 +1,117 @@
+import { NotFoundException, ForbiddenException } from "@nestjs/common";
+import type { ConnectorConnection, NormalizedIdentity } from "@tactical-media-broadcast-hub/core";
+import type { SessionPayload } from "../auth/session.js";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+import type { SealedCredential } from "../vault/vault.js";
+import type { ConnectionSummary } from "./connections.service.js";
+import { scrub } from "../audit/audit.service.js";
+
+export interface StoredConnection { connection: ConnectorConnection; credential: SealedCredential | null }
+export interface ConnectionStore {
+  list(workspaceId: string): Promise<ConnectionSummary[]>;
+  get(workspaceId: string, id: string): Promise<StoredConnection>;
+  assertAuthorized(session: SessionPayload): Promise<void>;
+  save(session: SessionPayload, connection: ConnectorConnection, identity: NormalizedIdentity, credential: SealedCredential, reconnect: boolean): Promise<void>;
+  rotateCredential(workspaceId: string, id: string, previous: SealedCredential, credential: SealedCredential): Promise<void>;
+  remove(session: SessionPayload, id: string, revoke: (stored: StoredConnection) => Promise<void>): Promise<void>;
+}
+
+export class PgConnectionStore implements ConnectionStore {
+  constructor(private readonly transaction: typeof withTenant = withTenant) {}
+  async assertAuthorized(session: SessionPayload): Promise<void> {
+    if (session.expiresAt <= Math.floor(Date.now() / 1000)) throw new ForbiddenException("Session expired");
+    const result = await this.transaction(session.workspaceId, (client) => client.query(
+      `SELECT 1 FROM workspaces w JOIN memberships m ON m.workspace_id = w.id
+       JOIN role_permissions rp ON rp.role = m.role
+       WHERE w.id = $1 AND w.authz_epoch = $2 AND m.user_id = $3 AND m.status = 'active' AND rp.permission = 'connection.manage'`,
+      [session.workspaceId, session.authzEpoch, session.userId],
+    ));
+    if (result.rowCount !== 1) throw new ForbiddenException("Connection authorization no longer valid");
+  }
+  async list(workspaceId: string): Promise<ConnectionSummary[]> {
+    const res = await this.transaction(workspaceId, (client) => client.query(
+      `SELECT c.*, cr.ciphertext, coalesce(cr.rotated_at, cr.created_at) AS rotated_at,
+       (SELECT array_agg(p.published_at ORDER BY p.published_at DESC) FROM publications p
+        WHERE p.connection_id = c.id AND p.published_at > now() - interval '24 hours') AS recent
+       FROM connections c LEFT JOIN LATERAL (SELECT * FROM credentials WHERE connection_id = c.id AND kind = 'connector-oauth' AND revoked_at IS NULL LIMIT 1) cr ON true WHERE c.disconnected_at IS NULL ORDER BY c.created_at`,
+    ));
+    return res.rows.map((row: { id: string; provider: string; channel_id: string; fields: Record<string, unknown>; ciphertext: Buffer | null; created_at: Date; rotated_at: Date | null; recent: Date[] | null }) => ({
+      id: row.id, provider: row.provider, channelId: row.channel_id, fields: scrub(row.fields) ?? {},
+      health: row.ciphertext ? "unavailable" : "needs_credentials", credentialRotatedAt: row.rotated_at?.toISOString() ?? null,
+      recentPublishes: (row.recent ?? []).map((date) => date.toISOString()), createdAt: row.created_at.toISOString(),
+    }));
+  }
+  async get(workspaceId: string, id: string): Promise<StoredConnection> {
+    return this.transaction(workspaceId, (client) => this.read(client, workspaceId, id));
+  }
+  private async read(client: PoolClient, workspaceId: string, id: string): Promise<StoredConnection> {
+    const result = await client.query(
+      `SELECT c.*, cr.ciphertext, cr.key_version FROM connections c LEFT JOIN LATERAL
+       (SELECT * FROM credentials WHERE connection_id = c.id AND kind = 'connector-oauth' AND revoked_at IS NULL LIMIT 1) cr ON true WHERE c.id = $1`, [id],
+    );
+    const row = result.rows[0] as { id: string; provider: string; channel_id: string; fields: Record<string, string>; created_at: Date; ciphertext: Buffer | null; key_version: number } | undefined;
+    if (!row) throw new NotFoundException("Connection not found");
+    return {
+      connection: { id: row.id, workspaceId, provider: row.provider, channelId: row.channel_id, fields: row.fields, createdAt: row.created_at, credentialId: { kind: "credential-ref", id: row.id } },
+      credential: row.ciphertext ? { ciphertext: row.ciphertext, keyVersion: row.key_version } : null,
+    };
+  }
+  async save(session: SessionPayload, connection: ConnectorConnection, identity: NormalizedIdentity, credential: SealedCredential, reconnect: boolean): Promise<void> {
+    await this.transaction(session.workspaceId, async (client) => {
+      // Serialize with membership revocation; re-check at commit, not only before provider I/O.
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [session.workspaceId]);
+      const allowed = await client.query(`SELECT 1 FROM memberships m JOIN workspaces w ON w.id = m.workspace_id JOIN role_permissions rp ON rp.role = m.role WHERE m.user_id = $1 AND m.status = 'active' AND w.authz_epoch = $2 AND rp.permission = 'connection.manage'`, [session.userId, session.authzEpoch]);
+      if (!allowed.rowCount || session.expiresAt <= Math.floor(Date.now() / 1000)) throw new ForbiddenException();
+      const fields = { ...connection.fields, handle: identity.handle, displayName: identity.displayName ?? identity.handle, remoteId: identity.remoteId };
+      if (reconnect) {
+        const updated = await client.query("UPDATE connections SET fields = $2, disconnected_at = NULL WHERE id = $1 AND provider = $3 RETURNING id", [connection.id, fields, connection.provider]);
+        if (!updated.rowCount) throw new NotFoundException("Connection removed during authorization");
+      } else {
+        await client.query("INSERT INTO connections (id, workspace_id, provider, channel_id, fields) VALUES ($1,$2,$3,$4,$5)", [connection.id, session.workspaceId, connection.provider, connection.channelId, fields]);
+      }
+      const existing = await client.query("SELECT id FROM credentials WHERE connection_id = $1 AND kind = 'connector-oauth' FOR UPDATE", [connection.id]);
+      if (existing.rows[0]) {
+        await client.query("UPDATE credentials SET ciphertext = $2, key_version = $3, rotated_at = now(), revoked_at = NULL WHERE id = $1", [existing.rows[0].id, credential.ciphertext, credential.keyVersion]);
+      } else {
+        await client.query("INSERT INTO credentials (workspace_id, connection_id, kind, ciphertext, key_version) VALUES ($1,$2,'connector-oauth',$3,$4)", [session.workspaceId, connection.id, credential.ciphertext, credential.keyVersion]);
+      }
+      await client.query("SELECT audit_append($1,$2,$3,$4,'connection',$5,$6)", [session.workspaceId, session.userId, session.role, reconnect ? "connection.reconnect" : "connection.connect", connection.id, { provider: connection.provider }]);
+    });
+  }
+  async remove(session: SessionPayload, id: string, revoke: (stored: StoredConnection) => Promise<void>): Promise<void> {
+    let stored: StoredConnection | undefined;
+    await this.transaction(session.workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [session.workspaceId]);
+      const allowed = await client.query(`SELECT 1 FROM memberships m JOIN workspaces w ON w.id = m.workspace_id JOIN role_permissions rp ON rp.role = m.role WHERE m.user_id = $1 AND m.status = 'active' AND w.authz_epoch = $2 AND rp.permission = 'connection.manage'`, [session.userId, session.authzEpoch]);
+      if (!allowed.rowCount || session.expiresAt <= Math.floor(Date.now() / 1000)) throw new ForbiddenException();
+      const locked = await client.query("SELECT id FROM connections WHERE id = $1 FOR UPDATE", [id]);
+      if (!locked.rowCount) throw new NotFoundException("Connection not found");
+      stored = await this.read(client, session.workspaceId, id);
+      await client.query("UPDATE credentials SET revoked_at = now() WHERE connection_id = $1 AND revoked_at IS NULL", [id]);
+      await client.query("UPDATE connections SET disconnected_at = COALESCE(disconnected_at, now()) WHERE id = $1", [id]);
+      // Undispatched intent pauses. Dispatched or unknown work retains all evidence.
+      const paused = await client.query<{ id: string; draft_id: string }>(`UPDATE scheduled_publications s SET state = 'needs_reauthorization', error_code = 'CREDENTIAL_CHANGED'
+        WHERE connection_id = $1 AND state IN ('pending', 'in_flight') AND NOT EXISTS
+          (SELECT 1 FROM publishing_attempts a WHERE a.schedule_id = s.id AND (a.status = 'unknown' OR (a.dispatch_started_at IS NOT NULL AND a.status NOT IN ('completed', 'failed'))))
+        RETURNING s.id, s.draft_id`, [id]);
+      const scheduleIds = paused.rows.map((row) => row.id);
+      const draftIds = paused.rows.map((row) => row.draft_id);
+      await client.query("UPDATE publishing_attempts SET status = 'abandoned', owner_token = NULL, lease_until = NULL, error_code = 'CREDENTIAL_CHANGED' WHERE schedule_id = ANY($1::uuid[]) AND status IN ('ready', 'in_progress')", [scheduleIds]);
+      await client.query("UPDATE drafts SET state = CASE WHEN approved_revision = revision AND approved_hash IS NOT NULL THEN 'approved' ELSE 'editing' END, updated_at = now() WHERE id = ANY($1::uuid[]) AND state = 'scheduled'", [draftIds]);
+      await client.query("SELECT audit_append($1,$2,$3,'connection.remove','connection',$4,NULL)", [session.workspaceId, session.userId, session.role, id]);
+    });
+    if (stored) {
+      try { await revoke(stored); }
+      catch { await this.transaction(session.workspaceId, (client) => client.query("SELECT audit_append($1,$2,$3,'connection.revoke_failed','connection',$4,NULL)", [session.workspaceId, session.userId, session.role, id])); }
+    }
+  }
+  async rotateCredential(workspaceId: string, id: string, previous: SealedCredential, credential: SealedCredential): Promise<void> {
+    await this.transaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      // A health refresh must never overwrite a concurrent explicit reconnect.
+      const updated = await client.query("UPDATE credentials SET ciphertext = $3, key_version = $4, rotated_at = now() WHERE connection_id = $1 AND ciphertext = $2 AND kind = 'connector-oauth' AND revoked_at IS NULL RETURNING id", [id, previous.ciphertext, credential.ciphertext, credential.keyVersion]);
+      if (updated.rowCount) await client.query("SELECT audit_append($1,NULL,'Service','credential.refresh','connection',$2,NULL)", [workspaceId, id]);
+    });
+  }
+}
diff --git a/apps/api/src/connections/connections.controller.ts b/apps/api/src/connections/connections.controller.ts
new file mode 100644
index 0000000..f42da3f
--- /dev/null
+++ b/apps/api/src/connections/connections.controller.ts
@@ -0,0 +1,84 @@
+import { Body, Controller, Delete, Get, Inject, Param, Post, Query, Req, Res, UseGuards } from "@nestjs/common";
+import type { Request, Response } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { optionalString, parseId, requireObject, requireSession, requireString } from "../http/validation.js";
+import { ConnectionsService, type ConnectionSummary } from "./connections.service.js";
+import { AUTH_TTL_MS, stateCookieName, validState } from "./pending.js";
+
+@Controller("connections")
+export class ConnectionsController {
+  constructor(@Inject(ConnectionsService) private readonly connections: ConnectionsService) {}
+
+  @Get()
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.view")
+  async list(@Req() request: Request & AuthenticatedRequest): Promise<ConnectionSummary[]> {
+    return this.connections.list(requireSession(request).workspaceId);
+  }
+
+  @Get("providers")
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.view")
+  providers() { return this.connections.providers(); }
+
+  private redirectResponse(response: Response, authorization: { redirectUrl: string; state: string; binding: string }) {
+    response.setHeader("Cache-Control", "no-store");
+    response.cookie(stateCookieName(authorization.state), authorization.binding, {
+      httpOnly: true, secure: process.env.NODE_ENV === "production", sameSite: "lax",
+      path: "/connections/callback", maxAge: AUTH_TTL_MS,
+    });
+    return { redirectUrl: authorization.redirectUrl };
+  }
+
+  @Post("authorize")
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.manage")
+  async authorize(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown, @Res({ passthrough: true }) response: Response) {
+    const input = requireObject(body, "authorization");
+    const authorization = await this.connections.authorize(requireSession(request), requireString(input.provider, "provider"), optionalString(input.instanceUrl, "instanceUrl"));
+    return this.redirectResponse(response, authorization);
+  }
+
+  /** Deliberately outside RbacGuard: the provider's browser redirect carries no bearer header. */
+  @Get("callback")
+  async callback(@Req() request: Request, @Query() query: Record<string, unknown>, @Res() response: Response): Promise<void> {
+    const state = typeof query.state === "string" ? query.state : "";
+    const name = validState(state) ? stateCookieName(state) : "";
+    const cookie = name ? (request.headers.cookie ?? "").split(";").map((part) => part.trim()).find((part) => part.startsWith(`${name}=`))?.slice(name.length + 1) : undefined;
+    let binding = "";
+    try { binding = decodeURIComponent(cookie ?? ""); } catch { /* Malformed cookies fail state validation. */ }
+    const location = await this.connections.callback(state, binding, typeof query.code === "string" ? query.code : undefined, typeof query.error === "string" ? query.error : undefined);
+    if (name) response.clearCookie(name, { path: "/connections/callback", httpOnly: true, secure: process.env.NODE_ENV === "production", sameSite: "lax" });
+    response.setHeader("Cache-Control", "no-store");
+    response.setHeader("Referrer-Policy", "no-referrer");
+    response.redirect(303, location);
+  }
+
+  // Public endpoint spelling is API routing, not provider behavior branching.
+  // eslint-disable-next-line no-restricted-syntax
+  @Post("telegram/bot-token")
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.manage")
+  async botToken(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<{ connected: true; token: string }> {
+    const input = requireObject(body, "bot token");
+    const id = optionalString(input.connectionId, "connectionId");
+    const channelId = optionalString(input.channelId, "channelId");
+    const token = await this.connections.botToken(requireSession(request), requireString(input.token, "token"), channelId ? { channelId } : {}, id ? parseId(id) : undefined);
+    return { connected: true, token };
+  }
+
+  @Post(":connectionId/reconnect")
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.manage")
+  async reconnect(@Req() request: Request & AuthenticatedRequest, @Param("connectionId") id: string, @Res({ passthrough: true }) response: Response) {
+    return this.redirectResponse(response, await this.connections.reconnect(requireSession(request), parseId(id)));
+  }
+
+  @Delete(":connectionId")
+  @UseGuards(RbacGuard)
+  @RequirePermission("connection.manage")
+  async remove(@Req() request: Request & AuthenticatedRequest, @Param("connectionId") id: string): Promise<{ removed: true; token: string }> {
+    const token = await this.connections.remove(requireSession(request), parseId(id));
+    return { removed: true, token };
+  }
+}
diff --git a/apps/api/src/connections/connections.integration.test.ts b/apps/api/src/connections/connections.integration.test.ts
new file mode 100644
index 0000000..681bd3e
--- /dev/null
+++ b/apps/api/src/connections/connections.integration.test.ts
@@ -0,0 +1,345 @@
+import "reflect-metadata";
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import { createHash, randomUUID } from "node:crypto";
+import { Module, UnauthorizedException, type ExecutionContext, type INestApplication } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ConnectorConnection, NormalizedIdentity } from "@tactical-media-broadcast-hub/core";
+import { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import { createMastodonConnector } from "../../../../packages/connector-mastodon/src/index.js";
+import { createTelegramConnector } from "@tactical-media-broadcast-hub/connector-telegram";
+import { createPeerTubeConnector } from "../../../../packages/connector-peertube/src/index.js";
+import { Vault, type SealedCredential } from "../vault/vault.js";
+import type { SessionPayload } from "../auth/session.js";
+import { RbacGuard } from "../rbac/rbac.guard.js";
+import { logger } from "../telemetry/logger.js";
+import { ConnectionsController } from "./connections.controller.js";
+import { CONNECTION_DEPENDENCIES, ConnectionsService, type ConnectionDependencies, type ConnectionSummary } from "./connections.service.js";
+import type { ConnectionStore, StoredConnection } from "./connection-store.js";
+import { RedisPendingStore } from "./pending.js";
+import { MemoryPendingRedis } from "./testing.js";
+import { injectHttp } from "./http-test-transport.js";
+
+class MemoryConnections implements ConnectionStore {
+  readonly rows = new Map<string, StoredConnection>();
+  readonly audit: Array<Record<string, string>> = [];
+  authorized = true;
+  async assertAuthorized(session: SessionPayload): Promise<void> {
+    if (!this.authorized || session.workspaceId !== sessionFixture.workspaceId) throw new Error("membership revoked");
+  }
+  async list(workspaceId: string): Promise<ConnectionSummary[]> {
+    return [...this.rows.values()].filter(({ connection }) => connection.workspaceId === workspaceId).map(({ connection, credential }) => ({
+      id: connection.id, provider: connection.provider, channelId: connection.channelId, fields: { ...connection.fields },
+      health: credential ? "unavailable" : "needs_credentials", credentialRotatedAt: null, recentPublishes: [], createdAt: connection.createdAt.toISOString(),
+    }));
+  }
+  async get(workspaceId: string, id: string): Promise<StoredConnection> {
+    const row = this.rows.get(id);
+    if (!row || row.connection.workspaceId !== workspaceId) throw new Error("connection not found");
+    return row;
+  }
+  async save(session: SessionPayload, connection: ConnectorConnection, identity: NormalizedIdentity, credential: SealedCredential, reconnect: boolean): Promise<void> {
+    await this.assertAuthorized(session);
+    if (reconnect && !this.rows.has(connection.id)) throw new Error("connection removed");
+    this.rows.set(connection.id, { connection: { ...connection, fields: { ...connection.fields, remoteId: identity.remoteId, handle: identity.handle } }, credential });
+    this.audit.push({ action: reconnect ? "connection.reconnect" : "connection.connect", provider: connection.provider });
+  }
+  async remove(session: SessionPayload, id: string, revoke: (stored: StoredConnection) => Promise<void>): Promise<void> {
+    await this.assertAuthorized(session);
+    await revoke(await this.get(session.workspaceId, id));
+    this.rows.delete(id);
+    this.audit.push({ action: "connection.remove" });
+  }
+  async rotateCredential(workspaceId: string, id: string, previous: SealedCredential, credential: SealedCredential): Promise<void> {
+    const row = await this.get(workspaceId, id);
+    if (row.credential?.ciphertext.equals(previous.ciphertext)) {
+      row.credential = credential;
+      this.audit.push({ action: "credential.refresh" });
+    }
+  }
+}
+const sessionFixture: SessionPayload = {
+  userId: randomUUID(), workspaceId: randomUUID(), role: "Owner", authzEpoch: 1,
+  issuedAt: Math.floor(Date.now() / 1000), expiresAt: Math.floor(Date.now() / 1000) + 3600,
+};
+@Module({})
+class TestModule {}
+
+async function form(request: IncomingMessage): Promise<URLSearchParams> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) chunks.push(Buffer.from(chunk as Uint8Array));
+  return new URLSearchParams(Buffer.concat(chunks).toString());
+}
+function json(response: ServerResponse, value: unknown, status = 200): void {
+  response.writeHead(status, { "content-type": "application/json" }); response.end(JSON.stringify(value));
+}
+
+describe("HTTP OAuth connect with real connectors and mock authorization server", () => {
+  let mock: Server;
+  let origin: string;
+  let apiOrigin: string;
+  let app: INestApplication;
+  const store = new MemoryConnections();
+  const redis = new MemoryPendingRedis();
+  const encryption = new Vault();
+  const activeTokens = new Set<string>();
+  const grants = new Map<string, { challenge: string; redirectUri: string }>();
+  const revokedTokens: string[] = [];
+  const guard = vi.spyOn(RbacGuard.prototype, "canActivate").mockImplementation(async (context: ExecutionContext) => {
+    const request = context.switchToHttp().getRequest<{ headers: Record<string, string>; session?: SessionPayload }>();
+    if (request.headers.authorization !== "Bearer test-session") throw new UnauthorizedException();
+    request.session = sessionFixture; return true;
+  });
+  const warn = vi.spyOn(logger, "warn").mockImplementation(() => undefined);
+  const info = vi.spyOn(logger, "info").mockImplementation(() => undefined);
+  let nextAccount = "account-1";
+  let issued = 0;
+  let failExchange = false;
+  let bridgeConfigured = false;
+  const botToken = "12345:bot_token_secret";
+
+  beforeEach(() => {
+    store.rows.clear(); store.audit.length = 0; store.authorized = true;
+    redis.entries.clear(); activeTokens.clear(); grants.clear(); revokedTokens.length = 0;
+    nextAccount = "account-1"; issued = 0; failExchange = false; bridgeConfigured = false;
+    warn.mockClear(); info.mockClear();
+  });
+
+  beforeAll(async () => {
+    mock = createServer((request, response) => { void (async () => {
+      const url = new URL(request.url ?? "/", origin);
+      if (url.pathname === "/api/v1/apps") {
+        const body = await form(request);
+        expect(body.get("redirect_uris")).toBe(`${apiOrigin}/connections/callback`);
+        json(response, { client_id: "client-id", client_secret: "registered-client-secret" });
+      } else if (url.pathname === "/oauth/authorize") {
+        const code = randomUUID();
+        grants.set(code, { challenge: url.searchParams.get("code_challenge") ?? "", redirectUri: url.searchParams.get("redirect_uri") ?? "" });
+        const redirect = new URL(url.searchParams.get("redirect_uri") ?? "");
+        redirect.searchParams.set("state", url.searchParams.get("state") ?? "");
+        redirect.searchParams.set("code", code);
+        response.writeHead(302, { location: redirect.toString() }); response.end();
+      } else if (url.pathname === "/oauth/token") {
+        const body = await form(request);
+        const code = body.get("code") ?? "";
+        const grant = grants.get(code);
+        grants.delete(code);
+        if (failExchange || !grant || grant.redirectUri !== body.get("redirect_uri") || grant.challenge !== createHash("sha256").update(body.get("code_verifier") ?? "").digest("base64url") || body.get("client_secret") !== "registered-client-secret") {
+          json(response, { error: "secret echoed: registered-client-secret token-secret-leak" }, 400); return;
+        }
+        const token = `access-token-secret-${++issued}`;
+        activeTokens.add(token);
+        json(response, { access_token: token, refresh_token: `refresh-token-secret-${issued}`, token_type: "Bearer", scope: "read write:statuses write:media", created_at: Date.now() / 1000 });
+      } else if (url.pathname === "/api/v1/accounts/verify_credentials") {
+        const token = (request.headers.authorization ?? "").slice(7);
+        if (!activeTokens.has(token)) { json(response, { error: `revoked ${token}` }, 401); return; }
+        json(response, { id: nextAccount, username: "alice", acct: "alice", display_name: "Alice", avatar: "", url: `${origin}/@alice` });
+      } else if (url.pathname === "/api/v1/oauth-clients/local") {
+        json(response, { client_id: "client-id", client_secret: "registered-client-secret" });
+      } else if (url.pathname === "/api/v1/users/me") {
+        const token = (request.headers.authorization ?? "").slice(7);
+        if (!activeTokens.has(token)) { json(response, { error: "invalid token" }, 401); return; }
+        json(response, { id: 1, username: "alice", account: { id: 1, name: "alice", host: "127.0.0.1", displayName: "Alice" } });
+      } else if (url.pathname === "/api/v1/users/token") {
+        const body = await form(request);
+        if (body.get("grant_type") !== "refresh_token" || body.get("client_secret") !== "registered-client-secret") { json(response, { error: "invalid refresh" }, 401); return; }
+        const token = `access-token-secret-${++issued}`;
+        activeTokens.add(token);
+        json(response, { access_token: token, refresh_token: `refresh-token-secret-${issued}` });
+      } else if (url.pathname === "/api/v1/users/revoke-token") {
+        const token = (request.headers.authorization ?? "").slice(7);
+        revokedTokens.push(token); activeTokens.delete(token); json(response, {});
+      } else if (url.pathname === "/oauth/revoke") {
+        const body = await form(request);
+        const token = body.get("token") ?? "";
+        revokedTokens.push(token); activeTokens.delete(token); json(response, {});
+      } else if (url.pathname.startsWith("/bot")) {
+        if (!url.pathname.startsWith(`/bot${botToken}/`)) { json(response, { ok: false, error_code: 401, description: `unauthorized ${url.pathname}` }); return; }
+        json(response, { ok: true, result: { id: 12345, is_bot: true, username: "test_bot", first_name: "Test bot" } });
+      } else { json(response, { error: "not found" }, 404); }
+    })().catch(() => json(response, { error: "mock failure" }, 500)); });
+    origin = "http://127.0.0.1:4500";
+    const deps: ConnectionDependencies = {
+      renewSession: async () => "replacement-session",
+      store, pending: new RedisPendingStore(redis, encryption), encryption,
+      appUrl: "http://localhost:3001", callbackUrl: "",
+      registry: (credentials) => {
+        const registry = new ConnectorRegistry();
+        registry.register(createMastodonConnector({ credentials, fetchImpl: mockFetch, requestsPerSecond: 100_000 }));
+        registry.register(createPeerTubeConnector({ credentials, fetchImpl: mockFetch, requestsPerSecond: 100_000,
+          env: bridgeConfigured ? { PEERTUBE_AUTHORIZE_PATH: "/oauth/authorize", PEERTUBE_TOKEN_PATH: "/oauth/token" } : {},
+        }));
+        const botFetch: typeof fetch = (input, init) => fetch(String(input).replace("https://api.telegram.org", origin), init);
+        registry.register(createTelegramConnector({ credentials, fetchImpl: botFetch, requestsPerSecond: 100_000 }));
+        return registry;
+      },
+    };
+    app = await NestFactory.create({ module: TestModule, controllers: [ConnectionsController], providers: [
+      ConnectionsService, { provide: CONNECTION_DEPENDENCIES, useValue: deps },
+
+    ] }, { logger: false });
+    await app.init();
+    apiOrigin = "http://api.local";
+    deps.callbackUrl = `${apiOrigin}/connections/callback`;
+  });
+  afterAll(async () => {
+    await app?.close();
+
+    warn.mockRestore(); info.mockRestore(); guard.mockRestore();
+  });
+  const mockFetch: typeof globalThis.fetch = (input, init) => injectHttp((request, response) => { mock.emit("request", request, response); }, input, init);
+  const fetch: typeof globalThis.fetch = (input, init) => {
+    const url = new URL(input instanceof Request ? input.url : String(input));
+    if (url.origin === origin) return mockFetch(input, init);
+    if (url.origin !== apiOrigin) throw new Error("Unexpected test destination");
+    const adapter = app.getHttpAdapter();
+    return injectHttp((request, response) => { adapter.getInstance().handle(request, response); }, input, init);
+  };
+  async function api(path: string, method = "GET", body?: unknown): Promise<Response> {
+    return fetch(`${apiOrigin}/connections${path}`, { method, headers: { authorization: "Bearer test-session", "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body) });
+  }
+  async function begin(id?: string, provider = "mastodon"): Promise<{ redirectUrl: string; cookie: string }> {
+    const response = id ? await api(`/${id}/reconnect`, "POST", {}) : await api("/authorize", "POST", { provider, instanceUrl: origin });
+    expect(response.status).toBe(201);
+    const { redirectUrl } = await response.json() as { redirectUrl: string };
+    expect(new URL(redirectUrl).searchParams.get("code_challenge_method")).toBe("S256");
+    return { redirectUrl, cookie: response.headers.get("set-cookie")?.split(";")[0] ?? "" };
+  }
+  async function finish(authorization: { redirectUrl: string; cookie: string }): Promise<Response> {
+    const consent = await fetch(authorization.redirectUrl, { redirect: "manual" });
+    expect(consent.status).toBe(302);
+    return fetch(consent.headers.get("location") ?? "", { redirect: "manual", headers: { cookie: authorization.cookie } });
+  }
+  async function listed(): Promise<ConnectionSummary[]> { return (await (await api("")).json()) as ConnectionSummary[]; }
+
+  it("authorize → provider → unauthenticated callback → healthy list; reconnect rotates; remove revokes and clears row + vault envelope", async () => {
+    const auth = await begin();
+    expect(auth.cookie).toMatch(/^ap_connect_/);
+    expect(JSON.stringify([...redis.entries.values()])).not.toContain("registered-client-secret");
+    const callback = await finish(auth);
+    expect(callback.status).toBe(303);
+    expect(callback.headers.get("location")).toBe("http://localhost:3001/connections?connect=success");
+    expect(callback.headers.get("set-cookie")).toContain("Expires=");
+    const rows = await listed();
+    expect(rows).toHaveLength(1); expect(rows[0]?.health).toBe("healthy");
+    expect(rows[0]?.capabilities).toContain("publishText");
+    const id = rows[0]?.id ?? "";
+    const before = store.rows.get(id)?.credential?.ciphertext;
+    expect(before).toBeDefined();
+    const stored = store.rows.get(id)?.credential;
+    if (!stored) throw new Error("credential missing");
+    expect((await new Vault().open(sessionFixture.workspaceId, id, stored)).toString()).toContain("access-token-secret-1");
+    expect(JSON.stringify(rows)).not.toContain("token-secret");
+    const second = await finish(await begin(id));
+    expect(second.headers.get("location")).toContain("connect=success");
+    expect((await listed())[0]?.id).toBe(id);
+    expect(store.rows.get(id)?.credential?.ciphertext.equals(before ?? Buffer.alloc(0))).toBe(false);
+    expect(store.audit.at(-1)?.action).toBe("connection.reconnect");
+    const replay = await finish(auth);
+    expect(replay.headers.get("location")).toContain("connect=failure");
+    expect((await api(`/${id}`, "DELETE")).status).toBe(200);
+    expect(revokedTokens).toContain("access-token-secret-2");
+    expect(await listed()).toHaveLength(0); expect(store.rows.size).toBe(0); expect(redis.entries.size).toBe(0);
+    const observable = JSON.stringify({ audit: store.audit, warn: warn.mock.calls, info: info.mock.calls });
+    for (const secret of ["access-token-secret", "refresh-token-secret", "registered-client-secret"]) expect(observable).not.toContain(secret);
+  });
+
+  it("rejects missing auth on authorize, missing/wrong browser cookie and preserves a valid pending state", async () => {
+    expect((await fetch(`${apiOrigin}/connections/authorize`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ provider: "mastodon", instanceUrl: origin }) })).status).toBe(401);
+    const auth = await begin();
+    const consent = await fetch(auth.redirectUrl, { redirect: "manual" });
+    const callbackUrl = consent.headers.get("location") ?? "";
+    const missing = await fetch(callbackUrl, { redirect: "manual" });
+    expect(missing.headers.get("location")).toContain("connect=failure");
+    const wrong = await fetch(callbackUrl, { redirect: "manual", headers: { cookie: auth.cookie.replace(sessionFixture.workspaceId, randomUUID()) } });
+    expect(wrong.headers.get("location")).toContain("connect=failure");
+    const good = await fetch(callbackUrl, { redirect: "manual", headers: { cookie: auth.cookie } });
+    expect(good.headers.get("location")).toContain("connect=success");
+  });
+
+  it("failed exchange and different-account reconnect retain the previous encrypted credential; health detects revoked tokens", async () => {
+    await finish(await begin());
+    const row = (await listed())[0];
+    if (!row) throw new Error("connection missing");
+    const before = store.rows.get(row.id)?.credential?.ciphertext;
+    failExchange = true;
+    const failure = await finish(await begin(row.id));
+    failExchange = false;
+    expect(failure.headers.get("location")).toContain("connect=failure");
+    expect(store.rows.get(row.id)?.credential?.ciphertext.equals(before ?? Buffer.alloc(0))).toBe(true);
+    nextAccount = "other-account";
+    const wrongAccount = await finish(await begin(row.id));
+    nextAccount = "account-1";
+    expect(wrongAccount.headers.get("location")).toContain("connect=failure");
+    expect(store.rows.get(row.id)?.credential?.ciphertext.equals(before ?? Buffer.alloc(0))).toBe(true);
+    activeTokens.clear();
+    expect((await listed())[0]?.health).toBe("needs_credentials");
+    expect((await finish(await begin(row.id))).headers.get("location")).toContain("connect=success");
+    expect((await listed())[0]?.health).toBe("healthy");
+    expect(JSON.stringify(warn.mock.calls)).not.toContain("token-secret-leak");
+    expect(JSON.stringify(warn.mock.calls)).not.toContain("registered-client-secret");
+  });
+
+  it("rechecks workspace membership during callback, handles denial, and does not expose provider errors", async () => {
+    const revoked = await begin();
+    store.authorized = false;
+    expect((await finish(revoked)).headers.get("location")).toContain("connect=failure");
+    store.authorized = true;
+    const denied = await begin();
+    const url = new URL(`${apiOrigin}/connections/callback`);
+    url.searchParams.set("state", new URL(denied.redirectUrl).searchParams.get("state") ?? "");
+    url.searchParams.set("error", "access_denied token-secret-leak");
+    const response = await fetch(url, { redirect: "manual", headers: { cookie: denied.cookie } });
+    expect(response.headers.get("location")).toContain("connect=failure");
+    expect(JSON.stringify(warn.mock.calls)).not.toContain("token-secret-leak");
+  });
+
+  it("validates Telegram getMe, encrypts tokens, rotates in place and removes locally; PeerTube is capability-honest", async () => {
+    const bad = await api("/telegram/bot-token", "POST", { token: "12345:bad_secret" });
+    expect(bad.status).toBe(400); expect(await bad.text()).not.toContain("bad_secret");
+    const response = await api("/telegram/bot-token", "POST", { token: botToken, channelId: "@target" });
+    expect(response.status).toBe(201);
+    const bot = (await listed()).find((row) => row.provider === "telegram");
+    expect(bot?.health).toBe("healthy"); expect(bot?.channelId).toBe("@target");
+    const id = bot?.id ?? "";
+    const before = store.rows.get(id)?.credential?.ciphertext;
+    expect((await api("/telegram/bot-token", "POST", { token: botToken, connectionId: id })).status).toBe(201);
+    expect(store.rows.get(id)?.credential?.ciphertext.equals(before ?? Buffer.alloc(0))).toBe(false);
+    expect((await listed()).filter((row) => row.provider === "telegram")).toHaveLength(1);
+    expect((await api(`/${id}`, "DELETE")).status).toBe(200);
+    expect(store.rows.has(id)).toBe(false);
+    const providers = await (await api("/providers")).json() as Array<{ id: string; enabled: boolean; note?: string }>;
+    expect(providers.find((provider) => provider.id === "peertube")?.enabled).toBe(false);
+    expect((await api("/authorize", "POST", { provider: "peertube", instanceUrl: origin })).status).toBe(400);
+    expect(JSON.stringify({ audit: store.audit, warn: warn.mock.calls, info: info.mock.calls })).not.toContain(botToken);
+  });
+
+  it("runs PeerTube code flow only with an explicitly configured instance bridge", async () => {
+    bridgeConfigured = true;
+    expect((await finish(await begin(undefined, "peertube"))).headers.get("location")).toContain("connect=success");
+    const row = (await listed()).find((connection) => connection.provider === "peertube");
+    expect(row?.health).toBe("healthy");
+    const id = row?.id ?? "";
+    expect((await finish(await begin(id))).headers.get("location")).toContain("connect=success");
+    expect((await listed()).filter((connection) => connection.id === id)).toHaveLength(1);
+    const stored = store.rows.get(id)?.credential;
+    if (!stored) throw new Error("PeerTube credential missing");
+    const secrets = JSON.parse((await encryption.open(sessionFixture.workspaceId, id, stored)).toString()) as Record<string, string>;
+    activeTokens.delete(secrets.access_token ?? "");
+    expect((await listed()).find((connection) => connection.id === id)?.health).toBe("healthy");
+    expect(store.audit.at(-1)?.action).toBe("credential.refresh");
+    expect(store.rows.get(id)?.credential?.ciphertext.equals(stored.ciphertext)).toBe(false);
+    expect((await api(`/${id}`, "DELETE")).status).toBe(200);
+    bridgeConfigured = false;
+  });
+
+  it("does not resurrect a connection removed while reconnect consent is pending", async () => {
+    await finish(await begin());
+    const row = (await listed())[0];
+    if (!row) throw new Error("connection missing");
+    const pending = await begin(row.id);
+    expect((await api(`/${row.id}`, "DELETE")).status).toBe(200);
+    expect((await finish(pending)).headers.get("location")).toContain("connect=failure");
+    expect(store.rows.has(row.id)).toBe(false);
+  });
+});
diff --git a/apps/api/src/connections/connections.service.ts b/apps/api/src/connections/connections.service.ts
new file mode 100644
index 0000000..25ac270
--- /dev/null
+++ b/apps/api/src/connections/connections.service.ts
@@ -0,0 +1,231 @@
+import { BadRequestException, Inject, Injectable, Optional } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
+import type { ConnectorConnection, NormalizedIdentity } from "@tactical-media-broadcast-hub/core";
+import { AuthError, type AuthorizationRequest, type AuthorizationResult, type CredentialAccessor, type ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { SessionPayload } from "../auth/session.js";
+import { withTenant } from "../db/client.js";
+import { issueSessionInTenant } from "../auth/auth.service.js";
+import { vault, type Vault } from "../vault/vault.js";
+import { logger } from "../telemetry/logger.js";
+import { connectionRegistry } from "./connector-registry.js";
+import { PgConnectionStore, type ConnectionStore, type StoredConnection } from "./connection-store.js";
+import { AUTH_TTL_MS, browserHash, randomState, RedisPendingStore, type PendingStore } from "./pending.js";
+import { oauthFetch } from "./oauth-fetch.js";
+
+export type ConnectionHealth = "healthy" | "needs_credentials" | "unavailable";
+export interface ConnectionSummary {
+  id: string; provider: string; channelId: string; fields: Record<string, unknown>;
+  health: ConnectionHealth; credentialRotatedAt: string | null; recentPublishes: string[]; createdAt: string;
+  capabilities?: string[];
+}
+export interface ConnectionDependencies {
+  store: ConnectionStore;
+  pending: PendingStore;
+  encryption: Vault;
+  registry: (credentials: CredentialAccessor) => ConnectorRegistry;
+  appUrl: string;
+  callbackUrl: string;
+  renewSession(session: SessionPayload): Promise<string>;
+}
+export const CONNECTION_DEPENDENCIES = Symbol("CONNECTION_DEPENDENCIES");
+
+/** Each exchange has an isolated, tenant-bound working set; never writes plaintext to DB. */
+class StagedCredentials implements CredentialAccessor {
+  dirty = false;
+  constructor(private readonly workspaceId: string, private readonly connectionId: string, readonly secrets: Record<string, string> = {}) {}
+  private assert(connection: ConnectorConnection): void {
+    if (connection.workspaceId !== this.workspaceId || connection.id !== this.connectionId || connection.credentialId.id !== this.connectionId) throw new Error("Credential binding mismatch");
+  }
+  async getAccessToken(connection: ConnectorConnection): Promise<string> { return this.getSecret(connection, "access_token"); }
+  async getSecret(connection: ConnectorConnection, key: string): Promise<string> {
+    this.assert(connection);
+    const value = this.secrets[key];
+    if (!value) throw new Error("Credential missing");
+    return value;
+  }
+  async put(connection: ConnectorConnection, key: string, value: string): Promise<void> {
+    this.assert(connection);
+    if (typeof value !== "string" || !value) throw new Error("Provider returned invalid credential");
+    this.secrets[key] = value;
+    this.dirty = true;
+  }
+}
+function defaults(): ConnectionDependencies {
+  const appUrl = process.env.APP_URL ?? "http://localhost:3000";
+  return {
+    renewSession: (session) => withTenant(session.workspaceId, (client) => issueSessionInTenant(client, session.workspaceId, session.userId, session.expiresAt)),
+    store: new PgConnectionStore(), pending: new RedisPendingStore(), encryption: vault,
+    registry: (credentials) => connectionRegistry(credentials, oauthFetch), appUrl,
+    callbackUrl: process.env.CONNECTIONS_CALLBACK_URL ?? `${process.env.API_URL ?? "http://localhost:3000"}/connections/callback`,
+  };
+}
+
+@Injectable()
+export class ConnectionsService {
+  private readonly deps: ConnectionDependencies;
+  constructor(@Optional() @Inject(CONNECTION_DEPENDENCIES) dependencies?: ConnectionDependencies) { this.deps = dependencies ?? defaults(); }
+
+  providers() {
+    const registry = this.deps.registry(new StagedCredentials("", ""));
+    return registry.list().map((connector) => {
+      const manifest = connector.manifest();
+      return {
+        id: manifest.id, displayName: manifest.displayName, kind: manifest.oauth?.kind,
+        enabled: manifest.oauth?.connectEnabled !== false && Boolean(connector.validateToken || (connector.buildAuthorizationUrl && connector.exchangeCode)),
+        note: manifest.oauth?.connectNote, targetField: manifest.oauth?.targetField,
+        instanceRequired: manifest.oauth?.kind === "per-instance-oauth2",
+        capabilities: Object.entries(manifest.capabilities).filter(([, enabled]) => enabled === true).map(([key]) => key),
+      };
+    });
+  }
+  landing(status: "success" | "failure"): string {
+    const url = new URL("/connections", this.deps.appUrl);
+    url.searchParams.set("connect", status);
+    return url.toString();
+  }
+  async authorize(session: SessionPayload, provider: string, instanceUrl?: string, connectionId?: string) {
+    await this.deps.store.assertAuthorized(session);
+    const previous = connectionId ? await this.deps.store.get(session.workspaceId, connectionId) : undefined;
+    if (previous && previous.connection.provider !== provider) throw new BadRequestException("Provider mismatch");
+    const id = connectionId ?? randomUUID();
+    const appSecrets: Record<string, string> = {};
+    if (previous?.credential) {
+      const bytes = await this.deps.encryption.open(session.workspaceId, id, previous.credential);
+      const secrets = JSON.parse(bytes.toString()) as Record<string, string>;
+      // Reuse the registered app, but stage no previous account token.
+      for (const key of ["client_id", "client_secret"]) if (secrets[key]) appSecrets[key] = secrets[key];
+    }
+    const staging = new StagedCredentials(session.workspaceId, id, appSecrets);
+    const registry = this.deps.registry(staging);
+    if (!registry.has(provider)) throw new BadRequestException("Provider is not available");
+    const connector = registry.get(provider);
+    if (!connector.buildAuthorizationUrl || !connector.exchangeCode || connector.manifest().oauth?.connectEnabled === false) throw new BadRequestException(connector.manifest().oauth?.connectNote ?? "Redirect linking is unavailable");
+    const state = randomState();
+    const binding = `${session.workspaceId}.${randomState()}`;
+    const instance = previous?.connection.fields.instanceUrl ?? instanceUrl;
+    const request: AuthorizationRequest = {
+      state, workspaceId: session.workspaceId, connectionId: id, redirectUri: this.deps.callbackUrl,
+      fields: instance ? { instanceUrl: instance } : {},
+      ...(connector.manifest().oauth?.pkce ? { codeVerifier: randomState() } : {}),
+    };
+    try {
+      const redirect = await connector.buildAuthorizationUrl(request);
+      request.fields = redirect.connection.fields;
+      await this.deps.pending.put(state, { session, provider, request, secrets: staging.secrets, reconnect: Boolean(previous), expiresAt: Date.now() + AUTH_TTL_MS, browserHash: browserHash(binding) });
+      return { redirectUrl: redirect.authorizationUrl, state, binding };
+    } catch {
+      logger.warn({ event: "connection.authorize_failed", provider }, "Connection authorization failed");
+      throw new BadRequestException("Could not start authorization. Check the instance URL and provider configuration.");
+    }
+  }
+  async callback(state: string, binding: string, code?: string, providerError?: string): Promise<string> {
+    try {
+      const pending = await this.deps.pending.consume(state, binding);
+      await this.deps.store.assertAuthorized(pending.session);
+      if (providerError || !code || code.length > 4096) throw new Error("Provider authorization denied");
+      const id = pending.request.connectionId;
+      if (!id) throw new Error("Missing connection binding");
+      const staging = new StagedCredentials(pending.session.workspaceId, id, pending.secrets);
+      const connector = this.deps.registry(staging).get(pending.provider);
+      if (!connector.exchangeCode) throw new Error("Code exchange unavailable");
+      const result = await connector.exchangeCode({ ...pending.request, code });
+      try {
+        await this.persist(pending.session, result, staging, pending.reconnect);
+      } catch (error) {
+        // A failed DB write/account check must not leave an orphan authorization.
+        await connector.revokeCredentials?.(result.connection).catch(() => undefined);
+        throw error;
+      }
+      return this.landing("success");
+    } catch {
+      // Provider errors can echo secrets. Only a fixed event reaches logs/UI.
+      logger.warn({ event: "connection.callback_failed" }, "Connection callback failed");
+      return this.landing("failure");
+    }
+  }
+  async botToken(session: SessionPayload, token: string, fields: Record<string, string>, connectionId?: string): Promise<string> {
+    await this.deps.store.assertAuthorized(session);
+    const previous = connectionId ? await this.deps.store.get(session.workspaceId, connectionId) : undefined;
+    const id = connectionId ?? randomUUID();
+    const staging = new StagedCredentials(session.workspaceId, id);
+    const connector = this.deps.registry(staging).list().find((item) => item.manifest().oauth?.kind === "token" && item.validateToken);
+    if (!connector?.validateToken || (previous && previous.connection.provider !== connector.manifest().id)) throw new BadRequestException("Token linking is unavailable");
+    try {
+      const result = await connector.validateToken({ workspaceId: session.workspaceId, connectionId: id, token, fields: { ...previous?.connection.fields, ...fields } });
+      await this.persist(session, result, staging, Boolean(previous));
+      return await this.deps.renewSession(session);
+    } catch {
+      logger.warn({ event: "connection.token_failed" }, "Bot validation failed");
+      throw new BadRequestException("Bot validation failed. Check the token and try again.");
+    }
+  }
+  async reconnect(session: SessionPayload, id: string) {
+    const stored = await this.deps.store.get(session.workspaceId, id);
+    return this.authorize(session, stored.connection.provider, undefined, id);
+  }
+  private async persist(session: SessionPayload, result: AuthorizationResult, staging: StagedCredentials, reconnect: boolean): Promise<void> {
+    const { connection, identity } = result;
+    if (connection.workspaceId !== session.workspaceId || identity.provider !== connection.provider || !identity.remoteId || !identity.handle) throw new Error("Provider identity invalid");
+    if (reconnect) {
+      const previous = await this.deps.store.get(session.workspaceId, connection.id);
+      if (previous.connection.provider !== connection.provider || (previous.connection.fields.remoteId && previous.connection.fields.remoteId !== identity.remoteId)) throw new Error("Reconnect must use the same account");
+      connection.channelId = previous.connection.channelId;
+    } else if (!connection.fields.channelId) {
+      connection.channelId = identity.remoteId;
+    }
+    const encrypted = await this.deps.encryption.seal(session.workspaceId, connection.id, Buffer.from(JSON.stringify(staging.secrets)));
+    await this.deps.store.save(session, connection, identity, encrypted, reconnect);
+  }
+  private async credentials(workspaceId: string, id: string) {
+    const stored = await this.deps.store.get(workspaceId, id);
+    return this.storedCredentials(stored);
+  }
+  private async storedCredentials(stored: StoredConnection) {
+    const { workspaceId, id } = stored.connection;
+    if (!stored.credential) throw new AuthError("Credential missing", stored.connection.provider, false);
+    const bytes = await this.deps.encryption.open(workspaceId, id, stored.credential);
+    const secrets = JSON.parse(bytes.toString()) as Record<string, string>;
+    const staging = new StagedCredentials(workspaceId, id, secrets);
+    return { connection: stored.connection, connector: this.deps.registry(staging).get(stored.connection.provider), staging, stored };
+  }
+  async list(workspaceId: string): Promise<ConnectionSummary[]> {
+    const rows = await this.deps.store.list(workspaceId);
+    // Probe actual identity, rather than assuming a credential row means a valid token.
+    for (const row of rows) {
+      if (row.health === "needs_credentials") continue;
+      try {
+        const { connection, connector, staging, stored } = await this.credentials(workspaceId, row.id);
+        let identity: NormalizedIdentity;
+        try {
+          identity = await connector.getIdentity(connection);
+        } finally {
+          // Some connectors refresh during identity reads; keep the new refresh token durable.
+          if (staging.dirty && stored.credential) {
+            const sealed = await this.deps.encryption.seal(workspaceId, row.id, Buffer.from(JSON.stringify(staging.secrets)));
+            await this.deps.store.rotateCredential(workspaceId, row.id, stored.credential, sealed);
+          }
+        }
+        row.health = "healthy";
+        row.fields.handle = identity.handle;
+        row.capabilities = Object.entries(connector.manifest().capabilities).filter(([, enabled]) => enabled === true).map(([key]) => key);
+      } catch (error) {
+        row.health = error instanceof AuthError ? "needs_credentials" : "unavailable";
+      }
+    }
+    return rows;
+  }
+  async remove(session: SessionPayload, id: string): Promise<string> {
+    await this.deps.store.assertAuthorized(session);
+    await this.deps.store.remove(session, id, async (stored) => {
+      if (!stored.credential) return;
+      try {
+        const { connection, connector } = await this.storedCredentials(stored);
+        await connector.revokeCredentials?.(connection);
+      } catch (error) {
+        // Already invalid/revoked credentials are safe to remove locally.
+        if (!(error instanceof AuthError)) throw new BadRequestException("Provider revocation failed. Try removing again.");
+      }
+    });
+    return this.deps.renewSession(session);
+  }
+}
diff --git a/apps/api/src/connections/connector-registry.ts b/apps/api/src/connections/connector-registry.ts
new file mode 100644
index 0000000..8454727
--- /dev/null
+++ b/apps/api/src/connections/connector-registry.ts
@@ -0,0 +1,17 @@
+import { ConnectorRegistry, type CredentialAccessor } from "@tactical-media-broadcast-hub/connector-sdk";
+// eslint-disable-next-line no-restricted-syntax -- Connector composition boundary.
+import { createMastodonConnector } from "@tactical-media-broadcast-hub/connector-mastodon";
+// eslint-disable-next-line no-restricted-syntax -- Connector composition boundary.
+import { createPeerTubeConnector } from "../../../../packages/connector-peertube/src/index.js";
+// eslint-disable-next-line no-restricted-syntax -- Connector composition boundary.
+import { createTelegramConnector } from "@tactical-media-broadcast-hub/connector-telegram";
+
+/** Composition boundary only: services resolve manifests rather than branch on providers. */
+export function connectionRegistry(credentials: CredentialAccessor, fetchImpl: typeof fetch = fetch): ConnectorRegistry {
+  const registry = new ConnectorRegistry();
+  const options = { credentials, fetchImpl, env: process.env };
+  registry.register(createMastodonConnector(options));
+  registry.register(createPeerTubeConnector(options));
+  registry.register(createTelegramConnector(options));
+  return registry;
+}
diff --git a/apps/api/src/connections/http-test-transport.ts b/apps/api/src/connections/http-test-transport.ts
new file mode 100644
index 0000000..f2564e7
--- /dev/null
+++ b/apps/api/src/connections/http-test-transport.ts
@@ -0,0 +1,46 @@
+import { IncomingMessage, ServerResponse } from "node:http";
+import { Duplex } from "node:stream";
+import type { Socket } from "node:net";
+
+/** Runs real Node/Express HTTP handlers without binding a port (restricted CI). */
+export async function injectHttp(
+  handler: (request: IncomingMessage, response: ServerResponse) => void,
+  input: string | URL | Request,
+  init: RequestInit = {},
+): Promise<Response> {
+  const url = new URL(input instanceof Request ? input.url : String(input));
+  const output: Buffer[] = [];
+  const socket = new Duplex({
+    read() {},
+    write(chunk: Buffer, _encoding, callback) { output.push(Buffer.from(chunk)); callback(); },
+  });
+  // ServerResponse uses only Duplex operations; no network or unsafe dynamic values.
+  const httpSocket = socket as unknown as Socket;
+  const request = new IncomingMessage(httpSocket);
+  request.method = init.method ?? "GET";
+  request.complete = true;
+  request.url = `${url.pathname}${url.search}`;
+  request.headers = Object.fromEntries(new Headers(init.headers).entries());
+  request.headers.host = url.host;
+  const body = typeof init.body === "string" ? init.body : "";
+  if (body) request.headers["content-length"] = String(Buffer.byteLength(body));
+  request.push(body || null);
+  if (body) request.push(null);
+  const response = new ServerResponse(request);
+  response.assignSocket(httpSocket);
+  const completed = new Promise<Response>((resolve, reject) => {
+    response.once("error", reject);
+    response.once("finish", () => {
+      const bytes = Buffer.concat(output);
+      const bodyOffset = bytes.indexOf("\r\n\r\n") + 4;
+      const headers = new Headers();
+      for (const line of bytes.subarray(0, bodyOffset - 4).toString().split("\r\n").slice(1)) {
+        const separator = line.indexOf(":");
+        if (separator > 0) headers.append(line.slice(0, separator), line.slice(separator + 1).trim());
+      }
+      resolve(new Response([204, 304].includes(response.statusCode) ? null : bytes.subarray(bodyOffset), { status: response.statusCode, headers }));
+    });
+  });
+  handler(request, response);
+  return completed;
+}
diff --git a/apps/api/src/connections/oauth-fetch.test.ts b/apps/api/src/connections/oauth-fetch.test.ts
new file mode 100644
index 0000000..ef3ab1d
--- /dev/null
+++ b/apps/api/src/connections/oauth-fetch.test.ts
@@ -0,0 +1,11 @@
+import { describe, expect, it } from "vitest";
+import { publicAddress } from "./oauth-fetch.js";
+
+describe("authorization egress policy", () => {
+  it("rejects private, mapped, metadata, multicast and documentation addresses", () => {
+    for (const address of ["127.0.0.1", "10.0.0.1", "172.16.0.1", "192.168.1.1", "169.254.169.254", "100.64.1.1", "0.0.0.0", "224.0.0.1", "::1", "::ffff:127.0.0.1", "fc00::1", "fe80::1", "2001:db8::1", "2002:7f00:1::"]) expect(publicAddress(address), address).toBe(false);
+    expect(publicAddress("8.8.8.8")).toBe(true);
+    expect(publicAddress("2606:4700:4700::1111")).toBe(true);
+    expect(publicAddress("2001:4860:4860::8888")).toBe(true);
+  });
+});
diff --git a/apps/api/src/connections/oauth-fetch.ts b/apps/api/src/connections/oauth-fetch.ts
new file mode 100644
index 0000000..853caaa
--- /dev/null
+++ b/apps/api/src/connections/oauth-fetch.ts
@@ -0,0 +1 @@
+export { publicAddress, providerFetch as oauthFetch } from "@tactical-media-broadcast-hub/connector-runtime";
diff --git a/apps/api/src/connections/pending.test.ts b/apps/api/src/connections/pending.test.ts
new file mode 100644
index 0000000..40b646b
--- /dev/null
+++ b/apps/api/src/connections/pending.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it, vi, afterEach } from "vitest";
+import { Vault } from "../vault/vault.js";
+import { AUTH_TTL_MS, browserHash, randomState, RedisPendingStore, type PendingAuthorization } from "./pending.js";
+import { MemoryPendingRedis } from "./testing.js";
+
+function fixture() {
+  const redis = new MemoryPendingRedis();
+  const store = new RedisPendingStore(redis, new Vault());
+  const state = randomState();
+  const binding = `workspace-a.${randomState()}`;
+  const pending: PendingAuthorization = {
+    provider: "mastodon", request: { redirectUri: "http://localhost/callback", workspaceId: "workspace-a", state },
+    session: { userId: "user-a", workspaceId: "workspace-a", role: "Owner", authzEpoch: 1, issuedAt: 0, expiresAt: Date.now() / 1000 + 600 },
+    secrets: { client_secret: "registration-secret" }, reconnect: false, expiresAt: Date.now() + AUTH_TTL_MS, browserHash: browserHash(binding),
+  };
+  return { redis, store, state, binding, pending };
+}
+afterEach(() => vi.useRealTimers());
+describe("pending authorization binding", () => {
+  it("encrypts provider secrets and consumes state exactly once", async () => {
+    const { redis, store, state, binding, pending } = fixture();
+    await store.put(state, pending);
+    expect(JSON.stringify([...redis.entries.values()])).not.toContain("registration-secret");
+    expect(await store.consume(state, binding)).toEqual(pending);
+    await expect(store.consume(state, binding)).rejects.toThrow(/already used/);
+  });
+  it("rejects CSRF, unknown states and a different workspace without burning the valid state", async () => {
+    const { store, state, binding, pending } = fixture();
+    await store.put(state, pending);
+    await expect(store.consume(state, "")).rejects.toThrow(/mismatch/);
+    await expect(store.consume(state, binding.replace("workspace-a", "workspace-b"))).rejects.toThrow(/mismatch/);
+    await expect(store.consume(randomState(), binding)).rejects.toThrow();
+    await expect(store.consume("malformed", binding)).rejects.toThrow();
+    expect(await store.consume(state, binding)).toEqual(pending);
+  });
+  it("rejects a workspace mismatch inside the encrypted request", async () => {
+    const { store, state, binding, pending } = fixture();
+    pending.request.workspaceId = "workspace-b";
+    await store.put(state, pending);
+    await expect(store.consume(state, binding)).rejects.toThrow(/workspace mismatch/);
+  });
+  it("expires state after ten minutes and atomically fences simultaneous callbacks", async () => {
+    vi.useFakeTimers();
+    const { store, state, binding, pending } = fixture();
+    await store.put(state, pending);
+    const results = await Promise.allSettled([store.consume(state, binding), store.consume(state, binding)]);
+    expect(results.filter((item) => item.status === "fulfilled")).toHaveLength(1);
+    const next = fixture();
+    await next.store.put(next.state, next.pending);
+    vi.advanceTimersByTime(AUTH_TTL_MS);
+    await expect(next.store.consume(next.state, next.binding)).rejects.toThrow(/expired/);
+  });
+});
diff --git a/apps/api/src/connections/pending.ts b/apps/api/src/connections/pending.ts
new file mode 100644
index 0000000..ff914d8
--- /dev/null
+++ b/apps/api/src/connections/pending.ts
@@ -0,0 +1,57 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { BadRequestException } from "@nestjs/common";
+import type { AuthorizationRequest } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { SessionPayload } from "../auth/session.js";
+import { RespControlRedis, type ControlRedis } from "../media-control/redis.js";
+import { vault, type Vault } from "../vault/vault.js";
+
+export const AUTH_TTL_MS = 10 * 60_000;
+export const stateCookieName = (state: string): string => `ap_connect_${state}`;
+export const validState = (state: string): boolean => /^[A-Za-z0-9_-]{43}$/.test(state);
+export interface PendingAuthorization {
+  session: SessionPayload;
+  provider: string;
+  request: AuthorizationRequest;
+  secrets: Record<string, string>;
+  reconnect: boolean;
+  expiresAt: number;
+  browserHash: string;
+}
+export interface PendingStore {
+  put(state: string, pending: PendingAuthorization): Promise<void>;
+  consume(state: string, browserBinding: string): Promise<PendingAuthorization>;
+}
+export function browserHash(binding: string): string {
+  return createHash("sha256").update(binding).digest("hex");
+}
+export const randomState = (): string => randomBytes(32).toString("base64url");
+
+/** GET + compare-and-delete makes callbacks one-use across API replicas. */
+export class RedisPendingStore implements PendingStore {
+  constructor(
+    private readonly redis: Pick<ControlRedis, "get" | "set" | "eval"> = new RespControlRedis(process.env.REDIS_URL ?? "redis://localhost:6379"),
+    private readonly encryption: Vault = vault,
+  ) {}
+  async put(state: string, pending: PendingAuthorization): Promise<void> {
+    const sealed = await this.encryption.seal(pending.session.workspaceId, state, Buffer.from(JSON.stringify(pending)));
+    const value = JSON.stringify({ workspaceId: pending.session.workspaceId, ciphertext: sealed.ciphertext.toString("base64") });
+    if (!await this.redis.set(`oauth:pending:${state}`, value, { nx: true, pxMs: AUTH_TTL_MS })) throw new Error("state collision");
+  }
+  async consume(state: string, binding: string): Promise<PendingAuthorization> {
+    if (!validState(state) || binding.length > 200) throw new BadRequestException("Invalid authorization state");
+    const key = `oauth:pending:${state}`;
+    const raw = await this.redis.get(key);
+    if (!raw) throw new BadRequestException("Authorization expired or already used");
+    const envelope = JSON.parse(raw) as { workspaceId: string; ciphertext: string };
+    const opened = await this.encryption.open(envelope.workspaceId, state, { keyVersion: 1, ciphertext: Buffer.from(envelope.ciphertext, "base64") });
+    const pending = JSON.parse(opened.toString()) as PendingAuthorization;
+    const actual = Buffer.from(browserHash(binding));
+    const expected = Buffer.from(pending.browserHash);
+    if (pending.expiresAt <= Date.now() || pending.session.workspaceId !== envelope.workspaceId || pending.request.workspaceId !== envelope.workspaceId || !binding.startsWith(`${envelope.workspaceId}.`) || actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+      throw new BadRequestException("Authorization browser or workspace mismatch");
+    }
+    const consumed = await this.redis.eval("if redis.call('GET', KEYS[1]) == ARGV[1] then redis.call('DEL', KEYS[1]); return 1 end; return 0", [key], [raw]);
+    if (consumed !== 1) throw new BadRequestException("Authorization already used");
+    return pending;
+  }
+}
diff --git a/apps/api/src/connections/testing.ts b/apps/api/src/connections/testing.ts
new file mode 100644
index 0000000..030b6f6
--- /dev/null
+++ b/apps/api/src/connections/testing.ts
@@ -0,0 +1,23 @@
+import type { ControlRedis } from "../media-control/redis.js";
+
+/** TTL-faithful Redis substitute; compare-and-delete runs synchronously like Redis Lua. */
+export class MemoryPendingRedis implements Pick<ControlRedis, "get" | "set" | "eval"> {
+  readonly entries = new Map<string, { value: string; expiresAt: number }>();
+  async get(key: string): Promise<string | null> {
+    const entry = this.entries.get(key);
+    if (!entry || entry.expiresAt <= Date.now()) { this.entries.delete(key); return null; }
+    return entry.value;
+  }
+  async set(key: string, value: string, options: { nx?: boolean; pxMs?: number } = {}): Promise<boolean> {
+    if (options.nx && await this.get(key) !== null) return false;
+    this.entries.set(key, { value, expiresAt: Date.now() + (options.pxMs ?? 1000) });
+    return true;
+  }
+  async eval(_script: string, keys: string[], args: string[]): Promise<number> {
+    const key = keys[0] ?? "";
+    const entry = this.entries.get(key);
+    if (!entry || entry.value !== args[0] || entry.expiresAt <= Date.now()) return 0;
+    this.entries.delete(key);
+    return 1;
+  }
+}
diff --git a/apps/api/src/db/client.ts b/apps/api/src/db/client.ts
new file mode 100644
index 0000000..a31a898
--- /dev/null
+++ b/apps/api/src/db/client.ts
@@ -0,0 +1,59 @@
+import { Pool, type PoolClient } from "pg";
+import pino from "pino";
+
+const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
+
+export const pool = new Pool({
+  connectionString: process.env.DATABASE_URL,
+  max: Number(process.env.PG_POOL_MAX ?? 10),
+});
+
+/**
+ * Tenant-scoped transaction: sets app.workspace_id for the transaction so
+ * RLS policies and SECURITY DEFINER assertions see the tenant context.
+ * The setting is transaction-local (SET LOCAL) — it cannot leak.
+ */
+export async function withTenant<T>(
+  workspaceId: string,
+  fn: (client: PoolClient) => Promise<T>,
+): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+/** System-level transaction (no tenant context): RLS sees NULL context and returns nothing tenant-scoped. */
+export async function withSystem<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await pool.connect();
+  try {
+    await client.query("BEGIN");
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (err) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+export async function checkDatabase(): Promise<boolean> {
+  try {
+    await pool.query("SELECT 1");
+    return true;
+  } catch (err) {
+    logger.warn({ err: String(err) }, "db: unreachable");
+    return false;
+  }
+}
diff --git a/apps/api/src/db/migrate.cli.ts b/apps/api/src/db/migrate.cli.ts
new file mode 100644
index 0000000..6853f2a
--- /dev/null
+++ b/apps/api/src/db/migrate.cli.ts
@@ -0,0 +1,6 @@
+import { resolve } from "node:path";
+import { runMigrations } from "./migrate.js";
+const index = process.argv.indexOf("--dir");
+void runMigrations(resolve(index < 0 ? "migrations" : process.argv[index + 1] ?? "migrations"))
+  .then((files) => console.log({ applied: files }))
+  .catch(() => { console.error("Migration failed; schema remains unready. Inspect the phase and database records before retrying."); process.exitCode = 1; });
diff --git a/apps/api/src/db/migrate.test.ts b/apps/api/src/db/migrate.test.ts
new file mode 100644
index 0000000..093e0c6
--- /dev/null
+++ b/apps/api/src/db/migrate.test.ts
@@ -0,0 +1,12 @@
+import { describe, expect, it } from "vitest";
+import { migrationPhases } from "./migrate.js";
+describe("migration stage grammar", () => {
+  it("leaves 001–018 transactional and parses explicit stages", () => {
+    expect(migrationPhases("SELECT 1;")).toEqual([{ name: "", mode: "transaction", sql: "SELECT 1;" }]);
+    expect(migrationPhases("-- comment\n-- wp3:phase expand transaction\nSELECT 1;\n-- wp3:phase fill batch\nUPDATE t SET x=1;\n-- wp3:phase idx concurrent\nCREATE INDEX CONCURRENTLY t_idx ON t (x);").map((p) => [p.name, p.mode])).toEqual([["expand", "transaction"], ["fill", "batch"], ["idx", "concurrent"]]);
+  });
+  it("refuses duplicate phases and SQL before the first stage", () => {
+    expect(() => migrationPhases("-- wp3:phase expand transaction\nSELECT 1;\n-- wp3:phase expand transaction\nSELECT 2;")).toThrow(/duplicate/);
+    expect(() => migrationPhases("SELECT 0;\n-- wp3:phase expand transaction\nSELECT 1;")).toThrow(/before/);
+  });
+});
diff --git a/apps/api/src/db/migrate.ts b/apps/api/src/db/migrate.ts
new file mode 100644
index 0000000..fca2a3c
--- /dev/null
+++ b/apps/api/src/db/migrate.ts
@@ -0,0 +1,77 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+export interface MigrationPhase { name: string; mode: "transaction" | "batch" | "concurrent"; sql: string }
+/** Only explicit whole-line WP3 markers are accepted; old migrations stay transactional. */
+export function migrationPhases(sql: string): MigrationPhase[] {
+  const marker = /^-- wp3:phase ([a-z][a-z0-9_]*) (transaction|batch|concurrent)\s*$/gm;
+  const matches = [...sql.matchAll(marker)];
+  if (matches.length === 0) return [{ name: "", mode: "transaction", sql }];
+  if (sql.slice(0, matches[0]?.index).split("\n").some((line) => line.trim() && !line.trim().startsWith("--"))) throw new Error("SQL before migration phase");
+  const phases = matches.map((match, index): MigrationPhase => ({ name: match[1]!, mode: match[2] as MigrationPhase["mode"], sql: sql.slice(match.index! + match[0].length, matches[index + 1]?.index).trim() }));
+  if (new Set(phases.map((p) => p.name)).size !== phases.length) throw new Error("duplicate migration phase");
+  return phases;
+}
+
+async function concurrentIndex(client: PoolClient, sql: string): Promise<void> {
+  const parsed = /^CREATE (UNIQUE )?INDEX CONCURRENTLY ([a-z][a-z0-9_]*) ON ([a-z][a-z0-9_]*) ([\s\S]+);$/.exec(sql);
+  if (!parsed) throw new Error("concurrent phase must contain exactly one CREATE INDEX");
+  const [, unique, name, table, tail] = parsed;
+  const found = await client.query<{ indisvalid: boolean; definition: string }>("SELECT i.indisvalid, pg_get_indexdef(i.indexrelid) AS definition FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid JOIN pg_namespace n ON n.oid = c.relnamespace WHERE n.nspname = 'public' AND c.relname = $1", [name]);
+  const existing = found.rows[0];
+  if (existing) {
+    const expected = `CREATE ${unique ?? ""}INDEX ${name} ON public.${table} USING btree ${tail}`;
+    const normalize = (text: string): string => text.replace(/;$/, "").replace(/\s+/g, " ").trim();
+    if (normalize(existing.definition) !== normalize(expected)) throw new Error(`index ${name} definition differs`);
+    if (existing.indisvalid) return;
+    await client.query(`DROP INDEX CONCURRENTLY public.${name}`);
+  }
+  await client.query(sql);
+}
+
+/** Owner-only offline runner; runtime applications never call this. */
+export async function runMigrations(dir: string): Promise<string[]> {
+  if (!process.env.SUPER_DATABASE_URL) throw new Error("SUPER_DATABASE_URL is required for migrations");
+  const files = (await readdir(dir)).filter((f) => f.endsWith(".sql")).sort();
+  const applied: string[] = [];
+  const pool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL });
+  const client = await pool.connect();
+  try {
+    await client.query("SELECT pg_advisory_lock(193674839, 3)");
+    await client.query("SET lock_timeout = '5s'");
+    await client.query("CREATE TABLE IF NOT EXISTS schema_migrations (name text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())");
+    for (const file of files) {
+      if ((await client.query("SELECT 1 FROM schema_migrations WHERE name = $1", [file])).rowCount !== 0) continue;
+      for (const phase of migrationPhases(await readFile(join(dir, file), "utf8"))) {
+        const key = phase.name ? `${file}:${phase.name}` : file;
+        if ((await client.query("SELECT 1 FROM schema_migrations WHERE name = $1", [key])).rowCount !== 0) continue;
+        try {
+          if (phase.mode === "concurrent") {
+            await concurrentIndex(client, phase.sql);
+            await client.query("INSERT INTO schema_migrations(name) VALUES ($1)", [key]);
+          } else {
+            for (;;) {
+              await client.query("BEGIN");
+              const result = await client.query(phase.sql);
+              if (phase.mode === "batch" && (result.rowCount ?? 0) > 0) { await client.query("COMMIT"); continue; }
+              await client.query("INSERT INTO schema_migrations(name) VALUES ($1)", [key]);
+              await client.query("COMMIT");
+              break;
+            }
+          }
+        } catch (error) {
+          await client.query("ROLLBACK").catch(() => undefined);
+          throw new Error(`migration ${key} failed`, { cause: error });
+        }
+      }
+      await client.query("INSERT INTO schema_migrations(name) VALUES ($1) ON CONFLICT DO NOTHING", [file]);
+      applied.push(file);
+    }
+  } finally {
+    await client.query("SELECT pg_advisory_unlock(193674839, 3)").catch(() => undefined);
+    client.release();
+    await pool.end();
+  }
+  return applied;
+}
diff --git a/apps/api/src/db/production-schema.integration.test.ts b/apps/api/src/db/production-schema.integration.test.ts
new file mode 100644
index 0000000..ee148d0
--- /dev/null
+++ b/apps/api/src/db/production-schema.integration.test.ts
@@ -0,0 +1,326 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "./migrate.js";
+
+/**
+ * Migration 013 (streaming S1) against a live PostgreSQL: the same-channel
+ * invariant fails at the DB constraint, the production CHECKs hold, and FORCE
+ * RLS denies every new table across tenants. Assertions run as sp_app
+ * (DATABASE_URL); setup/cleanup as owner. Skipped without DATABASE_URL.
+ */
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+const appPool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const FK_VIOLATION = "23503";
+const UNIQUE_VIOLATION = "23505";
+const CHECK_VIOLATION = "23514";
+const RLS_VIOLATION = "42501";
+const ASSET = "a".repeat(64);
+
+async function asTenant<T>(workspaceId: string | null, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await appPool.connect();
+  try {
+    await client.query("BEGIN");
+    if (workspaceId !== null) await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+async function one(client: PoolClient, sql: string, params: unknown[]): Promise<string> {
+  const result = await client.query(sql, params);
+  return String(result.rows[0]?.id);
+}
+
+interface Channel { id: string; hls: string; playlist: string; scene: string; spare: string; slot: string; overlay: string; revision: string }
+
+async function seedChannel(client: PoolClient, ws: string, assetId: string): Promise<Channel> {
+  const id = await one(client, "INSERT INTO virtual_channels (workspace_id, slug, name) VALUES ($1, $2, 'Channel') RETURNING id", [ws, `ch-${randomUUID().slice(0, 8)}`]);
+  const hls = await one(client,
+    "INSERT INTO virtual_channel_sources (workspace_id, virtual_channel_id, kind, label, remote_ref, hls_url) VALUES ($1, $2, 'hls', 'Cam 1', $3, 'https://cdn.example.com/a.m3u8') RETURNING id",
+    [ws, id, `ref-${randomUUID()}`]);
+  const playlist = await one(client,
+    "INSERT INTO virtual_channel_sources (workspace_id, virtual_channel_id, kind, label, playlist_loop) VALUES ($1, $2, 'playlist', 'Fallback reel', true) RETURNING id",
+    [ws, id]);
+  await client.query("INSERT INTO playlist_items (workspace_id, virtual_channel_id, source_id, position, video_asset_id) VALUES ($1, $2, $3, 0, $4)", [ws, id, playlist, assetId]);
+  const scene = await one(client, "INSERT INTO production_scenes (workspace_id, virtual_channel_id, label, layout) VALUES ($1, $2, 'Main', '2x2') RETURNING id", [ws, id]);
+  const spare = await one(client, "INSERT INTO production_scenes (workspace_id, virtual_channel_id, label, layout) VALUES ($1, $2, 'Spare', 'single') RETURNING id", [ws, id]);
+  const slot = await one(client,
+    "INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index, source_id, audio_mode, gain_db) VALUES ($1, $2, $3, 0, $4, 'primary', -6) RETURNING id",
+    [ws, id, scene, hls]);
+  await client.query("INSERT INTO production_buses (workspace_id, virtual_channel_id, bus, scene_id) VALUES ($1, $2, 'program', $3), ($1, $2, 'preview', $3)", [ws, id, scene]);
+  const overlay = await one(client, "INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind) VALUES ($1, $2, $3, 'lower_third') RETURNING id", [ws, id, scene]);
+  const revision = await one(client,
+    "INSERT INTO overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, template_id, render_state, asset_id) VALUES ($1, $2, $3, 'lower-third-v1', 'rendered', $4) RETURNING id",
+    [ws, id, overlay, ASSET]);
+  await client.query("UPDATE overlay_slots SET current_revision_id = $2 WHERE id = $1", [overlay, revision]);
+  return { id, hls, playlist, scene, spare, slot, overlay, revision };
+}
+
+describe.skipIf(!dbAvailable)("production schema 013 (live DB)", () => {
+  let wsA: string;
+  let wsB: string;
+  let assetA: string;
+  let assetB: string;
+  let a1: Channel;
+  let a2: Channel;
+  let b1: Channel;
+
+  beforeAll(async () => {
+    await runMigrations(process.env.MIGRATIONS_DIR ?? join(process.cwd(), "migrations"));
+    const insert = "INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id";
+    wsA = String((await ownerPool.query(insert, ["Prod A", `prod-a-${randomUUID()}`])).rows[0]?.id);
+    wsB = String((await ownerPool.query(insert, ["Prod B", `prod-b-${randomUUID()}`])).rows[0]?.id);
+    const asset = "INSERT INTO video_assets (workspace_id, storage_key, mime_type, size_bytes) VALUES ($1, 'sha256/x.mp4', 'video/mp4', 1) RETURNING id";
+    assetA = await asTenant(wsA, (c) => one(c, asset, [wsA]));
+    assetB = await asTenant(wsB, (c) => one(c, asset, [wsB]));
+    a1 = await asTenant(wsA, (c) => seedChannel(c, wsA, assetA));
+    a2 = await asTenant(wsA, (c) => seedChannel(c, wsA, assetA));
+    b1 = await asTenant(wsB, (c) => seedChannel(c, wsB, assetB));
+  });
+
+  afterAll(async () => {
+    if (wsA !== undefined && wsB !== undefined) await ownerPool.query("DELETE FROM workspaces WHERE id IN ($1, $2)", [wsA, wsB]);
+    await appPool.end();
+    await ownerPool.end();
+  });
+
+  describe("same-channel invariant fails at the DB constraint", () => {
+    it("a slot cannot reference another channel's source (same workspace)", async () => {
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index, source_id) VALUES ($1, $2, $3, 1, $4)",
+        [wsA, a1.id, a1.scene, a2.hls]))).rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+
+    it("a slot cannot claim another channel to smuggle a foreign scene or source", async () => {
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index, source_id) VALUES ($1, $2, $3, 1, $4)",
+        [wsA, a2.id, a1.scene, a2.hls]))).rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+
+    it("a slot cannot be re-pointed to any source in place, nor moved to another scene", async () => {
+      await expect(asTenant(wsA, (c) => c.query("UPDATE scene_slots SET source_id = $2 WHERE id = $1", [a1.slot, a2.hls])))
+        .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query("UPDATE scene_slots SET source_id = $2 WHERE id = $1", [a1.slot, a1.playlist])))
+        .rejects.toThrow(/source_id is immutable/);
+      await expect(asTenant(wsA, (c) => c.query("UPDATE scene_slots SET scene_id = $2 WHERE id = $1", [a1.slot, a1.spare])))
+        .rejects.toThrow(/scene_id is immutable/);
+    });
+
+    it("a bus cannot hold another channel's scene, by insert or by TAKE-style update", async () => {
+      await expect(asTenant(wsA, (c) => c.query("UPDATE production_buses SET scene_id = $2 WHERE virtual_channel_id = $1 AND bus = 'program'", [a1.id, a2.scene])))
+        .rejects.toMatchObject({ code: FK_VIOLATION });
+      const moved = await asTenant(wsA, (c) => c.query("UPDATE production_buses SET scene_id = $2 WHERE virtual_channel_id = $1 AND bus = 'preview'", [a1.id, a1.spare]));
+      expect(moved.rowCount).toBe(1);
+    });
+
+    it("overlay slots and revisions stay inside their channel", async () => {
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind) VALUES ($1, $2, $3, 'logo')",
+        [wsA, a1.id, a2.scene]))).rejects.toMatchObject({ code: FK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, template_id) VALUES ($1, $2, $3, 'logo')",
+        [wsA, a1.id, a2.overlay]))).rejects.toMatchObject({ code: FK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query("UPDATE overlay_slots SET current_revision_id = $2 WHERE id = $1", [a1.overlay, a2.revision])))
+        .rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+
+    it("a playlist item cannot name another channel's source or another tenant's asset", async () => {
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO playlist_items (workspace_id, virtual_channel_id, source_id, position, video_asset_id) VALUES ($1, $2, $3, 1, $4)",
+        [wsA, a1.id, a2.playlist, assetA]))).rejects.toMatchObject({ code: FK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO playlist_items (workspace_id, virtual_channel_id, source_id, position, video_asset_id) VALUES ($1, $2, $3, 1, $4)",
+        [wsA, a1.id, a1.playlist, assetB]))).rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+  });
+
+  describe("production constraints", () => {
+    it("allows at most one primary audio slot per scene", async () => {
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index, source_id, audio_mode) VALUES ($1, $2, $3, 1, $4, 'primary')",
+        [wsA, a1.id, a1.scene, a1.playlist]))).rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+      await asTenant(wsA, (c) => c.query(
+        "INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index, source_id, audio_mode) VALUES ($1, $2, $3, 0, $4, 'primary'), ($1, $2, $5, 1, $4, 'on')",
+        [wsA, a1.id, a1.spare, a1.playlist, a1.scene]));
+    });
+
+    it("gain_db is -24..0 in 3 dB steps", async () => {
+      for (const bad of [-4, 3, -27, -1]) {
+        await expect(asTenant(wsA, (c) => c.query("UPDATE scene_slots SET gain_db = $2 WHERE id = $1", [a1.slot, bad])))
+          .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      }
+      for (const good of [-24, -3, 0]) await asTenant(wsA, (c) => c.query("UPDATE scene_slots SET gain_db = $2 WHERE id = $1", [a1.slot, good]));
+    });
+
+    it("geometry is all-or-nothing, positive, and inside the frame", async () => {
+      const set = (sql: string) => asTenant(wsA, (c) => c.query(`UPDATE scene_slots SET ${sql} WHERE id = $1`, [a1.slot]));
+      await expect(set("x = 0, y = 0, w = 100")).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(set("x = 0, y = 0, w = 0, h = 100")).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(set("x = -1, y = 0, w = 100, h = 100")).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(set("x = 9000, y = 0, w = 2000, h = 100")).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await set("x = 7000, y = 7000, w = 3000, h = 3000");
+    });
+
+    it("layouts, buses and source kinds are closed enums; playlist is a source kind", async () => {
+      await expect(asTenant(wsA, (c) => c.query("UPDATE production_scenes SET layout = '5x5' WHERE id = $1", [a1.spare])))
+        .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO production_buses (workspace_id, virtual_channel_id, bus) VALUES ($1, $2, 'aux')", [wsA, a1.id])))
+        .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO production_buses (workspace_id, virtual_channel_id, bus) VALUES ($1, $2, 'program')", [wsA, a1.id])))
+        .rejects.toMatchObject({ code: UNIQUE_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO virtual_channel_sources (workspace_id, virtual_channel_id, kind, label, hls_url) VALUES ($1, $2, 'rtmp', 'X', 'https://a.example/x')",
+        [wsA, a1.id]))).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      const kinds = await asTenant(wsA, (c) => c.query("SELECT kind FROM virtual_channel_sources WHERE virtual_channel_id = $1 ORDER BY kind", [a1.id]));
+      expect(kinds.rows.map((r: { kind: string }) => r.kind)).toEqual(["hls", "playlist"]);
+    });
+
+    it("labels with filtergraph metacharacters are rejected by the schema too", async () => {
+      for (const label of ["a;b", "x[0]", "a,b", "it's", "movie=/etc/passwd"]) {
+        await expect(asTenant(wsA, (c) => c.query("UPDATE production_scenes SET label = $2 WHERE id = $1", [a1.spare, label])))
+          .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      }
+    });
+
+    it("overlay kinds carry exactly their own parameters; rendered revisions carry a sha256 asset", async () => {
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind) VALUES ($1, $2, $3, 'chyron')", [wsA, a1.id, a1.scene])))
+        .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind, chyron_speed_px_s, chyron_strip_width_px) VALUES ($1, $2, $3, 'chyron', 401, 100)",
+        [wsA, a1.id, a1.scene]))).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind, chyron_speed_px_s, chyron_strip_width_px) VALUES ($1, $2, $3, 'chyron', 120, 16384)",
+        [wsA, a1.id, a1.scene]));
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind) VALUES ($1, $2, $3, 'clock')", [wsA, a1.id, a1.scene])))
+        .rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, template_id, render_state, asset_id) VALUES ($1, $2, $3, 'lt', 'rendered', 'movie=x')",
+        [wsA, a1.id, a1.overlay]))).rejects.toMatchObject({ code: CHECK_VIOLATION });
+      await expect(asTenant(wsA, (c) => c.query(
+        "INSERT INTO overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, template_id, render_state) VALUES ($1, $2, $3, 'lt', 'rendered')",
+        [wsA, a1.id, a1.overlay]))).rejects.toMatchObject({ code: CHECK_VIOLATION });
+    });
+  });
+
+  describe("lifecycle", () => {
+    it("deleting a source empties its slots (SET NULL keeps tenant + channel); a scene on a bus cannot be deleted", async () => {
+      const channel = await asTenant(wsA, (c) => seedChannel(c, wsA, assetA));
+      await asTenant(wsA, (c) => c.query("DELETE FROM virtual_channel_sources WHERE id = $1", [channel.hls]));
+      const slot = await asTenant(wsA, (c) => c.query("SELECT workspace_id, virtual_channel_id, source_id FROM scene_slots WHERE id = $1", [channel.slot]));
+      expect(slot.rows[0]).toEqual({ workspace_id: wsA, virtual_channel_id: channel.id, source_id: null });
+      await expect(asTenant(wsA, (c) => c.query("DELETE FROM production_scenes WHERE id = $1", [channel.scene])))
+        .rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+
+    it("deleting a rendered revision clears the slot's current revision; deleting a channel cascades everything", async () => {
+      const channel = await asTenant(wsA, (c) => seedChannel(c, wsA, assetA));
+      await asTenant(wsA, (c) => c.query("DELETE FROM overlay_revisions WHERE id = $1", [channel.revision]));
+      const overlay = await asTenant(wsA, (c) => c.query("SELECT current_revision_id FROM overlay_slots WHERE id = $1", [channel.overlay]));
+      expect(overlay.rows[0]?.current_revision_id).toBeNull();
+      await asTenant(wsA, (c) => c.query("DELETE FROM virtual_channels WHERE id = $1", [channel.id]));
+      const left = await asTenant(wsA, (c) => c.query(
+        `SELECT (SELECT count(*) FROM virtual_channel_sources WHERE virtual_channel_id = $1)
+              + (SELECT count(*) FROM production_scenes WHERE virtual_channel_id = $1)
+              + (SELECT count(*) FROM scene_slots WHERE virtual_channel_id = $1)
+              + (SELECT count(*) FROM production_buses WHERE virtual_channel_id = $1)
+              + (SELECT count(*) FROM overlay_slots WHERE virtual_channel_id = $1)
+              + (SELECT count(*) FROM overlay_revisions WHERE virtual_channel_id = $1)
+              + (SELECT count(*) FROM playlist_items WHERE virtual_channel_id = $1) AS n`, [channel.id]));
+      expect(Number(left.rows[0]?.n)).toBe(0);
+    });
+
+    it("a playlisted video asset cannot be deleted directly, but a workspace purge removes everything", async () => {
+      await expect(asTenant(wsA, (c) => c.query("DELETE FROM video_assets WHERE id = $1", [assetA])))
+        .rejects.toMatchObject({ code: FK_VIOLATION });
+      const ws = String((await ownerPool.query("INSERT INTO workspaces (name, slug) VALUES ('Purge', $1) RETURNING id", [`purge-${randomUUID()}`])).rows[0]?.id);
+      const asset = await asTenant(ws, (c) => one(c,
+        "INSERT INTO video_assets (workspace_id, storage_key, mime_type, size_bytes) VALUES ($1, 'sha256/p.mp4', 'video/mp4', 1) RETURNING id", [ws]));
+      await asTenant(ws, (c) => seedChannel(c, ws, asset));
+      await ownerPool.query("DELETE FROM workspaces WHERE id = $1", [ws]);
+      const left = await ownerPool.query(
+        `SELECT (SELECT count(*) FROM virtual_channels WHERE workspace_id = $1)
+              + (SELECT count(*) FROM playlist_items WHERE workspace_id = $1)
+              + (SELECT count(*) FROM production_buses WHERE workspace_id = $1)
+              + (SELECT count(*) FROM overlay_revisions WHERE workspace_id = $1) AS n`, [ws]);
+      expect(Number(left.rows[0]?.n)).toBe(0);
+    });
+
+    it("workspace and channel ownership columns are immutable", async () => {
+      await expect(asTenant(wsA, (c) => c.query("UPDATE production_scenes SET virtual_channel_id = $2 WHERE id = $1", [a1.spare, a2.id])))
+        .rejects.toThrow(/immutable/);
+      await expect(asTenant(wsA, (c) => c.query("UPDATE production_buses SET bus = 'preview' WHERE virtual_channel_id = $1 AND bus = 'program'", [a1.id])))
+        .rejects.toThrow(/bus is immutable/);
+      await expect(asTenant(wsA, (c) => c.query("UPDATE virtual_channels SET workspace_id = $2 WHERE id = $1", [a1.id, wsB])))
+        .rejects.toThrow(/immutable|row-level security/);
+    });
+  });
+
+  describe("RLS denial suite (FORCE, NULLIF tenant isolation)", () => {
+    const tables = [
+      "virtual_channels", "virtual_channel_sources", "playlist_items", "production_scenes",
+      "scene_slots", "production_buses", "overlay_slots", "overlay_revisions",
+    ] as const;
+
+    it.each(tables)("%s has RLS enabled and forced", async (table) => {
+      const flags = await ownerPool.query("SELECT relrowsecurity, relforcerowsecurity FROM pg_class WHERE oid = $1::regclass", [table]);
+      expect(flags.rows[0]).toEqual({ relrowsecurity: true, relforcerowsecurity: true });
+    });
+
+    it.each(tables)("%s: tenant B sees, updates and deletes none of A's rows", async (table) => {
+      const seen = await asTenant(wsB, (c) => c.query(`SELECT count(*)::int AS n FROM ${table} WHERE workspace_id = $1`, [wsA]));
+      expect(seen.rows[0]?.n).toBe(0);
+      const updated = await asTenant(wsB, (c) => c.query(`UPDATE ${table} SET updated_at = now() WHERE workspace_id = $1`, [wsA]));
+      expect(updated.rowCount).toBe(0);
+      const deleted = await asTenant(wsB, (c) => c.query(`DELETE FROM ${table} WHERE workspace_id = $1`, [wsA]));
+      expect(deleted.rowCount).toBe(0);
+      const ownStillThere = await asTenant(wsA, (c) => c.query(`SELECT count(*)::int AS n FROM ${table}`));
+      expect(ownStillThere.rows[0]?.n).toBeGreaterThan(0);
+    });
+
+    it.each(tables)("%s: no tenant context (and an empty one) sees nothing", async (table) => {
+      const none = await asTenant(null, (c) => c.query(`SELECT count(*)::int AS n FROM ${table}`));
+      expect(none.rows[0]?.n).toBe(0);
+      const empty = await asTenant("", (c) => c.query(`SELECT count(*)::int AS n FROM ${table}`));
+      expect(empty.rows[0]?.n).toBe(0);
+    });
+
+    it("tenant B cannot write rows into A's workspace (WITH CHECK) on any table", async () => {
+      const attempts: Array<[string, unknown[]]> = [
+        ["INSERT INTO virtual_channels (workspace_id, slug, name) VALUES ($1, 'x-rls', 'X')", [wsA]],
+        ["INSERT INTO virtual_channel_sources (workspace_id, virtual_channel_id, kind, label, playlist_loop) VALUES ($1, $2, 'playlist', 'X', false)", [wsA, a1.id]],
+        ["INSERT INTO playlist_items (workspace_id, virtual_channel_id, source_id, position, video_asset_id) VALUES ($1, $2, $3, 9, $4)", [wsA, a1.id, a1.playlist, assetA]],
+        ["INSERT INTO production_scenes (workspace_id, virtual_channel_id, label, layout) VALUES ($1, $2, 'X', 'single')", [wsA, a1.id]],
+        ["INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index) VALUES ($1, $2, $3, 3)", [wsA, a1.id, a1.scene]],
+        ["INSERT INTO production_buses (workspace_id, virtual_channel_id, bus) VALUES ($1, $2, 'program')", [wsA, a1.id]],
+        ["INSERT INTO overlay_slots (workspace_id, virtual_channel_id, scene_id, kind) VALUES ($1, $2, $3, 'logo')", [wsA, a1.id, a1.scene]],
+        ["INSERT INTO overlay_revisions (workspace_id, virtual_channel_id, overlay_slot_id, template_id) VALUES ($1, $2, $3, 'lt')", [wsA, a1.id, a1.overlay]],
+      ];
+      for (const [sql, params] of attempts) {
+        await expect(asTenant(wsB, (c) => c.query(sql, params)), sql).rejects.toMatchObject({ code: RLS_VIOLATION });
+      }
+    });
+
+    it("tenant B cannot point its own rows at A's channel, scene or source", async () => {
+      await expect(asTenant(wsB, (c) => c.query(
+        "INSERT INTO scene_slots (workspace_id, virtual_channel_id, scene_id, slot_index, source_id) VALUES ($1, $2, $3, 2, $4)",
+        [wsB, b1.id, b1.scene, a1.hls]))).rejects.toMatchObject({ code: FK_VIOLATION });
+      await expect(asTenant(wsB, (c) => c.query(
+        "UPDATE production_buses SET scene_id = $2 WHERE virtual_channel_id = $1 AND bus = 'program'", [b1.id, a1.scene])))
+        .rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+  });
+});
diff --git a/apps/api/src/db/publishing-migration.integration.test.ts b/apps/api/src/db/publishing-migration.integration.test.ts
new file mode 100644
index 0000000..94a5890
--- /dev/null
+++ b/apps/api/src/db/publishing-migration.integration.test.ts
@@ -0,0 +1,68 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { mkdtemp, readdir, readFile, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Pool } from "pg";
+import { runMigrations } from "./migrate.js";
+import { assertPublishingSchema } from "@tactical-media-broadcast-hub/publishing-execution";
+const ownerUrl = process.env.PUBLISHING_IT_SUPER_DATABASE_URL;
+const appUrl = process.env.PUBLISHING_IT_DATABASE_URL;
+describe.skipIf(!ownerUrl || !appUrl)("publishing migration upgrade and resumability (local DB)", () => {
+  let admin: Pool; let owner: Pool; let app: Pool; let dir: string;
+  let database: string; let previousOwner: string | undefined;
+  beforeAll(async () => {
+    const url = new URL(ownerUrl!); url.pathname = "/postgres";
+    admin = new Pool({ connectionString: url.toString() });
+    database = `wp3_migration_sol_${Date.now()}`;
+    await admin.query(`CREATE DATABASE ${database}`);
+    url.pathname = `/${database}`; previousOwner = process.env.SUPER_DATABASE_URL;
+    process.env.SUPER_DATABASE_URL = url.toString(); owner = new Pool({ connectionString: url.toString() });
+    const runtimeUrl = new URL(appUrl!); runtimeUrl.pathname = `/${database}`; app = new Pool({ connectionString: runtimeUrl.toString() });
+    dir = await mkdtemp(join(tmpdir(), "wp3-migrations-sol-"));
+    for (const file of (await readdir("migrations")).filter((name) => name.endsWith(".sql") && name < "018")) await writeFile(join(dir, file), await readFile(join("migrations", file)));
+    await runMigrations(dir);
+  }, 30_000);
+  afterAll(async () => {
+    if (previousOwner === undefined) delete process.env.SUPER_DATABASE_URL; else process.env.SUPER_DATABASE_URL = previousOwner;
+    await owner?.end(); await app?.end();
+    if (admin && database) await admin.query(`DROP DATABASE ${database}`);
+    await admin?.end();
+  });
+  it("upgrades legacy schedules without inventing authorization and resumes 019 after failed cutover", async () => {
+    const user = (await owner.query("INSERT INTO users(external_id, username, display_name) VALUES('migration-sol', 'migration-sol', 'Migration') RETURNING id")).rows[0].id as string;
+    const workspace = (await owner.query("INSERT INTO workspaces(name,slug) VALUES('Migration','migration-sol') RETURNING id")).rows[0].id as string;
+    const connection = (await owner.query("INSERT INTO connections(workspace_id,provider,channel_id) VALUES($1,'mastodon','channel') RETURNING id", [workspace])).rows[0].id as string;
+    const keys = ["legacy-pending", "legacy-flight", "legacy-done"];
+    for (const [index, key] of keys.entries()) {
+      const draft = (await owner.query("INSERT INTO drafts(workspace_id,author_user_id,post,state) VALUES($1,$2,'{}','scheduled') RETURNING id", [workspace, user])).rows[0].id as string;
+      await owner.query("INSERT INTO scheduled_publications(workspace_id,draft_id,connection_id,publish_at,idempotency_key,state) VALUES($1,$2,$3,now(),$4,$5)", [workspace, draft, connection, key, index === 1 ? "in_flight" : "pending"]);
+      if (index === 2) await owner.query("INSERT INTO publications(workspace_id,draft_id,connection_id,idempotency_key,remote_id,published_at) VALUES($1,$2,$3,$4,'remote',now())", [workspace, draft, connection, key]);
+    }
+    await writeFile(join(dir, "018_publishing_execution.sql"), await readFile("migrations/018_publishing_execution.sql"));
+    await runMigrations(dir);
+    const upgraded = await owner.query("SELECT state, scheduled_by_user_id, execution_version FROM scheduled_publications ORDER BY idempotency_key");
+    expect(upgraded.rows.map((row) => row.state)).toEqual(["done", "failed", "needs_reauthorization"]);
+    expect(upgraded.rows.every((row) => row.scheduled_by_user_id === null && row.execution_version === 0)).toBe(true);
+    const original = await readFile("migrations/019_publishing_integration.sql", "utf8");
+    await writeFile(join(dir, "019_publishing_integration.sql"), original.replace("DROP FUNCTION publishing_due_schedules(integer);", "SELECT nonexistent_cutover_function();"));
+    await expect(runMigrations(dir)).rejects.toThrow("cutover failed");
+    expect((await owner.query("SELECT name FROM schema_migrations WHERE name = '019_publishing_integration.sql'")).rowCount).toBe(0);
+    await expect(assertPublishingSchema(app)).rejects.toThrow();
+    expect((await owner.query("SELECT name FROM schema_migrations WHERE name LIKE '019%:%'")).rowCount).toBe(3);
+    await writeFile(join(dir, "019_publishing_integration.sql"), original);
+    await expect(runMigrations(dir)).resolves.toEqual(["019_publishing_integration.sql"]);
+    await expect(assertPublishingSchema(app)).resolves.toBeUndefined();
+    await expect(runMigrations(dir)).resolves.toEqual([]);
+    const role = (await app.query("SELECT current_user, rolsuper, rolbypassrls FROM pg_roles WHERE rolname = current_user")).rows[0];
+    expect(role).toEqual({ current_user: "sp_app", rolsuper: false, rolbypassrls: false });
+  }, 30_000);
+  it("repairs an invalid concurrent index only when its definition matches", async () => {
+    const file = "020_test_concurrent.sql";
+    await writeFile(join(dir, file), "-- wp3:phase expand transaction\nCREATE TABLE migration_index_test(v integer); INSERT INTO migration_index_test VALUES(1),(1);\n-- wp3:phase idx concurrent\nCREATE UNIQUE INDEX CONCURRENTLY migration_index_test_idx ON migration_index_test (v);");
+    await expect(runMigrations(dir)).rejects.toThrow("idx failed");
+    expect((await owner.query("SELECT indisvalid FROM pg_index WHERE indexrelid = 'migration_index_test_idx'::regclass")).rows[0]?.indisvalid).toBe(false);
+    await owner.query("DELETE FROM migration_index_test WHERE ctid NOT IN (SELECT min(ctid) FROM migration_index_test GROUP BY v)");
+    await expect(runMigrations(dir)).resolves.toEqual([file]);
+    expect((await owner.query("SELECT indisvalid FROM pg_index WHERE indexrelid = 'migration_index_test_idx'::regclass")).rows[0]?.indisvalid).toBe(true);
+  }, 30_000);
+});
diff --git a/apps/api/src/db/tenancy.integration.test.ts b/apps/api/src/db/tenancy.integration.test.ts
new file mode 100644
index 0000000..fd0e020
--- /dev/null
+++ b/apps/api/src/db/tenancy.integration.test.ts
@@ -0,0 +1,176 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool } from "pg";
+import { pool, withTenant, withSystem } from "./client.js";
+import { runMigrations } from "./migrate.js";
+import { PublishingExecutionRepository } from "@tactical-media-broadcast-hub/publishing-execution";
+
+/**
+ * Audit-finding acceptance tests against a live PostgreSQL.
+ * Migrations + cleanup run via the owner pool (SUPER_DATABASE_URL);
+ * the assertions run as sp_app so FORCE RLS binds honestly.
+ * Skipped without DATABASE_URL.
+ */
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+
+async function asOwner<T>(fn: (client: import("pg").PoolClient) => Promise<T>): Promise<T> {
+  const client = await ownerPool.connect();
+  try {
+    return await fn(client);
+  } finally {
+    client.release();
+  }
+}
+
+describe.skipIf(!dbAvailable)("tenancy + audit chain (live DB)", () => {
+  let wsA: string;
+  let wsB: string;
+
+  beforeAll(async () => {
+    await runMigrations(process.env.MIGRATIONS_DIR ?? join(process.cwd(), "migrations"));
+    await asOwner(async (client) => {
+      await client.query("DELETE FROM audit_log");
+      await client.query("DELETE FROM memberships");
+      await client.query("DELETE FROM connections");
+      await client.query("DELETE FROM credentials");
+      await client.query("DELETE FROM workspaces");
+      const a = await client.query("INSERT INTO workspaces (name, slug) VALUES ('A', $1) RETURNING id", [`a-${Date.now()}`]);
+      const b = await client.query("INSERT INTO workspaces (name, slug) VALUES ('B', $1) RETURNING id", [`b-${Date.now()}`]);
+      wsA = a.rows[0].id as string;
+      wsB = b.rows[0].id as string;
+    });
+  });
+
+  afterAll(async () => {
+    await asOwner(async (client) => {
+      await client.query("DELETE FROM workspaces WHERE id IN ($1, $2)", [wsA, wsB]);
+    });
+    await pool.end();
+    await ownerPool.end();
+  });
+
+  it("RLS isolates tenants: A sees only A's connections (FORCE applies to owner)", async () => {
+    await withTenant(wsA, async (client) => {
+      await client.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', 'ch-a')", [wsA]);
+    });
+    await withTenant(wsB, async (client) => {
+      await client.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', 'ch-b')", [wsB]);
+    });
+    const seenFromA = await withTenant(wsA, async (client) => {
+      return (await client.query("SELECT channel_id FROM connections")).rows.map((r) => r.channel_id);
+    });
+    expect(seenFromA).toEqual(["ch-a"]);
+    const seenFromSystem = await withSystem(async (client) => {
+      return (await client.query("SELECT count(*)::int AS n FROM connections")).rows[0]?.n;
+    });
+    expect(seenFromSystem).toBe(0);
+  });
+
+  it("SECURITY DEFINER tenant assertion: cross-tenant call rejected (finding #3)", async () => {
+    await expect(
+      withTenant(wsB, async (client) => {
+        await client.query("SELECT audit_append($1, NULL, 'system', 'x', 'y', 'z', NULL)", [wsA]);
+      }),
+    ).rejects.toThrow(/tenant context mismatch/);
+  });
+
+  it("audit branch: tenant context => tenant chain even for service callers (findings #1/#6)", async () => {
+    await withTenant(wsA, async (client) => {
+      const r = await client.query("SELECT audit_append($1, NULL, 'sp_scheduler', 'job.ran', 'job', 'j1', NULL) AS id", [wsA]);
+      expect(r.rows[0]?.id).toBeTruthy();
+      const row = await client.query("SELECT workspace_id, actor_role FROM audit_log WHERE id = $1", [r.rows[0].id]);
+      expect(row.rows[0]?.workspace_id).toBe(wsA);
+      expect(row.rows[0]?.actor_role).toBe("sp_scheduler");
+      // system append inside tenant context must be refused
+      await expect(client.query("SELECT audit_append_system(NULL, 'x', 'y', 'z', NULL)")).rejects.toThrow();
+    });
+  });
+
+  it("membership change bumps authz_epoch => sessions fail closed (finding #2)", async () => {
+    const before = Number(await withSystem(async (c) => (await c.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [wsA])).rows[0]?.authz_epoch));
+    await asOwner(async (c) => {
+      const u = await c.query("INSERT INTO users (external_id, email, display_name) VALUES ($1, 'e@x', 'E') RETURNING id", [`ext-${Date.now()}`]);
+      await withTenant(wsA, async (tenantClient) => {
+        await tenantClient.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Publisher')", [wsA, u.rows[0].id]);
+      });
+    });
+    const after = Number(await withSystem(async (c) => (await c.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [wsA])).rows[0]?.authz_epoch));
+    expect(after).toBeGreaterThan(before);
+  });
+
+  it("hash chain detects tampering", async () => {
+    await withTenant(wsA, async (client) => {
+      await client.query("SELECT audit_append($1, NULL, 'system', 't.1', 't', '1', NULL)", [wsA]);
+      await client.query("SELECT audit_append($1, NULL, 'system', 't.2', 't', '2', NULL)", [wsA]);
+    });
+    const ok = await withTenant(wsA, async (c) => (await c.query("SELECT audit_verify_chain($1) AS ok", [wsA])).rows[0]?.ok);
+    expect(ok).toBe(true);
+    // direct tamper (as owner, inside the tenant context, bypassing the append fn)
+    await withTenant(wsA, async (c) => {
+      await c.query("UPDATE audit_log SET action = 'forged' WHERE action = 't.1'");
+    });
+    const broken = await withTenant(wsA, async (c) => (await c.query("SELECT audit_verify_chain($1) AS ok", [wsA])).rows[0]?.ok);
+    expect(broken).toBe(false);
+  });
+
+  it("verifies a legacy v1 row followed by v2 and detects a changed v2 diff", async () => {
+    await withTenant(wsB, async (client) => {
+      await client.query(
+        `WITH stamp AS MATERIALIZED (SELECT clock_timestamp() AS at)
+         INSERT INTO audit_log (workspace_id, action, target_type, target_id, diff, at, prev_hash, hash, hash_version)
+         SELECT $1, 'legacy', 'test', 'legacy', '{"value":1}'::jsonb, stamp.at, NULL,
+                audit_hash(NULL, NULL, 'legacy', 'legacy', stamp.at), 1 FROM stamp`,
+        [wsB],
+      );
+      await client.query("SELECT audit_append($1, NULL, 'system', 'modern', 'test', 'modern', $2)", [wsB, { value: 2 }]);
+      const verified = await client.query("SELECT audit_verify_chain($1) AS ok", [wsB]);
+      expect(verified.rows[0]?.ok).toBe(true);
+      await client.query("UPDATE audit_log SET diff = $2 WHERE workspace_id = $1 AND action = 'modern'", [wsB, { value: 3 }]);
+      const broken = await client.query("SELECT audit_verify_chain($1) AS ok", [wsB]);
+      expect(broken.rows[0]?.ok).toBe(false);
+    });
+  });
+
+  it("scheduler claim refuses a pending schedule whose draft is not approved", async () => {
+    const repository = new PublishingExecutionRepository(pool);
+    try {
+      const user = await asOwner(async (client) => {
+        const inserted = await client.query(
+          "INSERT INTO users (external_id, email, display_name) VALUES ($1, 'claim@example.com', 'Claim') RETURNING id",
+          [`claim-${Date.now()}`],
+        );
+        return inserted.rows[0]?.id as string;
+      });
+      const key = `claim-${Date.now()}`;
+      await withTenant(wsA, async (client) => {
+        const connection = await client.query(
+          "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', 'claim') RETURNING id",
+          [wsA],
+        );
+        const draft = await client.query(
+          "INSERT INTO drafts (workspace_id, author_user_id, post, state) VALUES ($1, $2, $3, 'in_review') RETURNING id",
+          [wsA, user, { text: "unapproved", mediaAssetIds: [], visibility: "public", providerMetadata: {} }],
+        );
+        await client.query(
+          "INSERT INTO scheduled_publications (workspace_id, draft_id, connection_id, publish_at, idempotency_key) VALUES ($1, $2, $3, now(), $4)",
+          [wsA, draft.rows[0]?.id, connection.rows[0]?.id, key],
+        );
+      });
+      const schedule = await withTenant(wsA, (client) => client.query("SELECT id, generation FROM scheduled_publications WHERE idempotency_key = $1", [key]));
+      await expect(repository.claim({ workspaceId: wsA, scheduleId: String(schedule.rows[0]?.id), generation: String(schedule.rows[0]?.generation), idempotencyKey: key })).resolves.toMatchObject({ kind: "failed", code: "EXECUTION_FENCE_MISSING" });
+      const state = await withTenant(wsA, (client) => client.query("SELECT state FROM scheduled_publications WHERE idempotency_key = $1", [key]));
+      expect(state.rows[0]?.state).toBe("pending");
+    } finally {
+      // The shared repository uses the caller-owned pool, closed by suite cleanup.
+    }
+  });
+
+  it("workspace_id is immutable on tenant rows (finding #8)", async () => {
+    await expect(
+      withTenant(wsA, async (c) => {
+        await c.query("UPDATE connections SET workspace_id = $1 WHERE channel_id = 'ch-a'", [wsB]);
+      }),
+    ).rejects.toThrow(/workspace_id is immutable/);
+  });
+});
diff --git a/apps/api/src/demo/demo.controller.ts b/apps/api/src/demo/demo.controller.ts
new file mode 100644
index 0000000..f55bcae
--- /dev/null
+++ b/apps/api/src/demo/demo.controller.ts
@@ -0,0 +1,57 @@
+import { Controller, Get, Post, Body, Req, UseGuards } from "@nestjs/common";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { withTenant } from "../db/client.js";
+import type { Request } from "express";
+
+@Controller("demo")
+@UseGuards(RbacGuard)
+export class DemoController {
+  @Get("health-audit")
+  @RequirePermission("audit.view")
+  async viewAudit(@Req() req: Request & AuthenticatedRequest): Promise<{ workspaceId: string }> {
+    return { workspaceId: req.session?.workspaceId ?? "none" };
+  }
+
+  @Post("connections")
+  @RequirePermission("connection.manage")
+  async addConnection(
+    @Req() req: Request & AuthenticatedRequest,
+    @Body() body: { provider: string; channelId: string },
+  ): Promise<{ id: string }> {
+    const session = req.session;
+    if (session === undefined) throw new Error("unreachable: guard sets session");
+    const workspaceId = session.workspaceId;
+    return withTenant(workspaceId, async (client) => {
+      const inserted = await client.query(
+        "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, $2, $3) RETURNING id",
+        [workspaceId, body.provider, body.channelId],
+      );
+      const id = inserted.rows[0]?.id as string;
+      await client.query("SELECT audit_append($1, $2, $3, 'connection.created', 'connection', $4, $5)", [
+        workspaceId,
+        session.userId,
+        session.role,
+        id,
+        JSON.stringify({ provider: body.provider }),
+      ]);
+      return { id };
+    });
+  }
+
+  @Post("echo-audited")
+  @RequirePermission("workspace.view")
+  async echoAudited(@Req() req: Request & AuthenticatedRequest, @Body() body: { apiKey?: string; note?: string }): Promise<{ ok: true }> {
+    const session = req.session;
+    if (session === undefined) throw new Error("unreachable: guard sets session");
+    await appendTenantAudit(session.workspaceId, {
+      actorUserId: session.userId,
+      actorRole: session.role,
+      action: "demo.echo",
+      targetType: "demo",
+      targetId: "echo",
+      diff: { apiKey: body.apiKey ?? null, note: body.note ?? null },
+    });
+    return { ok: true };
+  }
+}
diff --git a/apps/api/src/director/config.ts b/apps/api/src/director/config.ts
new file mode 100644
index 0000000..25b4c13
--- /dev/null
+++ b/apps/api/src/director/config.ts
@@ -0,0 +1,139 @@
+/**
+ * Director channel configuration — API-side mirror of
+ * apps/scheduler/src/director/config.ts.
+ *
+ * The API answers snapshot/fence reads from the same DIRECTOR_CHANNELS
+ * document the scheduler parses, so both parsers must agree on the shape.
+ * Duplicating the parser (rather than importing scheduler sources into the
+ * API's dependency graph) keeps each app's build independent; the shared
+ * fixture test in director.service.test.ts asserts both parse identically.
+ */
+import type { AutoDirectorRule, DirectorAction, DirectorCondition, SceneLayout, SwitchPolicy } from "@tactical-media-broadcast-hub/core";
+
+export interface DirectorChannelConfig {
+  readonly workspaceId: string;
+  readonly channelId: string;
+  readonly generation: string;
+  readonly rules: readonly AutoDirectorRule[];
+  readonly policy: SwitchPolicy | undefined;
+  readonly fallbackSceneId: string | null;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const GENERATION = /^[\x21-\x7e]{1,64}$/;
+const POLICY_NAMES: readonly SwitchPolicy["name"][] = [
+  "highest_priority", "oldest_live", "newest_live", "round_robin", "operator_required",
+  "picture_in_picture", "two_up", "split_screen", "grid",
+];
+const LAYOUTS: readonly SceneLayout[] = ["single", "pip", "two_up", "split_horizontal", "split_vertical", "grid", "custom"];
+const CONDITION_FIELDS: readonly DirectorCondition["field"][] = ["live_source_count", "max_priority", "source_state"];
+const CONDITION_OPS: readonly DirectorCondition["op"][] = [">=", "<=", "==", ">"];
+const SELECTIONS: readonly DirectorAction["selection"][] = ["top_priority", "all_live", "oldest_live", "explicit"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function uuid(value: unknown, field: string): string {
+  if (typeof value !== "string" || !UUID.test(value)) throw new Error(`${field} must be a UUID`);
+  return value;
+}
+
+function nonNegativeInt(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${field} must be a non-negative integer`);
+  return value;
+}
+
+function parseCondition(value: unknown, field: string): DirectorCondition {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const conditionField = value.field;
+  const op = value.op;
+  if (typeof conditionField !== "string" || !CONDITION_FIELDS.includes(conditionField as DirectorCondition["field"])) {
+    throw new Error(`${field}.field must be one of ${CONDITION_FIELDS.join(", ")}`);
+  }
+  if (typeof op !== "string" || !CONDITION_OPS.includes(op as DirectorCondition["op"])) {
+    throw new Error(`${field}.op must be one of ${CONDITION_OPS.join(", ")}`);
+  }
+  const ruleValue = value.value;
+  if (typeof ruleValue !== "number" && typeof ruleValue !== "string") throw new Error(`${field}.value must be a number or string`);
+  return { field: conditionField as DirectorCondition["field"], op: op as DirectorCondition["op"], value: ruleValue };
+}
+
+function parseAction(value: unknown, field: string): DirectorAction {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const selection = value.selection;
+  if (typeof selection !== "string" || !SELECTIONS.includes(selection as DirectorAction["selection"])) {
+    throw new Error(`${field}.selection must be one of ${SELECTIONS.join(", ")}`);
+  }
+  const layout = value.layout;
+  if (typeof layout !== "string" || !LAYOUTS.includes(layout as SceneLayout)) {
+    throw new Error(`${field}.layout must be one of ${LAYOUTS.join(", ")}`);
+  }
+  let sourceIds: string[] | undefined;
+  if (value.sourceIds !== undefined) {
+    if (!Array.isArray(value.sourceIds)) throw new Error(`${field}.sourceIds must be an array`);
+    sourceIds = value.sourceIds.map((id, i) => uuid(id, `${field}.sourceIds[${i}]`));
+    if (new Set(sourceIds).size !== sourceIds.length) throw new Error(`${field}.sourceIds must be unique`);
+  }
+  if (selection === "explicit" && (sourceIds === undefined || sourceIds.length === 0)) {
+    throw new Error(`${field}.selection explicit requires sourceIds`);
+  }
+  return { layout: layout as SceneLayout, selection: selection as DirectorAction["selection"], ...(sourceIds === undefined ? {} : { sourceIds }) };
+}
+
+function parseRule(value: unknown, channelId: string, index: number): AutoDirectorRule {
+  const field = `DIRECTOR_CHANNELS[${index}].rules[${index}]`;
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  if (value.virtualChannelId !== undefined && value.virtualChannelId !== channelId) {
+    throw new Error(`${field}.virtualChannelId must match the channel it is configured on`);
+  }
+  return {
+    id: uuid(value.id, `${field}.id`),
+    virtualChannelId: channelId,
+    priority: nonNegativeInt(value.priority ?? 0, `${field}.priority`),
+    condition: parseCondition(value.condition, `${field}.condition`),
+    action: parseAction(value.action, `${field}.action`),
+  };
+}
+
+function parsePolicy(value: unknown, field: string): SwitchPolicy {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const name = value.name;
+  if (typeof name !== "string" || !POLICY_NAMES.includes(name as SwitchPolicy["name"])) {
+    throw new Error(`${field}.name must be one of ${POLICY_NAMES.join(", ")}`);
+  }
+  return {
+    name: name as SwitchPolicy["name"],
+    liveConfirmations: nonNegativeInt(value.liveConfirmations ?? 2, `${field}.liveConfirmations`),
+    offlineConfirmations: nonNegativeInt(value.offlineConfirmations ?? 3, `${field}.offlineConfirmations`),
+    noMediaSeconds: nonNegativeInt(value.noMediaSeconds ?? 10, `${field}.noMediaSeconds`),
+    minHoldMs: nonNegativeInt(value.minHoldMs ?? 2_000, `${field}.minHoldMs`),
+    switchCooldownMs: nonNegativeInt(value.switchCooldownMs ?? 10_000, `${field}.switchCooldownMs`),
+  };
+}
+
+export function parseDirectorChannels(raw: string | undefined): DirectorChannelConfig[] {
+  if (raw === undefined || raw.trim() === "") return [];
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed)) throw new Error("DIRECTOR_CHANNELS must be a JSON array");
+  return parsed.map((entry, index) => {
+    const field = `DIRECTOR_CHANNELS[${index}]`;
+    if (!isRecord(entry)) throw new Error(`${field} must be an object`);
+    const channelId = uuid(entry.channelId, `${field}.channelId`);
+    const generation = entry.generation;
+    if (typeof generation !== "string" || !GENERATION.test(generation)) {
+      throw new Error(`${field}.generation must be 1-64 printable characters`);
+    }
+    const rules = Array.isArray(entry.rules) ? entry.rules.map((rule, i) => parseRule(rule, channelId, i)) : [];
+    const fallbackSceneId = entry.fallbackSceneId === undefined || entry.fallbackSceneId === null
+      ? null : uuid(entry.fallbackSceneId, `${field}.fallbackSceneId`);
+    return {
+      workspaceId: uuid(entry.workspaceId, `${field}.workspaceId`),
+      channelId,
+      generation,
+      rules,
+      policy: entry.policy === undefined ? undefined : parsePolicy(entry.policy, `${field}.policy`),
+      fallbackSceneId,
+    };
+  });
+}
diff --git a/apps/api/src/director/director.controller.ts b/apps/api/src/director/director.controller.ts
new file mode 100644
index 0000000..102bfdc
--- /dev/null
+++ b/apps/api/src/director/director.controller.ts
@@ -0,0 +1,84 @@
+/**
+ * Internal director endpoints (WP10 wiring slice).
+ *
+ * Process-to-process only: a shared-secret bearer (DIRECTOR_API_TOKEN) when
+ * configured, plus the ref's workspace/channel UUID shape. Not registered under
+ * the session RBAC guard — the scheduler worker has no browser session; its
+ * authorization is the generation/version fence in DirectorService.
+ */
+import { BadRequestException, Body, Controller, Get, Headers, HttpCode, Inject, Param, Post } from "@nestjs/common";
+import { DirectorService, type DirectorApplyBody } from "./director.service.js";
+
+function requireToken(token: string | undefined): void {
+  const expected = process.env.DIRECTOR_API_TOKEN;
+  if (expected === undefined || expected === "") return; // unset = local dev, no shared secret configured
+  if (token !== `Bearer ${expected}`) throw new BadRequestException("director token is invalid");
+}
+
+@Controller("internal/director/channels")
+export class DirectorController {
+  constructor(@Inject(DirectorService) private readonly director: DirectorService) {}
+
+  @Get(":workspaceId/:channelId/state")
+  async state(@Headers() headers: Record<string, string>, @Param("workspaceId") ws: string, @Param("channelId") ch: string): Promise<unknown> {
+    requireToken(headers.authorization);
+    return this.director.channelState(ws, ch);
+  }
+
+  @Get(":workspaceId/:channelId/fence")
+  async fence(@Headers() headers: Record<string, string>, @Param("workspaceId") ws: string, @Param("channelId") ch: string): Promise<unknown> {
+    requireToken(headers.authorization);
+    return this.director.fence(ws, ch);
+  }
+
+  @Post(":workspaceId/:channelId/apply")
+  @HttpCode(200)
+  async apply(@Headers() headers: Record<string, string>, @Param("workspaceId") ws: string, @Param("channelId") ch: string,
+    @Body() body: unknown): Promise<unknown> {
+    requireToken(headers.authorization);
+    return this.director.applyProgramSwitch(ws, ch, parseApply(body));
+  }
+
+  @Post(":workspaceId/:channelId/audit")
+  @HttpCode(204)
+  async audit(@Headers() headers: Record<string, string>, @Param("workspaceId") ws: string, @Param("channelId") ch: string,
+    @Body() body: unknown): Promise<void> {
+    requireToken(headers.authorization);
+    const event = body as { commandId?: unknown; outcome?: unknown; reason?: unknown };
+    if (typeof event.commandId !== "string" || (event.outcome !== "SUPERSEDED" && event.outcome !== "AUTHZ_REVOKED")
+      || typeof event.reason !== "string") throw new BadRequestException("audit event is invalid");
+    await this.director.audit(ws, ch, { commandId: event.commandId, outcome: event.outcome, reason: event.reason });
+  }
+}
+
+function parseApply(body: unknown): DirectorApplyBody {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new BadRequestException("apply body must be an object");
+  const value = body as Record<string, unknown>;
+  const commandId = value.commandId;
+  if (typeof commandId !== "string" || commandId === "" || commandId.length > 128) throw new BadRequestException("commandId must be 1-128 characters");
+  const expectedDesiredVersion = value.expectedDesiredVersion;
+  if (typeof expectedDesiredVersion !== "number" || !Number.isSafeInteger(expectedDesiredVersion) || expectedDesiredVersion < 0) {
+    throw new BadRequestException("expectedDesiredVersion must be a non-negative integer");
+  }
+  const authzEpoch = value.authzEpoch;
+  if (typeof authzEpoch !== "number" || !Number.isSafeInteger(authzEpoch) || authzEpoch < 0) {
+    throw new BadRequestException("authzEpoch must be a non-negative integer");
+  }
+  const program = value.program;
+  if (typeof program !== "object" || program === null) throw new BadRequestException("program must be an object");
+  const p = program as Record<string, unknown>;
+  let parsedProgram: DirectorApplyBody["program"];
+  if (p.kind === "sources") {
+    if (!Array.isArray(p.sourceIds) || p.sourceIds.some((id) => typeof id !== "string")) throw new BadRequestException("program.sourceIds must be strings");
+    parsedProgram = { kind: "sources", sourceIds: p.sourceIds };
+  } else if (p.kind === "fallback") {
+    if (p.sceneId !== null && typeof p.sceneId !== "string") throw new BadRequestException("program.sceneId must be a string or null");
+    parsedProgram = { kind: "fallback", sceneId: p.sceneId as string | null };
+  } else throw new BadRequestException("program.kind must be sources or fallback");
+  const layout = value.layout;
+  if (typeof layout !== "string" || layout === "") throw new BadRequestException("layout must be a non-empty string");
+  if (!Array.isArray(value.reasons) || value.reasons.some((r) => typeof r !== "string")) throw new BadRequestException("reasons must be strings");
+  const releaseOverride = value.releaseOverride;
+  if (releaseOverride !== undefined && typeof releaseOverride !== "string") throw new BadRequestException("releaseOverride must be a string");
+  return { commandId, expectedDesiredVersion, authzEpoch, program: parsedProgram, layout, reasons: value.reasons, ...(releaseOverride === undefined ? {} : { releaseOverride }) };
+}
diff --git a/apps/api/src/director/director.module.ts b/apps/api/src/director/director.module.ts
new file mode 100644
index 0000000..faf5132
--- /dev/null
+++ b/apps/api/src/director/director.module.ts
@@ -0,0 +1,31 @@
+/**
+ * Director wiring module (WP10 integration slice).
+ *
+ * Minimal by design: the director service reads live-monitor state and writes
+ * through MediaControlService; no chatgov/feeds/virtual-channels dependency.
+ * Registration is one line in app.module.ts:
+ *
+ *   import { DirectorModule } from "./director/director.module.js";
+ *   imports: [..., DirectorModule]
+ */
+import { Module } from "@nestjs/common";
+import { MediaControlModule } from "../media-control/media-control.module.js";
+import { DirectorController } from "./director.controller.js";
+import { DirectorService } from "./director.service.js";
+import { MediaControlService } from "../media-control/media-control.service.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+
+@Module({
+  imports: [MediaControlModule],
+  controllers: [DirectorController],
+  providers: [
+    {
+      provide: DirectorService,
+      inject: [MediaControlService],
+      useFactory: (control: MediaControlService) =>
+        new DirectorService({ control, audit: appendTenantAudit }),
+    },
+  ],
+  exports: [DirectorService],
+})
+export class DirectorModule {}
diff --git a/apps/api/src/director/director.service.test.ts b/apps/api/src/director/director.service.test.ts
new file mode 100644
index 0000000..1e6043b
--- /dev/null
+++ b/apps/api/src/director/director.service.test.ts
@@ -0,0 +1,331 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { ConflictException } from "@nestjs/common";
+import { describe, expect, it } from "vitest";
+import { decide } from "../../../scheduler/src/director/engine.js";
+import { MediaControlService } from "../media-control/media-control.service.js";
+import { MemoryRedis } from "../production/testing/memory-redis.js";
+import { Ed25519ControlSigner } from "../media-control/wire.js";
+import type { TenantTransaction } from "../production/journal.js";
+import { DirectorService, engineState, type DirectorApplyBody, type DirectorChannelConfig } from "./director.service.js";
+import { parseDirectorChannels } from "./config.js";
+
+/**
+ * WP10 wiring slice: the port pair against fakes.
+ *
+ * The database double implements exactly the three queries the service issues
+ * (fence, source join, scene resolution) over a small in-memory aggregate, and
+ * MediaControlService runs for real on the MemoryRedis + aggregate-transaction
+ * fixture used by control-s3.test.ts. The engine itself is imported from the
+ * scheduler package — the same pure decide() the evaluator workflow runs.
+ */
+
+const WS = randomUUID();
+const CH = randomUUID();
+const SOURCE_A = randomUUID();
+const SOURCE_B = randomUUID();
+const SCENE_SOLO = randomUUID();
+const SCENE_FALLBACK = randomUUID();
+
+interface SceneRow { sceneId: string; sources: string[] }
+
+/** In-memory channel aggregate: fence + sources + scenes, in query order. */
+class ChannelDatabase {
+  desiredVersion = 4;
+  authzEpoch = 7;
+  readonly sources: Array<{ id: string; priority: number; monitorState: string | null; version: number | null; stateEnteredAt: Date | null; lastMediaAt: string | null; lastOutcome: string | null }> = [];
+  readonly scenes: SceneRow[] = [];
+  failAudit = false;
+
+  readonly transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> => {
+    const query = async (sql: string, values: unknown[]): Promise<{ rows: Record<string, unknown>[]; rowCount: number }> => {
+      if (sql.includes("FROM virtual_channel_sources")) {
+        // The SOURCE_JOIN: monitor rows keyed by (connection_id, remote_ref).
+        const rows = this.sources.map((s) => ({
+          id: s.id, priority: s.priority, monitor_state: s.monitorState, monitor_version: s.version,
+          state_entered_at: s.stateEnteredAt,
+          tier_status: s.lastMediaAt === null && s.lastOutcome === null ? null
+            : { "media-health": { lastMediaAt: s.lastMediaAt, lastOutcome: s.lastOutcome } },
+        }));
+        return { rows, rowCount: rows.length };
+      }
+      if (sql.includes("SELECT desired_version FROM virtual_channels")) {
+        if (this.desiredVersion < 0) return { rows: [], rowCount: 0 };
+        return { rows: [{ desired_version: String(this.desiredVersion) }], rowCount: 1 };
+      }
+      if (sql.includes("SELECT authz_epoch FROM workspaces")) {
+        return { rows: [{ authz_epoch: String(this.authzEpoch) }], rowCount: 1 };
+      }
+      if (sql.includes("FROM production_scenes")) {
+        // Scene resolution: bound slots exactly equal the selected sources.
+        const selected = values.slice(2, -1).map(String);
+        const match = this.scenes.find((scene) => [...scene.sources].sort().join() === [...selected].sort().join() && scene.sources.length === selected.length);
+        return { rows: match === undefined ? [] : [{ scene_id: match.sceneId }], rowCount: match === undefined ? 0 : 1 };
+      }
+      throw new Error(`unexpected director query: ${sql.slice(0, 60)}`);
+    };
+    return fn({ query } as unknown as PoolClient);
+  };
+}
+
+/** media-control transaction double over the same aggregate (control-s3 pattern). */
+class BusDatabase {
+  state = { version: 0, preview: null as string | null, program: null as string | null, receipts: [] as unknown[] };
+  readonly scenes = new Set<string>();
+  /** productionScenes served to the production snapshot: one slotless scene per known scene id. */
+  sceneList(): Array<{ id: string; label: string; layout: string }> {
+    return [...this.scenes].map((id) => ({ id, label: id === id ? "Scene" : "Scene", layout: "single" }));
+  }
+  readonly transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> => {
+    const query = async (sql: string, values: unknown[] = []): Promise<{ rows: unknown[]; rowCount: number }> => {
+      let rows: unknown[] = [];
+      if (sql.startsWith("SELECT id FROM virtual_channels")) rows = [{ id: CH }];
+      else if (sql.startsWith("SELECT desired_version")) rows = [{ desired_version: String(this.state.version), desired_status: "STOPPED" }];
+      else if (sql.includes("FROM audit_log")) {
+        const found = sql.includes("requestId") ? this.state.receipts.find(r => (r as { requestId?: string }).requestId === values[2]) : this.state.receipts.at(-1);
+        rows = found ? [{ diff: found }] : [];
+      } else if (sql.startsWith("SELECT scene_id")) rows = [{ scene_id: this.state.preview }];
+      else if (sql.startsWith("INSERT INTO production_buses")) { if (sql.includes("'program'")) this.state.program = String(values[2]); else this.state.preview = String(values[2]); }
+      else if (sql.startsWith("UPDATE virtual_channels")) this.state.version = Number(values[2]);
+      else if (sql.startsWith("SELECT audit_append")) { this.state.receipts.push(values[6]); return { rows: [], rowCount: 1 }; }
+      else if (sql.startsWith("SELECT id,label,layout")) rows = this.sceneList();
+      else if (sql.startsWith("SELECT bus,scene_id")) rows = [{ bus: "preview", scene_id: this.state.preview }, { bus: "program", scene_id: this.state.program }];
+      else if (sql.startsWith("SELECT id FROM production_scenes")) rows = this.scenes.has(String(values[2])) ? [{ id: values[2] }] : [];
+      else if (sql.startsWith("SELECT scene_id,slot_index") || sql.includes("FROM scene_slots")) rows = [];
+      else if (sql.includes("FROM virtual_channel_sources")) rows = [];
+      else if (sql.includes("FROM overlay_slots")) rows = [];
+      return { rows, rowCount: sql.startsWith("UPDATE") ? 1 : rows.length };
+    };
+    return fn({ query } as unknown as PoolClient);
+  };
+}
+
+function config(over: Partial<DirectorChannelConfig> = {}): DirectorChannelConfig {
+  return {
+    workspaceId: WS, channelId: CH, generation: "g1",
+    rules: [{
+      id: randomUUID(), virtualChannelId: CH, priority: 1,
+      condition: { field: "live_source_count", op: ">=", value: 1 },
+      action: { layout: "single", selection: "top_priority" },
+    }],
+    policy: { name: "highest_priority", liveConfirmations: 1, offlineConfirmations: 1, noMediaSeconds: 10, minHoldMs: 0, switchCooldownMs: 0 },
+    fallbackSceneId: SCENE_FALLBACK,
+    ...over,
+  };
+}
+
+async function fixture(channelConfig: DirectorChannelConfig): Promise<{
+  db: ChannelDatabase; bus: BusDatabase; service: DirectorService; control: MediaControlService;
+}> {
+  const db = new ChannelDatabase();
+  const bus = new BusDatabase();
+  bus.scenes.add(SCENE_SOLO);
+  bus.scenes.add(SCENE_FALLBACK);
+  const redis = new MemoryRedis();
+  const control = new MediaControlService({
+    transaction: bus.transaction, redis,
+    signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey), assignments: [],
+  });
+  await control.assign(WS, CH, "media-worker-a", 1);
+  const service = new DirectorService({
+    transaction: db.transaction, control,
+    audit: async () => randomUUID(),
+    channels: () => [channelConfig],
+  });
+  return { db, bus, service, control };
+}
+
+const apply = (over: Partial<DirectorApplyBody> = {}): DirectorApplyBody => ({
+  commandId: `${CH}:9:1`, expectedDesiredVersion: 4, authzEpoch: 7,
+  program: { kind: "sources", sourceIds: [SOURCE_A] }, layout: "single", reasons: ["rule"],
+  ...over,
+});
+
+describe("engineState mapping", () => {
+  it("maps monitor states and reads anything else as UNKNOWN", () => {
+    for (const state of ["OFFLINE", "PROBING", "LIVE", "UNSTABLE", "ERROR"]) {
+      expect(engineState(state)).toBe(state);
+    }
+    expect(engineState(null)).toBe("UNKNOWN");
+    expect(engineState("weird")).toBe("UNKNOWN");
+  });
+});
+
+describe("DirectorStatePort read (channelState)", () => {
+  it("joins monitor rows by source identity and renders the engine input shape", async () => {
+    const entered = new Date("2026-10-09T12:00:00Z");
+    const local = new ChannelDatabase();
+    local.sources.push(
+      { id: SOURCE_A, priority: 50, monitorState: "LIVE", version: 3, stateEnteredAt: entered, lastMediaAt: "2026-10-09T12:00:01Z", lastOutcome: "ok" },
+      { id: SOURCE_B, priority: 10, monitorState: null, version: null, stateEnteredAt: null, lastMediaAt: null, lastOutcome: null },
+    );
+    const svc = new DirectorService({ transaction: local.transaction, control: { director: async () => { throw new Error("unreachable"); } }, channels: () => [config()] });
+    const read = await svc.channelState(WS, CH);
+    if (read.kind !== "current") throw new Error("expected current");
+    expect(read.desiredVersion).toBe(4);
+    expect(read.authzEpoch).toBe(7);
+    expect(read.sources).toEqual([
+      expect.objectContaining({ id: SOURCE_A, priority: 50, state: "LIVE", version: 3, liveSinceMs: entered.getTime(), lastMediaAtMs: Date.parse("2026-10-09T12:00:01Z") }),
+      expect.objectContaining({ id: SOURCE_B, state: "UNKNOWN" }),
+    ]);
+    // Optional engine fields are absent (never null): a null would de-confirm
+    // every source as no-media inside decide().
+    expect("lastMediaAtMs" in (read.sources[1] ?? {})).toBe(false);
+    expect("mediaFailed" in (read.sources[0] ?? {})).toBe(false);
+    expect(read.rules).toHaveLength(1);
+    expect(read.policy.name).toBe("highest_priority");
+    expect(read.fallbackSceneId).toBe(SCENE_FALLBACK);
+  });
+
+  it("returns superseded when the channel is not configured for the director", async () => {
+    const local = new ChannelDatabase();
+    const svc = new DirectorService({ transaction: local.transaction, control: { director: async () => { throw new Error("unreachable"); } }, channels: () => [] });
+    expect(await svc.channelState(WS, CH)).toEqual({ kind: "superseded", code: "SUPERSEDED" });
+    expect(await svc.fence(WS, CH)).toBeUndefined();
+  });
+});
+
+describe("DesiredStatePort apply (applyProgramSwitch)", () => {
+  /** The evaluator loop: read -> decide, carrying memory/lastSwitch between ticks. */
+  async function evaluate(service: DirectorService, db: ChannelDatabase, ticks: number): Promise<ReturnType<typeof decide>> {
+    let memory: ReturnType<typeof decide>["memory"] | undefined;
+    let lastSwitch: ReturnType<typeof decide>["lastSwitch"] | undefined;
+    let decision: ReturnType<typeof decide> | undefined;
+    for (let tick = 0; tick < ticks; tick += 1) {
+      if (tick > 0) for (const source of db.sources) if (source.version !== null) source.version += 1; // a fresh monitor sample per tick
+      const read = await service.channelState(WS, CH);
+      if (read.kind !== "current") throw new Error("expected current");
+      decision = decide({
+        sources: read.sources, rules: read.rules, policy: read.policy,
+        now: 100_000 + tick * 5_000, channelId: CH, fallbackSceneId: read.fallbackSceneId,
+        ...(memory === undefined ? {} : { memory }), ...(lastSwitch === undefined ? {} : { lastSwitch }),
+      });
+      memory = decision.memory; lastSwitch = decision.lastSwitch;
+    }
+    if (decision === undefined) throw new Error("no decision");
+    return decision;
+  }
+
+  it("applies a decision end to end: read -> decide (debounced) -> pst-select + cut through media control", async () => {
+    // liveConfirmations 2: the engine must see two fresh monitor samples before
+    // trusting a LIVE report — the debounce the evaluator relies on.
+    const { db, bus, service } = await fixture(config({
+      policy: { name: "highest_priority", liveConfirmations: 2, offlineConfirmations: 1, noMediaSeconds: 10, minHoldMs: 0, switchCooldownMs: 0 },
+    }));
+    db.scenes.push({ sceneId: SCENE_SOLO, sources: [SOURCE_A] });
+    db.sources.push({ id: SOURCE_A, priority: 50, monitorState: "LIVE", version: 3, stateEnteredAt: new Date("2026-10-09T12:00:00Z"), lastMediaAt: null, lastOutcome: "ok" });
+
+    // First tick: one sample, unconfirmed — the engine holds the fallback.
+    const probing = await evaluate(service, db, 1);
+    expect(probing.program.kind).toBe("fallback");
+    // Second tick (new monitor version): confirmed LIVE, the rule fires.
+    const decision = await evaluate(service, db, 2);
+    expect(decision.program).toEqual({ kind: "sources", sourceIds: [SOURCE_A] });
+    expect(decision.switched).toBe(true);
+
+    const read = await service.channelState(WS, CH);
+    if (read.kind !== "current") throw new Error("expected current");
+    const outcome = await service.applyProgramSwitch(WS, CH, {
+      commandId: `${CH}:0:1`, expectedDesiredVersion: read.desiredVersion, authzEpoch: read.authzEpoch,
+      program: decision.program, layout: decision.layout, reasons: decision.reasons,
+    });
+    expect(outcome).toMatchObject({ kind: "applied" });
+    expect(bus.state.preview).toBe(SCENE_SOLO);
+    expect(bus.state.program).toBe(SCENE_SOLO);
+    // pst + cut are two desired-version bumps
+    expect(bus.state.version).toBe(2);
+  });
+
+  it("replays the same commandId without switching twice (idempotent keys, no new receipts)", async () => {
+    const { db, bus, service } = await fixture(config());
+    db.scenes.push({ sceneId: SCENE_SOLO, sources: [SOURCE_A] });
+    const body = apply();
+    const first = await service.applyProgramSwitch(WS, CH, body);
+    expect(first).toMatchObject({ kind: "applied" });
+    // An activity retry arrives with the same fence: the derived idempotency
+    // keys hit media-control's stored receipts, so nothing is written twice.
+    const second = await service.applyProgramSwitch(WS, CH, body);
+    expect(second.kind).not.toBe("conflict");
+    expect(bus.state.receipts).toHaveLength(2); // pst + cut, still exactly once each
+    expect(bus.state.version).toBe(2);
+    // Once the fence has moved (a concurrent writer won), the same command is a conflict.
+    db.desiredVersion = body.expectedDesiredVersion + 1;
+    expect(await service.applyProgramSwitch(WS, CH, body)).toEqual({ kind: "conflict" });
+  });
+
+  it("rejects a stale fence (desired version or authz epoch moved)", async () => {
+    const { db, service } = await fixture(config());
+    db.desiredVersion = 5;
+    expect(await service.applyProgramSwitch(WS, CH, apply())).toEqual({ kind: "conflict" });
+    db.desiredVersion = 4;
+    db.authzEpoch = 8;
+    expect(await service.applyProgramSwitch(WS, CH, apply())).toEqual({ kind: "conflict" });
+  });
+
+  it("falls back to the configured fallback scene when no scene holds the selection", async () => {
+    const { db, bus, service } = await fixture(config());
+    db.scenes.push({ sceneId: randomUUID(), sources: [SOURCE_A, SOURCE_B] }); // different selection
+    const outcome = await service.applyProgramSwitch(WS, CH, apply());
+    expect(outcome).toMatchObject({ kind: "applied" });
+    expect(bus.state.program).toBe(SCENE_FALLBACK);
+  });
+
+  it("fails closed with a conflict when the selection has no scene and no fallback exists", async () => {
+    const { service } = await fixture(config({ fallbackSceneId: null }));
+    await expect(service.applyProgramSwitch(WS, CH, apply())).resolves.toEqual({ kind: "conflict" });
+  });
+
+  it("an explicit fallback program selects the fallback scene", async () => {
+    const { bus, service } = await fixture(config());
+    const outcome = await service.applyProgramSwitch(WS, CH, apply({ program: { kind: "fallback", sceneId: null } }));
+    expect(outcome).toMatchObject({ kind: "applied" });
+    expect(bus.state.program).toBe(SCENE_FALLBACK);
+  });
+
+  it("classifies media-control conflicts as CAS outcomes and propagates the rest", async () => {
+    const failing = new DirectorService({
+      transaction: new ChannelDatabase().transaction,
+      control: { director: async () => { throw new ConflictException("channel is not assigned to a media worker"); } },
+      channels: () => [config()],
+    });
+    await expect(failing.applyProgramSwitch(WS, CH, apply())).resolves.toEqual({ kind: "conflict" });
+    const exploding = new DirectorService({
+      transaction: new ChannelDatabase().transaction,
+      control: { director: async () => { throw new Error("redis down"); } },
+      channels: () => [config()],
+    });
+    await expect(exploding.applyProgramSwitch(WS, CH, apply())).rejects.toThrow("redis down");
+  });
+
+  it("unwired desired-state port fails closed without touching media control", async () => {
+    const svc = new DirectorService({ transaction: new ChannelDatabase().transaction, channels: () => [config()] });
+    await expect(svc.applyProgramSwitch(WS, CH, apply())).resolves.toEqual({ kind: "conflict" });
+  });
+});
+
+describe("config parser (API side)", () => {
+  it("parses a full channel document and rejects malformed entries", () => {
+    const rule = { id: randomUUID(), priority: 2, condition: { field: "live_source_count", op: ">=", value: 1 }, action: { layout: "grid", selection: "all_live" } };
+    const parsed = parseDirectorChannels(JSON.stringify([{ workspaceId: WS, channelId: CH, generation: "g-1", rules: [rule], policy: { name: "grid", liveConfirmations: 1 }, fallbackSceneId: null }]));
+    expect(parsed).toHaveLength(1);
+    expect(parsed[0]).toMatchObject({ workspaceId: WS, channelId: CH, generation: "g-1", fallbackSceneId: null });
+    expect(parsed[0]?.rules[0]).toMatchObject({ priority: 2 });
+    expect(parsed[0]?.policy?.liveConfirmations).toBe(1);
+    expect(parseDirectorChannels(undefined)).toEqual([]);
+    expect(() => parseDirectorChannels("{}")).toThrow();
+    expect(() => parseDirectorChannels(JSON.stringify([{ workspaceId: WS }]))).toThrow();
+    expect(() => parseDirectorChannels(JSON.stringify([{ workspaceId: WS, channelId: "nope", generation: "g" }]))).toThrow();
+    expect(() => parseDirectorChannels(JSON.stringify([{ workspaceId: WS, channelId: CH, generation: "g", rules: [{ ...rule, action: { ...rule.action, selection: "explicit" } }] }]))).toThrow(/explicit requires sourceIds/);
+  });
+
+  it("matches the scheduler-side parser on the same document (shape compatibility)", async () => {
+    const { parseDirectorChannels: schedulerParse } = await import("../../../scheduler/src/director/config.js");
+    const document = JSON.stringify([{
+      workspaceId: WS, channelId: CH, generation: "shared-1",
+      rules: [{ id: randomUUID(), priority: 1, condition: { field: "source_state", op: "==", value: "LIVE" }, action: { layout: "pip", selection: "explicit", sourceIds: [SOURCE_A] } }],
+      policy: { name: "two_up", liveConfirmations: 3, offlineConfirmations: 4, noMediaSeconds: 30, minHoldMs: 5_000, switchCooldownMs: 15_000 },
+      fallbackSceneId: SCENE_FALLBACK,
+    }]);
+    expect(schedulerParse(document)).toEqual(parseDirectorChannels(document));
+  });
+});
diff --git a/apps/api/src/director/director.service.ts b/apps/api/src/director/director.service.ts
new file mode 100644
index 0000000..e5e68e9
--- /dev/null
+++ b/apps/api/src/director/director.service.ts
@@ -0,0 +1,322 @@
+/**
+ * Director wiring service (WP10 integration slice): the API-side half of the
+ * engine's two ports.
+ *
+ * DirectorStatePort.read  <- channelState(): joins a channel's sources with
+ *   the live monitor (virtual_channel_sources LEFT JOIN source_monitor_states
+ *   on the monitor's own keyed identity (workspace_id, connection_id,
+ *   remote_ref)) and renders the engine's input shape.
+ * DesiredStatePort        <- fence()/applyProgramSwitch(): fence from
+ *   virtual_channels.desired_version + workspaces.authz_epoch; apply via
+ *   MediaControlService.director() (the transactional outbox behind
+ *   setDesired), with pst-select + cut under idempotency keys derived from
+ *   the director's commandId, so a retried activity is a duplicate, never a
+ *   double switch.
+ *
+ * The scheduler's evaluator drives these over HTTP (internal director
+ * endpoints); the service is process-agnostic so tests can call it directly.
+ */
+import { BadRequestException, ConflictException, Inject, Injectable, NotFoundException, Optional } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { DEFAULT_SWITCH_POLICY } from "@tactical-media-broadcast-hub/core";
+import { withTenant } from "../db/client.js";
+import { isUuid } from "../http/validation.js";
+import type { MediaControlService } from "../media-control/media-control.service.js";
+import type { DirectorActor } from "../production/journal.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { parseDirectorChannels, type DirectorChannelConfig } from "./config.js";
+
+export type { DirectorChannelConfig } from "./config.js";
+
+/**
+ * Engine-facing source row (transport twin of the scheduler's
+ * DirectorChannelSource). Optional fields are ABSENT, never null: the engine
+ * reads `lastMediaAtMs !== undefined` as "known", so a null would read as
+ * epoch 0 and de-confirm every source as no-media (caught by the port-pair
+ * test). JSON drops undefined keys, keeping wire and engine forms identical.
+ */
+export interface DirectorSourceRow {
+  id: string;
+  priority: number;
+  enabled: boolean;
+  autoSelect: boolean;
+  state:
+    | "OFFLINE" | "UNKNOWN" | "PROBING" | "STARTING" | "LIVE" | "UNSTABLE" | "ENDING" | "ERROR";
+  version?: number;
+  liveSinceMs?: number;
+  lastMediaAtMs?: number;
+  mediaFailed?: boolean;
+}
+
+export interface DirectorChannelSnapshot {
+  kind: "current";
+  desiredVersion: number;
+  authzEpoch: number;
+  generation: string;
+  sources: DirectorSourceRow[];
+  rules: DirectorChannelConfig["rules"];
+  policy: NonNullable<DirectorChannelConfig["policy"]>;
+  fallbackSceneId: string | null;
+  override: null;
+  principalPermissions: Record<string, string[]>;
+}
+
+export type DirectorChannelRead = DirectorChannelSnapshot | { kind: "superseded"; code: "SUPERSEDED" };
+
+export interface DirectorApplyBody {
+  commandId: string;
+  expectedDesiredVersion: number;
+  authzEpoch: number;
+  program: { kind: "sources"; sourceIds: string[] } | { kind: "fallback"; sceneId: string | null };
+  layout: string;
+  reasons: string[];
+  releaseOverride?: string;
+}
+
+export type DirectorApplyOutcome =
+  | { kind: "applied" | "duplicate"; desiredVersion: number }
+  | { kind: "conflict" };
+
+export interface DirectorFence {
+  generation: string;
+  desiredVersion: number;
+  authzEpoch: number;
+  directorAuthorized: boolean;
+}
+
+export interface DirectorServiceDependencies {
+  transaction: typeof withTenant;
+  control: Pick<MediaControlService, "director">;
+  audit?: typeof appendTenantAudit;
+  /** Channel configuration; default reads DIRECTOR_CHANNELS once at construction. */
+  channels?: () => DirectorChannelConfig[];
+}
+
+export const DIRECTOR_DEPENDENCIES = Symbol("DIRECTOR_DEPENDENCIES");
+
+/** Row-level SQL for one channel's sources joined to their monitor state. */
+const SOURCE_QUERY = `
+  SELECT s.id, s.priority,
+         m.state AS monitor_state, m.version AS monitor_version,
+         m.state_entered_at,
+         m.tier_status->'media-health'->>'lastMediaAt' AS last_media_at,
+         m.tier_status->'media-health'->>'lastOutcome' AS media_last_outcome
+    FROM virtual_channel_sources s
+    LEFT JOIN source_monitor_states m
+      ON m.workspace_id = s.workspace_id
+     AND m.connection_id = s.connection_id
+     AND m.remote_ref = s.remote_ref
+   WHERE s.workspace_id = $1 AND s.virtual_channel_id = $2
+   ORDER BY s.priority DESC, s.id`;
+
+/** Monitor states the monitor schema admits (012); anything else reads UNKNOWN. */
+const MONITOR_STATES = ["OFFLINE", "PROBING", "LIVE", "UNSTABLE", "ERROR"] as const;
+
+/** The engine's source state from a monitor row (never-mapped => UNKNOWN). */
+export function engineState(monitorState: string | null): DirectorSourceRow["state"] {
+  return (MONITOR_STATES as readonly string[]).includes(monitorState ?? "")
+    ? monitorState as DirectorSourceRow["state"]
+    : "UNKNOWN";
+}
+
+function epochMs(value: unknown): number | null {
+  if (value === null || value === undefined) return null;
+  const parsed = value instanceof Date ? value.getTime() : Date.parse(String(value));
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+/** The evaluator acts as a service principal; its writes are attributed to the director itself. */
+export const DIRECTOR_ACTOR: DirectorActor = { userId: null, role: "director" };
+
+@Injectable()
+export class DirectorService {
+  private readonly deps: DirectorServiceDependencies;
+  private readonly envChannels: DirectorChannelConfig[];
+
+  constructor(@Optional() @Inject(DIRECTOR_DEPENDENCIES) dependencies?: Partial<DirectorServiceDependencies>) {
+    this.deps = {
+      transaction: dependencies?.transaction ?? withTenant,
+      control: dependencies?.control ?? {
+        // No injected media-control service: this process cannot apply desired
+        // state. Reads still work (the evaluator fences on them and audits
+        // SUPERSEDED), but applyProgramSwitch fails closed.
+        director: () => { throw new ConflictException("director desired-state port is not wired"); },
+      },
+      ...(dependencies?.audit === undefined ? {} : { audit: dependencies.audit }),
+      ...(dependencies?.channels === undefined ? {} : { channels: dependencies.channels }),
+    };
+    this.envChannels = parseDirectorChannels(process.env.DIRECTOR_CHANNELS);
+  }
+
+  /** Configured channel for a ref; undefined when the director is not configured for it. */
+  channel(workspaceId: string, channelId: string): DirectorChannelConfig | undefined {
+    const configured = this.deps.channels?.() ?? this.envChannels;
+    return configured.find((c) => c.workspaceId === workspaceId && c.channelId === channelId);
+  }
+
+  /** DirectorStatePort.read: the engine's full input for one channel. */
+  async channelState(workspaceId: string, channelId: string): Promise<DirectorChannelRead> {
+    assertRef(workspaceId, channelId);
+    const channel = this.channel(workspaceId, channelId);
+    if (channel === undefined) return { kind: "superseded", code: "SUPERSEDED" };
+    return this.deps.transaction(workspaceId, async (client) => {
+      const fence = await this.readFence(client, workspaceId, channelId, channel.generation);
+      if (fence.generation !== channel.generation) return { kind: "superseded" as const, code: "SUPERSEDED" as const };
+      const sources = await client.query(SOURCE_QUERY, [workspaceId, channelId]);
+      return {
+        kind: "current" as const,
+        desiredVersion: fence.desiredVersion,
+        authzEpoch: fence.authzEpoch,
+        generation: fence.generation,
+        sources: sources.rows.map((row: Record<string, unknown>) => this.sourceRow(row)),
+        rules: channel.rules,
+        policy: channel.policy ?? DEFAULT_SWITCH_POLICY,
+        fallbackSceneId: channel.fallbackSceneId,
+        override: null,
+        principalPermissions: {},
+      };
+    });
+  }
+
+  private sourceRow(row: Record<string, unknown>): DirectorSourceRow {
+    const tierStatus = row.tier_status as Record<string, { lastOutcome?: string; lastMediaAt?: string }> | null | undefined;
+    const mediaHealth = tierStatus?.["media-health"];
+    const version = row.monitor_version === null || row.monitor_version === undefined ? undefined : Number(row.monitor_version);
+    const liveSinceMs = epochMs(row.state_entered_at);
+    const lastMediaAtMs = epochMs(mediaHealth?.lastMediaAt);
+    const mediaFailed = mediaHealth?.lastOutcome === "fail" || mediaHealth?.lastOutcome === "error";
+    return {
+      id: String(row.id),
+      priority: Number(row.priority ?? 0),
+      enabled: true,
+      autoSelect: true,
+      state: engineState(row.monitor_state as string | null),
+      ...(version === undefined ? {} : { version }),
+      ...(liveSinceMs === null ? {} : { liveSinceMs }),
+      ...(lastMediaAtMs === null ? {} : { lastMediaAtMs }),
+      ...(mediaFailed ? { mediaFailed: true } : {}),
+    };
+  }
+
+  /** DesiredStatePort.fence. */
+  async fence(workspaceId: string, channelId: string): Promise<DirectorFence | undefined> {
+    assertRef(workspaceId, channelId);
+    const channel = this.channel(workspaceId, channelId);
+    if (channel === undefined) return undefined;
+    return this.deps.transaction(workspaceId, (client) => this.readFence(client, workspaceId, channelId, channel.generation));
+  }
+
+  private async readFence(client: PoolClient, workspaceId: string, channelId: string, generation: string): Promise<DirectorFence> {
+    const found = await client.query<{ desired_version: string | number }>(
+      "SELECT desired_version FROM virtual_channels WHERE workspace_id = $1 AND id = $2", [workspaceId, channelId]);
+    if (found.rowCount === 0) throw new NotFoundException(`virtual channel ${channelId} not found`);
+    const desiredVersion = Number(found.rows[0]?.desired_version);
+    if (!Number.isSafeInteger(desiredVersion) || desiredVersion < 0) throw new Error("desired_version is not a safe integer");
+    const epoch = await client.query<{ authz_epoch: string | number }>("SELECT authz_epoch FROM workspaces WHERE id = $1", [workspaceId]);
+    const authzEpoch = Number(epoch.rows[0]?.authz_epoch);
+    if (!Number.isSafeInteger(authzEpoch) || authzEpoch < 0) throw new Error("authz_epoch is not a safe integer");
+    return {
+      generation,
+      desiredVersion,
+      authzEpoch,
+      // Principal revocation is a later slice (it needs a persisted principal
+      // per evaluator); until then the fence is generation + desiredVersion.
+      directorAuthorized: true,
+    };
+  }
+
+  /**
+   * DesiredStatePort.apply: a director decision as a desired-state write.
+   *
+   * Resolves the decision's program to a scene, then pst-select (preview) +
+   * cut (preview -> program) through MediaControlService.director(), whose
+   * receipt lookup makes both steps idempotent under keys derived from the
+   * director's commandId: an activity retry replays the committed receipt
+   * instead of switching twice.
+   */
+  async applyProgramSwitch(workspaceId: string, channelId: string, body: DirectorApplyBody): Promise<DirectorApplyOutcome> {
+    assertRef(workspaceId, channelId);
+    if (typeof body.commandId !== "string" || body.commandId === "" || body.commandId.length > 128) {
+      throw new BadRequestException("commandId must be 1-128 characters");
+    }
+    const channel = this.channel(workspaceId, channelId);
+    if (channel === undefined) throw new ConflictException("director is not configured for this channel");
+    const fence = await this.fence(workspaceId, channelId);
+    if (fence === undefined) return { kind: "conflict" };
+    if (fence.desiredVersion !== body.expectedDesiredVersion || fence.authzEpoch !== body.authzEpoch) return { kind: "conflict" };
+
+    try {
+      // Resolve the decision's program to a scene the channel owns.
+      const scene = await this.deps.transaction(workspaceId, (client) =>
+        this.sceneForProgram(client, workspaceId, channelId, body.program, channel));
+      // pst-select arms the scene on preview; cut moves preview to program.
+      // Two commands, one decision: each has its own idempotency key derived
+      // from the director's commandId, so replays stop at the stored receipt.
+      const selected = await this.deps.control.director(workspaceId, channelId,
+        { type: "pst-select", sceneId: scene.sceneId }, `${body.commandId}:pst`, DIRECTOR_ACTOR);
+      await this.deps.control.director(workspaceId, channelId,
+        { type: "cut" }, `${body.commandId}:cut`, DIRECTOR_ACTOR);
+      return { kind: "applied", desiredVersion: selected.desiredVersion };
+    } catch (error) {
+      return classifyConflict(error);
+    }
+  }
+
+  /** Resolve the decision's program to a scene id: an explicit scene, or a scene holding exactly those sources. */
+  private async sceneForProgram(
+    client: PoolClient, workspaceId: string, channelId: string,
+    program: DirectorApplyBody["program"], channel: DirectorChannelConfig,
+  ): Promise<{ sceneId: string }> {
+    if (program.kind === "fallback") {
+      const sceneId = program.sceneId ?? channel.fallbackSceneId;
+      if (sceneId === null) throw new ConflictException("channel has no fallback scene configured");
+      return { sceneId };
+    }
+    if (program.sourceIds.length === 0) throw new ConflictException("program switch selected no sources");
+    // A scene whose bound slots are exactly the selected sources (order and
+    // multiplicity included): that scene is the director's program scene.
+    const placeholders = program.sourceIds.map((_, i) => `$${i + 3}`).join(",");
+    const found = await client.query<{ scene_id: string }>(
+      `SELECT sc.id AS scene_id
+         FROM production_scenes sc
+         LEFT JOIN scene_slots sl
+           ON sl.scene_id = sc.id AND sl.workspace_id = sc.workspace_id AND sl.virtual_channel_id = sc.virtual_channel_id
+        WHERE sc.workspace_id = $1 AND sc.virtual_channel_id = $2
+        GROUP BY sc.id
+       HAVING array_length(array_agg(sl.source_id ORDER BY sl.slot_index) FILTER (WHERE sl.source_id IS NOT NULL), 1) = $${program.sourceIds.length + 3}
+          AND array_agg(sl.source_id ORDER BY sl.slot_index) FILTER (WHERE sl.source_id IS NOT NULL) @> ARRAY[${placeholders}]::uuid[]`,
+      [workspaceId, channelId, ...program.sourceIds, program.sourceIds.length]);
+    if (found.rowCount === 0) {
+      // No scene authored for this selection: switch to the channel's declared
+      // fallback so the channel never stalls on an unrenderable program.
+      if (channel.fallbackSceneId === null) throw new ConflictException("no scene holds the selected sources and no fallback scene is configured");
+      return { sceneId: channel.fallbackSceneId };
+    }
+    return { sceneId: String(found.rows[0]?.scene_id) };
+  }
+
+  /** Outcomes the evaluator audits when it cannot write (generation/authz fences). */
+  async audit(workspaceId: string, channelId: string, event: { commandId: string; outcome: "SUPERSEDED" | "AUTHZ_REVOKED"; reason: string }): Promise<void> {
+    assertRef(workspaceId, channelId);
+    const append = this.deps.audit ?? appendTenantAudit;
+    await append(workspaceId, {
+      actorUserId: null,
+      actorRole: "director",
+      action: `director.${event.outcome.toLowerCase()}`,
+      targetType: "production_command",
+      targetId: channelId,
+      diff: { commandId: event.commandId, outcome: event.outcome, reason: event.reason },
+    });
+  }
+}
+
+function assertRef(workspaceId: string, channelId: string): void {
+  if (!isUuid(workspaceId)) throw new BadRequestException("workspaceId must be a UUID");
+  if (!isUuid(channelId)) throw new BadRequestException("channelId must be a UUID");
+}
+
+/** Media-control conflicts are CAS outcomes the evaluator re-reads on; anything else propagates. */
+function classifyConflict(error: unknown): DirectorApplyOutcome {
+  if (error instanceof ConflictException || error instanceof NotFoundException) return { kind: "conflict" };
+  throw error;
+}
diff --git a/apps/api/src/director/port-pair.test.ts b/apps/api/src/director/port-pair.test.ts
new file mode 100644
index 0000000..349e76a
--- /dev/null
+++ b/apps/api/src/director/port-pair.test.ts
@@ -0,0 +1,172 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { Controller, Module, type INestApplication } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import { describe, expect, it } from "vitest";
+import { DirectorController } from "./director.controller.js";
+import { DirectorService } from "./director.service.js";
+import { MediaControlService } from "../media-control/media-control.service.js";
+import { MemoryRedis } from "../production/testing/memory-redis.js";
+import { Ed25519ControlSigner } from "../media-control/wire.js";
+import type { TenantTransaction } from "../production/journal.js";
+import { decide } from "../../../scheduler/src/director/engine.js";
+import { HttpDirectorStatePort, HttpDesiredStatePort } from "../../../scheduler/src/director/adapters.js";
+import { DirectorHttpClient } from "../../../scheduler/src/director/http.client.js";
+
+/**
+ * Port-pair integration (WP10): the scheduler's HTTP adapters against a real
+ * Nest application hosting the API's director endpoints, with media control
+ * running for real on its MemoryRedis fixture. This is the exact chain the
+ * production wiring uses — internal endpoints, response validation, fence,
+ * engine input shape and the desired-state write — minus the database.
+ *
+ * The scheduler-side pieces are imported from apps/scheduler (pure modules
+ * only: engine, adapters, http.client), the same cross-package pattern
+ * live-monitor's poller tests use.
+ */
+const WS = "3f2b8e40-1a5c-4c7e-9d10-6f8d1a000001";
+const CH = "3f2b8e40-1a5c-4c7e-9d10-6f8d1a000002";
+const SRC_A = "3f2b8e40-1a5c-4c7e-9d10-6f8d1a000003";
+const SRC_B = "3f2b8e40-1a5c-4c7e-9d10-6f8d1a000004";
+const SCENE_SOLO = "3f2b8e40-1a5c-4c7e-9d10-6f8d1a000005";
+const SCENE_FALLBACK = "3f2b8e40-1a5c-4c7e-9d10-6f8d1a000006";
+
+/** Director-side database double: fence + source join + scene resolution. */
+class DirectorDb {
+  desiredVersion = 4;
+  authzEpoch = 7;
+  readonly sources: Array<Record<string, unknown>> = [];
+  readonly scenes: Array<{ sceneId: string; sources: string[] }> = [];
+  readonly transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> =>
+    fn({ query: async (sql: string, values: unknown[]): Promise<{ rows: Record<string, unknown>[]; rowCount: number }> => {
+      if (sql.includes("FROM virtual_channel_sources")) return { rows: this.sources, rowCount: this.sources.length };
+      if (sql.includes("SELECT desired_version FROM virtual_channels")) return { rows: [{ desired_version: String(this.desiredVersion) }], rowCount: 1 };
+      if (sql.includes("SELECT authz_epoch FROM workspaces")) return { rows: [{ authz_epoch: String(this.authzEpoch) }], rowCount: 1 };
+      if (sql.includes("FROM production_scenes")) {
+        const selected = values.slice(2, -1).map(String);
+        const match = this.scenes.find((scene) => scene.sources.length === selected.length && [...scene.sources].sort().join() === [...selected].sort().join());
+        return { rows: match === undefined ? [] : [{ scene_id: match.sceneId }], rowCount: match === undefined ? 0 : 1 };
+      }
+      throw new Error(`unexpected query: ${sql.slice(0, 60)}`);
+    } } as unknown as PoolClient);
+}
+
+/** media-control transaction double (control-s3 pattern). */
+class BusDb {
+  state = { version: 0, preview: null as string | null, program: null as string | null, receipts: [] as unknown[] };
+  readonly scenes = new Set<string>([SCENE_SOLO, SCENE_FALLBACK]);
+  readonly transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> =>
+    fn({ query: async (sql: string, values: unknown[] = []): Promise<{ rows: unknown[]; rowCount: number }> => {
+      let rows: unknown[] = [];
+      if (sql.startsWith("SELECT id FROM virtual_channels")) rows = [{ id: CH }];
+      else if (sql.startsWith("SELECT desired_version")) rows = [{ desired_version: String(this.state.version), desired_status: "STOPPED" }];
+      else if (sql.includes("FROM audit_log")) {
+        const found = sql.includes("requestId") ? this.state.receipts.find(r => (r as { requestId?: string }).requestId === values[2]) : this.state.receipts.at(-1);
+        rows = found ? [{ diff: found }] : [];
+      } else if (sql.startsWith("SELECT scene_id")) rows = [{ scene_id: this.state.preview }];
+      else if (sql.startsWith("INSERT INTO production_buses")) { if (sql.includes("'program'")) this.state.program = String(values[2]); else this.state.preview = String(values[2]); }
+      else if (sql.startsWith("UPDATE virtual_channels")) this.state.version = Number(values[2]);
+      else if (sql.startsWith("SELECT audit_append")) { this.state.receipts.push(values[6]); return { rows: [], rowCount: 1 }; }
+      else if (sql.startsWith("SELECT id,label,layout")) rows = [...this.scenes].map((id) => ({ id, label: "Scene", layout: "single" }));
+      else if (sql.startsWith("SELECT bus,scene_id")) rows = [{ bus: "preview", scene_id: this.state.preview }, { bus: "program", scene_id: this.state.program }];
+      else if (sql.startsWith("SELECT id FROM production_scenes")) rows = this.scenes.has(String(values[2])) ? [{ id: values[2] }] : [];
+      else if (sql.includes("FROM scene_slots") || sql.includes("FROM virtual_channel_sources") || sql.includes("FROM overlay_slots")) rows = [];
+      return { rows, rowCount: sql.startsWith("UPDATE") ? 1 : rows.length };
+    } } as unknown as PoolClient);
+}
+
+const RULES = [{
+  id: randomUUID(), virtualChannelId: CH, priority: 1,
+  condition: { field: "live_source_count" as const, op: ">=" as const, value: 1 },
+  action: { layout: "single" as const, selection: "top_priority" as const },
+}];
+const POLICY = { name: "highest_priority" as const, liveConfirmations: 1, offlineConfirmations: 1, noMediaSeconds: 600, minHoldMs: 0, switchCooldownMs: 0 };
+
+/**
+ * The production DirectorController, inherited verbatim: routes and handler
+ * bodies are the shipped ones (Nest reads the decorators off the prototype);
+ * only the service instance comes from the module below.
+ */
+@Controller("internal/director/channels")
+class BoundDirectorController extends DirectorController {}
+
+async function apiStack(db: DirectorDb, bus: BusDb): Promise<INestApplication> {
+  const control = new MediaControlService({
+    transaction: bus.transaction, redis: new MemoryRedis(),
+    signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey), assignments: [],
+  });
+  await control.assign(WS, CH, "media-worker-a", 1);
+  const service = new DirectorService({
+    transaction: db.transaction, control, audit: async () => randomUUID(),
+    channels: () => [{ workspaceId: WS, channelId: CH, generation: "g1", rules: RULES, policy: POLICY, fallbackSceneId: SCENE_FALLBACK }],
+  });
+
+  @Module({ controllers: [BoundDirectorController], providers: [{ provide: DirectorService, useValue: service }] })
+  class PairModule {}
+  const application = await NestFactory.create(PairModule, { logger: false });
+  await application.init();
+  return application;
+}
+
+describe("director port pair over HTTP (scheduler adapters <-> API endpoints)", () => {
+  it("state read -> decide -> fence -> apply, end to end", async () => {
+    const db = new DirectorDb();
+    const bus = new BusDb();
+    db.scenes.push({ sceneId: SCENE_SOLO, sources: [SRC_A] });
+    db.sources.push({ id: SRC_A, priority: 50, monitor_state: "LIVE", monitor_version: 3, state_entered_at: new Date("2026-10-09T12:00:00Z"), tier_status: null });
+    db.sources.push({ id: SRC_B, priority: 10, monitor_state: null, monitor_version: null, state_entered_at: null, tier_status: null });
+    const application = await apiStack(db, bus);
+    try {
+      await application.listen(0, "127.0.0.1");
+      const port = (application.getHttpServer().address() as { port: number }).port;
+      const client = new DirectorHttpClient({ baseUrl: `http://127.0.0.1:${port}` });
+      const state = new HttpDirectorStatePort(client);
+      const desired = new HttpDesiredStatePort(client);
+      const ref = { workspaceId: WS, channelId: CH, generation: "g1" };
+
+      // 1. read -> decide
+      const snapshot = await state.read(ref);
+      if (snapshot.kind !== "current") throw new Error("expected current");
+      expect(snapshot.sources).toHaveLength(2);
+      expect(snapshot.sources[0]).toMatchObject({ id: SRC_A, state: "LIVE", version: 3 });
+      const decision = decide({ sources: snapshot.sources, rules: snapshot.rules, policy: snapshot.policy, now: 100_000 });
+      expect(decision.program).toEqual({ kind: "sources", sourceIds: [SRC_A] });
+
+      // 2. fence matches the snapshot the decision was based on
+      const fence = await desired.fence(ref);
+      expect(fence).toMatchObject({ generation: "g1", desiredVersion: snapshot.desiredVersion, authzEpoch: snapshot.authzEpoch });
+
+      // 3. apply lands as preview + program through media control
+      const outcome = await desired.writeProgram({
+        ref, commandId: `${CH}:1`, expectedDesiredVersion: fence!.desiredVersion, authzEpoch: fence!.authzEpoch,
+        program: decision.program, layout: decision.layout, reasons: decision.reasons,
+      });
+      expect(outcome).toEqual({ kind: "applied", desiredVersion: 1 });
+      expect(bus.state.preview).toBe(SCENE_SOLO);
+      expect(bus.state.program).toBe(SCENE_SOLO);
+    } finally {
+      await application.close();
+    }
+  });
+
+  it("a stale fence is a conflict, never a write", async () => {
+    const db = new DirectorDb();
+    const bus = new BusDb();
+    db.scenes.push({ sceneId: SCENE_SOLO, sources: [SRC_A] });
+    const application = await apiStack(db, bus);
+    try {
+      await application.listen(0, "127.0.0.1");
+      const port = (application.getHttpServer().address() as { port: number }).port;
+      const client = new DirectorHttpClient({ baseUrl: `http://127.0.0.1:${port}` });
+      db.desiredVersion = 99; // a concurrent writer moved the fence
+      const outcome = await new HttpDesiredStatePort(client).writeProgram({
+        ref: { workspaceId: WS, channelId: CH, generation: "g1" }, commandId: "c", expectedDesiredVersion: 4, authzEpoch: 7,
+        program: { kind: "sources", sourceIds: [SRC_A] }, layout: "single", reasons: [],
+      });
+      expect(outcome).toEqual({ kind: "conflict" });
+      expect(bus.state.receipts).toHaveLength(0);
+    } finally {
+      await application.close();
+    }
+  });
+});
diff --git a/apps/api/src/feeds/column-scheduler.ts b/apps/api/src/feeds/column-scheduler.ts
new file mode 100644
index 0000000..e499fb9
--- /dev/null
+++ b/apps/api/src/feeds/column-scheduler.ts
@@ -0,0 +1,352 @@
+/**
+ * Columns scheduler (P1 — design §3.3/§3.4/§3.5).
+ *
+ * Generalizes the legacy feeds poll loop into a due-SOURCES loop. The design
+ * rule (§3.5): "the legacy home poll is the degenerate platform_feed source" —
+ * so there is one loop, and `/feeds`'s per-connection home poll is simply the
+ * `source_kind = 'home'` subset of it.
+ *
+ * Reused unchanged from the feeds loop:
+ *   - the per-key Redis lease (renewable, released in `finally`) so replicas
+ *     never double-poll one source;
+ *   - the cooldown key (`SET NX PX`) that makes repeated refresh clicks and
+ *     the 5-second discovery timer unable to bypass the interval;
+ *   - interval + 20 % jitter, SDK `RateLimitError.retryAfterMs` override.
+ *
+ * New per design §3.4:
+ *   - `column_sources` is the due list: `next_poll_at <= now`, `state <>
+ *     'disabled'`, `refresh_policy.paused` false — the DB row replaces the
+ *     in-memory "one cycle per connection" bookkeeping;
+ *   - identities shared by several columns collapse to ONE poll (the fan-out
+ *     in `ColumnStore.storeItems` writes the item rows for every sharing
+ *     column), so following the same account in two columns costs one call;
+ *   - `consecutive_failures` drives exponential backoff (the same
+ *     monitor-poller curve: 2^n capped at 120 s), and the outcome is written
+ *     back to the source row (`state`, `last_error`, `next_poll_at`) — the
+ *     persisted truth the UI surfaces as `ColumnView.source.state`;
+ *   - per-host tokens come from `@tactical-media-broadcast-hub/egress` HostBudgets (shared
+ *     `host_budgets` rows — one bucket per host across every caller and host
+ *     class, deployment-wide), so feeds and monitor fetches to the same host
+ *     contend for the same tokens rather than each rate-limiting the host.
+ *
+ * P1 scope note: only the `home` source kind is executed against a connector
+ * here (`getFeed(kind:'home')` — today's behavior); `mentions`/`search`/
+ * `author` rows are planned with the P2 connector work, so they park in
+ * `unsupported` rather than silently skipping. Item normalization runs through
+ * the same P0c `normalizeFeedItem` funnel the legacy loop uses.
+ */
+import { Inject, Injectable, Logger, Optional, type OnApplicationBootstrap, type OnApplicationShutdown } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import { RateLimitError, type ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import { DEFAULT_INTERVAL_MS } from "@tactical-media-broadcast-hub/core";
+import { pool, withTenant } from "../db/client.js";
+import { ColumnStore } from "./column-store.js";
+import { normalizeFeedItem, type NormalizedFeedItem } from "./feed-normalize.js";
+import type { ControlRedis } from "../media-control/redis.js";
+import type { ConnectionSummary } from "../connections/connections.service.js";
+
+export const COLUMN_SCHEDULER_DEPENDENCIES = Symbol("COLUMN_SCHEDULER_DEPENDENCIES");
+
+export interface ColumnSchedulerDependencies {
+  redis: Pick<ControlRedis, "get" | "set" | "eval">;
+  registry: ConnectorRegistry;
+  connection(workspaceId: string, id: string): Promise<ConnectorConnection>;
+  /** Legacy /feeds cache write-through, so /feeds reads stay cache-first. */
+  cacheHomeFeed(workspaceId: string, connectionId: string, items: NormalizedFeedItem[]): Promise<void>;
+  /** Effective host key for a provider's API host (egress hostBudgetKey). */
+  hostKeyOf(provider: string, connection: ConnectorConnection): string;
+  /** Draw one token from the shared per-host budget. */
+  consumeBudget(hostKey: string): Promise<void>;
+  random(): number;
+  now(): number;
+}
+
+/** Poll admission order per §3.4: due, enabled, not paused, oldest first. */
+interface DueRow {
+  workspace_id: string;
+  id: string;
+  provider: string;
+  connection_id: string | null;
+  source_kind: "home" | "mentions" | "search" | "author";
+  query: string | null;
+  actor_ref: string | null;
+  interval_ms: number;
+  paused: boolean;
+  consecutive_failures: number;
+}
+
+const LEASE_MS = 30_000;
+const BACKOFF_CAP_MS = 120_000;
+const RENEW_LEASE = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) else return 0 end";
+const RELEASE_LEASE = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) else return 0 end";
+
+/** Minimum spacing between two forced refreshes of one source (cache-loss safe). */
+export const FORCE_FLOOR_MS = 15_000;
+
+const DEFAULT_INTERVALS: Record<DueRow["source_kind"], number> = {
+  home: DEFAULT_INTERVAL_MS.platform_feed,
+  mentions: DEFAULT_INTERVAL_MS.platform_feed,
+  search: DEFAULT_INTERVAL_MS.keyword,
+  author: DEFAULT_INTERVAL_MS.account_list,
+};
+
+/** Poll cadence: spec refresh_policy interval, else the §1.2 per-kind default. */
+export function effectiveIntervalMs(intervalMs: number | null, sourceKind: DueRow["source_kind"]): number {
+  return intervalMs ?? DEFAULT_INTERVALS[sourceKind];
+}
+
+/** The monitor-poller backoff curve: 2^n * interval scale, capped at 120 s. */
+export function backoffDelayMs(failures: number, intervalMs: number): number {
+  return Math.min(BACKOFF_CAP_MS, intervalMs * 2 ** Math.min(7, Math.max(0, failures - 1)));
+}
+
+/**
+ * Discovery cadence: sources self-schedule via next_poll_at, so the loop only
+ * needs to sweep for newly due rows often enough to honor the 60 s floor.
+ */
+const SWEEP_MS = 5_000;
+
+@Injectable()
+export class ColumnScheduler implements OnApplicationBootstrap, OnApplicationShutdown {
+  private readonly logger = new Logger(ColumnScheduler.name);
+  private running = false;
+  private timer?: ReturnType<typeof setTimeout>;
+  private active?: Promise<void>;
+  constructor(
+    private readonly store: ColumnStore,
+    @Optional() @Inject(COLUMN_SCHEDULER_DEPENDENCIES) private readonly deps?: ColumnSchedulerDependencies,
+  ) {}
+
+  onApplicationBootstrap(): void {
+    this.running = true;
+    this.schedule(0);
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    await this.active;
+  }
+
+  private schedule(delay: number): void {
+    if (!this.running) return;
+    this.timer = setTimeout(() => {
+      this.active = this.pollDue().catch(() => this.logger.warn("Column sweep unavailable")).then(() => undefined).finally(() => {
+        this.active = undefined;
+        this.schedule(SWEEP_MS + Math.round((this.deps?.random() ?? Math.random()) * 1_000));
+      });
+    }, delay);
+    this.timer.unref();
+  }
+
+  /** One pass over every workspace's due sources. Errors are per-source, never fatal. */
+  async pollDue(): Promise<{ polled: number; skipped: number; failed: number }> {
+    const workspaces = await this.workspaces();
+    const totals = { polled: 0, skipped: 0, failed: 0 };
+    for (const workspaceId of workspaces) {
+      const pass = await this.pollWorkspaceDue(workspaceId);
+      totals.polled += pass.polled;
+      totals.skipped += pass.skipped;
+      totals.failed += pass.failed;
+    }
+    return totals;
+  }
+
+  /**
+   * The due-source scan (§3.4). Read-only against the DB (withTenant, FORCE
+   * RLS), then each source polls through its own lease/cooldown; the state
+   * write-back happens in the same tenant context. Returns per-source counts
+   * for the same shape the legacy loop reports.
+   */
+  async pollWorkspaceDue(workspaceId: string): Promise<{ polled: number; skipped: number; failed: number }> {
+    const due = await this.dueSources(workspaceId);
+    const results = { polled: 0, skipped: 0, failed: 0 };
+    for (const row of due) {
+      const outcome = await this.pollSource(workspaceId, row);
+      results[outcome] += 1;
+    }
+    return results;
+  }
+
+  private async dueSources(workspaceId: string): Promise<DueRow[]> {
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query<DueRow>(
+        `SELECT s.workspace_id, s.id, s.provider, s.connection_id, s.source_kind, s.query, s.actor_ref,
+                (sc.refresh_policy->>'intervalMs')::int AS interval_ms,
+                COALESCE((sc.refresh_policy->>'paused')::boolean, false) AS paused,
+                s.consecutive_failures
+           FROM column_sources s
+           JOIN stream_columns sc ON sc.id = s.column_id
+          WHERE s.workspace_id = $1
+            AND sc.deleted_at IS NULL -- a soft-deleted column's sources retire with it
+            AND s.state <> 'disabled'
+            AND COALESCE((sc.refresh_policy->>'paused')::boolean, false) = false
+            AND (s.next_poll_at IS NULL OR s.next_poll_at <= now())
+          ORDER BY s.created_at`,
+        [workspaceId],
+      );
+      return result.rows;
+    });
+  }
+
+  private async pollSource(workspaceId: string, row: DueRow): Promise<"polled" | "skipped" | "failed"> {
+    if (this.deps === undefined) return "skipped";
+    const interval = effectiveIntervalMs(row.interval_ms, row.source_kind);
+    const cooldownMs = interval + Math.round(interval * 0.2 * this.deps.random());
+    const key = `columns:${workspaceId}:${row.id}`;
+    const leaseKey = `${key}:lease`;
+    const cooldownKey = `${key}:cooldown`;
+    const owner = randomUUID();
+    if (!await this.deps.redis.set(leaseKey, owner, { nx: true, pxMs: LEASE_MS })) return "skipped";
+    let heartbeat: ReturnType<typeof setInterval> | undefined;
+    let renew: Promise<unknown> = Promise.resolve();
+    let cooldown = cooldownMs;
+    let started = false;
+    try {
+      if (!await this.deps.redis.set(cooldownKey, "idle", { nx: true, pxMs: cooldownMs })) return "skipped";
+      started = true;
+      heartbeat = setInterval(() => {
+        renew = this.deps!.redis.eval(RENEW_LEASE, [leaseKey], [owner, String(LEASE_MS)]).catch(() => {
+          this.logger.warn("Column poll lease renewal unavailable");
+        });
+      }, LEASE_MS / 3);
+      heartbeat.unref();
+
+      const page = await this.fetch(workspaceId, row);
+      const items = page.filter((item): item is NormalizedFeedItem => item !== null);
+      await this.store.storeItems(workspaceId, row.id, items);
+      await this.recordSuccess(workspaceId, row.id, interval);
+      // The legacy /feeds surface stays cache-first for home sources: the
+      // same items land in the hot cache the /feeds read path uses.
+      if (row.source_kind === "home" && row.connection_id !== null) {
+        await this.deps.cacheHomeFeed(workspaceId, row.connection_id, items);
+      }
+      return "polled";
+    } catch (error) {
+      const outcome = await this.recordFailure(workspaceId, row, error, interval);
+      cooldown = outcome.cooldownMs;
+      return "failed";
+    } finally {
+      if (heartbeat) clearInterval(heartbeat);
+      await renew;
+      try {
+        if (started) await this.deps.redis.set(cooldownKey, "idle", { pxMs: cooldown });
+      } finally {
+        await this.deps.redis.eval(RELEASE_LEASE, [leaseKey], [owner]);
+      }
+    }
+  }
+
+  /** Normalizes a page through the P0c funnel. P1 executes home only. */
+  private async fetch(workspaceId: string, row: DueRow): Promise<Array<NormalizedFeedItem | null>> {
+    if (this.deps === undefined) return [];
+    if (row.source_kind !== "home") {
+      throw new UnsupportedSourceError(row.source_kind);
+    }
+    if (row.connection_id === null) {
+      // home is always connection-bound (a platform_feed column); a NULL
+      // connection row is corrupt, not pollable.
+      throw new UnsupportedSourceError("home-without-connection");
+    }
+    if (!this.deps.registry.has(row.provider)) throw new UnsupportedSourceError(`unknown-provider:${row.provider}`);
+    const connector = this.deps.registry.get(row.provider);
+    if (connector.getFeed === undefined) throw new UnsupportedSourceError(`feed-unsupported:${row.provider}`);
+    const connection = await this.deps.connection(workspaceId, row.connection_id);
+    const hostKey = this.deps.hostKeyOf(row.provider, connection);
+    await this.deps.consumeBudget(hostKey);
+    const page = await connector.getFeed(connection, { kind: "home", limit: 40 });
+    return (page?.items ?? []).map((item: FeedItem) => normalizeFeedItem(item, connection));
+  }
+
+  private async recordSuccess(workspaceId: string, sourceId: string, intervalMs: number): Promise<void> {
+    await withTenant(workspaceId, async (client) => {
+      await client.query(
+        `UPDATE column_sources
+            SET state = 'ready', last_error = NULL, last_polled_at = now(), consecutive_failures = 0,
+                next_poll_at = now() + ($3::int * interval '1 millisecond'), updated_at = now()
+          WHERE workspace_id = $1 AND id = $2`,
+        [workspaceId, sourceId, intervalMs],
+      );
+    });
+  }
+
+  private async recordFailure(workspaceId: string, row: DueRow, error: unknown, intervalMs: number): Promise<{ cooldownMs: number }> {
+    const rateLimited = error instanceof RateLimitError;
+    const unsupported = error instanceof UnsupportedSourceError;
+    const retryAfter = error instanceof RateLimitError ? error.retryAfterMs : undefined;
+    const failures = row.consecutive_failures;
+    const backoff = unsupported ? intervalMs : backoffDelayMs(failures + 1, intervalMs);
+    const cooldownMs = rateLimited && retryAfter !== undefined ? Math.max(intervalMs, retryAfter) : backoff;
+    await withTenant(workspaceId, async (client) => {
+      await client.query(
+        `UPDATE column_sources
+            SET state = $3, last_error = $4, last_polled_at = now(),
+                consecutive_failures = CASE WHEN $3 = 'unsupported' THEN consecutive_failures ELSE consecutive_failures + 1 END,
+                next_poll_at = now() + ($5::bigint * interval '1 millisecond'), updated_at = now()
+          WHERE workspace_id = $1 AND id = $2`,
+        [workspaceId, row.id,
+          unsupported ? "unsupported" : rateLimited ? "rate_limited" : "error",
+          unsupported ? `unsupported source kind ${row.source_kind}` : error instanceof Error ? error.message.slice(0, 240) : "poll failed",
+          cooldownMs],
+      );
+    }).catch(() => this.logger.warn("Column source state write-back unavailable"));
+    return { cooldownMs };
+  }
+
+  /**
+   * Workspace listing spans tenants by definition, so it runs on the pool
+   * with no tenant binding; every actual read/write below re-enters
+   * withTenant(workspaceId) so FORCE RLS still binds per source.
+   */
+  /**
+   * Explicit refresh (§1.4 POST :id/refresh): mark this column's sources due
+   * NOW. The per-source cooldown/lease still arbitrates the actual call, so a
+   * refresh button cannot bypass the interval or double-fire mid-poll.
+   */
+  /**
+   * Explicit refresh (§1.4 POST :id/refresh) forces this column's sources due,
+   * but not through a cooldown that is still authoritative in the DB: the
+   * Redis cooldown is a cache (a flush loses it), so next_poll_at — persisted
+   * — is the guard a forced refresh must still respect. FORCE_FLOOR_MS is a
+   * deliberately small window: the button stays responsive for a manual
+   * refresh while a double-click or a cache flush cannot double-poll a host.
+   */
+  async forceColumnDue(workspaceId: string, columnId: string): Promise<number> {
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        `UPDATE column_sources SET next_poll_at = now(), updated_at = now()
+          WHERE workspace_id = $1 AND column_id = $2 AND state <> 'disabled'
+            AND (last_polled_at IS NULL OR last_polled_at <= now() - ($3::bigint * interval '1 millisecond'))
+          RETURNING id`,
+        [workspaceId, columnId, FORCE_FLOOR_MS],
+      );
+      return result.rowCount ?? 0;
+    });
+  }
+
+  /** User-facing enable/disable of a single source (state machine §3.4). */
+  async setSourceDisabled(workspaceId: string, sourceId: string, disabled: boolean): Promise<void> {
+    await withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        `UPDATE column_sources SET state = $3, next_poll_at = CASE WHEN $3 = 'disabled' THEN NULL ELSE now() END, updated_at = now()
+          WHERE workspace_id = $1 AND id = $2`,
+        [workspaceId, sourceId, disabled ? "disabled" : "pending"],
+      );
+      if ((result.rowCount ?? 0) === 0) throw new Error(`column source ${sourceId} not found`);
+    });
+  }
+
+  private async workspaces(): Promise<string[]> {
+    const result = await pool.query<{ id: string }>("SELECT id FROM workspaces ORDER BY id");
+    return result.rows.map((row) => row.id);
+  }
+}
+
+/** Raised for source kinds P1 does not execute; parks the row in `unsupported`. */
+export class UnsupportedSourceError extends Error {
+  constructor(reason: string) {
+    super(`column source unsupported in P1: ${reason}`);
+    this.name = "UnsupportedSourceError";
+  }
+}
diff --git a/apps/api/src/feeds/column-store.ts b/apps/api/src/feeds/column-store.ts
new file mode 100644
index 0000000..911c90d
--- /dev/null
+++ b/apps/api/src/feeds/column-store.ts
@@ -0,0 +1,652 @@
+/**
+ * Columns persistence (P1 — design §1.2/§1.4).
+ *
+ * `stream_columns` (021) is the persisted column list; this repository owns
+ * every mutation plus the resolved-source rows in `column_sources` (026) and
+ * the per-source item rows in `feed_items`/`feed_item_columns` written by the
+ * poll loop. Reads run under `withTenant` so FORCE RLS binds honestly.
+ *
+ * Everything the client can send is parsed with the P0a core validators
+ * (`parseStreamColumnSpec`, `parseRefreshPolicyClamped`, `clampTitle`,
+ * `clampPosition`) — the DB CHECKs are backstops, never the validation layer.
+ * `StreamColumnsValidationError` is translated to 422 at the controller.
+ */
+import { BadRequestException, Inject, Injectable, NotFoundException, Optional, UnprocessableEntityException } from "@nestjs/common";
+import { createHash } from "node:crypto";
+import type { PoolClient } from "pg";
+import {
+  clampPosition, clampTitle, parseRefreshPolicyClamped, parseStreamColumnSpec,
+  StreamColumnsValidationError, type RefreshPolicy, type StreamColumnSpec, type StreamColumnType,
+} from "@tactical-media-broadcast-hub/core";
+import type { SessionPayload } from "../auth/session.js";
+import { withTenant } from "../db/client.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import type { NormalizedFeedItem } from "./feed-normalize.js";
+import type { ConnectionSummary } from "../connections/connections.service.js";
+
+export type ColumnSourceKind = "home" | "mentions" | "search" | "author";
+export type ColumnSourceState =
+  | "pending" | "ready" | "stale" | "error" | "unsupported" | "rate_limited" | "budget_paused" | "disabled";
+
+export interface ColumnRecord {
+  id: string;
+  type: StreamColumnType;
+  title: string;
+  position: number;
+  spec: StreamColumnSpec;
+  refreshPolicy: RefreshPolicy;
+  createdAt: string;
+  updatedAt: string;
+}
+
+/** `ColumnView.source` (design §1.4): the scheduler-facing row, squashed. */
+export interface ColumnSourceView {
+  id: string;
+  /** Owning column — present so a bulk source query can be grouped per column. */
+  columnId: string;
+  provider: string;
+  connectionId: string | null;
+  sourceKind: ColumnSourceKind;
+  query: string | null;
+  actorRef: string | null;
+  state: ColumnSourceState;
+  lastError: string | null;
+  lastPolledAt: string | null;
+  nextPollAt: string | null;
+  consecutiveFailures: number;
+}
+
+export interface CreateColumn {
+  type: StreamColumnType;
+  title: string;
+  position?: number;
+  spec: unknown;
+  refreshPolicy?: unknown;
+}
+
+export interface UpdateColumn {
+  title?: string;
+  position?: number;
+  spec?: unknown;
+  refreshPolicy?: unknown;
+}
+
+export interface StoredFeedItem {
+  id: string;
+  dedupKey: string;
+  createdAtRemote: string;
+  item: NormalizedFeedItem;
+}
+
+/** The identity one poll resolves to — see `sourceIdentities` below. */
+interface SourceIdentity {
+  provider: string;
+  connectionId: string | null;
+  sourceKind: ColumnSourceKind;
+  query: string | null;
+  actorRef: string | null;
+}
+
+const identityKey = (identity: SourceIdentity): string =>
+  JSON.stringify([identity.provider, identity.connectionId, identity.sourceKind, identity.query, identity.actorRef]);
+
+export function mapValidationError<T>(parse: () => T): T {
+  try {
+    return parse();
+  } catch (error) {
+    if (error instanceof StreamColumnsValidationError) throw new UnprocessableEntityException(error.message);
+    throw error;
+  }
+}
+
+/**
+ * sha256(workspace | provider | canonical remote id) — design §3.3. The
+ * canonicalization keeps a provider that restates an item with decorations
+ * (e.g. Mastodon's `scheduled:123` vs `123`) from double-storing the same
+ * remote object.
+ */
+export function dedupKeyFor(workspaceId: string, provider: string, remoteId: string): string {
+  const canonical = remoteId.replace(/^scheduled:/, "");
+  return createHash("sha256").update(`${workspaceId}|${provider}|${canonical}`).digest("hex");
+}
+
+/**
+ * The polled identities a column spec resolves to (§3.3/§3.4). platform_feed
+ * is the degenerate case: one connection, one kind per source row. keyword and
+ * saved_search expand to one keyless search source per platform. account_list
+ * expands to one author source per account entry.
+ */
+export function sourceIdentities(type: StreamColumnType, spec: StreamColumnSpec): SourceIdentity[] {
+  switch (type) {
+    case "platform_feed": {
+      const feed = spec as import("@tactical-media-broadcast-hub/core").PlatformFeedSpec;
+      const kinds = feed.kinds.length > 0 ? feed.kinds : (["home"] as const);
+      return kinds.map((kind): SourceIdentity => ({
+        provider: "", connectionId: feed.connectionId, sourceKind: kind, query: null, actorRef: null,
+      }));
+    }
+    case "keyword":
+    case "saved_search": {
+      const keyword = spec as import("@tactical-media-broadcast-hub/core").KeywordSpec;
+      return keyword.platforms.map((provider): SourceIdentity => ({
+        provider, connectionId: null, sourceKind: "search", query: keyword.query, actorRef: null,
+      }));
+    }
+    case "account_list": {
+      const list = spec as import("@tactical-media-broadcast-hub/core").AccountListSpec;
+      return list.accounts.map((account): SourceIdentity => ({
+        provider: account.provider, connectionId: null, sourceKind: "author", query: null, actorRef: account.handle,
+      }));
+    }
+  }
+}
+
+/** Providers referenced by a spec (empty for platform_feed: the connection supplies it). */
+export function columnProviders(type: StreamColumnType, spec: StreamColumnSpec): string[] {
+  switch (type) {
+    case "platform_feed": return [];
+    case "keyword":
+    case "saved_search": return (spec as import("@tactical-media-broadcast-hub/core").KeywordSpec).platforms;
+    case "account_list": return (spec as import("@tactical-media-broadcast-hub/core").AccountListSpec).accounts.map((account) => account.provider);
+  }
+}
+
+/** The title today's implicit column renders: "Display Name · handle" (web streams-data liveColumns). */
+export function seedTitle(row: ConnectionSummary): string {
+  const displayName = String(row.fields.displayName ?? "").trim() || row.channelId;
+  const handle = String(row.fields.handle ?? "").trim() || row.channelId;
+  return clampTitle(`${displayName} · ${handle}`);
+}
+
+interface ColumnRow {
+  id: string; type: StreamColumnType; title: string; position: number;
+  spec: unknown; refresh_policy: unknown; created_at: Date; updated_at: Date;
+}
+
+const COLUMN_SELECT = "id, type, title, position, spec, refresh_policy, created_at, updated_at";
+
+function toRecord(row: ColumnRow): ColumnRecord {
+  return {
+    id: row.id,
+    type: row.type,
+    title: row.title,
+    position: row.position,
+    spec: mapValidationError(() => parseStreamColumnSpec(row.type, row.spec)),
+    refreshPolicy: parseRefreshPolicyClamped(row.refresh_policy ?? {}),
+    createdAt: row.created_at.toISOString(),
+    updatedAt: row.updated_at.toISOString(),
+  };
+}
+
+const SOURCE_SELECT = `SELECT s.id, s.column_id, s.provider, s.connection_id, s.source_kind, s.query, s.actor_ref,
+  s.state, s.last_error, s.last_polled_at, s.next_poll_at, s.consecutive_failures
+  FROM column_sources s WHERE s.workspace_id = $1`;
+
+function sourceFromRow(row: Record<string, unknown>): ColumnSourceView {
+  return {
+    id: String(row.id),
+    columnId: String(row.column_id),
+    provider: String(row.provider),
+    connectionId: row.connection_id === null || row.connection_id === undefined ? null : String(row.connection_id),
+    sourceKind: row.source_kind as ColumnSourceKind,
+    query: row.query === null || row.query === undefined ? null : String(row.query),
+    actorRef: row.actor_ref === null || row.actor_ref === undefined ? null : String(row.actor_ref),
+    state: row.state as ColumnSourceState,
+    lastError: row.last_error === null || row.last_error === undefined ? null : String(row.last_error),
+    lastPolledAt: isoOrNull(row.last_polled_at),
+    nextPollAt: isoOrNull(row.next_poll_at),
+    consecutiveFailures: Number(row.consecutive_failures ?? 0),
+  };
+}
+
+function isoOrNull(value: unknown): string | null {
+  return value === null || value === undefined ? null : (value as Date).toISOString();
+}
+
+export interface ColumnStoreDependencies {
+  /** Resolve a connection's provider for platform_feed source rows. */
+  providerOf(workspaceId: string, connectionId: string): Promise<string>;
+  /** Feed-capable connection summaries — the lazy seeding input. */
+  connections(workspaceId: string): Promise<ConnectionSummary[]>;
+}
+
+export const COLUMN_STORE_DEPENDENCIES = Symbol("COLUMN_STORE_DEPENDENCIES");
+
+@Injectable()
+export class ColumnStore {
+  constructor(@Optional() @Inject(COLUMN_STORE_DEPENDENCIES) private readonly deps?: ColumnStoreDependencies) {}
+
+  private async providerOf(workspaceId: string, connectionId: string): Promise<string> {
+    if (this.deps) return this.deps.providerOf(workspaceId, connectionId);
+    return withTenant(workspaceId, async (client): Promise<string> => {
+      const result = await client.query<{ provider: string }>(
+        "SELECT provider FROM connections WHERE id = $1 AND workspace_id = $2 AND disconnected_at IS NULL", [connectionId, workspaceId]);
+      const row = result.rows[0];
+      if (row === undefined) throw new NotFoundException(`connection ${connectionId} not found`);
+      return row.provider;
+    });
+  }
+
+  private async connections(workspaceId: string): Promise<ConnectionSummary[]> {
+    if (this.deps) return this.deps.connections(workspaceId);
+    const { PgConnectionStore } = await import("../connections/connection-store.js");
+    return new PgConnectionStore().list(workspaceId);
+  }
+
+  async list(workspaceId: string): Promise<ColumnRecord[]> {
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT ${COLUMN_SELECT} FROM stream_columns WHERE deleted_at IS NULL ORDER BY position, created_at`);
+      return result.rows.map((row) => toRecord(row as ColumnRow));
+    });
+  }
+
+  async get(workspaceId: string, id: string): Promise<ColumnRecord> {
+    return withTenant(workspaceId, async (client) => this.read(client, workspaceId, id));
+  }
+
+  async sources(workspaceId: string, columnId?: string): Promise<ColumnSourceView[]> {
+    return withTenant(workspaceId, async (client) => {
+      const result = columnId === undefined
+        ? await client.query(`${SOURCE_SELECT} ORDER BY s.created_at`, [workspaceId])
+        : await client.query(`${SOURCE_SELECT} AND s.column_id = $2 ORDER BY s.created_at`, [workspaceId, columnId]);
+      return result.rows.map((row) => sourceFromRow(row));
+    });
+  }
+
+  async create(session: SessionPayload, input: CreateColumn): Promise<ColumnRecord> {
+    const spec = mapValidationError(() => parseStreamColumnSpec(input.type, input.spec));
+    const policy = parseRefreshPolicyClamped(input.refreshPolicy ?? {});
+    const title = clampTitle(input.title ?? "");
+    if (title === "") throw new UnprocessableEntityException("title must be 1..80 characters after trimming");
+    return withTenant(session.workspaceId, async (client) => {
+      await this.assertSpecReferenceable(client, session.workspaceId, input.type, spec);
+      const position = input.position === undefined
+        ? await this.nextPosition(client, session.workspaceId)
+        : clampPosition(input.position);
+      const result = await client.query(
+        `INSERT INTO stream_columns (workspace_id, type, title, position, spec, refresh_policy, created_by)
+         VALUES ($1,$2,$3,$4,$5,$6,$7) RETURNING ${COLUMN_SELECT}`,
+        [session.workspaceId, input.type, title, position, JSON.stringify(spec), JSON.stringify(policy), session.userId],
+      );
+      const record = toRecord(result.rows[0] as ColumnRow);
+      await this.writeSources(client, session.workspaceId, record.id, input.type, spec);
+      await appendTenantAudit(session.workspaceId, {
+        actorUserId: session.userId, actorRole: session.role, action: "columns.created",
+        targetType: "stream_column", targetId: record.id, diff: { type: input.type, title },
+      });
+      return record;
+    });
+  }
+
+  async update(session: SessionPayload, id: string, input: UpdateColumn): Promise<ColumnRecord> {
+    if (Object.keys(input).length === 0) throw new BadRequestException("no recognized fields to update");
+    return withTenant(session.workspaceId, async (client) => {
+      await client.query("SELECT id FROM stream_columns WHERE workspace_id = $1 AND id = $2 AND deleted_at IS NULL FOR UPDATE", [session.workspaceId, id]);
+      const current = await this.read(client, session.workspaceId, id);
+      const title = input.title === undefined ? current.title : clampTitle(input.title);
+      if (title === "") throw new UnprocessableEntityException("title must be 1..80 characters after trimming");
+      // Column type is immutable (design §1.4: PATCH carries title/position/
+      // spec/refresh_policy); a different type is a new column.
+      const spec = input.spec === undefined ? current.spec : mapValidationError(() => parseStreamColumnSpec(current.type, input.spec));
+      const policy = input.refreshPolicy === undefined ? current.refreshPolicy : parseRefreshPolicyClamped(input.refreshPolicy);
+      const position = input.position === undefined ? current.position : clampPosition(input.position);
+      if (input.spec !== undefined) await this.assertSpecReferenceable(client, session.workspaceId, current.type, spec);
+      const result = await client.query(
+        `UPDATE stream_columns SET title = $3, position = $4, spec = $5, refresh_policy = $6, updated_at = now()
+         WHERE workspace_id = $1 AND id = $2 AND deleted_at IS NULL RETURNING ${COLUMN_SELECT}`,
+        [session.workspaceId, id, title, position, JSON.stringify(spec), JSON.stringify(policy)],
+      );
+      if (result.rows[0] === undefined) throw new NotFoundException(`column ${id} not found`);
+      if (input.spec !== undefined) await this.rewriteSources(client, session.workspaceId, id, current.type, spec);
+      await appendTenantAudit(session.workspaceId, {
+        actorUserId: session.userId, actorRole: session.role, action: "columns.updated",
+        targetType: "stream_column", targetId: id,
+        diff: { titleChanged: title !== current.title, positionChanged: position !== current.position, specChanged: input.spec !== undefined },
+      });
+      return toRecord(result.rows[0] as ColumnRow);
+    });
+  }
+
+  private async writeSources(client: PoolClient, workspaceId: string, columnId: string, type: StreamColumnType, spec: StreamColumnSpec): Promise<void> {
+    for (const identity of sourceIdentities(type, spec)) {
+      const provider = identity.provider !== "" ? identity.provider : await this.providerOf(workspaceId, identity.connectionId ?? "");
+      await client.query(
+        `INSERT INTO column_sources (workspace_id, column_id, provider, connection_id, source_kind, query, actor_ref)
+         VALUES ($1,$2,$3,$4,$5,$6,$7)
+         ON CONFLICT (workspace_id, column_id, provider, source_kind, connection_id, query, actor_ref) DO NOTHING`,
+        [workspaceId, columnId, provider, identity.connectionId, identity.sourceKind, identity.query, identity.actorRef],
+      );
+    }
+  }
+
+  /** Spec identity changes rewrite the source set; identities no longer referenced by this column are dropped. */
+  private async rewriteSources(client: PoolClient, workspaceId: string, columnId: string, type: StreamColumnType, spec: StreamColumnSpec): Promise<void> {
+    const wanted = new Set(sourceIdentities(type, spec).map(identityKey));
+    const existing = await client.query<{ id: string; provider: string; connection_id: string | null; source_kind: ColumnSourceKind; query: string | null; actor_ref: string | null }>(
+      "SELECT id, provider, connection_id, source_kind, query, actor_ref FROM column_sources WHERE workspace_id = $1 AND column_id = $2", [workspaceId, columnId]);
+    for (const row of existing.rows) {
+      const identity: SourceIdentity = { provider: row.provider, connectionId: row.connection_id, sourceKind: row.source_kind, query: row.query, actorRef: row.actor_ref };
+      if (!wanted.has(identityKey(identity))) {
+        await client.query("DELETE FROM column_sources WHERE workspace_id = $1 AND id = $2", [workspaceId, row.id]);
+      }
+    }
+    await this.writeSources(client, workspaceId, columnId, type, spec);
+  }
+
+  async remove(session: SessionPayload, id: string): Promise<void> {
+    await withTenant(session.workspaceId, async (client) => {
+      await client.query("SELECT id FROM stream_columns WHERE workspace_id = $1 AND id = $2 AND deleted_at IS NULL FOR UPDATE", [session.workspaceId, id]);
+      const result = await client.query(
+        "UPDATE stream_columns SET deleted_at = now(), updated_at = now() WHERE workspace_id = $1 AND id = $2 AND deleted_at IS NULL RETURNING id", [session.workspaceId, id]);
+      if (result.rows[0] === undefined) throw new NotFoundException(`column ${id} not found`);
+      await appendTenantAudit(session.workspaceId, {
+        actorUserId: session.userId, actorRole: session.role, action: "columns.deleted",
+        targetType: "stream_column", targetId: id,
+      });
+    });
+  }
+
+  /**
+   * Explicit order (design §1.4 POST /reorder): the client sends the full
+   * ordered id list; positions are rewritten densely. Unknown, foreign or
+   * missing ids are a 400 — a partial reorder would corrupt the order.
+   */
+  async reorder(session: SessionPayload, ids: string[]): Promise<ColumnRecord[]> {
+    if (ids.length === 0) return this.list(session.workspaceId);
+    if (new Set(ids).size !== ids.length) throw new BadRequestException("reorder ids must be unique");
+    return withTenant(session.workspaceId, async (client) => {
+      const existing = await client.query<{ id: string }>(
+        "SELECT id FROM stream_columns WHERE workspace_id = $1 AND deleted_at IS NULL", [session.workspaceId]);
+      if (ids.length !== existing.rows.length || !existing.rows.every((row) => ids.includes(row.id))) {
+        throw new BadRequestException("reorder must list every column in the workspace exactly once");
+      }
+      // Two-phase write: the unique (workspace_id, position) index would fire
+      // mid-swap if positions were assigned in place (e.g. moving column 0 to
+      // the end collides with the row already at that slot). Parking every row
+      // at a high negative offset first leaves the final range untouched, so
+      // the second pass can never collide. Offsets are outside the CHECK
+      // (position >= 0) only transiently... so instead park at (n + i), which
+      // is >= 0, unique within the transaction, and freed before phase two.
+      // Phase 1 — park every row at a unique high slot (n, n+1, …) so the
+      // unique (workspace_id, position) index can't fire mid-reorder.
+      let park = ids.length;
+      for (const id of ids) {
+        await client.query("UPDATE stream_columns SET position = $3 WHERE workspace_id = $1 AND id = $2", [session.workspaceId, id, park]);
+        park += 1;
+      }
+      // Phase 2 — assign final dense ranks in the REQUESTED order. The parked
+      // range is disjoint from [0, n), so no intermediate state collides.
+      const byId = new Map(ids.map((id, index) => [id, index] as const));
+      const current = await client.query<ColumnRow>(
+        `SELECT ${COLUMN_SELECT} FROM stream_columns WHERE workspace_id = $1 AND deleted_at IS NULL`, [session.workspaceId]);
+      const records = current.rows
+        .map((row) => toRecord(row as ColumnRow))
+        .sort((a, b) => (byId.get(a.id) ?? 0) - (byId.get(b.id) ?? 0));
+      let rank = 0;
+      for (const record of records) {
+        await client.query("UPDATE stream_columns SET position = $3, updated_at = now() WHERE workspace_id = $1 AND id = $2", [session.workspaceId, record.id, rank]);
+        record.position = rank;
+        rank += 1;
+      }
+      await appendTenantAudit(session.workspaceId, {
+        actorUserId: session.userId, actorRole: session.role, action: "columns.reordered",
+        targetType: "workspace", targetId: session.workspaceId, diff: { count: ids.length },
+      });
+      return records;
+    });
+  }
+
+  /**
+   * Lazy seeding (design §6 P1): on the first column-API touch for a workspace
+   * with no columns at all, materialize TODAY's implicit /feeds columns — one
+   * platform_feed column per feed-capable connection, titled exactly like the
+   * implicit column the UI renders today ("Display · handle", kinds ["home"],
+   * position by connection creation order), so the Streams page is unchanged.
+   * Idempotent by construction: a second call sees a non-empty column list and
+   * seeds nothing — including for connections added later.
+   */
+  async ensureSeeded(workspaceId: string, connections: ConnectionSummary[], capable: (row: ConnectionSummary) => boolean): Promise<{ seeded: number }> {
+    const rows = connections.filter(capable);
+    if (rows.length === 0) return { seeded: 0 };
+    return withTenant(workspaceId, async (client) => {
+      // Serialize concurrent first touches without taking a row lock on
+      // workspaces itself: a FOR UPDATE here deadlocks with any FK insert
+      // into audit_log/column_sources from a nested withTenant client,
+      // because FK validation takes FOR KEY SHARE on the parent workspace
+      // row. Advisory xact locks never block key-share, so seeding
+      // serializes while audits and FK checks proceed.
+      await client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [`columns-seed:${workspaceId}`]);
+      const existing = await client.query<{ count: string }>(
+        "SELECT count(*)::text AS count FROM stream_columns WHERE workspace_id = $1 AND deleted_at IS NULL", [workspaceId]);
+      if (Number(existing.rows[0]?.count ?? 0) > 0) return { seeded: 0 };
+      const seeder = await client.query<{ user_id: string }>(
+        "SELECT m.user_id FROM memberships m JOIN users u ON u.id = m.user_id WHERE m.workspace_id = $1 ORDER BY m.created_at, u.created_at LIMIT 1", [workspaceId]);
+      const createdBy = seeder.rows[0]?.user_id;
+      if (createdBy === undefined) return { seeded: 0 }; // no member to attribute
+      let seeded = 0;
+      let position = 0;
+      for (const row of rows) {
+        const spec = { connectionId: row.id, kinds: ["home"] } as const;
+        const inserted = await client.query<{ id: string }>(
+          `INSERT INTO stream_columns (workspace_id, type, title, position, spec, refresh_policy, created_by)
+           VALUES ($1,'platform_feed',$2,$3,$4,'{}',$5) RETURNING id`,
+          [workspaceId, seedTitle(row), position, JSON.stringify(spec), createdBy],
+        );
+        const columnId = inserted.rows[0]?.id;
+        if (columnId === undefined) continue;
+        await client.query(
+          `INSERT INTO column_sources (workspace_id, column_id, provider, connection_id, source_kind)
+           VALUES ($1,$2,$3,$4,'home')
+           ON CONFLICT (workspace_id, column_id, provider, source_kind, connection_id, query, actor_ref) DO NOTHING`,
+          [workspaceId, columnId, row.provider, row.id],
+        );
+        seeded += 1;
+        position += 1;
+      }
+      if (seeded > 0) await appendTenantAudit(workspaceId, {
+        actorUserId: null, actorRole: "system", action: "columns.seeded",
+        targetType: "workspace", targetId: workspaceId, diff: { seeded },
+      });
+      return { seeded };
+    });
+  }
+
+  /**
+   * import-saved-searches (design §1.4): the localStorage saved-searches
+   * contract moves server-side. Each query becomes a saved_search column over
+   * the platforms the workspace can actually search, defaulting to every
+   * connected feed provider when the client sends none. Idempotent per query:
+   * a live saved_search column with the same query is skipped.
+   */
+  async importSavedSearches(
+    session: SessionPayload, queries: string[], platforms: string[],
+  ): Promise<{ imported: number; skipped: number }> {
+    if (platforms.length === 0) return { imported: 0, skipped: queries.length };
+    return withTenant(session.workspaceId, async (client) => {
+      let imported = 0;
+      let skipped = 0;
+      for (const raw of queries) {
+        const query = raw.trim();
+        if (query === "") { skipped += 1; continue; }
+        const duplicate = await client.query<{ id: string }>(
+          `SELECT id FROM stream_columns WHERE workspace_id = $1 AND deleted_at IS NULL AND type = 'saved_search'
+             AND spec->>'query' = $2 LIMIT 1`, [session.workspaceId, query]);
+        if (duplicate.rows[0] !== undefined) { skipped += 1; continue; }
+        const spec = { query, platforms, matchMode: "any" } as const;
+        const title = clampTitle(query);
+        if (title === "") { skipped += 1; continue; }
+        const position = await this.nextPosition(client, session.workspaceId);
+        const inserted = await client.query<{ id: string }>(
+          `INSERT INTO stream_columns (workspace_id, type, title, position, spec, refresh_policy, created_by)
+           VALUES ($1,'saved_search',$2,$3,$4,'{}',$5) RETURNING id`,
+          [session.workspaceId, title, position, JSON.stringify(spec), session.userId],
+        );
+        const columnId = inserted.rows[0]?.id;
+        if (columnId === undefined) { skipped += 1; continue; }
+        await this.writeSources(client, session.workspaceId, columnId, "saved_search",
+          parseStreamColumnSpec("saved_search", spec));
+        imported += 1;
+      }
+      if (imported > 0) await appendTenantAudit(session.workspaceId, {
+        actorUserId: session.userId, actorRole: session.role, action: "columns.saved_searches_imported",
+        targetType: "workspace", targetId: session.workspaceId, diff: { imported, skipped },
+      });
+      return { imported, skipped };
+    });
+  }
+
+  /**
+   * Poll-time item persistence (§3.3): first writer wins per dedup key (the
+   * cross-column dedup), then fan-out rows link the item to every column
+   * whose source shares this source's identity — which is how "same account
+   * in two columns costs one poll" still surfaces items in both.
+   */
+  async storeItems(workspaceId: string, sourceId: string, items: NormalizedFeedItem[]): Promise<{ stored: number; fanned: number }> {
+    if (items.length === 0) return { stored: 0, fanned: 0 };
+    return withTenant(workspaceId, async (client) => {
+      const found = await client.query<{ id: string; provider: string; connection_id: string | null; source_kind: ColumnSourceKind; query: string | null; actor_ref: string | null }>(
+        "SELECT id, provider, connection_id, source_kind, query, actor_ref FROM column_sources WHERE workspace_id = $1 AND id = $2", [workspaceId, sourceId]);
+      const source = found.rows[0];
+      if (source === undefined) return { stored: 0, fanned: 0 };
+      const sharing = await client.query<{ column_id: string }>(
+        `SELECT column_id FROM column_sources
+          WHERE workspace_id = $1 AND provider = $2 AND source_kind = $3
+            AND connection_id IS NOT DISTINCT FROM $4 AND query IS NOT DISTINCT FROM $5 AND actor_ref IS NOT DISTINCT FROM $6
+            AND state <> 'disabled'`,
+        [workspaceId, source.provider, source.source_kind, source.connection_id, source.query, source.actor_ref]);
+      const columnIds = sharing.rows.map((row) => row.column_id);
+      let stored = 0;
+      let fanned = 0;
+      for (const item of items) {
+        const dedupKey = dedupKeyFor(workspaceId, item.provider, item.remoteId);
+        // First writer wins per dedup key (the workspace-wide cross-column
+        // dedup, §3.3) — the returning row resolves the item id either way.
+        const inserted = await client.query<{ id: string }>(
+          `INSERT INTO feed_items (workspace_id, dedup_key, provider, remote_id, item_id, author_handle, author_ref, url,
+             created_at_remote, fetched_at, content, plain_text, media, metrics, source_id, expires_at)
+           VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,now(),$10,$11,$12,$13,$14,$15)
+           ON CONFLICT (workspace_id, dedup_key) DO UPDATE SET fetched_at = feed_items.fetched_at RETURNING id`,
+          [workspaceId, dedupKey, item.provider, item.remoteId, item.id, item.authorHandle, item.authorRef, item.url,
+            item.createdAt.toISOString(), JSON.stringify(item.content), item.plainText, JSON.stringify(item.media),
+            JSON.stringify(item.metrics), sourceId, item.expiresAt === null || item.expiresAt === undefined ? null : item.expiresAt.toISOString()],
+        );
+        const itemId = inserted.rows[0]?.id;
+        if (itemId === undefined) continue;
+        stored += 1;
+        // Fan out regardless of who inserted: an item ingested for one source
+        // identity is visible to EVERY column sharing that identity, including
+        // items an earlier poll already stored (§3.3) — otherwise the second
+        // column's dedup-hit items would never get their link rows.
+        for (const columnId of columnIds) {
+          const linked = await client.query(
+            "INSERT INTO feed_item_columns (workspace_id, item_id, column_id) VALUES ($1,$2,$3) ON CONFLICT DO NOTHING",
+            [workspaceId, itemId, columnId]);
+          fanned += linked.rowCount ?? 0;
+        }
+      }
+      return { stored, fanned };
+    });
+  }
+
+  /**
+   * Keyset page for GET /feeds/columns/:id/items (§1.4). Cursor rule:
+   * (created_at_remote DESC, dedup_key DESC) — a pure position in a total
+   * order, so paging survives cache flushes and later insertions alike.
+   */
+  async columnItems(
+    workspaceId: string, columnId: string, options: { cursor?: { at: number; key: string }; limit: number },
+  ): Promise<{ items: StoredFeedItem[]; nextCursor: string | null }> {
+    return withTenant(workspaceId, async (client) => {
+      const column = await client.query("SELECT id FROM stream_columns WHERE workspace_id = $1 AND id = $2 AND deleted_at IS NULL", [workspaceId, columnId]);
+      if (column.rows[0] === undefined) throw new NotFoundException(`column ${columnId} not found`);
+      const params: unknown[] = [workspaceId, columnId];
+      const filter = options.cursor === undefined ? "" : " AND (i.created_at_remote, i.dedup_key) < ($3::timestamptz, $4)";
+      if (options.cursor !== undefined) params.push(new Date(options.cursor.at).toISOString(), options.cursor.key);
+      params.push(options.limit + 1);
+      const result = await client.query(
+        `SELECT i.id, i.dedup_key, i.created_at_remote, i.provider, i.remote_id, i.item_id, i.author_handle,
+                i.author_ref, i.url, i.content, i.plain_text, i.media, i.metrics, i.expires_at
+         FROM feed_items i
+         JOIN feed_item_columns fic ON fic.item_id = i.id AND fic.column_id = $2
+         WHERE i.workspace_id = $1${filter}
+         ORDER BY i.created_at_remote DESC, i.dedup_key DESC
+         LIMIT $${params.length}`,
+        params,
+      );
+      const rows = result.rows;
+      const hasMore = rows.length > options.limit;
+      const items = (hasMore ? rows.slice(0, options.limit) : rows).map((row) => storedItemFromRow(row));
+      const last = items[items.length - 1];
+      return {
+        items,
+        nextCursor: hasMore && last
+          ? Buffer.from(JSON.stringify({ at: Date.parse(last.createdAtRemote), key: last.dedupKey })).toString("base64url")
+          : null,
+      };
+    });
+  }
+
+  private async nextPosition(client: PoolClient, workspaceId: string): Promise<number> {
+    const result = await client.query<{ max: number | null }>(
+      "SELECT max(position) AS max FROM stream_columns WHERE workspace_id = $1 AND deleted_at IS NULL", [workspaceId]);
+    return (result.rows[0]?.max ?? -1) + 1;
+  }
+
+  /** A spec's references must exist in the workspace before the column can persist. */
+  private async assertSpecReferenceable(client: PoolClient, workspaceId: string, type: StreamColumnType, spec: StreamColumnSpec): Promise<void> {
+    if (type === "platform_feed") {
+      const connectionId = (spec as import("@tactical-media-broadcast-hub/core").PlatformFeedSpec).connectionId;
+      const result = await client.query(
+        "SELECT 1 FROM connections WHERE workspace_id = $1 AND id = $2 AND disconnected_at IS NULL", [workspaceId, connectionId]);
+      if (result.rows[0] === undefined) throw new UnprocessableEntityException("platform_feed: connectionId does not reference a connection in this workspace");
+      return;
+    }
+    const providers = columnProviders(type, spec);
+    if (providers.length === 0) return;
+    const result = await client.query<{ provider: string }>(
+      "SELECT DISTINCT provider FROM connections WHERE workspace_id = $1 AND disconnected_at IS NULL AND provider = ANY($2)", [workspaceId, providers]);
+    const present = new Set(result.rows.map((row) => row.provider));
+    const missing = [...new Set(providers)].filter((provider) => !present.has(provider));
+    if (missing.length > 0) throw new UnprocessableEntityException(`no connection for provider(s): ${missing.join(", ")}`);
+  }
+
+  private async read(client: PoolClient, workspaceId: string, id: string): Promise<ColumnRecord> {
+    const result = await client.query(
+      `SELECT ${COLUMN_SELECT} FROM stream_columns WHERE workspace_id = $1 AND id = $2 AND deleted_at IS NULL`, [workspaceId, id]);
+    const row = result.rows[0];
+    if (row === undefined) throw new NotFoundException(`column ${id} not found`);
+    return toRecord(row as ColumnRow);
+  }
+}
+
+interface FeedItemRow {
+  id: string; dedup_key: string; created_at_remote: Date; provider: string; remote_id: string; item_id: string;
+  author_handle: string; author_ref: string | null; url: string | null; content: unknown; plain_text: string;
+  media: unknown; metrics: unknown; expires_at: Date | null;
+}
+
+function storedItemFromRow(row: FeedItemRow): StoredFeedItem {
+  const metrics = (typeof row.metrics === "object" && row.metrics !== null ? row.metrics : {}) as Record<string, number>;
+  const item: NormalizedFeedItem = {
+    id: row.item_id,
+    remoteId: row.remote_id,
+    provider: row.provider,
+    // The store page does not carry a live connection id; the column's source
+    // rows hold it, so the connectionId field is filled by the caller when it
+    // matters (the items endpoint derives it from the column spec).
+    connectionId: "",
+    authorHandle: row.author_handle,
+    authorRef: row.author_ref,
+    url: row.url,
+    text: row.plain_text,
+    content: row.content as NormalizedFeedItem["content"],
+    plainText: row.plain_text,
+    createdAt: row.created_at_remote,
+    mediaUrls: [],
+    media: Array.isArray(row.media) ? row.media as NormalizedFeedItem["media"] : [],
+    metrics,
+    expiresAt: row.expires_at,
+  };
+  return { id: row.id, dedupKey: row.dedup_key, createdAtRemote: new Date(row.created_at_remote).toISOString(), item };
+}
diff --git a/apps/api/src/feeds/columns.controller.ts b/apps/api/src/feeds/columns.controller.ts
new file mode 100644
index 0000000..8800064
--- /dev/null
+++ b/apps/api/src/feeds/columns.controller.ts
@@ -0,0 +1,300 @@
+/**
+ * Columns API (P1 — design §1.4).
+ *
+ * Routes (all under /feeds, the surface the Streams page already calls):
+ *   GET    /feeds/columns                        list (+ lazy seeding on first touch)
+ *   POST   /feeds/columns                        create
+ *   GET    /feeds/columns/:id                    one column
+ *   PATCH  /feeds/columns/:id                    update (title/position/spec/refreshPolicy)
+ *   DELETE /feeds/columns/:id                    soft delete
+ *   POST   /feeds/columns/reorder                explicit full-list order
+ *   POST   /feeds/columns/import-saved-searches  localStorage contract migration
+ *   GET    /feeds/columns/:id/items              keyset-cursored items
+ *   POST   /feeds/columns/:id/refresh            force a poll (cooldown-gated)
+ *   POST   /feeds/columns/:id/sources/:sourceId/disable|enable
+ *
+ * Writes are gated on `streams.columns.manage` (026 seed: Owner/Admin/Editor);
+ * reads stay on `draft.view` — the same permission /feeds uses, so every
+ * current reader keeps reading. GET /feeds is untouched except the additive
+ * `meta.columns` block.
+ */
+import { BadRequestException, Body, Controller, Delete, Get, Inject, NotFoundException, Param, Patch, Post, Query, Req, UnprocessableEntityException, UseGuards } from "@nestjs/common";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { parseId, parseLimit, requireObject, requireSession, requireString } from "../http/validation.js";
+import type { SessionPayload } from "../auth/session.js";
+import {
+  ColumnStore, mapValidationError, type ColumnRecord, type ColumnSourceView, type CreateColumn, type StoredFeedItem, type UpdateColumn,
+} from "./column-store.js";
+import { ColumnScheduler } from "./column-scheduler.js";
+import { FeedsService } from "./feeds.service.js";
+import type { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+
+export interface ColumnResponse extends ColumnRecord {
+  sources: ColumnSourceView[];
+}
+
+export interface ColumnItemsResponse {
+  items: StoredFeedItem[];
+  nextCursor: string | null;
+}
+
+/** DI token for the shared connector registry (single process-wide instance). */
+export const COLUMNS_REGISTRY = Symbol("COLUMNS_REGISTRY");
+
+@Controller("feeds/columns")
+@UseGuards(RbacGuard)
+export class ColumnsController {
+  constructor(
+    @Inject(ColumnStore) private readonly store: ColumnStore,
+    @Inject(ColumnScheduler) private readonly scheduler: ColumnScheduler,
+    @Inject(FeedsService) private readonly feeds: FeedsService,
+    @Inject(COLUMNS_REGISTRY) private readonly registry: ConnectorRegistry,
+  ) {}
+
+  @Get()
+  @RequirePermission("draft.view")
+  async list(@Req() request: AuthenticatedRequest): Promise<ColumnResponse[]> {
+    const session = requireSession(request);
+    await this.ensureSeeded(session);
+    return this.views(session.workspaceId, await this.store.list(session.workspaceId));
+  }
+
+  @Post()
+  @RequirePermission("streams.columns.manage")
+  async create(@Req() request: AuthenticatedRequest, @Body() body: unknown): Promise<ColumnResponse> {
+    const session = requireSession(request);
+    const input = parseCreate(body);
+    await this.ensureSeeded(session);
+    const record = await this.store.create(session, input);
+    return this.view(record, await this.store.sources(session.workspaceId, record.id));
+  }
+
+  @Get(":id")
+  @RequirePermission("draft.view")
+  async get(@Req() request: AuthenticatedRequest, @Param("id") id: string): Promise<ColumnResponse> {
+    const session = requireSession(request);
+    await this.ensureSeeded(session);
+    const record = await this.store.get(session.workspaceId, parseId(id));
+    return this.view(record, await this.store.sources(session.workspaceId, record.id));
+  }
+
+  @Patch(":id")
+  @RequirePermission("streams.columns.manage")
+  async update(@Req() request: AuthenticatedRequest, @Param("id") id: string, @Body() body: unknown): Promise<ColumnResponse> {
+    const session = requireSession(request);
+    const record = await this.store.update(session, parseId(id), parseUpdate(body));
+    return this.view(record, await this.store.sources(session.workspaceId, record.id));
+  }
+
+  @Delete(":id")
+  @RequirePermission("streams.columns.manage")
+  async remove(@Req() request: AuthenticatedRequest, @Param("id") id: string): Promise<{ id: string; deleted: true }> {
+    const session = requireSession(request);
+    const parsed = parseId(id);
+    await this.store.remove(session, parsed);
+    return { id: parsed, deleted: true };
+  }
+
+  @Post("reorder")
+  @RequirePermission("streams.columns.manage")
+  async reorder(@Req() request: AuthenticatedRequest, @Body() body: unknown): Promise<ColumnResponse[]> {
+    const session = requireSession(request);
+    const ids = parseIds(requireObject(body, "body").ids);
+    return this.views(session.workspaceId, await this.store.reorder(session, ids));
+  }
+
+  @Post("import-saved-searches")
+  @RequirePermission("streams.columns.manage")
+  async importSavedSearches(@Req() request: AuthenticatedRequest, @Body() body: unknown): Promise<{ imported: number; skipped: number }> {
+    const session = requireSession(request);
+    const payload = requireObject(body, "body");
+    const rawQueries = payload.queries;
+    if (!Array.isArray(rawQueries) || rawQueries.length === 0) {
+      throw new BadRequestException("queries must be a non-empty array of saved search strings");
+    }
+    for (const query of rawQueries) {
+      if (typeof query !== "string") throw new BadRequestException("queries must contain strings only");
+    }
+    if (rawQueries.length > 100) throw new BadRequestException("queries supports at most 100 entries per call");
+    const rawPlatforms = payload.platforms;
+    let platforms: string[];
+    if (rawPlatforms === undefined || rawPlatforms === null) {
+      platforms = this.searchCapableProviders(await this.connectedProviders(session));
+    } else {
+      if (!Array.isArray(rawPlatforms) || rawPlatforms.some((provider) => typeof provider !== "string")) {
+        throw new BadRequestException("platforms must be an array of provider ids");
+      }
+      platforms = [...new Set(rawPlatforms as string[])];
+      // Provider ids are opaque to the P0a schema by design; the registry is
+      // the app-side source of truth, so an unknown id is a 422 here rather
+      // than a saved_search column that can never resolve a source.
+      const unknown = platforms.filter((provider) => !this.registry.has(provider));
+      if (unknown.length > 0) {
+        throw new UnprocessableEntityException(`unknown provider id(s): ${unknown.join(", ")}`);
+      }
+    }
+    return this.store.importSavedSearches(session, rawQueries, platforms);
+  }
+
+  @Get(":id/items")
+  @RequirePermission("draft.view")
+  async items(
+    @Req() request: AuthenticatedRequest,
+    @Param("id") id: string,
+    @Query("cursor") cursor?: string,
+    @Query("limit") limit?: string,
+  ): Promise<ColumnItemsResponse> {
+    const session = requireSession(request);
+    return this.store.columnItems(session.workspaceId, parseId(id), {
+      cursor: cursor === undefined || cursor === "" ? undefined : decodeColumnCursor(cursor),
+      limit: parseLimit(limit, 40, 200),
+    });
+  }
+
+  @Post(":id/refresh")
+  @RequirePermission("streams.columns.manage")
+  async refresh(@Req() request: AuthenticatedRequest, @Param("id") id: string): Promise<{ id: string; refreshed: number }> {
+    const session = requireSession(request);
+    const parsed = parseId(id);
+    await this.store.get(session.workspaceId, parsed); // 404 before polling
+    // Force-due this column's sources; the scheduler's cooldown/lease still
+    // decides whether a call actually goes out (refresh cannot bypass them).
+    const forced = await this.forceDue(session.workspaceId, parsed);
+    const outcome = await this.scheduler.pollWorkspaceDue(session.workspaceId);
+    return { id: parsed, refreshed: forced > 0 ? outcome.polled : 0 };
+  }
+
+  @Post(":id/sources/:sourceId/disable")
+  @RequirePermission("streams.columns.manage")
+  async disableSource(@Req() request: AuthenticatedRequest, @Param("id") id: string, @Param("sourceId") sourceId: string): Promise<{ id: string; state: string }> {
+    const session = requireSession(request);
+    return this.setSourceState(session, parseId(id), parseId(sourceId), true);
+  }
+
+  @Post(":id/sources/:sourceId/enable")
+  @RequirePermission("streams.columns.manage")
+  async enableSource(@Req() request: AuthenticatedRequest, @Param("id") id: string, @Param("sourceId") sourceId: string): Promise<{ id: string; state: string }> {
+    const session = requireSession(request);
+    return this.setSourceState(session, parseId(id), parseId(sourceId), false);
+  }
+
+  // -- helpers -------------------------------------------------------------
+
+  private async setSourceState(session: SessionPayload, columnId: string, sourceId: string, disabled: boolean): Promise<{ id: string; state: string }> {
+    const sources = await this.store.sources(session.workspaceId, columnId);
+    const source = sources.find((row) => row.id === sourceId);
+    if (source === undefined) throw new NotFoundException(`source ${sourceId} not found on column ${columnId}`);
+    await this.scheduler.setSourceDisabled(session.workspaceId, sourceId, disabled);
+    return { id: sourceId, state: disabled ? "disabled" : "pending" };
+  }
+
+  private async ensureSeeded(session: SessionPayload): Promise<void> {
+    const connections = await this.feeds.capableConnections(session.workspaceId);
+    await this.store.ensureSeeded(session.workspaceId, connections, () => true);
+  }
+
+  /** Bulk view assembly: one source query, grouped per column. */
+  private async views(workspaceId: string, records: ColumnRecord[]): Promise<ColumnResponse[]> {
+    if (records.length === 0) return [];
+    const byColumn = new Map<string, ColumnSourceView[]>();
+    for (const source of await this.store.sources(workspaceId)) {
+      const list = byColumn.get(source.columnId);
+      if (list === undefined) byColumn.set(source.columnId, [source]);
+      else list.push(source);
+    }
+    return records.map((record) => ({ ...record, sources: byColumn.get(record.id) ?? [] }));
+  }
+
+  private async view(record: ColumnRecord, sources: ColumnSourceView[]): Promise<ColumnResponse> {
+    return { ...record, sources };
+  }
+
+  private async connectedProviders(session: SessionPayload): Promise<string[]> {
+    const rows = await this.feeds.capableConnections(session.workspaceId);
+    return [...new Set(rows.map((row) => row.provider))];
+  }
+
+  /** Providers whose manifest declares the P0b search capability. */
+  private searchCapableProviders(providers: string[]): string[] {
+    return providers.filter((provider) => {
+      if (!this.registry.has(provider)) return false;
+      return this.registry.get(provider).manifest().search === true;
+    });
+  }
+
+  private async forceDue(workspaceId: string, columnId: string): Promise<number> {
+    return this.scheduler.forceColumnDue(workspaceId, columnId);
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// Request parsing (unknown body in, typed DTO out; 400 on shape errors)
+// ---------------------------------------------------------------------------
+
+function parseCreate(body: unknown): CreateColumn {
+  const payload = requireObject(body, "body");
+  const type = requireString(payload.type, "type");
+  if (type !== "platform_feed" && type !== "keyword" && type !== "account_list" && type !== "saved_search") {
+    throw new BadRequestException("type must be one of platform_feed|keyword|account_list|saved_search");
+  }
+  const title = requireString(payload.title, "title");
+  const position = payload.position === undefined ? undefined : requirePosition(payload.position);
+  return {
+    type,
+    title,
+    position,
+    spec: payload.spec === undefined ? {} : payload.spec,
+    refreshPolicy: payload.refreshPolicy,
+  };
+}
+
+function parseUpdate(body: unknown): UpdateColumn {
+  const payload = requireObject(body, "body");
+  const update: UpdateColumn = {};
+  if (payload.title !== undefined) update.title = requireString(payload.title, "title");
+  if (payload.position !== undefined) update.position = requirePosition(payload.position);
+  if (payload.spec !== undefined) update.spec = payload.spec;
+  if (payload.refreshPolicy !== undefined) {
+    if (typeof payload.refreshPolicy !== "object" || payload.refreshPolicy === null || Array.isArray(payload.refreshPolicy)) {
+      throw new BadRequestException("refreshPolicy must be an object");
+    }
+    update.refreshPolicy = payload.refreshPolicy;
+  }
+  return update;
+}
+
+function requirePosition(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 2_147_483_647) {
+    throw new BadRequestException("position must be an integer between 0 and 2147483647");
+  }
+  return value;
+}
+
+function parseIds(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length === 0) throw new BadRequestException("ids must be a non-empty array of column ids");
+  const ids: string[] = [];
+  for (const id of value) {
+    if (typeof id !== "string") throw new BadRequestException("ids must contain strings only");
+    ids.push(parseId(id));
+  }
+  return ids;
+}
+
+/**
+ * The keyset cursor: base64url JSON `{ at, key }` where `at` is the item's
+ * created_at_remote epoch ms and `key` its dedup_key. Mirrors the /feeds
+ * cursor contract (opaque, ≤4096 chars, position in a total order).
+ */
+export function decodeColumnCursor(cursor: string): { at: number; key: string } {
+  try {
+    if (cursor.length > 4096) throw new Error();
+    const parsed: unknown = JSON.parse(Buffer.from(cursor, "base64url").toString());
+    if (typeof parsed !== "object" || parsed === null || !("at" in parsed) || !("key" in parsed) ||
+      typeof (parsed as { at: unknown }).at !== "number" || !Number.isFinite((parsed as { at: number }).at) ||
+      typeof (parsed as { key: unknown }).key !== "string") throw new Error();
+    return { at: (parsed as { at: number }).at, key: (parsed as { key: string }).key };
+  } catch {
+    throw new BadRequestException("Invalid column cursor");
+  }
+}
diff --git a/apps/api/src/feeds/columns.dependencies.ts b/apps/api/src/feeds/columns.dependencies.ts
new file mode 100644
index 0000000..f5af93b
--- /dev/null
+++ b/apps/api/src/feeds/columns.dependencies.ts
@@ -0,0 +1,165 @@
+/**
+ * Columns wiring (P1): production dependency providers for the ColumnStore
+ * and ColumnScheduler, mirroring feeds.dependencies.ts.
+ *
+ * The scheduler's per-host budget draws from `@tactical-media-broadcast-hub/egress`
+ * HostBudgets — the SAME `host_budgets` rows every other egress caller uses
+ * (monitor, bulk import), keyed by the egress `hostBudgetKey` rule (IDNA
+ * lowercased host + effective port), so feeds polls and monitor polls to one
+ * host contend for one shared bucket. That is the §3.4 requirement: budgets
+ * are per-host totals, never per-process.
+ *
+ * The egress package is type-imported and loaded natively at runtime (the
+ * same pattern as live-monitor/poller/egress.ts and virtual-channels/
+ * import-egress.ts) because it is ESM-only.
+ */
+import { Inject, Injectable, Optional } from "@nestjs/common";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import type { CredentialAccessor, ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { pool } from "../db/client.js";
+import { PgConnectionStore } from "../connections/connection-store.js";
+import { RespControlRedis, type ControlRedis } from "../media-control/redis.js";
+import { vault } from "../vault/vault.js";
+import { feedRegistry } from "./feed-registry.js";
+import { FeedsService } from "./feeds.service.js";
+import {
+  ColumnStore, COLUMN_STORE_DEPENDENCIES, type ColumnStoreDependencies,
+} from "./column-store.js";
+import {
+  ColumnScheduler, COLUMN_SCHEDULER_DEPENDENCIES, type ColumnSchedulerDependencies,
+} from "./column-scheduler.js";
+import { COLUMNS_REGISTRY } from "./columns.controller.js";
+
+type EgressPackage = typeof import("../../../../packages/egress/src/index.js");
+
+const nativeImport = new Function("specifier", "return import(specifier)") as (specifier: string) => Promise<EgressPackage>;
+
+function resolveEgressPackage(): string {
+  for (const start of [process.cwd(), __dirname]) {
+    for (let root = start; ; root = dirname(root)) {
+      const directory = resolve(root, "packages/egress");
+      const files = process.env.NODE_ENV === "production" ? ["dist/index.js"] : ["src/index.ts", "dist/index.js"];
+      for (const file of files) {
+        const candidate = resolve(directory, file);
+        if (existsSync(candidate)) return candidate;
+      }
+      if (dirname(root) === root) break;
+    }
+  }
+  throw new Error("Build packages/egress before starting the columns scheduler");
+}
+
+/** Process-wide egress binding shared by the columns scheduler. */
+export interface ColumnsEgress {
+  consume(hostKey: string): Promise<void>;
+}
+
+let sharedEgress: Promise<ColumnsEgress> | undefined;
+
+export function columnsEgress(): Promise<ColumnsEgress> {
+  sharedEgress ??= (async () => {
+    const specifier = pathToFileURL(resolveEgressPackage()).href;
+    const pkg = await nativeImport(specifier);
+    const budgets = new pkg.HostBudgets({ pool, hostClasses: { feeds: { capacity: 3, refillPerInterval: 10 } } });
+    return { consume: (hostKey) => budgets.consume(hostKey, "feeds") };
+  })();
+  return sharedEgress;
+}
+
+/** The API host key for a provider's feed calls, per the egress hostBudgetKey rule. */
+export function feedHostKey(provider: string, connection: ConnectorConnection): string {
+  const raw = typeof connection.fields.instanceUrl === "string" && connection.fields.instanceUrl !== ""
+    ? connection.fields.instanceUrl
+    : providerApiBaseUrl(provider);
+  try {
+    const url = new URL(raw);
+    const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+    const port = url.port || (url.protocol === "https:" ? "443" : "80");
+    return `${host}:${port}`;
+  } catch {
+    return `${provider}:443`;
+  }
+}
+
+/** Fallback API endpoints per provider (used only when no instanceUrl exists). */
+const PROVIDER_API_HOSTS: Record<string, string> = {
+  mastodon: "https://mastodon.social",
+  bluesky: "https://bsky.app",
+  youtube: "https://www.googleapis.com",
+  reddit: "https://www.reddit.com",
+  telegram: "https://api.telegram.org",
+  twitter: "https://api.twitter.com",
+  "mock-social": "https://mock.social",
+};
+
+function providerApiBaseUrl(provider: string): string {
+  return PROVIDER_API_HOSTS[provider] ?? `https://${provider}.example`;
+}
+
+/** The credential accessor feedRegistry needs (shared with feeds.dependencies). */
+function credentials(): CredentialAccessor {
+  const store = new PgConnectionStore();
+  return {
+    async getAccessToken(connection) { return credentials().getSecret(connection, "access_token"); },
+    async getSecret(connection, key) {
+      const stored = await store.get(connection.workspaceId, connection.id);
+      if (!stored.credential) throw new Error("Credential missing");
+      const bytes = await vault.open(connection.workspaceId, connection.id, stored.credential);
+      const secrets = JSON.parse(bytes.toString()) as Record<string, unknown>;
+      const value = secrets[key];
+      if (typeof value !== "string" || !value) throw new Error("Credential missing");
+      return value;
+    },
+    async put(connection, key, value) {
+      const stored = await store.get(connection.workspaceId, connection.id);
+      if (!stored.credential) throw new Error("Credential missing");
+      const bytes = await vault.open(connection.workspaceId, connection.id, stored.credential);
+      const secrets = JSON.parse(bytes.toString()) as Record<string, unknown>;
+      secrets[key] = value;
+      const sealed = await vault.seal(connection.workspaceId, connection.id, Buffer.from(JSON.stringify(secrets)));
+      await store.rotateCredential(connection.workspaceId, connection.id, stored.credential, sealed);
+    },
+  };
+}
+
+let sharedRegistry: ConnectorRegistry | undefined;
+
+/** One registry per process, preserving per-host HTTP token buckets. */
+export function columnsRegistry(): ConnectorRegistry {
+  sharedRegistry ??= feedRegistry(credentials());
+  return sharedRegistry;
+}
+
+/** Provider wiring for FeedsModule (see feeds.module.ts). */
+export const columnsProviders = [
+  { provide: COLUMN_STORE_DEPENDENCIES, useFactory: (): ColumnStoreDependencies => {
+    const store = new PgConnectionStore();
+    return {
+      providerOf: async (workspaceId, connectionId) => {
+        const rows = await store.list(workspaceId);
+        const row = rows.find((candidate) => candidate.id === connectionId);
+        if (row === undefined) throw new Error(`connection ${connectionId} not found`);
+        return row.provider;
+      },
+      connections: (workspaceId) => store.list(workspaceId),
+    };
+  } },
+  { provide: COLUMNS_REGISTRY, useFactory: () => columnsRegistry() },
+  { provide: COLUMN_SCHEDULER_DEPENDENCIES, inject: [FeedsService], useFactory: (feeds: FeedsService): ColumnSchedulerDependencies => {
+    const redis: Pick<ControlRedis, "get" | "set" | "eval"> = new RespControlRedis(process.env.REDIS_URL ?? "redis://127.0.0.1:6379");
+    const connectionStore = new PgConnectionStore();
+    return {
+      redis,
+      registry: columnsRegistry(),
+      connection: async (workspaceId, id) => (await connectionStore.get(workspaceId, id)).connection,
+      cacheHomeFeed: (workspaceId, connectionId, items) => feeds.cacheHomeFeed(workspaceId, connectionId, items),
+      hostKeyOf: feedHostKey,
+      consumeBudget: (hostKey) => columnsEgress().then((egress) => egress.consume(hostKey)),
+      random: Math.random,
+      now: Date.now,
+    };
+  } },
+];
diff --git a/apps/api/src/feeds/columns.integration.test.ts b/apps/api/src/feeds/columns.integration.test.ts
new file mode 100644
index 0000000..5860ddf
--- /dev/null
+++ b/apps/api/src/feeds/columns.integration.test.ts
@@ -0,0 +1,376 @@
+/**
+ * Columns P1 integration tests — real Postgres (migrations ≤ 026 applied),
+ * RLS-faithful via the app pool, following the video.integration.test pattern.
+ *
+ * Covers the DELIVER test list:
+ *   - CRUD + reorder, including RBAC 403 for an ungranted role
+ *   - seed idempotency (re-touch creates no duplicates)
+ *   - cooldown enforcement on the column endpoints
+ *   - cursor survival across a cache flush
+ *   - keyset items pagination (stable order, no skips/dupes across pages)
+ *   - dedup: same remote item from two columns sharing an identity → one row,
+ *     visible in both
+ */
+import "reflect-metadata";
+import { randomUUID } from "node:crypto";
+import { ForbiddenException, type CallHandler, type ExecutionContext, type INestApplication } from "@nestjs/common";
+import { NestFactory, Reflector } from "@nestjs/core";
+import { Pool } from "pg";
+import { afterAll, beforeAll, afterEach, describe, expect, it, vi } from "vitest";
+import { InMemoryCredentials, type ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import type { SessionPayload } from "../auth/session.js";
+import { PERMISSION_KEY, RbacGuard } from "../rbac/rbac.guard.js";
+import { injectHttp } from "../connections/http-test-transport.js";
+import { feedRegistry } from "./feed-registry.js";
+import { FeedsService } from "./feeds.service.js";
+import { FeedsController } from "./feeds.controller.js";
+import { ColumnsController, COLUMNS_REGISTRY } from "./columns.controller.js";
+import { ColumnStore } from "./column-store.js";
+import { ColumnScheduler, type ColumnSchedulerDependencies } from "./column-scheduler.js";
+import { MemoryFeedRedis } from "./testing.js";
+import type { ConnectionSummary } from "../connections/connections.service.js";
+
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+// Setup runs as the table owner (superuser in dev) because memberships has
+// FORCE RLS and the seed path needs to insert without a tenant context.
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+
+// The app pool is imported lazily where needed; ColumnStore's own fallback
+// deps use withTenant from db/client, but these tests always inject explicit
+// deps, so no module-scope side-effectful import is required.
+
+const owner: SessionPayload = { userId: randomUUID(), workspaceId: randomUUID(), role: "Owner", authzEpoch: 1, issuedAt: 0, expiresAt: 9_999_999_999 };
+const viewer: SessionPayload = { ...owner, userId: randomUUID(), role: "Moderator" }; // no streams.columns.manage
+
+const item = (remoteId: string, minutesAgo: number): FeedItem => ({
+  id: remoteId, remoteId, provider: "mock-social", authorHandle: "alice", text: `post ${remoteId}`,
+  mediaUrls: [], createdAt: new Date(Date.now() - minutesAgo * 60_000), metrics: {},
+});
+
+function setupRegistry(items: FeedItem[]): ConnectorRegistry {
+  const registry = feedRegistry(new InMemoryCredentials());
+  const mock = registry.get("mock-social");
+  const original = mock.getFeed;
+  if (original === undefined) throw new Error("mock-social has no feed");
+  mock.getFeed = vi.fn(async () => ({ items }));
+  return registry;
+}
+
+describe.skipIf(!dbAvailable)("columns P1 (live DB)", () => {
+  let app: INestApplication;
+  let store: ColumnStore;
+  let scheduler: ColumnScheduler;
+  let feeds: FeedsService;
+  let redis: MemoryFeedRedis;
+  let connections: Array<{ summary: ConnectionSummary; connection: ConnectorConnection }>;
+  let items: FeedItem[];
+  let granted = true;
+  let registry: ConnectorRegistry;
+
+  beforeAll(async () => {
+    // Users first (ids are DB-generated and captured for memberships), then
+    // workspace + members, in the owner pool which bypasses RLS for setup.
+    const inserted = await ownerPool.query<{ id: string }>(
+      `INSERT INTO users (external_id, email, display_name, username)
+       VALUES ($1,$2,'Columns P1 Owner',$3) RETURNING id`, [`u-${randomUUID()}`, `o-${randomUUID()}@example.com`, `p1o${randomUUID().slice(0, 8)}`]);
+    (owner as { userId: string }).userId = String(inserted.rows[0]?.id);
+    const viewerRow = await ownerPool.query<{ id: string }>(
+      `INSERT INTO users (external_id, email, display_name, username)
+       VALUES ($1,$2,'Columns P1 Viewer',$3) RETURNING id`, [`u-${randomUUID()}`, `v-${randomUUID()}@example.com`, `p1v${randomUUID().slice(0, 8)}`]);
+    (viewer as { userId: string }).userId = String(viewerRow.rows[0]?.id);
+    const workspace = await ownerPool.query(
+      "INSERT INTO workspaces (name, slug) VALUES ('columns p1', $1) RETURNING id", [`cols-${randomUUID()}`]);
+    const workspaceId = String(workspace.rows[0]?.id);
+    // memberships is FORCE RLS: insert inside the workspace's tenant context.
+    const setupClient = await ownerPool.connect();
+    try {
+      await setupClient.query("BEGIN");
+      await setupClient.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      await setupClient.query(
+        "INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1,$2,'Owner'), ($1,$3,'Moderator')",
+        [workspaceId, owner.userId, viewer.userId]);
+      await setupClient.query("COMMIT");
+    } finally {
+      setupClient.release();
+    }
+    (owner as { workspaceId: string }).workspaceId = workspaceId;
+    (viewer as { workspaceId: string }).workspaceId = workspaceId;
+
+    items = [item("i-1", 1), item("i-2", 5), item("i-3", 10), item("i-4", 30), item("i-5", 60)];
+    registry = setupRegistry(items);
+
+    // Two feed-capable connections in the workspace: the seeding input.
+    connections = [];
+    for (let index = 0; index < 2; index += 1) {
+      // The DB generates the id (connections has no id column we may set);
+      // RETURNING it keeps the FK target and the summary in sync.
+      const inserted = await ownerPool.query<{ id: string; created_at: Date }>(
+        "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1,'mock-social',$2) RETURNING id, created_at", [owner.workspaceId, `ch-${index}`]);
+      const id = String(inserted.rows[0]?.id);
+      const createdAt = inserted.rows[0]?.created_at as Date;
+      const summary: ConnectionSummary = {
+        id, provider: "mock-social", channelId: `ch-${index}`, fields: {}, health: "healthy",
+        credentialRotatedAt: null, recentPublishes: [], createdAt: createdAt.toISOString(),
+      };
+      const connection: ConnectorConnection = {
+        id, workspaceId: owner.workspaceId, provider: "mock-social", channelId: `ch-${index}`,
+        credentialId: { kind: "credential-ref", id }, fields: {}, createdAt,
+      };
+      connections.push({ summary, connection });
+    }
+
+    redis = new MemoryFeedRedis();
+    store = new ColumnStore({
+      providerOf: async (_ws, id) => connections.find((row) => row.summary.id === id)?.summary.provider ?? "mock-social",
+      connections: async (ws) => ws === owner.workspaceId ? connections.map((row) => row.summary) : [],
+    });
+    feeds = new FeedsService({
+      redis, registry, random: () => 0.5, requestsPerSecond: () => 0.5,
+      workspaces: async () => [owner.workspaceId],
+      connections: async (ws) => ws === owner.workspaceId ? connections.map((row) => row.summary) : [],
+      connection: async (ws, id) => { const row = connections.find((c) => c.summary.id === id); if (!row || ws !== owner.workspaceId) throw new Error(); return row.connection; },
+      visible: async (s) => s.workspaceId === owner.workspaceId ? connections.map((row) => row.summary.id) : [],
+      audit: async () => undefined,
+    }, store);
+    scheduler = new ColumnScheduler(store, {
+      redis, registry,
+      connection: async (ws, id) => { const row = connections.find((c) => row_summary(c) === id); if (!row || ws !== owner.workspaceId) throw new Error(); return row.connection; },
+      cacheHomeFeed: async (ws, id, normalized) => { if (ws === owner.workspaceId) await feeds.cacheHomeFeed(ws, id, normalized); },
+      hostKeyOf: () => "mock.social:443",
+      consumeBudget: async () => undefined,
+      random: () => 0.5,
+      now: () => Date.now(),
+    });
+
+    // Both poll loops stay off: the feeds discovery timer would contend with
+    // ensureSeeded's workspace row lock (this suite drives polls explicitly).
+    vi.spyOn(scheduler, "onApplicationBootstrap").mockImplementation(() => undefined);
+    vi.spyOn(feeds, "onApplicationBootstrap").mockImplementation(() => undefined);
+    vi.spyOn(RbacGuard.prototype, "canActivate").mockImplementation(async (context: ExecutionContext) => {
+      const request = context.switchToHttp().getRequest<{ headers: Record<string, string>; session?: SessionPayload }>();
+      if (request.headers.authorization !== "Bearer test-session") throw new ForbiddenException("unauthenticated");
+      const session = request.headers["x-test-user"] === "viewer" ? viewer : owner;
+      const permission = new Reflector().get<string>(PERMISSION_KEY, context.getHandler());
+      // The seeded RBAC: streams.columns.manage is Owner/Admin/Editor only.
+      if (permission === "streams.columns.manage" && !granted) throw new ForbiddenException("missing permission");
+      request.session = session;
+      return true;
+    });
+    app = await NestFactory.create({
+      module: class TestModule {},
+      controllers: [ColumnsController, FeedsController],
+      providers: [
+        { provide: FeedsService, useValue: feeds },
+        { provide: ColumnStore, useValue: store },
+        { provide: ColumnScheduler, useValue: scheduler },
+        { provide: COLUMNS_REGISTRY, useValue: registry },
+      ],
+    }, { logger: false });
+    await app.init();
+  });
+
+  afterEach(() => { granted = true; });
+
+  afterAll(async () => {
+    await app?.close();
+    if (owner.workspaceId !== undefined) await ownerPool.query("DELETE FROM workspaces WHERE id = $1", [owner.workspaceId]);
+    await ownerPool.end();
+  });
+
+  const request = (path: string, method = "GET", body?: unknown, user: "owner" | "viewer" = "owner") =>
+    injectHttp(app.getHttpAdapter().getInstance(), `http://api.test${path}`, {
+      method, headers: { authorization: "Bearer test-session", "x-test-user": user, "content-type": "application/json" },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+
+  it("seeds one platform_feed column per feed connection, idempotently, with sources", async () => {
+    const first = await request("/feeds/columns");
+    expect(first.status).toBe(200);
+    const seeded = await first.json() as Array<{ id: string; type: string; title: string; sources: Array<{ sourceKind: string; state: string }> }>;
+    expect(seeded).toHaveLength(2);
+    expect(seeded.every((column) => column.type === "platform_feed")).toBe(true);
+    expect(seeded[0]?.sources).toHaveLength(1);
+    expect(seeded[0]?.sources[0]?.sourceKind).toBe("home");
+    // Titles reproduce the implicit column the UI renders today.
+    expect(seeded[0]?.title).toContain("·");
+
+    // Second touch seeds nothing.
+    const second = await request("/feeds/columns");
+    expect(await second.json()).toHaveLength(2);
+    // And the DB agrees: two columns, two source rows, one per connection.
+    const rows = await ownerPool.query("SELECT count(*)::int AS c FROM stream_columns WHERE workspace_id = $1", [owner.workspaceId]);
+    expect(rows.rows[0]?.c).toBe(2);
+    const sources = await ownerPool.query("SELECT count(*)::int AS c FROM column_sources WHERE workspace_id = $1", [owner.workspaceId]);
+    expect(sources.rows[0]?.c).toBe(2);
+  });
+
+  it("enforces streams.columns.manage on writes while reads stay on draft.view", async () => {
+    granted = false;
+    expect((await request("/feeds/columns", "POST", { type: "keyword", title: "x", spec: { query: "q", platforms: ["mock-social"] } }, "viewer")).status).toBe(403);
+    granted = true;
+    const created = await request("/feeds/columns", "POST", { type: "keyword", title: "news", spec: { query: "anarch", platforms: ["mock-social"] } });
+    expect(created.status).toBe(201);
+    const column = await created.json() as { id: string; sources: Array<{ sourceKind: string }> };
+    expect(column.sources.map((source) => source.sourceKind)).toEqual(["search"]);
+    // Reads: viewer (no manage permission) still reads columns and items.
+    expect((await request(`/feeds/columns/${column.id}`, "GET", undefined, "viewer")).status).toBe(200);
+    granted = false;
+    expect((await request(`/feeds/columns/${column.id}`, "PATCH", { title: "z" })).status).toBe(403);
+    expect((await request(`/feeds/columns/${column.id}`, "DELETE")).status).toBe(403);
+    expect((await request("/feeds/columns/reorder", "POST", { ids: [] })).status).toBe(403);
+    granted = true;
+    await request(`/feeds/columns/${column.id}`, "DELETE");
+  });
+
+  it("rejects invalid specs with 422 and never stores them", async () => {
+    const bad = await request("/feeds/columns", "POST", { type: "keyword", title: "bad", spec: { query: "", platforms: ["mock-social"] } });
+    expect(bad.status).toBe(422);
+    const badConnection = await request("/feeds/columns", "POST", { type: "platform_feed", title: "bad", spec: { connectionId: randomUUID() } });
+    expect(badConnection.status).toBe(422);
+    const count = await ownerPool.query(
+      "SELECT count(*)::int AS c FROM stream_columns WHERE workspace_id = $1 AND deleted_at IS NULL", [owner.workspaceId]);
+    expect(count.rows[0]?.c).toBe(2); // only the two seeded columns (the RBAC test's column was soft-deleted)
+  });
+
+  it("polls due sources, persists items, and fans out to columns sharing an identity", async () => {
+    const columns = await (await request("/feeds/columns")).json() as Array<{ id: string; sources: Array<{ id: string }> }>;
+    const first = columns[0]!;
+    const outcome = await scheduler.pollWorkspaceDue(owner.workspaceId);
+    expect(outcome.polled).toBeGreaterThanOrEqual(2); // both seeded home sources
+
+    // Items landed in the store for the polled column.
+    const page = await store.columnItems(owner.workspaceId, first.id, { limit: 10 });
+    expect(page.items.length).toBeGreaterThanOrEqual(1);
+    expect(page.items.every((stored) => stored.item.remoteId.startsWith("i-"))).toBe(true);
+    // The source row moved to ready with a next poll scheduled.
+    const sources = await store.sources(owner.workspaceId, first.id);
+    expect(sources[0]?.state).toBe("ready");
+    expect(sources[0]?.nextPollAt).not.toBeNull();
+  });
+
+  it("keyset pagination: pages in stable order, no skips or duplicates, cursor survives cache flush", async () => {
+    const columns = await (await request("/feeds/columns")).json() as Array<{ id: string }>;
+    const columnId = columns[0]!.id;
+    const seen: string[] = [];
+    let cursor: string | null = null;
+    // limit 2 over 5 items = 3 pages (2,2,1)
+    for (let page = 0; page < 3; page += 1) {
+      const response = await request(`/feeds/columns/${columnId}/items?limit=2${cursor === null ? "" : `&cursor=${cursor}`}`);
+      expect(response.status).toBe(200);
+      const body = await response.json() as { items: Array<{ item: { remoteId: string } }>; nextCursor: string | null };
+      for (const stored of body.items) seen.push(stored.item.remoteId);
+      cursor = body.nextCursor;
+      if (cursor === null) break;
+    }
+    expect(seen.length).toBe(new Set(seen).size); // no duplicates
+    expect(seen).toHaveLength(items.length);      // no skips
+
+    // Cursor survival: flush every cache key, then continue from a cursor
+    // minted before the flush — the store page must pick up exactly where the
+    // cache left off because the cursor is a position in the stored order.
+    redis.entries.clear();
+    const beforeFlush = await request(`/feeds/columns/${columnId}/items?limit=1`);
+    const firstCursor = ((await beforeFlush.json()) as { nextCursor: string | null }).nextCursor;
+    expect(firstCursor).not.toBeNull();
+    redis.entries.clear();
+    const afterFlush = await request(`/feeds/columns/${columnId}/items?limit=10&cursor=${firstCursor}`);
+    expect(afterFlush.status).toBe(200);
+    const pageItems = (await afterFlush.json()) as { items: Array<{ item: { remoteId: string } }> };
+    // Everything strictly after the first item, in keyset order.
+    expect(pageItems.items.map((stored) => stored.item.remoteId)).toEqual(seen.slice(1));
+  });
+
+  it("cooldown blocks a forced refresh from issuing a second poll", async () => {
+    const columns = await (await request("/feeds/columns")).json() as Array<{ id: string }>;
+    const columnId = columns[0]!.id;
+    const before = registry.get("mock-social").getFeed as ReturnType<typeof vi.fn>;
+    const callsBefore = before.mock.calls.length;
+    const outcome = await scheduler.pollWorkspaceDue(owner.workspaceId);
+    expect(outcome.polled).toBe(0); // sources just polled: next_poll_at is in the future
+    // The HTTP refresh endpoint cannot bypass the persisted floor: the poll
+    // happened seconds ago, so force-due refuses even though the Redis
+    // cooldown keys were flushed (cursor-survival test) — next_poll_at is the
+    // authoritative guard, not the cache.
+    const refreshed = await request(`/feeds/columns/${columnId}/refresh`, "POST");
+    expect(refreshed.status).toBe(201);
+    const body = await refreshed.json() as { refreshed: number };
+    expect(body.refreshed).toBe(0); // DB floor refused the forced poll
+    expect(before.mock.calls.length).toBe(callsBefore);
+  });
+
+  it("dedups the same remote item across columns sharing an identity", async () => {
+    // Second column on the same connection as the first: same identity.
+    const columns = await (await request("/feeds/columns")).json() as Array<{ id: string; sources: Array<{ id: string }> }>;
+    const [first, second] = columns;
+    expect(first && second).toBeTruthy();
+    // Make both due again, then poll: one identity, one connector call.
+    await ownerPool.query("UPDATE column_sources SET next_poll_at = now() WHERE workspace_id = $1", [owner.workspaceId]);
+    const getFeed = registry.get("mock-social").getFeed as ReturnType<typeof vi.fn>;
+    const before = getFeed.mock.calls.length;
+    const outcome = await scheduler.pollWorkspaceDue(owner.workspaceId);
+    expect(outcome.polled).toBe(2);
+    expect(getFeed.mock.calls.length).toBe(before + 2); // two source rows, two calls (per-source semantics)
+    // One feed_items row per remote item — the dedup key is workspace-wide.
+    const stored = await ownerPool.query("SELECT count(*)::int AS c FROM feed_items WHERE workspace_id = $1", [owner.workspaceId]);
+    expect(stored.rows[0]?.c).toBe(items.length);
+    // Both columns surface the same items.
+    const left = await store.columnItems(owner.workspaceId, first!.id, { limit: 10 });
+    const right = await store.columnItems(owner.workspaceId, second!.id, { limit: 10 });
+    expect(left.items).toHaveLength(items.length);
+    expect(right.items).toHaveLength(items.length);
+    // And a cursor minted on one column pages identically on the other.
+    expect(left.items.map((row) => row.item.remoteId)).toEqual(right.items.map((row) => row.item.remoteId));
+  });
+
+  it("reorder requires the full id list and rewrites positions densely", async () => {
+    const columns = await (await request("/feeds/columns")).json() as Array<{ id: string; position: number }>;
+    const ids = columns.map((column) => column.id);
+    const partial = await request("/feeds/columns/reorder", "POST", { ids: [ids[0]!] });
+    expect(partial.status).toBe(400);
+    const reordered = await request("/feeds/columns/reorder", "POST", { ids: [...ids].reverse() });
+    expect(reordered.status).toBe(201);
+    const after = await reordered.json() as Array<{ id: string; position: number }>;
+    expect(after.map((column) => column.id)).toEqual([...ids].reverse());
+    expect(after.map((column) => column.position)).toEqual([0, 1]);
+  });
+
+  it("import-saved-searches creates idempotent saved_search columns", async () => {
+    // No search-capable provider is connected (mock-social declares none), so
+    // the implicit-platforms path correctly skips everything rather than
+    // inventing a platform the workspace cannot search.
+    const skipped = await request("/feeds/columns/import-saved-searches", "POST", { queries: ["anarch"] });
+    expect(skipped.status).toBe(201);
+    expect(await skipped.json()).toEqual({ imported: 0, skipped: 1 });
+    // Explicit platforms still import (the UI knows which it used locally).
+    const imported = await request("/feeds/columns/import-saved-searches", "POST", { queries: ["anarch", "mutual aid"], platforms: ["mock-social"] });
+    expect(imported.status).toBe(201);
+    expect(await imported.json()).toEqual({ imported: 2, skipped: 0 });
+    // Re-import: idempotent per query.
+    const again = await request("/feeds/columns/import-saved-searches", "POST", { queries: ["anarch", "squatting"], platforms: ["mock-social"] });
+    expect(await again.json()).toEqual({ imported: 1, skipped: 1 });
+    const columns = await (await request("/feeds/columns")).json() as Array<{ type: string; title: string }>;
+    const searches = columns.filter((column) => column.type === "saved_search");
+    expect(searches.map((column) => column.title).sort()).toEqual(["anarch", "mutual aid", "squatting"]);
+    // Unknown platform ids are rejected up front (P0a schema rules).
+    const bad = await request("/feeds/columns/import-saved-searches", "POST", { queries: ["x"], platforms: ["not-a-provider"] });
+    expect(bad.status).toBe(422);
+  });
+
+  it("GET /feeds keeps its external shape and gains additive meta.columns", async () => {
+    const response = await request("/feeds");
+    expect(response.status).toBe(200);
+    const feed = await response.json() as { items: unknown[]; nextCursor: string | null; meta: { configuredFeeds: number; columns?: Array<{ id: string }> } };
+    expect(Array.isArray(feed.items)).toBe(true);
+    expect(feed.meta.configuredFeeds).toBe(2);
+    expect(feed.meta.columns?.length).toBeGreaterThanOrEqual(2); // seeded columns surface
+  });
+
+  it("invalid cursor is a 400 and unknown column a 404", async () => {
+    expect((await request(`/feeds/columns/${randomUUID()}/items`)).status).toBe(404);
+    expect((await request("/feeds/columns/not-a-uuid/items")).status).toBe(400);
+    expect((await request("/feeds/columns/00000000-0000-0000-0000-000000000000/items?cursor=garbage")).status).toBe(400);
+  });
+});
+
+function row_summary(row: { summary: ConnectionSummary }): string { return row.summary.id; }
diff --git a/apps/api/src/feeds/feed-normalize.test.ts b/apps/api/src/feeds/feed-normalize.test.ts
new file mode 100644
index 0000000..c59dea5
--- /dev/null
+++ b/apps/api/src/feeds/feed-normalize.test.ts
@@ -0,0 +1,366 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import { createMockSocialConnector, createMockSocialState } from "../../../../packages/connector-mock-social/src/index.js";
+import { DEFAULT_MEDIA_PROXY, parseProviderHtml, type CustomEmoji, type LinkPreview, type MediaProxyPolicy, type RichTextDocument } from "../../../../packages/safe-content/src/index.js";
+import { astToPlainText, feedAuthorRef, feedItemMedia, normalizeFeedItem, type MediaRef, type NormalizedFeedItem } from "./feed-normalize.js";
+import { FeedsService, feedCacheKey } from "./feeds.service.js";
+import type { FeedDependencies } from "./feeds.dependencies.js";
+import { MemoryFeedRedis } from "./testing.js";
+
+/** Per-connector fixtures (design §3.2 provider table) + hostile-HTML cases. */
+interface ProviderFixture {
+  provider: string;
+  contentKind?: "text" | "html";
+  instanceUrl?: string;
+  emojis?: readonly CustomEmoji[];
+  item: FeedItem;
+  url?: unknown;
+  expiresAt?: unknown;
+  linkPreview?: unknown;
+}
+
+const PROXY: MediaProxyPolicy = DEFAULT_MEDIA_PROXY;
+const connection = (fields: Record<string, string> = {}): ConnectorConnection => ({
+  id: "conn-1", workspaceId: "ws-1", provider: "mastodon", channelId: "conn-1",
+  credentialId: { kind: "credential-ref", id: "cred-1" }, fields, createdAt: new Date(),
+});
+
+const mastodonStatus: FeedItem = {
+  id: "1001", provider: "mastodon", remoteId: "1001", authorHandle: "alice@foreso.social",
+  // The exact HTML shape Mastodon emits: p/br/a, mention + hashtag + invisible
+  // ellipsis link spans, HTML-escaped ampersands, raw emoji <img> tags.
+  text: '<p>A call for <span class="h-card"><a href="https://foreso.social/@bob" class="u-url mention">@<span>bob</span></a></span> &amp; friends</p><p>#<a href="https://foreso.social/tags/acampada26" rel="tag">acampada26</a> kicks off <a href="https://example.org/manifesto" rel="nofollow noopener noreferrer noopener" target="_blank"><span class="invisible">https://</span><span class="ellipsis">example.org/manifes</span><span class="invisible">to</span></a> <img src="https://foreso.social/emoji/ok.png" alt=":ok:" draggable="false"><br>line two <b>bolded</b></p>',
+  mediaUrls: ["https://cdn.foreso.social/media/1234.png", "https://cdn.foreso.social/media/clip.mp4"],
+  createdAt: new Date("2026-10-06T12:00:00.000Z"),
+  metrics: { reblogs: 2, replies: 1, favourites: 5, broken: Number.NaN, infinite: Number.POSITIVE_INFINITY },
+};
+const xssStatus: FeedItem = {
+  id: "2002", provider: "mastodon", remoteId: "2002", authorHandle: "mallory@evil.example",
+  text: '<p>hi <script>alert("pwned")</script><img src=x onerror="alert(1)"><iframe srcdoc="<script>alert(2)</script>"></iframe><style>body{}</style><svg><circle/></svg><a href="javascript:alert(3)">click</a><a href="https://ok.example/pass">pass</a><a href="java\tscript:alert(4)">tabbed</a></p><p>after</p>',
+  mediaUrls: ["javascript:alert(5)", "data:text/html,evil", "//protocol-relative.example/x.png", "https://cdn.example/ok.png"],
+  createdAt: new Date("2026-10-06T12:01:00.000Z"),
+  metrics: {},
+};
+
+const fixturePlainText: ProviderFixture = {
+  // Plain-text provider source (Bluesky/Telegram-style): auto-linked, no HTML.
+  provider: "bluesky",
+  item: {
+    id: "1", provider: "bluesky", remoteId: "at://did:plc:abc/app.bsky.feed.post/1",
+    authorHandle: "acampada.bsky.social", mediaUrls: [], createdAt: new Date("2026-10-06T10:00:00.000Z"),
+    metrics: { likes: 3 },
+    text: "Line one\n\n hub https://github.com/eche/acampada26/blob/main/core/search.ts #acampada26 @alice@foreso.social",
+  },
+  url: "https://bsky.app/profile/acampada.bsky.social/post/1",
+};
+const fixtureMastodonHtml: ProviderFixture = {
+  // Mastodon status HTML: allowlist parser, mention + ellipsis link + emoji.
+  provider: "mastodon",
+  contentKind: "html",
+  emojis: [{ shortcode: "ok", url: "https://foreso.social/emoji/ok.png" }],
+  item: mastodonStatus,
+  url: "https://foreso.social/@alice/1001",
+};
+const fixtureHostileHtml: ProviderFixture = {
+  // Hostile HTML from a compromised/bogus federated peer.
+  provider: "mastodon",
+  contentKind: "html",
+  instanceUrl: "https://EVIL.example:443/",
+  item: xssStatus,
+  url: "javascript:alert(6)",
+  linkPreview: { url: "javascript:alert(7)", title: "javascript:alert(8)", image: "javascript:alert(9)" },
+};
+const fixtureMastodonLinkPreview: ProviderFixture = {
+  // Mastodon HTML + card (link-preview) payload as one source row.
+  provider: "mastodon",
+  contentKind: "html",
+  item: { ...mastodonStatus, id: "1002", remoteId: "1002", text: '<p>with a <span class="h-card"><a href="https://foreso.social/@bob" class="u-url mention">@<span>bob</span></a></span> card</p>', mediaUrls: [] },
+  url: "https://foreso.social/@alice/1002",
+  linkPreview: {
+    url: "https://example.org/manifesto", title: "Manifesto &lt;scripts&gt; &amp; plans",
+    description: "A plan", siteName: "example dot org", image: "https://cdn.example.org/cover.png",
+  },
+};
+const fixtures: Record<"plainText" | "mastodonHtml" | "hostileHtml" | "mastodonLinkPreview", ProviderFixture> = {
+  plainText: fixturePlainText,
+  mastodonHtml: fixtureMastodonHtml,
+  hostileHtml: fixtureHostileHtml,
+  mastodonLinkPreview: fixtureMastodonLinkPreview,
+};
+
+/** No provider CDN URL outside the media-proxy query string, ever. */
+function assertProxyOnly(media: MediaRef[]): void {
+  const serialized = JSON.stringify(media);
+  let index = serialized.indexOf("https://");
+  while (index !== -1) {
+    expect(serialized.slice(0, index)).toContain(`${PROXY.proxyPath}?url=`);
+    index = serialized.indexOf("https://", index + 1);
+  }
+  for (const ref of media) expect(ref.proxyUrl.startsWith(`${PROXY.proxyPath}?url=`)).toBe(true);
+}
+
+/** Raw-remnant scan applied to every fixture's AST, plain text and media. */
+function assertZeroRawRemnants(ast: RichTextDocument, plainText: string, media: MediaRef[]): void {
+  const astJson = JSON.stringify(ast);
+  const hostile: RegExp[] = [
+    /<\s*(script|iframe|style|img|svg|math|template|form|object|embed|applet|frame)\b/i,
+    /<\s*\/\s*/, /<!--/, /&#/, /&amp;|&lt;|&gt;|&quot;|&apos;|&nbsp;/i,
+    /javascript:/i, /vbscript:/i, /data:/i, /file:/i, /\/\/evil/, /\/\/protocol-relative/,
+    /on(?:error|load|click|mouseover)\b|on\w+\s*=/i, /srcdoc|src\s*=|href\s*=/i, /alert\s*\(/i,
+  ];
+  for (const haystack of [astJson, plainText, JSON.stringify(media)]) {
+    for (const pattern of hostile) expect(haystack).not.toMatch(pattern);
+  }
+  expect(astJson).not.toContain("<p>");
+  expect(astJson).not.toContain("<b>");
+  assertProxyOnly(media);
+}
+
+function normalizeFixture(fixture: ProviderFixture) {
+  return normalizeFeedItem(fixture.item, { ...connection(fixture.instanceUrl ? { instanceUrl: fixture.instanceUrl } : {}), provider: fixture.provider }, {
+    contentKind: fixture.contentKind,
+    emojis: fixture.emojis,
+    url: fixture.url,
+    expiresAt: fixture.expiresAt,
+    linkPreview: fixture.linkPreview,
+  });
+}
+
+const flat = (ast: RichTextDocument): string[] =>
+  ast.children.map((paragraph) => paragraph.children.map((node) => node.type).join(","));
+
+describe("feed normalization v2 (columns P0c)", () => {
+  it("keeps legacy /feeds fields byte-identical while adding the v2 fields additively", () => {
+    const normalized = normalizeFeedItem(mastodonStatus, connection(), { url: "https://foreso.social/@alice/1001" });
+    expect(normalized).not.toBeNull();
+    expect(normalized).toMatchObject({
+      id: "1001", remoteId: "1001", provider: "mastodon", connectionId: "conn-1",
+      authorHandle: "alice@foreso.social", text: mastodonStatus.text,
+      mediaUrls: mastodonStatus.mediaUrls,
+      metrics: { reblogs: 2, replies: 1, favourites: 5 }, // NaN/Infinity dropped
+      createdAt: new Date("2026-10-06T12:00:00.000Z"),
+    });
+    expect(Object.keys(normalized?.metrics ?? {})).toEqual(["reblogs", "replies", "favourites"]);
+    expect(normalized?.authorRef).toBe("mastodon:alice@foreso.social");
+    expect(normalized?.url).toBe("https://foreso.social/@alice/1001");
+    expect(normalized?.content?.type).toBe("doc");
+    expect(typeof normalized?.plainText).toBe("string");
+    expect(Array.isArray(normalized?.media)).toBe(true);
+    expect(normalized?.expiresAt).toBeNull();
+  });
+
+  it("normalizes the plain-text fixture with auto-linked http(s) URLs only", () => {
+    const normalized = normalizeFixture(fixturePlainText);
+    expect(normalized).not.toBeNull();
+    assertZeroRawRemnants(normalized?.content as RichTextDocument, normalized?.plainText as string, normalized?.media as MediaRef[]);
+    expect(flat(normalized?.content as RichTextDocument)).toEqual([
+      "text",
+      "text,link,text,hashtag,text,mention",
+    ]);
+    const link = normalized?.content?.children[1]?.children.find((node) => node.type === "link");
+    expect(link?.type === "link" && link.href).toBe("https://github.com/eche/acampada26/blob/main/core/search.ts");
+    expect(link?.type === "link" && link.host).toBe("github.com");
+    expect(normalized?.plainText).toBe("Line one\n\n hub github.com/eche/acampada26/blob/main/core/search.ts #acampada26 @alice@foreso.social");
+    expect(normalized?.authorRef).toBe("bluesky:acampada.bsky.social");
+    expect(normalized?.url).toBe("https://bsky.app/profile/acampada.bsky.social/post/1");
+    expect(normalized?.media).toEqual([]);
+    expect(normalized?.expiresAt).toBeNull();
+  });
+
+  it("normalizes the Mastodon HTML fixture (mention, ellipsis link, emoji, breaks) with zero raw remnants", () => {
+    const normalized = normalizeFixture(fixtureMastodonHtml);
+    expect(normalized).not.toBeNull();
+    const ast = normalized?.content as RichTextDocument;
+    assertZeroRawRemnants(ast, normalized?.plainText as string, normalized?.media as MediaRef[]);
+    expect(ast.truncated).toBe(false);
+    // Invisible spans drop their URL scheme, the ellipsis span becomes "…",
+    // the mention qualifies its handle from the href host, the emoji <img>
+    // alt becomes a proxied emoji node, <b> unwraps to plain text.
+    expect(normalized?.plainText).toBe("A call for @bob@foreso.social & friends\n\n#acampada26 kicks off example.org/manifes… :ok:\nline two bolded");
+    expect(flat(ast)).toEqual([
+      "text,mention,text",
+      "text,link,text,link,text,emoji,linebreak,text",
+    ]);
+    const mention = ast.children[0]?.children[1];
+    expect(mention).toEqual({ type: "mention", handle: "bob@foreso.social", href: "https://foreso.social/@bob" });
+    const link = ast.children[1]?.children.find((node) => node.type === "link" && node.href === "https://example.org/manifesto");
+    expect(link?.type === "link" && link.host).toBe("example.org");
+    expect(link?.type === "link" && link.children.map((child) => child.type === "text" ? child.text : null).join("")).toBe("example.org/manifes…");
+    const emoji = ast.children[1]?.children.find((node) => node.type === "emoji");
+    expect(emoji?.type === "emoji" && emoji.src).toBe(`${PROXY.proxyPath}?url=${encodeURIComponent("https://foreso.social/emoji/ok.png")}`);
+    // Attachments become proxy media refs; kind is sniffed from the extension.
+    expect(normalized?.media).toEqual([
+      { kind: "image", proxyUrl: `${PROXY.proxyPath}?url=${encodeURIComponent("https://cdn.foreso.social/media/1234.png")}` },
+      { kind: "video", proxyUrl: `${PROXY.proxyPath}?url=${encodeURIComponent("https://cdn.foreso.social/media/clip.mp4")}` },
+    ]);
+    assertProxyOnly(normalized?.media as MediaRef[]);
+  });
+
+  it("normalizes the hostile-HTML fixture: scripts, iframes, handlers and unsafe schemes leave no remnants", () => {
+    const normalized = normalizeFixture(fixtureHostileHtml);
+    expect(normalized).not.toBeNull();
+    const ast = normalized?.content as RichTextDocument;
+    assertZeroRawRemnants(ast, normalized?.plainText as string, normalized?.media as MediaRef[]);
+    // Script/style/iframe/svg contents vanish entirely; img alt is empty; the
+    // javascript: link degrades to its inert label; the tab-split "java\tscript:"
+    // scheme is refused; only the one safe link survives as a real link node.
+    expect(flat(ast)).toEqual(["text,link,text", "text"]);
+    const onlyLink = ast.children[0]?.children[1];
+    expect(onlyLink).toEqual({
+      type: "link", href: "https://ok.example/pass", host: "ok.example",
+      children: [{ type: "text", text: "pass" }],
+    });
+    expect(normalized?.plainText).toBe("hi clickpasstabbed\n\nafter");
+    expect(normalized?.plainText).not.toMatch(/alert|pwned|onerror|javascript|srcdoc/i);
+    // Federated host appends to the author ref via instanceUrl (punycoded, port stripped).
+    expect(normalized?.authorRef).toBe("mastodon:mallory@evil.example");
+    // Permalink with an unsafe scheme is refused, not carried.
+    expect(normalized?.url).toBeNull();
+    // Hostile media URLs are dropped wholesale; only the safe https URL is proxied.
+    expect(normalized?.mediaUrls).toHaveLength(4); // legacy field stays as the source delivered it
+    expect(normalized?.media).toEqual([{ kind: "image", proxyUrl: `${PROXY.proxyPath}?url=${encodeURIComponent("https://cdn.example/ok.png")}` }]);
+    assertProxyOnly(normalized?.media as MediaRef[]);
+    // Hostile card: unsafe URL/title/image all rejected → no preview survives.
+    expect(normalized?.linkPreview).toBeUndefined();
+  });
+
+  it("sanitizes the Mastodon link-preview card payload (text fields, proxied image, safe href)", () => {
+    const normalized = normalizeFixture(fixtureMastodonLinkPreview);
+    expect(normalized).not.toBeNull();
+    const preview = normalized?.linkPreview as LinkPreview;
+    expect(preview).not.toBeNull();
+    expect(preview).toEqual({
+      type: "linkPreview", href: "https://example.org/manifesto", host: "example.org",
+      title: "Manifesto <scripts> & plans", description: "A plan", siteName: "example dot org",
+      image: `${PROXY.proxyPath}?url=${encodeURIComponent("https://cdn.example.org/cover.png")}`,
+    });
+    // OpenGraph fields are text: the entity-decoded title carries no live markup.
+    expect(preview.title).toContain("<scripts>");
+    expect(preview.title).not.toMatch(/&lt;|&amp;/);
+    assertZeroRawRemnants(normalized?.content as RichTextDocument, normalized?.plainText as string, normalized?.media as MediaRef[]);
+  });
+
+  it("round-trips every fixture AST through JSON (storage shape) with a stable plainText", () => {
+    for (const [name, fixture] of Object.entries(fixtures)) {
+      const normalized = normalizeFixture(fixture);
+      expect(normalized, name).not.toBeNull();
+      const ast = normalized?.content as RichTextDocument;
+      assertZeroRawRemnants(ast, normalized?.plainText as string, normalized?.media as MediaRef[]);
+      const roundTripped = JSON.parse(JSON.stringify(ast)) as RichTextDocument;
+      expect(roundTripped, name).toEqual(ast);
+      expect(astToPlainText(roundTripped), name).toBe(normalized?.plainText);
+    }
+  });
+
+  it("matches the reference parseProviderHtml derivation for the Mastodon fixture", () => {
+    const fixture = fixtureMastodonHtml;
+    const reference = parseProviderHtml(fixture.item.text, { emojis: fixture.emojis });
+    const normalized = normalizeFixture(fixture);
+    expect(normalized?.content).toEqual(reference);
+    expect(astToPlainText(reference)).toBe(normalized?.plainText);
+  });
+
+  it("builds canonical author refs: handle host wins, instanceUrl fills federated hosts, IDN punycodes", () => {
+    expect(feedAuthorRef("mastodon", "alice@foreso.social")).toBe("mastodon:alice@foreso.social");
+    expect(feedAuthorRef("mastodon", "alice", "https://fedoraproject.org/@alice")).toBe("mastodon:alice@fedoraproject.org");
+    expect(feedAuthorRef("mastodon", "alice", "https://bücher.example:8443/path")).toBe("mastodon:alice@xn--bcher-kva.example");
+    expect(feedAuthorRef("mastodon", "alice", "gopher://odd.example")).toBe("mastodon:alice");
+    expect(feedAuthorRef("mastodon", "@bob@", "https://ok.example")).toBeNull();
+    expect(feedAuthorRef("mastodon", "has space")).toBeNull();
+    expect(feedAuthorRef("mastodon", "")).toBeNull();
+  });
+
+  it("expires items per ToS: explicit Date, date-like string, and unparseable → null", () => {
+    const base = { ...mastodonStatus, mediaUrls: [] };
+    const at = normalizeFeedItem(base, connection(), { expiresAt: new Date("2026-11-05T00:00:00.000Z") });
+    expect(at?.expiresAt).toEqual(new Date("2026-11-05T00:00:00.000Z"));
+    const fromString = normalizeFeedItem(base, connection(), { expiresAt: "2026-11-05T00:00:00.000Z" });
+    expect(fromString?.expiresAt).toEqual(new Date("2026-11-05T00:00:00.000Z"));
+    expect(normalizeFeedItem(base, connection(), { expiresAt: "not-a-date" })?.expiresAt).toBeNull();
+    expect(normalizeFeedItem(base, connection())?.expiresAt).toBeNull();
+  });
+
+  it("drops items failing the legacy validation", () => {
+    expect(normalizeFeedItem({ ...mastodonStatus, remoteId: 42 as unknown as string }, connection())).toBeNull();
+    expect(normalizeFeedItem({ ...mastodonStatus, createdAt: new Date(Number.NaN) }, connection())).toBeNull();
+    expect(normalizeFeedItem({ ...mastodonStatus, authorHandle: 7 as unknown as string }, connection())).toBeNull();
+    expect(normalizeFeedItem(mastodonStatus, connection())).not.toBeNull();
+  });
+
+  it("proxies only safe media: scheme tricks, protocol-relative and oversized URLs are dropped", () => {
+    const media = feedItemMedia([
+      "https://cdn.example/a.png", "javascript:alert(1)", "data:text/html,x", "//rel.example/b.png",
+      "https://user:pass@cred.example/c.jpg", "not a url", "https://cdn.example/d.webm?v=2", 42,
+    ]);
+    // Credential-bearing URLs are refused by the same safe-URL gate.
+    expect(media.map((ref) => ref.kind)).toEqual(["image", "video"]); // extension sniff
+    expect(media[1]?.proxyUrl).toBe(`${PROXY.proxyPath}?url=${encodeURIComponent("https://cdn.example/d.webm?v=2")}`);
+    assertProxyOnly(media);
+    expect(feedItemMedia("not-an-array")).toEqual([]);
+  });
+
+  it("serves legacy cache payloads (no AST) and v2 payloads through the unchanged /feeds shape", async () => {
+    const state = createMockSocialState();
+    state.feed = [];
+    const mock = createMockSocialConnector(state);
+    const registry = new ConnectorRegistry(); registry.register(mock);
+    const redis = new MemoryFeedRedis();
+    const connectionId = randomUUID();
+    const deps: FeedDependencies = {
+      redis, registry, workspaces: async () => ["ws-1"],
+      connections: async () => [{ id: connectionId, provider: "mock-social", channelId: connectionId, fields: {}, health: "healthy", credentialRotatedAt: null, recentPublishes: [], createdAt: new Date().toISOString() }],
+      connection: async (_ws, id) => ({ id, workspaceId: "ws-1", provider: "mock-social", channelId: id, credentialId: { kind: "credential-ref", id }, fields: {}, createdAt: new Date() }),
+      visible: async () => [connectionId], audit: async () => undefined, requestsPerSecond: () => 0.5, random: () => 0.5,
+    };
+    const service = new FeedsService(deps);
+    const session = { workspaceId: "ws-1", userId: randomUUID(), role: "Owner", authzEpoch: 1, issuedAt: 0, expiresAt: 9_999_999_999 };
+    const key = feedCacheKey("ws-1", connectionId);
+    const legacy = { id: "legacy", remoteId: "legacy", provider: "mock-social", connectionId, authorHandle: "old@social", text: "legacy item", mediaUrls: ["https://cdn.old.example/a.png"], createdAt: new Date("2026-10-01T00:00:00.000Z"), metrics: { likes: 1 } };
+    await redis.set(key, JSON.stringify({ items: [legacy], fetchedAt: new Date().toISOString(), handle: "old@social", displayName: "Old" }), { pxMs: 99_000 });
+    const served = await service.read(session);
+    expect(served.items).toHaveLength(1);
+    expect(served.items[0]).toMatchObject({ remoteId: "legacy", text: "legacy item", metrics: { likes: 1 } });
+    expect(served.items[0]?.createdAt).toBeInstanceOf(Date);
+    expect("content" in (served.items[0] as object)).toBe(false); // additive: absent, not null
+    expect("expiresAt" in (served.items[0] as object)).toBe(false);
+    // A v2 payload keeps the legacy fields and adds the new ones through the same response.
+    const normalized = normalizeFeedItem({ ...legacy, id: "v2", remoteId: "v2" }, { ...connection(), provider: "mock-social" }, { url: "https://old.example/legacy/2", expiresAt: new Date("2026-11-01T00:00:00.000Z") });
+    await redis.set(key, JSON.stringify({ items: [normalized], fetchedAt: new Date().toISOString(), handle: "old@social", displayName: "Old" }), { pxMs: 99_000 });
+    const v2Served = await service.read(session);
+    expect(v2Served.items[0]).toMatchObject({ remoteId: "v2", text: "legacy item", authorRef: "mock-social:old@social", url: "https://old.example/legacy/2" });
+    expect((v2Served.items[0] as { content?: { type?: string } }).content?.type).toBe("doc");
+    expect(v2Served.items[0]?.createdAt).toBeInstanceOf(Date);
+    expect((v2Served.items[0] as unknown as { expiresAt?: Date }).expiresAt).toEqual(new Date("2026-11-01T00:00:00.000Z"));
+  });
+
+  it("still polls and serves end-to-end: connector feed → v2 cache → /feeds response", async () => {
+    const state = createMockSocialState();
+    state.feed = [{
+      id: "e2e", remoteId: "e2e", provider: "mock-social", authorHandle: "carol@social",
+      text: "End to end #acampada", mediaUrls: ["https://cdn.social/e2e.png"],
+      createdAt: new Date("2026-10-06T09:00:00.000Z"), metrics: { likes: 2 },
+    }];
+    const mock = createMockSocialConnector(state);
+    const registry = new ConnectorRegistry(); registry.register(mock);
+    const deps: FeedDependencies = {
+      redis: new MemoryFeedRedis(), registry, workspaces: async () => ["ws-1"],
+      connections: async () => [{ id: "conn-e2e", provider: "mock-social", channelId: "conn-e2e", fields: {}, health: "healthy", credentialRotatedAt: null, recentPublishes: [], createdAt: new Date().toISOString() }],
+      connection: async (_ws, id) => ({ id, workspaceId: "ws-1", provider: "mock-social", channelId: id, credentialId: { kind: "credential-ref", id }, fields: {}, createdAt: new Date() }),
+      visible: async () => ["conn-e2e"], audit: async () => undefined, requestsPerSecond: () => 0.5, random: () => 0.5,
+    };
+    const service = new FeedsService(deps);
+    expect(await service.pollWorkspace("ws-1")).toEqual({ polled: 1, skipped: 0, failed: 0 });
+    const response = await service.read({ workspaceId: "ws-1", userId: randomUUID(), role: "Owner", authzEpoch: 1, issuedAt: 0, expiresAt: 9_999_999_999 });
+    expect(response.items).toHaveLength(1);
+    const item = response.items[0] as NormalizedFeedItem | undefined;
+    expect(item).toBeDefined();
+    expect(item).toMatchObject({ remoteId: "e2e", text: "End to end #acampada", authorRef: "mock-social:carol@social", metrics: { likes: 2 } });
+    expect(item?.content?.type).toBe("doc");
+    expect(item?.content?.children[0]?.children.map((node) => node.type)).toEqual(["text", "hashtag"]);
+    expect(item?.plainText).toBe("End to end #acampada");
+    expect(item?.media?.[0]?.proxyUrl).toBe(`${PROXY.proxyPath}?url=${encodeURIComponent("https://cdn.social/e2e.png")}`);
+    assertZeroRawRemnants(item?.content as RichTextDocument, item?.plainText as string, item?.media as MediaRef[]);
+  });
+});
diff --git a/apps/api/src/feeds/feed-normalize.ts b/apps/api/src/feeds/feed-normalize.ts
new file mode 100644
index 0000000..8fc919f
--- /dev/null
+++ b/apps/api/src/feeds/feed-normalize.ts
@@ -0,0 +1,211 @@
+/**
+ * Feed-item normalization v2 (columns P0c — design §3.2 "Normalization" + §6).
+ *
+ * Every source type funnels into ONE `normalizeFeedItem()`. The legacy `/feeds`
+ * response fields (`text`, `mediaUrls`, `metrics`, dates, ids) are unchanged;
+ * the columns fields are strictly additive:
+ *
+ * - `authorRef`   canonical `{provider}:{handle@host}`; the host is appended
+ *   only when resolvable (from the handle itself, else the connection's
+ *   `instanceUrl` field, IDN→punycode + lowercased by `URL`). No host →
+ *   `{provider}:{handle}`; invalid handle → null.
+ * - `url`         provider permalink candidate — only absolute, credential-free
+ *   http(s) URLs survive (`parseSafeHttpUrl`); anything else → null.
+ * - `content`     safe-content rich-text AST. The ONLY render source: raw HTML
+ *   never survives as markup (`contentKind: "html"` feeds Mastodon-style
+ *   sanitized HTML through the allowlist parser; plain text is auto-linked
+ *   http(s)-only). Scripts, iframes, styles, event handlers and unsafe
+ *   schemes are dropped or reduced to inert text by the parser.
+ * - `plainText`   derived from the AST at ingest (stable function of the AST)
+ *   for saved-search client filtering and previews.
+ * - `media`       proxy-minted media refs; raw provider CDN URLs are only ever
+ *   carried inside the proxy query (`/api/media-proxy?url=…`), never as the
+ *   browser-facing URL.
+ * - `expiresAt`   nullable ToS expiry (YouTube Data-API items: fetched+30d).
+ * - `linkPreview` sanitized Mastodon `card`/OpenGraph payload or null.
+ *
+ * Legacy validation semantics are retained verbatim: finite dates, string
+ * remoteId/handle/text, finite metrics; invalid items are dropped (null).
+ */
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import {
+  DEFAULT_MEDIA_PROXY,
+  neutralizeText,
+  parseLinkPreview,
+  parsePlainText,
+  parseProviderHtml,
+  parseSafeHttpUrl,
+  toProxiedMediaUrl,
+  type CustomEmoji,
+  type LinkPreview,
+  type MediaProxyPolicy,
+  type ParseOptions,
+  type RichTextDocument,
+} from "../../../../packages/safe-content/src/index.js";
+import type { StreamFeedItem } from "./feeds.service.js";
+
+/** Media reference (design §1.2 `feed_items.media`). */
+export interface MediaRef {
+  kind: "image" | "video";
+  /** Media-proxy URL — never the raw provider CDN URL. */
+  proxyUrl: string;
+  width?: number;
+  height?: number;
+  alt?: string;
+}
+
+/** Fully normalized v2 item — everything the persisted `feed_items` row needs. */
+export type NormalizedFeedItem = StreamFeedItem & {
+  authorRef: string | null;
+  url: string | null;
+  content: RichTextDocument;
+  plainText: string;
+  media: MediaRef[];
+  expiresAt: Date | null;
+  linkPreview?: LinkPreview;
+};
+
+export type FeedContentKind = "text" | "html";
+
+export interface NormalizeFeedItemOptions {
+  /** "html" = Mastodon-style sanitized HTML → allowlist AST; default plain text. */
+  contentKind?: FeedContentKind;
+  /** Provider permalink candidate; relative/unsafe schemes → null. */
+  url?: unknown;
+  /** ToS expiry (YouTube Data API: fetched_at + 30d). Unparseable → null. */
+  expiresAt?: unknown;
+  /** Mastodon `card` / OpenGraph payload → sanitized preview; hostile → null. */
+  linkPreview?: unknown;
+  mediaProxy?: MediaProxyPolicy;
+  emojis?: readonly CustomEmoji[];
+}
+
+/** Upper bound on media refs per item; Mastodon ≤4, YouTube 1 — generous cap. */
+const MAX_MEDIA = 16;
+/** Extension sniff for kind when the source only offers bare URLs. */
+const VIDEO_EXT = /\.(?:mp4|webm|mov|m4v|ogv)(?:[?#]|$)/i;
+/** Same shape safe-content enforces for handles (`user` | `user@host`). */
+const HANDLE = /^[\p{L}\p{N}_.-]{1,64}(?:@[\p{L}\p{N}.-]{1,253})?$/u;
+
+/**
+ * Canonical author ref `{provider}:{handle@host}` (design §3.1/§3.2). The host
+ * comes from the handle itself, else from a federated `instanceUrl` connection
+ * field; `URL` lowercases and punycodes it, and the port never participates.
+ */
+export function feedAuthorRef(provider: string, authorHandle: string, instanceUrl?: unknown): string | null {
+  const handle = neutralizeText(authorHandle).trim().replace(/^@+/, "");
+  if (!HANDLE.test(handle)) return null;
+  const host = handle.includes("@") ? null : instanceHost(instanceUrl);
+  return `${provider}:${handle}${host ? `@${host}` : ""}`;
+}
+
+function instanceHost(raw: unknown): string | null {
+  if (typeof raw !== "string" || raw.trim() === "") return null;
+  try {
+    const url = new URL(raw.trim());
+    return url.protocol === "http:" || url.protocol === "https:" ? url.hostname : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Derives proxy-minted media refs; unsafe origin URLs are dropped entirely. */
+export function feedItemMedia(urls: unknown, policy: MediaProxyPolicy = DEFAULT_MEDIA_PROXY): MediaRef[] {
+  if (!Array.isArray(urls)) return [];
+  const out: MediaRef[] = [];
+  for (const raw of urls.slice(0, MAX_MEDIA)) {
+    const proxyUrl = toProxiedMediaUrl(raw, policy);
+    if (proxyUrl === null) continue;
+    out.push({ kind: typeof raw === "string" && VIDEO_EXT.test(raw) ? "video" : "image", proxyUrl });
+  }
+  return out;
+}
+
+/**
+ * Flat text derived from a rich-text document. Pure and total over the closed
+ * AST: same document in, same string out — stable across storage round-trips.
+ * Links contribute their visible label (for parsed plain text that is the URL
+ * without the scheme, so host/path terms stay filterable).
+ */
+export function astToPlainText(doc: RichTextDocument): string {
+  const lines: string[] = [];
+  for (const paragraph of doc.children) {
+    let line = "";
+    for (const node of paragraph.children) {
+      switch (node.type) {
+        case "text":
+          line += node.text;
+          break;
+        case "emoji":
+          line += `:${node.shortcode}:`;
+          break;
+        case "linebreak":
+          line += "\n";
+          break;
+        case "link":
+          for (const child of node.children) line += child.type === "text" ? child.text : `:${child.shortcode}:`;
+          break;
+        case "mention":
+          line += `@${node.handle}`;
+          break;
+        case "hashtag":
+          line += `#${node.tag}`;
+          break;
+      }
+    }
+    lines.push(line);
+  }
+  return lines.join("\n\n");
+}
+
+function normalizeExpiresAt(raw: unknown): Date | null {
+  if (raw instanceof Date) return Number.isFinite(raw.getTime()) ? raw : null;
+  if (typeof raw === "string" || typeof raw === "number") {
+    const date = new Date(raw);
+    return Number.isFinite(date.getTime()) ? date : null;
+  }
+  return null;
+}
+
+/**
+ * The single funnel (design §3.2). Returns null for items failing the legacy
+ * validation, otherwise the legacy shape plus the additive v2 fields. Content
+ * is parsed here — callers never pass an AST, so raw provider HTML cannot
+ * bypass the allowlist parser.
+ */
+export function normalizeFeedItem(
+  item: FeedItem,
+  connection: ConnectorConnection,
+  options: NormalizeFeedItemOptions = {},
+): NormalizedFeedItem | null {
+  const createdAt = new Date(item.createdAt);
+  if (!Number.isFinite(createdAt.getTime()) || typeof item.remoteId !== "string" || typeof item.text !== "string" || typeof item.authorHandle !== "string") {
+    return null;
+  }
+  const mediaProxy = options.mediaProxy ?? DEFAULT_MEDIA_PROXY;
+  const parseOptions: ParseOptions = { mediaProxy, ...(options.emojis ? { emojis: options.emojis } : {}) };
+  const content = options.contentKind === "html"
+    ? parseProviderHtml(item.text, parseOptions)
+    : parsePlainText(item.text, parseOptions);
+  const safeUrl = parseSafeHttpUrl(options.url);
+  const preview = parseLinkPreview(options.linkPreview, mediaProxy);
+  const mediaUrls = Array.isArray(item.mediaUrls) ? item.mediaUrls.filter((url): url is string => typeof url === "string") : [];
+  return {
+    id: typeof item.id === "string" ? item.id : item.remoteId,
+    remoteId: item.remoteId,
+    provider: connection.provider,
+    connectionId: connection.id,
+    authorHandle: item.authorHandle,
+    authorRef: feedAuthorRef(connection.provider, item.authorHandle, connection.fields.instanceUrl),
+    url: safeUrl === null ? null : safeUrl.href,
+    text: item.text,
+    content,
+    plainText: astToPlainText(content),
+    createdAt,
+    mediaUrls,
+    media: feedItemMedia(item.mediaUrls, mediaProxy),
+    metrics: Object.fromEntries(Object.entries(item.metrics ?? {}).filter(([, value]) => typeof value === "number" && Number.isFinite(value))),
+    expiresAt: normalizeExpiresAt(options.expiresAt),
+    ...(preview === null ? {} : { linkPreview: preview }),
+  };
+}
diff --git a/apps/api/src/feeds/feed-registry.ts b/apps/api/src/feeds/feed-registry.ts
new file mode 100644
index 0000000..e6df6c9
--- /dev/null
+++ b/apps/api/src/feeds/feed-registry.ts
@@ -0,0 +1,18 @@
+import type { CredentialAccessor } from "@tactical-media-broadcast-hub/connector-sdk";
+import { connectionRegistry } from "../connections/connector-registry.js";
+import { oauthFetch } from "../connections/oauth-fetch.js";
+import { createMockSocialConnector, createMockSocialState } from "../../../../packages/connector-mock-social/src/index.js";
+
+/** Composition boundary: the demo connector uses deterministic public data, no OAuth. */
+export function feedRegistry(credentials: CredentialAccessor) {
+  const registry = connectionRegistry(credentials, oauthFetch);
+  const state = createMockSocialState();
+  const now = Date.now();
+  state.feed = Array.from({ length: 12 }, (_, index) => ({
+    id: `demo-feed-${index}`, remoteId: `demo-feed-${index}`, provider: "mock-social",
+    authorHandle: "mock@social", text: `Mock Social feed item ${index + 1}: ready for Streams.`,
+    mediaUrls: [], createdAt: new Date(now - index * 60_000), metrics: { likes: index },
+  }));
+  registry.register(createMockSocialConnector(state));
+  return registry;
+}
diff --git a/apps/api/src/feeds/feeds.controller.ts b/apps/api/src/feeds/feeds.controller.ts
new file mode 100644
index 0000000..4c8c7f8
--- /dev/null
+++ b/apps/api/src/feeds/feeds.controller.ts
@@ -0,0 +1,23 @@
+import { Controller, Get, Inject, Param, Post, Query, Req, UseGuards } from "@nestjs/common";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { parseId, parseLimit, requireSession } from "../http/validation.js";
+import { FeedsService } from "./feeds.service.js";
+
+@Controller("feeds")
+@UseGuards(RbacGuard)
+export class FeedsController {
+  constructor(@Inject(FeedsService) private readonly feeds: FeedsService) {}
+  @Get()
+  @RequirePermission("draft.view")
+  list(@Req() request: AuthenticatedRequest, @Query("cursor") cursor?: string, @Query("limit") limit?: string) {
+    return this.feeds.read(requireSession(request), { cursor, limit: parseLimit(limit, 40, 200) });
+  }
+  @Post("refresh")
+  @RequirePermission("draft.view")
+  refresh(@Req() request: AuthenticatedRequest) { return this.feeds.refresh(requireSession(request)); }
+  @Get(":connectionId")
+  @RequirePermission("draft.view")
+  connection(@Req() request: AuthenticatedRequest, @Param("connectionId") connectionId: string, @Query("cursor") cursor?: string, @Query("limit") limit?: string) {
+    return this.feeds.read(requireSession(request), { connectionId: parseId(connectionId), cursor, limit: parseLimit(limit, 40, 200) });
+  }
+}
diff --git a/apps/api/src/feeds/feeds.dependencies.ts b/apps/api/src/feeds/feeds.dependencies.ts
new file mode 100644
index 0000000..dec65d0
--- /dev/null
+++ b/apps/api/src/feeds/feeds.dependencies.ts
@@ -0,0 +1,72 @@
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import type { ConnectorRegistry, CredentialAccessor } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { SessionPayload } from "../auth/session.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { PgConnectionStore } from "../connections/connection-store.js";
+import type { ConnectionSummary } from "../connections/connections.service.js";
+import { pool } from "../db/client.js";
+import { GroupsService, hasWorkspaceWideAccess } from "../groups/groups.service.js";
+import { RespControlRedis, type ControlRedis } from "../media-control/redis.js";
+import { vault } from "../vault/vault.js";
+import { feedRegistry } from "./feed-registry.js";
+
+export interface FeedDependencies {
+  redis: Pick<ControlRedis, "get" | "set" | "eval" | "close">;
+  registry: ConnectorRegistry;
+  workspaces(): Promise<string[]>;
+  connections(workspaceId: string): Promise<ConnectionSummary[]>;
+  connection(workspaceId: string, id: string): Promise<ConnectorConnection>;
+  visible(session: SessionPayload): Promise<string[]>;
+  audit(session: SessionPayload): Promise<void>;
+  /** Conservative share of the connector's SDK budget; remaining capacity serves other operations. */
+  requestsPerSecond(provider: string): number;
+  random(): number;
+}
+
+export function feedDefaults(): FeedDependencies {
+  const store = new PgConnectionStore();
+  // A single registry preserves the connector's per-host HTTP token buckets.
+  const credentials: CredentialAccessor = {
+    async getAccessToken(connection) { return credentials.getSecret(connection, "access_token"); },
+    async getSecret(connection, key) {
+      const stored = await store.get(connection.workspaceId, connection.id);
+      if (!stored.credential) throw new Error("Credential missing");
+      const bytes = await vault.open(connection.workspaceId, connection.id, stored.credential);
+      const secrets = JSON.parse(bytes.toString()) as Record<string, unknown>;
+      const value = secrets[key];
+      if (typeof value !== "string" || !value) throw new Error("Credential missing");
+      return value;
+    },
+    async put(connection, key, value) {
+      const stored = await store.get(connection.workspaceId, connection.id);
+      if (!stored.credential) throw new Error("Credential missing");
+      const bytes = await vault.open(connection.workspaceId, connection.id, stored.credential);
+      const secrets = JSON.parse(bytes.toString()) as Record<string, unknown>;
+      secrets[key] = value;
+      const sealed = await vault.seal(connection.workspaceId, connection.id, Buffer.from(JSON.stringify(secrets)));
+      await store.rotateCredential(connection.workspaceId, connection.id, stored.credential, sealed);
+    },
+  };
+  return {
+    redis: new RespControlRedis(process.env.REDIS_URL ?? "redis://127.0.0.1:6379"),
+    registry: feedRegistry(credentials),
+    async workspaces() {
+      const result = await pool.query<{ id: string }>("SELECT id FROM workspaces ORDER BY id");
+      return result.rows.map((row) => row.id);
+    },
+    connections: (workspaceId) => store.list(workspaceId),
+    connection: async (workspaceId, id) => (await store.get(workspaceId, id)).connection,
+    visible: async (session) => (await new GroupsService().getVisibleConnections(session.workspaceId, session.userId, hasWorkspaceWideAccess(session.role))).connectionIds,
+    audit: async (session) => { await appendTenantAudit(session.workspaceId, {
+      actorUserId: session.userId, actorRole: session.role, action: "feeds.refresh",
+      targetType: "workspace", targetId: session.workspaceId,
+    }); },
+    // The smallest current feed connector SDK budget is 0.5 RPS. Never raise it
+    // via an env override; lowering the SDK policy also lowers poll frequency.
+    requestsPerSecond: (provider) => {
+      const configured = Number(process.env[`CONNECTOR_RATE_${provider.toUpperCase().replace(/-/g, "_")}_RPS`]);
+      return Number.isFinite(configured) && configured > 0 ? Math.min(0.5, configured) : 0.5;
+    },
+    random: Math.random,
+  };
+}
diff --git a/apps/api/src/feeds/feeds.integration.test.ts b/apps/api/src/feeds/feeds.integration.test.ts
new file mode 100644
index 0000000..bdd5426
--- /dev/null
+++ b/apps/api/src/feeds/feeds.integration.test.ts
@@ -0,0 +1,102 @@
+import "reflect-metadata";
+import { randomUUID } from "node:crypto";
+import { Module, UnauthorizedException, ForbiddenException, type ExecutionContext, type INestApplication } from "@nestjs/common";
+import { NestFactory, Reflector } from "@nestjs/core";
+import { InMemoryCredentials } from "@tactical-media-broadcast-hub/connector-sdk";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+import { DemoController } from "../demo/demo.controller.js";
+import { PERMISSION_KEY, RbacGuard } from "../rbac/rbac.guard.js";
+import type { SessionPayload } from "../auth/session.js";
+import { injectHttp } from "../connections/http-test-transport.js";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { feedRegistry } from "./feed-registry.js";
+import { FeedsService, type FeedResponse } from "./feeds.service.js";
+import { FeedsController } from "./feeds.controller.js";
+import { MemoryFeedRedis } from "./testing.js";
+
+const memory = vi.hoisted(() => ({ rows: new Map<string, { id: string; workspaceId: string; provider: string; channelId: string }>(), audits: [] as string[] }));
+vi.mock("../db/client.js", () => ({
+  pool: {},
+  withTenant: async (workspaceId: string, callback: (client: { query(sql: string, values: unknown[]): Promise<{ rows: Array<{ id: string }>; rowCount: number }> }) => Promise<unknown>) => callback({
+    async query(sql, values) {
+      if (sql.startsWith("INSERT INTO connections")) {
+        const id = randomUUID();
+        memory.rows.set(id, { id, workspaceId, provider: String(values[1]), channelId: String(values[2]) });
+        return { rows: [{ id }], rowCount: 1 };
+      }
+      if (sql.includes("audit_append")) memory.audits.push(sql);
+      return { rows: [], rowCount: 1 };
+    },
+  }),
+}));
+const session: SessionPayload = { userId: randomUUID(), workspaceId: randomUUID(), role: "Owner", authzEpoch: 1, issuedAt: 0, expiresAt: 9_999_999_999 };
+@Module({})
+class TestModule {}
+
+describe("HTTP demo connection → connector poll → GET feeds", () => {
+  let app: INestApplication;
+  let canView = true;
+  const registry = feedRegistry(new InMemoryCredentials());
+  const service = new FeedsService({
+    redis: new MemoryFeedRedis(), registry, random: () => 0, requestsPerSecond: () => 0.5,
+    workspaces: async () => [session.workspaceId],
+    connections: async (ws) => [...memory.rows.values()].filter((row) => row.workspaceId === ws).map((row) => ({ ...row, fields: {}, health: "needs_credentials", recentPublishes: [], credentialRotatedAt: null, createdAt: new Date().toISOString() })),
+    connection: async (ws, id): Promise<ConnectorConnection> => {
+      const row = memory.rows.get(id); if (!row || row.workspaceId !== ws) throw new Error("Missing row");
+      return { ...row, fields: {}, credentialId: { kind: "credential-ref", id }, createdAt: new Date() };
+    },
+    visible: async (s) => [...memory.rows.values()].filter((row) => row.workspaceId === s.workspaceId).map((row) => row.id),
+    audit: async () => { memory.audits.push("feeds.refresh"); },
+  });
+  beforeAll(async () => {
+    vi.spyOn(service, "onApplicationBootstrap").mockImplementation(() => undefined);
+    vi.spyOn(RbacGuard.prototype, "canActivate").mockImplementation(async (context: ExecutionContext) => {
+      const req = context.switchToHttp().getRequest<{ headers: Record<string, string>; session?: SessionPayload }>();
+      if (req.headers.authorization !== "Bearer test-session") throw new UnauthorizedException();
+      const permission = new Reflector().get<string>(PERMISSION_KEY, context.getHandler());
+      if (permission === "draft.view" && !canView) throw new ForbiddenException();
+      req.session = session; return true;
+    });
+    app = await NestFactory.create({ module: TestModule, controllers: [DemoController, FeedsController], providers: [{ provide: FeedsService, useValue: service }] }, { logger: false });
+    await app.init();
+  });
+  afterAll(async () => { await app?.close(); vi.restoreAllMocks(); });
+  const request = (path: string, method = "GET", body?: unknown, auth = true) => injectHttp(app.getHttpAdapter().getInstance(), `http://api.test${path}`, {
+    method, headers: { ...(auth ? { authorization: "Bearer test-session" } : {}), "content-type": "application/json" }, body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  it("seeds through the real demo route without OAuth, then returns only feed-capable items", async () => {
+    const created = await request("/demo/connections", "POST", { provider: "mock-social", channelId: "demo-channel" });
+    expect(created.status).toBe(201);
+    const mockId = (await created.json() as { id: string }).id;
+    const other = await request("/demo/connections", "POST", { provider: "peertube", channelId: "video-channel" });
+    const otherId = (await other.json() as { id: string }).id;
+    const refreshed = await request("/feeds/refresh", "POST");
+    expect(refreshed.status).toBe(201);
+    expect(await refreshed.json()).toEqual({ polled: 1, skipped: 0, failed: 0 });
+    const response = await request("/feeds");
+    expect(response.status).toBe(200);
+    const feed = await response.json() as FeedResponse;
+    expect(feed.items).toHaveLength(12);
+    expect(feed.items.every((item) => item.connectionId === mockId && item.provider === "mock-social")).toBe(true);
+    expect(feed.meta.excludedConnections).toEqual([{ id: otherId, provider: "peertube", reason: "feed_not_supported" }]);
+    expect(feed.meta.connections[0]?.handle).toBe("mock@social");
+    expect(memory.audits.filter((entry) => entry === "feeds.refresh")).toHaveLength(1);
+    await service.pollWorkspace(session.workspaceId);
+    expect(memory.audits.filter((entry) => entry === "feeds.refresh")).toHaveLength(1);
+    const direct = await request(`/feeds/${mockId}?limit=2`);
+    expect((await direct.json() as FeedResponse).items).toHaveLength(2);
+    const absent = await request(`/feeds/${otherId}`);
+    expect((await absent.json() as FeedResponse).items).toEqual([]);
+  });
+  it("requires draft.view on all feed routes and rejects invalid cursor and ID", async () => {
+    expect((await request("/feeds", "GET", undefined, false)).status).toBe(401);
+    canView = false;
+    expect((await request("/feeds")).status).toBe(403);
+    expect((await request("/feeds/refresh", "POST")).status).toBe(403);
+    expect((await request(`/feeds/${[...memory.rows.keys()][0]}`)).status).toBe(403);
+    canView = true;
+    expect((await request("/feeds/not-a-uuid")).status).toBe(400);
+    expect((await request("/feeds?cursor=garbage")).status).toBe(400);
+    expect((await request("/feeds?limit=-1")).status).toBe(400);
+  });
+});
diff --git a/apps/api/src/feeds/feeds.module.ts b/apps/api/src/feeds/feeds.module.ts
new file mode 100644
index 0000000..191d59b
--- /dev/null
+++ b/apps/api/src/feeds/feeds.module.ts
@@ -0,0 +1,24 @@
+import { Module } from "@nestjs/common";
+import { FeedsController } from "./feeds.controller.js";
+import { FeedsService } from "./feeds.service.js";
+import { ColumnsController } from "./columns.controller.js";
+import { ColumnStore } from "./column-store.js";
+import { ColumnScheduler } from "./column-scheduler.js";
+import { columnsProviders } from "./columns.dependencies.js";
+
+/**
+ * Feeds + columns (P1): the columns controller/store/scheduler join the feeds
+ * module — one surface, one connector registry, one hot-cache dependency set.
+ * ColumnStore is injected into FeedsService for the additive meta.columns.
+ */
+@Module({
+  // Controllers are ordered deliberately: ColumnsController's static paths
+  // (/feeds/columns, /feeds/columns/reorder, …) must register BEFORE
+  // FeedsController's parametric /feeds/:connectionId, or that route would
+  // capture "columns" as a connection id (Express matches in declaration
+  // order in Express/Nest's router).
+  controllers: [ColumnsController, FeedsController],
+  providers: [FeedsService, ColumnStore, ColumnScheduler, ...columnsProviders],
+  exports: [FeedsService, ColumnStore, ColumnScheduler],
+})
+export class FeedsModule {}
diff --git a/apps/api/src/feeds/feeds.service.ts b/apps/api/src/feeds/feeds.service.ts
new file mode 100644
index 0000000..36ea1a3
--- /dev/null
+++ b/apps/api/src/feeds/feeds.service.ts
@@ -0,0 +1,257 @@
+import { BadRequestException, Inject, Injectable, Logger, NotFoundException, Optional, type OnApplicationBootstrap, type OnApplicationShutdown } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import { RateLimitError } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { SessionPayload } from "../auth/session.js";
+import type { ConnectionSummary } from "../connections/connections.service.js";
+import { normalizeFeedItem, type NormalizedFeedItem } from "./feed-normalize.js";
+import { feedDefaults, type FeedDependencies } from "./feeds.dependencies.js";
+import { ColumnStore, type ColumnRecord } from "./column-store.js";
+
+export const FEED_DEPENDENCIES = Symbol("FEED_DEPENDENCIES");
+export const FEED_CONCURRENCY = 4;
+const DISCOVERY_MS = 5_000;
+const CACHE_SLACK_MS = 30_000;
+const LEASE_MS = 30_000;
+const RENEW_LEASE = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) else return 0 end";
+const RELEASE_LEASE = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) else return 0 end";
+export const feedCacheKey = (workspaceId: string, id: string): string => `feeds:${workspaceId}:${id}:home`;
+export function feedIntervalMs(rps: number): number {
+  if (!Number.isFinite(rps) || rps <= 0) throw new Error("Feed rate must be positive");
+  // Identity + feed, allocating at most half the declared budget to polling.
+  return Math.max(60_000, Math.ceil(4_000 / rps));
+}
+export const feedCacheTtlMs = (intervalMs: number): number => Math.ceil(intervalMs * 1.2) + CACHE_SLACK_MS;
+export interface StreamFeedItem extends FeedItem { connectionId: string }
+interface CachedFeed { items: NormalizedFeedItem[]; fetchedAt: string; handle: string; displayName: string }
+export interface FeedResponse {
+  items: StreamFeedItem[];
+  nextCursor: string | null;
+  meta: {
+    configuredFeeds: number;
+    connections: Array<{ id: string; provider: string; handle: string; displayName: string; capabilities: string[]; fetchedAt: string | null; status: "ready" | "pending" }>;
+    excludedConnections: Array<{ id: string; provider: string; reason: "feed_not_supported" }>;
+    /**
+     * Additive (P1): the persisted column list, when the workspace has any.
+     * Absent (not null) for workspaces that never touched the columns API, so
+     * the legacy shape is byte-identical for existing clients.
+     */
+    columns?: Array<{ id: string; type: string; title: string; position: number }>;
+  };
+}
+interface Position { at: number; key: string }
+const itemKey = (item: StreamFeedItem): string => JSON.stringify([item.connectionId, item.id]);
+function position(item: StreamFeedItem): Position { return { at: item.createdAt.getTime(), key: itemKey(item) }; }
+function compare(a: Position, b: Position): number { return b.at - a.at || a.key.localeCompare(b.key); }
+function decodeCursor(cursor: string): Position {
+  try {
+    if (cursor.length > 4096) throw new Error();
+    const parsed: unknown = JSON.parse(Buffer.from(cursor, "base64url").toString());
+    if (typeof parsed !== "object" || parsed === null || !("at" in parsed) || !("key" in parsed) ||
+      typeof parsed.at !== "number" || !Number.isFinite(parsed.at) || typeof parsed.key !== "string") throw new Error();
+    return { at: parsed.at, key: parsed.key };
+  } catch { throw new BadRequestException("Invalid feed cursor"); }
+}
+function normalize(item: FeedItem, connection: ConnectorConnection): NormalizedFeedItem | null {
+  return normalizeFeedItem(item, connection);
+}
+export { normalize };
+
+@Injectable()
+export class FeedsService implements OnApplicationBootstrap, OnApplicationShutdown {
+  private readonly deps: FeedDependencies;
+  private readonly logger = new Logger(FeedsService.name);
+  private timer?: ReturnType<typeof setTimeout>;
+  private running = false;
+  private active?: Promise<void>;
+  private readonly cycles = new Map<string, Promise<{ polled: number; skipped: number; failed: number }>>();
+  private inFlight = 0;
+  private readonly waiters: Array<() => void> = [];
+  private readonly columns?: ColumnStore;
+  constructor(@Optional() @Inject(FEED_DEPENDENCIES) dependencies?: FeedDependencies, @Optional() @Inject(ColumnStore) columns?: ColumnStore) {
+    this.deps = dependencies ?? feedDefaults();
+    this.columns = columns;
+  }
+
+  /** Persisted columns for meta.columns (additive; absent when never created). */
+  async columnSummaries(workspaceId: string): Promise<Array<{ id: string; type: string; title: string; position: number }>> {
+    if (this.columns === undefined) return [];
+    return columnSummariesOf(await this.columns.list(workspaceId));
+  }
+
+  onApplicationBootstrap(): void {
+    this.running = true;
+    this.schedule(0);
+  }
+  async onApplicationShutdown(): Promise<void> {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    await this.active;
+    await Promise.allSettled(this.cycles.values());
+    this.deps.redis.close();
+  }
+  private schedule(delay: number): void {
+    if (!this.running) return;
+    this.timer = setTimeout(() => {
+      this.active = this.pollAll().catch(() => this.logger.warn("Feed discovery unavailable")).finally(() => {
+        this.active = undefined;
+        this.schedule(DISCOVERY_MS + Math.round(this.deps.random() * 1_000));
+      });
+    }, delay);
+    this.timer.unref();
+  }
+  async pollAll(): Promise<void> {
+    for (const workspaceId of await this.deps.workspaces()) await this.pollWorkspace(workspaceId);
+  }
+  /** Feed-capable connection summaries — the lazy-seeding input for columns. */
+  async capableConnections(workspaceId: string): Promise<ConnectionSummary[]> {
+    return (await this.deps.connections(workspaceId)).filter((row) => this.capable(row));
+  }
+
+  private capable(row: ConnectionSummary): boolean {
+    if (!this.deps.registry.has(row.provider)) return false;
+    const connector = this.deps.registry.get(row.provider);
+    return connector.manifest().capabilities.feed === true && connector.getFeed !== undefined;
+  }
+  /** Refresh shares the scheduler's cooldowns and concurrency limit; repeated clicks cannot bypass them. */
+  async refresh(session: SessionPayload) {
+    await this.deps.audit(session);
+    return this.pollWorkspace(session.workspaceId, await this.deps.visible(session));
+  }
+  pollWorkspace(workspaceId: string, visibleIds?: string[]): Promise<{ polled: number; skipped: number; failed: number }> {
+    const key = JSON.stringify([workspaceId, visibleIds?.slice().sort() ?? null]);
+    const current = this.cycles.get(key);
+    if (current) return current;
+    const cycle = this.cycle(workspaceId, visibleIds).finally(() => this.cycles.delete(key));
+    this.cycles.set(key, cycle);
+    return cycle;
+  }
+  private async cycle(workspaceId: string, visibleIds?: string[]) {
+    const rows = (await this.deps.connections(workspaceId)).filter((row) => this.capable(row) && (!visibleIds || visibleIds.includes(row.id)));
+    const results = { polled: 0, skipped: 0, failed: 0 };
+    let index = 0;
+    await Promise.all(Array.from({ length: Math.min(FEED_CONCURRENCY, rows.length) }, async () => {
+      for (let row = rows[index++]; row; row = rows[index++]) {
+        if (this.inFlight >= FEED_CONCURRENCY) await new Promise<void>((resolve) => this.waiters.push(resolve));
+        else this.inFlight += 1;
+        try { results[await this.poll(workspaceId, row)] += 1; }
+        catch { results.failed += 1; this.logger.warn("Feed poll unavailable"); }
+        finally {
+          const waiter = this.waiters.shift();
+          if (waiter) waiter(); else this.inFlight -= 1;
+        }
+      }
+    }));
+    return results;
+  }
+  private async poll(workspaceId: string, row: ConnectionSummary): Promise<"polled" | "skipped" | "failed"> {
+    const interval = feedIntervalMs(this.deps.requestsPerSecond(row.provider));
+    const delay = interval + Math.round(interval * 0.2 * this.deps.random());
+    const key = feedCacheKey(workspaceId, row.id);
+    const leaseKey = `${key}:lease`;
+    const owner = randomUUID();
+    if (!await this.deps.redis.set(leaseKey, owner, { nx: true, pxMs: LEASE_MS })) return "skipped";
+    let heartbeat: ReturnType<typeof setInterval> | undefined;
+    let renew: Promise<unknown> = Promise.resolve();
+    let cooldown = delay;
+    let started = false;
+    try {
+      if (!await this.deps.redis.set(`${key}:cooldown`, "idle", { nx: true, pxMs: delay })) return "skipped";
+      started = true;
+      heartbeat = setInterval(() => {
+        renew = this.deps.redis.eval(RENEW_LEASE, [leaseKey], [owner, String(LEASE_MS)]).catch(() => {
+          this.logger.warn("Feed lease renewal unavailable");
+        });
+      }, LEASE_MS / 3);
+      heartbeat.unref();
+      const connection = await this.deps.connection(workspaceId, row.id);
+      const connector = this.deps.registry.get(connection.provider);
+      const identity = await connector.getIdentity(connection);
+      const page = await connector.getFeed?.(connection, { kind: "home", limit: 40 });
+      const items = [...new Map((page?.items ?? []).map((item) => normalize(item, connection)).filter((item): item is NormalizedFeedItem => item !== null).map((item) => [itemKey(item), item])).values()];
+      await this.deps.redis.set(key, JSON.stringify({ items, fetchedAt: new Date().toISOString(), handle: identity.handle, displayName: identity.displayName ?? identity.handle } satisfies CachedFeed), { pxMs: feedCacheTtlMs(interval) });
+      return "polled";
+    } catch (error) {
+      await this.deps.redis.set(key, "null", { pxMs: feedCacheTtlMs(interval) });
+      if (error instanceof RateLimitError && error.retryAfterMs) cooldown = Math.max(delay, error.retryAfterMs);
+      return "failed";
+    } finally {
+      if (heartbeat) clearInterval(heartbeat);
+      await renew;
+      // Completing a long SDK call starts a fresh cooldown. The renewable
+      // lease prevents another replica from entering while that call runs.
+      try {
+        if (started) await this.deps.redis.set(`${key}:cooldown`, "idle", { pxMs: cooldown });
+      } finally { await this.deps.redis.eval(RELEASE_LEASE, [leaseKey], [owner]); }
+    }
+  }
+
+  /**
+   * Hot-cache write-through for the legacy /feeds surface (design §3.4): the
+   * column scheduler's home-source polls push their normalized items here so
+   * /feeds stays cache-first with no external polling of its own.
+   */
+  async cacheHomeFeed(workspaceId: string, connectionId: string, items: NormalizedFeedItem[]): Promise<void> {
+    const rows = await this.deps.connections(workspaceId);
+    const row = rows.find((candidate) => candidate.id === connectionId);
+    if (row === undefined) return;
+    const interval = feedIntervalMs(this.deps.requestsPerSecond(row.provider));
+    let handle = String(row.fields.handle ?? row.channelId);
+    let displayName = String(row.fields.displayName ?? row.channelId);
+    try {
+      const connection = await this.deps.connection(workspaceId, connectionId);
+      const identity = await this.deps.registry.get(connection.provider).getIdentity(connection);
+      handle = identity.handle;
+      displayName = identity.displayName ?? identity.handle;
+    } catch { /* Identity is best-effort here; the cached text still serves. */ }
+    await this.deps.redis.set(feedCacheKey(workspaceId, connectionId), JSON.stringify({
+      items, fetchedAt: new Date().toISOString(), handle, displayName,
+    } satisfies CachedFeed), { pxMs: feedCacheTtlMs(interval) });
+  }
+
+  async read(session: SessionPayload, options: { connectionId?: string; cursor?: string; limit?: number } = {}): Promise<FeedResponse> {
+    const limit = options.limit ?? 40;
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new BadRequestException("Invalid feed limit");
+    const after = options.cursor ? decodeCursor(options.cursor) : null;
+    const visible = new Set(await this.deps.visible(session));
+    const rows = (await this.deps.connections(session.workspaceId)).filter((row) => visible.has(row.id) && (!options.connectionId || row.id === options.connectionId));
+    if (options.connectionId && rows.length === 0) throw new NotFoundException("Connection not found");
+    const meta: FeedResponse["meta"] = { configuredFeeds: 0, connections: [], excludedConnections: [] };
+    const merged: StreamFeedItem[] = [];
+    for (const row of rows) {
+      if (!this.capable(row)) { meta.excludedConnections.push({ id: row.id, provider: row.provider, reason: "feed_not_supported" }); continue; }
+      meta.configuredFeeds += 1;
+      const raw = await this.deps.redis.get(feedCacheKey(session.workspaceId, row.id));
+      let cached: CachedFeed | null = null;
+      try { cached = raw ? JSON.parse(raw) as CachedFeed | null : null; } catch { /* An invalid cache is pending until the next poll. */ }
+      meta.connections.push({
+        id: row.id, provider: row.provider, handle: cached?.handle ?? String(row.fields.handle ?? row.channelId),
+        displayName: cached?.displayName ?? String(row.fields.displayName ?? row.channelId),
+        capabilities: Object.entries(this.deps.registry.get(row.provider).manifest().capabilities).filter(([, enabled]) => enabled === true).map(([capability]) => capability),
+        fetchedAt: cached?.fetchedAt ?? null, status: cached ? "ready" : "pending",
+      });
+      for (const cachedItem of cached?.items ?? []) {
+        merged.push({
+          ...cachedItem,
+          connectionId: row.id, provider: row.provider,
+          createdAt: new Date(cachedItem.createdAt),
+          ...(cachedItem.expiresAt === undefined ? {} : { expiresAt: cachedItem.expiresAt === null ? null : new Date(cachedItem.expiresAt) }),
+        } satisfies StreamFeedItem);
+      }
+    }
+    const sorted = merged.sort((a, b) => compare(position(a), position(b))).filter((item) => !after || compare(position(item), after) > 0);
+    const items = sorted.slice(0, limit);
+    const last = items[items.length - 1];
+    // Additive meta.columns: only when the workspace has persisted columns —
+    // a workspace that never touched the columns API gets the legacy shape.
+    if (this.columns !== undefined) {
+      const summaries = await columnSummariesOf(await this.columns.list(session.workspaceId));
+      if (summaries.length > 0) meta.columns = summaries;
+    }
+    return { items, nextCursor: sorted.length > limit && last ? Buffer.from(JSON.stringify(position(last))).toString("base64url") : null, meta };
+  }
+}
+
+function columnSummariesOf(records: ColumnRecord[]): Array<{ id: string; type: string; title: string; position: number }> {
+  return records.map((record) => ({ id: record.id, type: record.type, title: record.title, position: record.position }));
+}
diff --git a/apps/api/src/feeds/feeds.test.ts b/apps/api/src/feeds/feeds.test.ts
new file mode 100644
index 0000000..59c16e3
--- /dev/null
+++ b/apps/api/src/feeds/feeds.test.ts
@@ -0,0 +1,195 @@
+import "reflect-metadata";
+import { randomUUID } from "node:crypto";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { ConnectorRegistry, InMemoryCredentials, RateLimitError, type PlatformConnector } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import { createMockSocialConnector, createMockSocialState } from "../../../../packages/connector-mock-social/src/index.js";
+import type { SessionPayload } from "../auth/session.js";
+import type { ConnectionSummary } from "../connections/connections.service.js";
+import { FeedsService, feedCacheKey, feedCacheTtlMs, feedIntervalMs } from "./feeds.service.js";
+import type { FeedDependencies } from "./feeds.dependencies.js";
+import { connectionRegistry } from "../connections/connector-registry.js";
+import { MemoryFeedRedis } from "./testing.js";
+
+const session: SessionPayload = { workspaceId: randomUUID(), userId: randomUUID(), role: "Owner", authzEpoch: 1, issuedAt: 0, expiresAt: 9_999_999_999 };
+const item = (remoteId: string, createdAt = new Date()): FeedItem => ({ id: remoteId, remoteId, provider: "mock-social", authorHandle: "alice", text: remoteId, mediaUrls: [], createdAt, metrics: {} });
+function setup(count = 1, rps = 0.5) {
+  const state = createMockSocialState();
+  state.feed = [item("first")];
+  const mock = createMockSocialConnector(state);
+  const implementation = mock.getFeed;
+  if (!implementation) throw new Error("Mock feed missing");
+  const getFeed = vi.fn(implementation);
+  mock.getFeed = getFeed;
+  const registry = new ConnectorRegistry(); registry.register(mock);
+  const connections: ConnectorConnection[] = Array.from({ length: count }, () => {
+    const id = randomUUID();
+    return { id, workspaceId: session.workspaceId, provider: "mock-social", channelId: id, credentialId: { kind: "credential-ref", id }, fields: {}, createdAt: new Date() };
+  });
+  const redis = new MemoryFeedRedis();
+  const summaries = (): ConnectionSummary[] => connections.map((row) => ({ id: row.id, provider: row.provider, channelId: row.channelId, fields: row.fields, health: "healthy", credentialRotatedAt: null, recentPublishes: [], createdAt: row.createdAt.toISOString() }));
+  const deps: FeedDependencies = {
+    redis, registry, workspaces: async () => [session.workspaceId], connections: async (ws) => ws === session.workspaceId ? summaries() : [],
+    connection: async (_ws, id) => { const row = connections.find((row) => row.id === id); if (!row) throw new Error(); return row; },
+    visible: async (s) => s.workspaceId === session.workspaceId ? connections.map((row) => row.id) : [],
+    audit: vi.fn(async () => undefined), requestsPerSecond: () => rps, random: () => 0.5,
+  };
+  return { service: new FeedsService(deps), deps, connections, mock, state, getFeed, redis };
+}
+afterEach(() => vi.useRealTimers());
+describe("Feeds pipeline", () => {
+  it("caches normalized JSON with interval + jitter + slack TTL and expires it", async () => {
+    vi.useFakeTimers();
+    const { service, redis, connections } = setup();
+    await service.pollWorkspace(session.workspaceId);
+    const key = feedCacheKey(session.workspaceId, connections[0]?.id ?? "");
+    const entry = redis.entries.get(key);
+    expect(entry?.expiresAt).toBe(Date.now() + feedCacheTtlMs(60_000));
+    const response = await service.read(session);
+    expect(response.items[0]?.createdAt).toBeInstanceOf(Date);
+    expect(response.items[0]?.connectionId).toBe(connections[0]?.id);
+    await vi.advanceTimersByTimeAsync(feedCacheTtlMs(60_000));
+    expect(await redis.get(key)).toBeNull();
+    expect((await service.read(session)).meta.connections[0]?.status).toBe("pending");
+  });
+  it("merges newest first with a stable tie-break cursor, even when new items arrive", async () => {
+    const { service, connections, redis } = setup(2);
+    const date = new Date();
+    for (const row of connections) await redis.set(feedCacheKey(session.workspaceId, row.id), JSON.stringify({ fetchedAt: date.toISOString(), handle: "alice", displayName: "Alice", items: [item("same", date), item("older", new Date(date.getTime() - 1000))] }), { pxMs: 99_000 });
+    const first = await service.read(session, { limit: 1 });
+    expect(first.nextCursor).not.toBeNull();
+    const added = connections[0];
+    if (added) {
+      const key = feedCacheKey(session.workspaceId, added.id);
+      const raw = await redis.get(key);
+      const cached = JSON.parse(raw ?? "{}") as { items: FeedItem[] };
+      cached.items.unshift(item("new-arrival", new Date(date.getTime() + 1000)));
+      await redis.set(key, JSON.stringify(cached), { pxMs: 99_000 });
+    }
+    const next = await service.read(session, { limit: 1, cursor: first.nextCursor ?? undefined });
+    expect(next.items[0]?.connectionId).not.toBe(first.items[0]?.connectionId);
+    expect(next.items[0]?.remoteId).toBe("same");
+    const third = await service.read(session, { limit: 2, cursor: next.nextCursor ?? undefined });
+    expect(third.items.map((row) => row.remoteId)).toEqual(["older", "older"]);
+    expect(third.nextCursor).toBeNull();
+    await expect(service.read(session, { cursor: "bad" })).rejects.toThrow("Invalid feed cursor");
+  });
+  it("filters capabilities and missing methods, exposes exclusions without polling them", async () => {
+    const { service, deps, connections, mock } = setup(3);
+    const noFeed: PlatformConnector = { ...mock, manifest: () => ({ ...mock.manifest(), id: "no-feed", capabilities: { publishText: true, feed: false } }), getFeed: vi.fn() };
+    const missing: PlatformConnector = { ...mock, manifest: () => ({ ...mock.manifest(), id: "missing-feed" }), getFeed: undefined };
+    deps.registry.register(noFeed); deps.registry.register(missing);
+    if (connections[1]) connections[1].provider = "no-feed";
+    if (connections[2]) connections[2].provider = "missing-feed";
+    expect(await service.pollWorkspace(session.workspaceId)).toEqual({ polled: 1, skipped: 0, failed: 0 });
+    const response = await service.read(session);
+    expect(response.meta.configuredFeeds).toBe(1);
+    expect(response.meta.excludedConnections).toHaveLength(2);
+    expect(response.items).toHaveLength(1);
+    expect(noFeed.getFeed).not.toHaveBeenCalled();
+    expect((await service.read(session, { connectionId: connections[1]?.id })).items).toEqual([]);
+  });
+  it("applies group visibility to merged, per-account and refresh operations", async () => {
+    const { service, deps, connections } = setup(2);
+    deps.visible = async () => [connections[0]?.id ?? ""];
+    await service.refresh(session);
+    const response = await service.read(session);
+    expect(response.meta.connections).toHaveLength(1);
+    await expect(service.read(session, { connectionId: connections[1]?.id })).rejects.toThrow("Connection not found");
+    expect((await service.read({ ...session, workspaceId: randomUUID() })).items).toEqual([]);
+  });
+  it("paces low-budget scheduling with positive jitter; refresh and other replicas respect cooldown", async () => {
+    vi.useFakeTimers();
+    const { service, deps, getFeed } = setup(1, 0.01);
+    expect(feedIntervalMs(0.01)).toBe(400_000);
+    service.onApplicationBootstrap();
+    await vi.advanceTimersByTimeAsync(0);
+    expect(getFeed).toHaveBeenCalledTimes(1);
+    const replica = new FeedsService(deps);
+    expect((await replica.refresh(session)).skipped).toBe(1);
+    await vi.advanceTimersByTimeAsync(439_999);
+    expect(getFeed).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(6_000);
+    expect(getFeed).toHaveBeenCalledTimes(2);
+    expect(deps.audit).toHaveBeenCalledTimes(1);
+    await service.onApplicationShutdown();
+    await vi.advanceTimersByTimeAsync(900_000);
+    expect(getFeed).toHaveBeenCalledTimes(2);
+  });
+  it("renews a lease during slow polls and never overlaps refresh from another replica", async () => {
+    vi.useFakeTimers();
+    const { service, deps, getFeed } = setup();
+    let resolveFeed: (() => void) | undefined;
+    getFeed.mockImplementationOnce(() => new Promise((resolve) => { resolveFeed = () => resolve({ items: [item("slow")] }); }));
+    const active = service.pollWorkspace(session.workspaceId);
+    await vi.advanceTimersByTimeAsync(0);
+    await vi.advanceTimersByTimeAsync(150_000);
+    expect((await new FeedsService(deps).pollWorkspace(session.workspaceId)).skipped).toBe(1);
+    resolveFeed?.(); await active;
+    expect(getFeed).toHaveBeenCalledTimes(1);
+    expect((await service.pollWorkspace(session.workspaceId)).skipped).toBe(1);
+  });
+  it("uses stored credentials and the real connector HTTP limiter across accounts on one host", async () => {
+    vi.useFakeTimers();
+    const { deps, connections } = setup(2);
+    const credentials = new InMemoryCredentials();
+    const requests: Array<{ at: number; token: string; path: string }> = [];
+    const start = Date.now();
+    const fetchImpl: typeof fetch = async (input, init) => {
+      const url = new URL(String(input));
+      const token = new Headers(init?.headers).get("authorization") ?? "";
+      requests.push({ at: Date.now() - start, token, path: url.pathname });
+      const account = { id: "alice", username: "alice", acct: "alice", display_name: "Alice", avatar: "", url: "https://social.example/@alice" };
+      const data = url.pathname.endsWith("verify_credentials") ? account : [{
+        id: "status-1", created_at: new Date().toISOString(), content: "<p>A real timeline post</p>",
+        account, media_attachments: [], reblogs_count: 2, replies_count: 1, favourites_count: 3, reblog: null,
+      }];
+      return new Response(JSON.stringify(data), { headers: { "content-type": "application/json" } });
+    };
+    deps.registry = connectionRegistry(credentials, fetchImpl);
+    for (const row of connections) {
+      row.provider = "mastodon"; row.fields.instanceUrl = "https://social.example";
+      await credentials.put(row, "access_token", `secret-${row.id}`);
+    }
+    const service = new FeedsService(deps);
+    const polling = service.pollWorkspace(session.workspaceId);
+    await vi.advanceTimersByTimeAsync(12_000);
+    expect((await polling).polled).toBe(2);
+    expect(requests).toHaveLength(4);
+    expect(requests.every((request) => request.token.startsWith("Bearer secret-"))).toBe(true);
+    for (let i = 1; i < requests.length; i += 1) expect((requests[i]?.at ?? 0) - (requests[i - 1]?.at ?? 0)).toBeGreaterThanOrEqual(2000);
+    const response = await service.read(session);
+    expect(response.items).toHaveLength(2);
+    expect(response.items.every((post) => post.text === "A real timeline post" && post.metrics.favourites === 3)).toBe(true);
+  });
+  it("bounds concurrency across simultaneous workspace cycles", async () => {
+    const { service, deps, getFeed, connections } = setup(10);
+    let running = 0; let max = 0;
+    const releases: Array<() => void> = [];
+    getFeed.mockImplementation(() => new Promise((resolve) => {
+      running += 1; max = Math.max(max, running);
+      releases.push(() => { running -= 1; resolve({ items: [] }); });
+    }));
+    const polls = [service.pollWorkspace(session.workspaceId, connections.slice(0, 5).map((row) => row.id)), service.pollWorkspace(session.workspaceId, connections.slice(5).map((row) => row.id))];
+    for (let i = 0; i < 50; i += 1) { await new Promise<void>((resolve) => setImmediate(resolve)); for (const release of releases.splice(0)) release(); }
+    await Promise.all(polls);
+    expect(max).toBe(4);
+    expect(deps.audit).not.toHaveBeenCalled();
+  });
+  it("fails connections independently, clears stale data and honors Retry-After", async () => {
+    vi.useFakeTimers();
+    const { service, getFeed, mock, connections } = setup();
+    await service.pollWorkspace(session.workspaceId);
+    await vi.advanceTimersByTimeAsync(66_000);
+    getFeed.mockRejectedValueOnce(new RateLimitError("mock-social", 200_000));
+    expect((await service.pollWorkspace(session.workspaceId)).failed).toBe(1);
+    expect((await service.read(session)).items).toEqual([]);
+    await vi.advanceTimersByTimeAsync(100_000);
+    expect((await service.pollWorkspace(session.workspaceId)).skipped).toBe(1);
+    await vi.advanceTimersByTimeAsync(100_000);
+    vi.spyOn(mock, "getIdentity").mockRejectedValueOnce(new Error("Token revoked"));
+    expect((await service.pollWorkspace(session.workspaceId)).failed).toBe(1);
+    expect((await service.read(session, { connectionId: connections[0]?.id })).items).toEqual([]);
+    expect(getFeed).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/apps/api/src/feeds/testing.ts b/apps/api/src/feeds/testing.ts
new file mode 100644
index 0000000..9f785a7
--- /dev/null
+++ b/apps/api/src/feeds/testing.ts
@@ -0,0 +1,28 @@
+import type { FeedDependencies } from "./feeds.dependencies.js";
+
+/** TTL-faithful Redis surface, including ownership checks for renewable leases. */
+type FeedRedis = FeedDependencies["redis"];
+export class MemoryFeedRedis implements FeedRedis {
+  readonly entries = new Map<string, { value: string; expiresAt: number }>();
+  async get(key: string): Promise<string | null> {
+    const entry = this.entries.get(key);
+    if (!entry || entry.expiresAt <= Date.now()) { this.entries.delete(key); return null; }
+    return entry.value;
+  }
+  async set(key: string, value: string, options: { nx?: boolean; pxMs?: number } = {}): Promise<boolean> {
+    // Atomic NX check: do not yield between reading and writing.
+    const entry = this.entries.get(key);
+    if (options.nx && entry && entry.expiresAt > Date.now()) return false;
+    this.entries.set(key, { value, expiresAt: Date.now() + (options.pxMs ?? 1000) });
+    return true;
+  }
+  async eval(script: string, keys: string[], args: string[]): Promise<number> {
+    const key = keys[0] ?? "";
+    const entry = this.entries.get(key);
+    if (!entry || entry.value !== args[0] || entry.expiresAt <= Date.now()) return 0;
+    if (script.includes("PEXPIRE")) entry.expiresAt = Date.now() + Number(args[1]);
+    else this.entries.delete(key);
+    return 1;
+  }
+  close(): void {}
+}
diff --git a/apps/api/src/groups/groups.controller.ts b/apps/api/src/groups/groups.controller.ts
new file mode 100644
index 0000000..6034e8c
--- /dev/null
+++ b/apps/api/src/groups/groups.controller.ts
@@ -0,0 +1,161 @@
+import { BadRequestException, Body, Controller, Delete, Get, Inject, Param, Patch, Post, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { optionalString, parseId, requireObject, requireSession, requireString } from "../http/validation.js";
+import {
+  GroupsService,
+  hasWorkspaceWideAccess,
+  type GroupActor,
+  type GroupDetail,
+  type GroupMembershipResult,
+  type GroupSummary,
+  type VisibleConnections,
+} from "./groups.service.js";
+
+type AuthedRequest = Request & AuthenticatedRequest;
+
+function actorOf(request: AuthedRequest): GroupActor {
+  const session = requireSession(request);
+  return { userId: session.userId, role: session.role };
+}
+
+function optionalDescription(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") throw new BadRequestException("description must be a string");
+  return value;
+}
+
+/**
+ * Member add/remove and group delete bump the workspace authz epoch, which
+ * invalidates every live session; those responses carry `token` — the caller's
+ * replacement session (same contract as /team).
+ */
+@Controller("groups")
+@UseGuards(RbacGuard)
+export class GroupsController {
+  constructor(@Inject(GroupsService) private readonly groups: GroupsService) {}
+
+  /**
+   * The connections the caller may publish through (Compose calls this).
+   * Declared before `:id` so the literal path wins route matching.
+   * session.role is current: role changes bump the epoch and the guard rejects stale sessions.
+   */
+  @Get("visible-connections")
+  @RequirePermission("workspace.view")
+  async visibleConnections(@Req() request: AuthedRequest): Promise<VisibleConnections> {
+    const session = requireSession(request);
+    return this.groups.getVisibleConnections(session.workspaceId, session.userId, hasWorkspaceWideAccess(session.role));
+  }
+
+  @Get("mine")
+  @RequirePermission("workspace.view")
+  async mine(@Req() request: AuthedRequest): Promise<GroupSummary[]> {
+    const session = requireSession(request);
+    return this.groups.getUserGroups(session.workspaceId, session.userId);
+  }
+
+  @Post()
+  @RequirePermission("workspace.members.manage")
+  async create(@Req() request: AuthedRequest, @Body() body: unknown): Promise<GroupSummary> {
+    const dto = requireObject(body, "body");
+    return this.groups.createGroup(
+      requireSession(request).workspaceId,
+      requireString(dto.name, "name"),
+      optionalDescription(dto.description) ?? "",
+      actorOf(request),
+    );
+  }
+
+  @Get()
+  @RequirePermission("workspace.view")
+  async list(@Req() request: AuthedRequest): Promise<GroupSummary[]> {
+    return this.groups.listGroups(requireSession(request).workspaceId);
+  }
+
+  @Get(":id")
+  @RequirePermission("workspace.view")
+  async detail(@Req() request: AuthedRequest, @Param("id") id: string): Promise<GroupDetail> {
+    return this.groups.getGroupDetail(requireSession(request).workspaceId, parseId(id));
+  }
+
+  @Patch(":id")
+  @RequirePermission("workspace.members.manage")
+  async rename(@Req() request: AuthedRequest, @Param("id") id: string, @Body() body: unknown): Promise<GroupSummary> {
+    const dto = requireObject(body, "body");
+    return this.groups.renameGroup(
+      requireSession(request).workspaceId,
+      parseId(id),
+      { name: optionalString(dto.name, "name"), description: optionalDescription(dto.description) },
+      actorOf(request),
+    );
+  }
+
+  @Delete(":id")
+  @RequirePermission("workspace.members.manage")
+  async remove(@Req() request: AuthedRequest, @Param("id") id: string): Promise<GroupMembershipResult> {
+    return this.groups.deleteGroup(requireSession(request).workspaceId, parseId(id), actorOf(request));
+  }
+
+  @Post(":id/members")
+  @RequirePermission("workspace.members.manage")
+  async addMember(@Req() request: AuthedRequest, @Param("id") id: string, @Body() body: unknown): Promise<GroupMembershipResult> {
+    const dto = requireObject(body, "body");
+    return this.groups.addMember(
+      requireSession(request).workspaceId,
+      parseId(id),
+      parseId(requireString(dto.userId, "userId"), "userId"),
+      actorOf(request),
+    );
+  }
+
+  @Delete(":id/members/:userId")
+  @RequirePermission("workspace.members.manage")
+  async removeMember(
+    @Req() request: AuthedRequest,
+    @Param("id") id: string,
+    @Param("userId") userId: string,
+  ): Promise<GroupMembershipResult> {
+    return this.groups.removeMember(requireSession(request).workspaceId, parseId(id), parseId(userId, "userId"), actorOf(request));
+  }
+
+  @Post(":id/connections")
+  @RequirePermission("connection.manage")
+  async assignConnection(@Req() request: AuthedRequest, @Param("id") id: string, @Body() body: unknown): Promise<GroupSummary & GroupMembershipResult> {
+    const dto = requireObject(body, "body");
+    return this.groups.assignConnection(
+      requireSession(request).workspaceId,
+      parseId(id),
+      parseId(requireString(dto.connectionId, "connectionId"), "connectionId"),
+      actorOf(request),
+    );
+  }
+
+  @Delete(":id/connections/:connectionId")
+  @RequirePermission("connection.manage")
+  async unassignConnection(
+    @Req() request: AuthedRequest,
+    @Param("id") id: string,
+    @Param("connectionId") connectionId: string,
+  ): Promise<GroupSummary & GroupMembershipResult> {
+    return this.groups.unassignConnection(
+      requireSession(request).workspaceId,
+      parseId(id),
+      parseId(connectionId, "connectionId"),
+      actorOf(request),
+    );
+  }
+
+  @Post(":id/assets")
+  @RequirePermission("media.manage")
+  async assignAsset(@Req() request: AuthedRequest, @Param("id") id: string, @Body() body: unknown): Promise<GroupSummary> {
+    const dto = requireObject(body, "body");
+    return this.groups.assignAsset(requireSession(request).workspaceId, parseId(id), requireString(dto.assetId, "assetId"), actorOf(request));
+  }
+
+  /** Asset ids are storage keys and may contain `/`: pass them URL-encoded. */
+  @Delete(":id/assets/:assetId")
+  @RequirePermission("media.manage")
+  async unassignAsset(@Req() request: AuthedRequest, @Param("id") id: string, @Param("assetId") assetId: string): Promise<GroupSummary> {
+    return this.groups.unassignAsset(requireSession(request).workspaceId, parseId(id), assetId, actorOf(request));
+  }
+}
diff --git a/apps/api/src/groups/groups.integration.test.ts b/apps/api/src/groups/groups.integration.test.ts
new file mode 100644
index 0000000..9933c83
--- /dev/null
+++ b/apps/api/src/groups/groups.integration.test.ts
@@ -0,0 +1,251 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import type { ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * Groups against a live PostgreSQL, as sp_app (FORCE RLS binds).
+ * Uses its OWN database (GROUPS_IT_DATABASE_URL, plus GROUPS_IT_SUPER_DATABASE_URL
+ * for migrations/seeding) for the same reason as auth.integration.test.ts:
+ * tenancy.integration.test.ts wipes every workspace in the shared DB and vitest
+ * runs files in parallel. Skipped when unset.
+ */
+const appUrl = process.env.GROUPS_IT_DATABASE_URL;
+const ownerUrl = process.env.GROUPS_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  groups: typeof import("./groups.service.js");
+  guard: typeof import("../rbac/rbac.guard.js");
+  session: typeof import("../auth/session.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("groups (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let wsA: string;
+  let wsB: string;
+  let owner: string;
+  let admin: string;
+  let member: string;
+  let outsider: string;
+  let connShared: string;
+  let connPrivate: string;
+  let connB: string;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  async function epoch(ws: string): Promise<number> {
+    return asOwner(async (c) => Number((await c.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [ws])).rows[0]?.authz_epoch));
+  }
+
+  beforeAll(async () => {
+    // The pool reads DATABASE_URL at import time: point it at the isolated DB first.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      groups: await import("./groups.service.js"),
+      guard: await import("../rbac/rbac.guard.js"),
+      session: await import("../auth/session.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    // Seed via the owner pool (FORCE RLS still applies to the owner, so tenant
+    // rows are written inside a tenant context).
+    await asOwner(async (c) => {
+      const ws = async (name: string): Promise<string> =>
+        (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", [name, `${name}-${suffix}`])).rows[0].id as string;
+      wsA = await ws("grp-a");
+      wsB = await ws("grp-b");
+      const user = async (tag: string): Promise<string> =>
+        (
+          await c.query("INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4) RETURNING id", [
+            `grp:${tag}:${suffix}`,
+            `test-${tag}-${suffix}`,
+            `${tag}-${suffix}@example.com`,
+            tag,
+          ])
+        ).rows[0].id as string;
+      owner = await user("owner");
+      admin = await user("admin");
+      member = await user("member");
+      outsider = await user("outsider");
+
+      const inTenant = async (wsId: string, fn: () => Promise<void>): Promise<void> => {
+        await c.query("BEGIN");
+        await c.query("SELECT set_config('app.workspace_id', $1, true)", [wsId]);
+        await fn();
+        await c.query("COMMIT");
+      };
+      await inTenant(wsA, async () => {
+        for (const [u, role] of [
+          [owner, "Owner"],
+          [admin, "Admin"],
+          [member, "Publisher"],
+          [outsider, "Publisher"],
+        ] as const) {
+          await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, $3)", [wsA, u, role]);
+        }
+        const conn = async (ch: string): Promise<string> =>
+          (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id", [wsA, ch]))
+            .rows[0].id as string;
+        connShared = await conn("shared");
+        connPrivate = await conn("private");
+      });
+      await inTenant(wsB, async () => {
+        await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Owner')", [wsB, owner]);
+        connB = (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', 'b') RETURNING id", [wsB]))
+          .rows[0].id as string;
+      });
+    });
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE id = ANY($1::uuid[])", [[wsA, wsB]]);
+        await c.query("DELETE FROM users WHERE external_id LIKE $1", [`grp:%:${suffix}`]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  let groupId: string;
+
+  it("create group -> assign connection -> add member: the member sees exactly that connection", async () => {
+    const svc = new m.groups.GroupsService();
+    const actor = { userId: admin, role: "Admin" };
+    const group = await svc.createGroup(wsA, "Newsroom", "front desk", actor);
+    groupId = group.id;
+    await expect(svc.createGroup(wsA, "Newsroom", "", actor)).rejects.toMatchObject({ status: 409 });
+
+    await svc.assignConnection(wsA, groupId, connShared, actor);
+    const before = await epoch(wsA);
+    const added = await svc.addMember(wsA, groupId, member, actor);
+    expect(await epoch(wsA)).toBeGreaterThan(before);
+    // The replacement token carries the post-bump epoch.
+    expect(m.session.verifySession(added.token)?.authzEpoch).toBe(await epoch(wsA));
+
+    expect(await svc.getVisibleConnections(wsA, member, false)).toEqual({ scope: "groups", connectionIds: [connShared] });
+
+    const detail = await svc.getGroupDetail(wsA, groupId);
+    expect(detail.members.map((x) => x.userId)).toEqual([member]);
+    expect(detail.connections.map((x) => x.connectionId)).toEqual([connShared]);
+    expect((await svc.listGroups(wsA)).find((g) => g.id === groupId)).toMatchObject({ memberCount: 1, connectionCount: 1 });
+    expect((await svc.getUserGroups(wsA, member)).map((g) => g.id)).toEqual([groupId]);
+
+    const actions = await asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [wsA]);
+      const rows = (await c.query("SELECT action FROM audit_log WHERE target_id = $1 ORDER BY seq", [groupId])).rows as Array<{ action: string }>;
+      await c.query("COMMIT");
+      return rows.map((r) => r.action);
+    });
+    expect(actions).toEqual(["group.created", "group.connection_assigned", "group.member_added"]);
+  });
+
+  it("a non-member does NOT see the connection", async () => {
+    const svc = new m.groups.GroupsService();
+    expect(await svc.getVisibleConnections(wsA, outsider, false)).toEqual({ scope: "groups", connectionIds: [] });
+  });
+
+  it("Owner/Admin see ALL workspace connections regardless of group membership", async () => {
+    const svc = new m.groups.GroupsService();
+    for (const u of [owner, admin]) {
+      const visible = await svc.getVisibleConnections(wsA, u, true);
+      expect(visible.scope).toBe("workspace");
+      expect(new Set(visible.connectionIds)).toEqual(new Set([connShared, connPrivate]));
+    }
+  });
+
+  it("@RequireGroupAccess: member passes for the shared connection, outsider and private connection are forbidden, Owner passes", async () => {
+    const epochNow = await epoch(wsA);
+    const tokenFor = (userId: string, role: string): string =>
+      m.session.issueSession({ userId, workspaceId: wsA, role, authzEpoch: epochNow });
+    const check = async (token: string, connectionId: string): Promise<boolean | string> => {
+      const handler = (): void => undefined;
+      Reflect.defineMetadata(m.guard.PERMISSION_KEY, "publication.publish", handler);
+      Reflect.defineMetadata(m.guard.GROUP_ACCESS_KEY, true, handler);
+      const req = { headers: { authorization: `Bearer ${token}` }, params: { connectionId } };
+      const ctx = { getHandler: () => handler, switchToHttp: () => ({ getRequest: () => req }) } as unknown as ExecutionContext;
+      try {
+        return await new m.guard.RbacGuard(new Reflector()).canActivate(ctx);
+      } catch (err) {
+        return (err as Error).constructor.name;
+      }
+    };
+    expect(await check(tokenFor(member, "Publisher"), connShared)).toBe(true);
+    expect(await check(tokenFor(member, "Publisher"), connPrivate)).toBe("ForbiddenException");
+    expect(await check(tokenFor(outsider, "Publisher"), connShared)).toBe("ForbiddenException");
+    expect(await check(tokenFor(owner, "Owner"), connPrivate)).toBe(true);
+  });
+
+  it("cross-tenant scoping: a connection or user from another workspace cannot be attached", async () => {
+    const svc = new m.groups.GroupsService();
+    const actor = { userId: admin, role: "Admin" };
+    await expect(svc.assignConnection(wsA, groupId, connB, actor)).rejects.toMatchObject({ status: 404 });
+    // owner IS a member of B, but this checks a user with no wsA membership is refused:
+    const stranger = await asOwner(
+      async (c) =>
+        (await c.query(
+          "INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, 'S') RETURNING id",
+          [`grp:stranger:${suffix}`, `test-stranger-${suffix}`, `s-${suffix}@x.io`],
+        ))
+          .rows[0].id as string,
+    );
+    await expect(svc.addMember(wsA, groupId, stranger, actor)).rejects.toMatchObject({ status: 400 });
+  });
+
+  it("remove member -> authz_epoch bumps -> connection no longer visible", async () => {
+    const svc = new m.groups.GroupsService();
+    const before = await epoch(wsA);
+    await svc.removeMember(wsA, groupId, member, { userId: admin, role: "Admin" });
+    expect(await epoch(wsA)).toBeGreaterThan(before);
+    expect(await svc.getVisibleConnections(wsA, member, false)).toEqual({ scope: "groups", connectionIds: [] });
+    await expect(svc.removeMember(wsA, groupId, member, { userId: admin, role: "Admin" })).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("deleting a group with members bumps the epoch via the cascade", async () => {
+    const svc = new m.groups.GroupsService();
+    const actor = { userId: admin, role: "Admin" };
+    const g = await svc.createGroup(wsA, "Ephemeral", "", actor);
+    await svc.addMember(wsA, g.id, member, actor);
+    const before = await epoch(wsA);
+    await svc.deleteGroup(wsA, g.id, actor);
+    expect(await epoch(wsA)).toBeGreaterThan(before);
+    await expect(svc.getGroupDetail(wsA, g.id)).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("RLS: workspace A's group rows are invisible from workspace B's context and from no context", async () => {
+    const { withTenant, withSystem } = m.db;
+    const count = async (client: PoolClient, table: string): Promise<number> =>
+      Number((await client.query(`SELECT count(*)::int AS n FROM ${table}`)).rows[0]?.n);
+    await new m.groups.GroupsService().assignAsset(wsA, groupId, "media/abc.png", { userId: admin, role: "Admin" });
+
+    const fromA = await withTenant(wsA, async (c) => ({ groups: await count(c, "groups"), assets: await count(c, "group_assets") }));
+    expect(fromA.groups).toBeGreaterThan(0);
+    expect(fromA.assets).toBe(1);
+    for (const table of ["groups", "group_members", "group_connections", "group_assets"]) {
+      expect(await withTenant(wsB, (c) => count(c, table))).toBe(0);
+      expect(await withSystem((c) => count(c, table))).toBe(0);
+    }
+    await expect(new m.groups.GroupsService().getGroupDetail(wsB, groupId)).rejects.toMatchObject({ status: 404 });
+    // WITH CHECK: a B-context write cannot target A.
+    await expect(
+      withTenant(wsB, (c) => c.query("INSERT INTO groups (workspace_id, name) VALUES ($1, 'smuggled')", [wsA])),
+    ).rejects.toThrow(/row-level security/);
+  });
+});
diff --git a/apps/api/src/groups/groups.service.ts b/apps/api/src/groups/groups.service.ts
new file mode 100644
index 0000000..15756c1
--- /dev/null
+++ b/apps/api/src/groups/groups.service.ts
@@ -0,0 +1,472 @@
+import { BadRequestException, ConflictException, Injectable, NotFoundException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { scrub, type AuditEvent } from "../audit/audit.service.js";
+import { issueSessionInTenant } from "../auth/auth.service.js";
+import { withTenant } from "../db/client.js";
+
+/**
+ * Groups: sub-workspace sharing scopes. Owner/Admin publish through every
+ * connection; everyone else publishes only through connections assigned to a
+ * group they belong to.
+ *
+ * Every mutation writes its audit row on the SAME transaction (audit_append on
+ * the tenant client), so a change can never land without its audit entry.
+ *
+ * Group-membership changes bump the workspace authz epoch (008 trigger), which
+ * invalidates all live sessions — including the caller's. Those mutations return
+ * a fresh token for the caller, minted inside the same transaction (same
+ * contract as TeamService).
+ */
+
+export const WORKSPACE_WIDE_ROLES: readonly string[] = ["Owner", "Admin"];
+
+export function hasWorkspaceWideAccess(role: string): boolean {
+  return WORKSPACE_WIDE_ROLES.includes(role);
+}
+
+export interface GroupActor {
+  userId: string;
+  role: string;
+}
+
+export interface GroupSummary {
+  id: string;
+  name: string;
+  description: string;
+  memberCount: number;
+  connectionCount: number;
+  assetCount: number;
+  createdAt: string;
+}
+
+export interface GroupMember {
+  userId: string;
+  email: string;
+  displayName: string;
+  addedBy: string | null;
+  addedAt: string;
+}
+
+export interface GroupConnection {
+  connectionId: string;
+  provider: string;
+  channelId: string;
+  assignedBy: string | null;
+  assignedAt: string;
+}
+
+export interface GroupAsset {
+  assetId: string;
+  assignedBy: string | null;
+  assignedAt: string;
+}
+
+export interface GroupDetail extends GroupSummary {
+  members: GroupMember[];
+  connections: GroupConnection[];
+  assets: GroupAsset[];
+}
+
+/** Result of a mutation that bumps the authz epoch: the caller's replacement session. */
+export interface GroupMembershipResult {
+  token: string;
+}
+
+export interface VisibleConnections {
+  /** "workspace": Owner/Admin — every connection. "groups": union of the user's groups. */
+  scope: "workspace" | "groups";
+  connectionIds: string[];
+}
+
+interface GroupRow {
+  id: string;
+  name: string;
+  description: string;
+  created_at: Date;
+  member_count: string | number;
+  connection_count: string | number;
+  asset_count: string | number;
+}
+
+const GROUP_SELECT = `SELECT g.id, g.name, g.description, g.created_at,
+    (SELECT count(*) FROM group_members gm WHERE gm.group_id = g.id) AS member_count,
+    (SELECT count(*) FROM group_connections gc WHERE gc.group_id = g.id) AS connection_count,
+    (SELECT count(*) FROM group_assets ga WHERE ga.group_id = g.id) AS asset_count
+  FROM groups g`;
+
+function summaryFromRow(row: GroupRow): GroupSummary {
+  return {
+    id: row.id,
+    name: row.name,
+    description: row.description,
+    memberCount: Number(row.member_count),
+    connectionCount: Number(row.connection_count),
+    assetCount: Number(row.asset_count),
+    createdAt: new Date(row.created_at).toISOString(),
+  };
+}
+
+function iso(value: Date): string {
+  return new Date(value).toISOString();
+}
+
+/** node-postgres surfaces SQLSTATE on `code`. */
+function pgCode(err: unknown): string | undefined {
+  if (typeof err !== "object" || err === null || !("code" in err)) return undefined;
+  const code = (err as { code: unknown }).code;
+  return typeof code === "string" ? code : undefined;
+}
+
+const UNIQUE_VIOLATION = "23505";
+const FK_VIOLATION = "23503";
+
+async function audit(client: PoolClient, workspaceId: string, event: AuditEvent): Promise<void> {
+  await client.query("SELECT audit_append($1, $2, $3, $4, $5, $6, $7)", [
+    workspaceId,
+    event.actorUserId,
+    event.actorRole,
+    event.action,
+    event.targetType,
+    event.targetId,
+    scrub(event.diff ?? null),
+  ]);
+}
+
+@Injectable()
+export class GroupsService {
+  async createGroup(workspaceId: string, name: string, description: string, actor: GroupActor): Promise<GroupSummary> {
+    const cleanName = name.trim();
+    if (cleanName === "") throw new BadRequestException("name must be a non-empty string");
+    return withTenant(workspaceId, async (client) => {
+      let id: string;
+      try {
+        const res = await client.query(
+          "INSERT INTO groups (workspace_id, name, description) VALUES ($1, $2, $3) RETURNING id",
+          [workspaceId, cleanName, description],
+        );
+        id = res.rows[0]?.id as string;
+      } catch (err) {
+        if (pgCode(err) === UNIQUE_VIOLATION) throw new ConflictException(`a group named "${cleanName}" already exists`);
+        throw err;
+      }
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.created",
+        targetType: "group",
+        targetId: id,
+        diff: { name: cleanName, description },
+      });
+      return this.summary(client, id);
+    });
+  }
+
+  async renameGroup(
+    workspaceId: string,
+    groupId: string,
+    changes: { name?: string; description?: string },
+    actor: GroupActor,
+  ): Promise<GroupSummary> {
+    const name = changes.name?.trim();
+    if (name === "") throw new BadRequestException("name must be a non-empty string");
+    if (name === undefined && changes.description === undefined) {
+      throw new BadRequestException("nothing to update: pass name and/or description");
+    }
+    return withTenant(workspaceId, async (client) => {
+      const before = await this.summary(client, groupId, true);
+      try {
+        await client.query(
+          "UPDATE groups SET name = COALESCE($2, name), description = COALESCE($3, description) WHERE id = $1",
+          [groupId, name ?? null, changes.description ?? null],
+        );
+      } catch (err) {
+        if (pgCode(err) === UNIQUE_VIOLATION) throw new ConflictException(`a group named "${name ?? ""}" already exists`);
+        throw err;
+      }
+      const after = await this.summary(client, groupId);
+      const diff: Record<string, unknown> = {};
+      if (after.name !== before.name) diff.name = [before.name, after.name];
+      if (after.description !== before.description) diff.description = [before.description, after.description];
+      if (Object.keys(diff).length > 0) {
+        await audit(client, workspaceId, {
+          actorUserId: actor.userId,
+          actorRole: actor.role,
+          action: "group.renamed",
+          targetType: "group",
+          targetId: groupId,
+          diff,
+        });
+      }
+      return after;
+    });
+  }
+
+  /** Cascades to members/connections/assets; member rows going away bump the epoch. */
+  async deleteGroup(workspaceId: string, groupId: string, actor: GroupActor): Promise<GroupMembershipResult> {
+    return withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const before = await this.summary(client, groupId, true);
+      await client.query("DELETE FROM groups WHERE id = $1", [groupId]);
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.deleted",
+        targetType: "group",
+        targetId: groupId,
+        diff: {
+          name: before.name,
+          memberCount: before.memberCount,
+          connectionCount: before.connectionCount,
+          assetCount: before.assetCount,
+        },
+      });
+      return { token: await issueSessionInTenant(client, workspaceId, actor.userId) };
+    });
+  }
+
+  async addMember(workspaceId: string, groupId: string, userId: string, actor: GroupActor): Promise<GroupMembershipResult> {
+    return withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      await this.summary(client, groupId);
+      let inserted: number;
+      try {
+        const res = await client.query(
+          `INSERT INTO group_members (workspace_id, group_id, user_id, added_by) VALUES ($1, $2, $3, $4)
+           ON CONFLICT (group_id, user_id) DO NOTHING`,
+          [workspaceId, groupId, userId, actor.userId],
+        );
+        inserted = res.rowCount ?? 0;
+      } catch (err) {
+        // Composite FK to memberships: the user is not a member of this workspace.
+        if (pgCode(err) === FK_VIOLATION) throw new BadRequestException("user is not a member of this workspace");
+        throw err;
+      }
+      if (inserted === 0) throw new ConflictException("user is already a member of this group");
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.member_added",
+        targetType: "group",
+        targetId: groupId,
+        diff: { userId },
+      });
+      return { token: await issueSessionInTenant(client, workspaceId, actor.userId) };
+    });
+  }
+
+  async removeMember(workspaceId: string, groupId: string, userId: string, actor: GroupActor): Promise<GroupMembershipResult> {
+    return withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const res = await client.query("DELETE FROM group_members WHERE group_id = $1 AND user_id = $2", [groupId, userId]);
+      if ((res.rowCount ?? 0) === 0) throw new NotFoundException("user is not a member of this group");
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.member_removed",
+        targetType: "group",
+        targetId: groupId,
+        diff: { userId },
+      });
+      return { token: await issueSessionInTenant(client, workspaceId, actor.userId) };
+    });
+  }
+
+  async assignConnection(workspaceId: string, groupId: string, connectionId: string, actor: GroupActor): Promise<GroupSummary & GroupMembershipResult> {
+    return withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      await this.summary(client, groupId);
+      let inserted: number;
+      try {
+        const res = await client.query(
+          `INSERT INTO group_connections (workspace_id, group_id, connection_id, assigned_by) VALUES ($1, $2, $3, $4)
+           ON CONFLICT (group_id, connection_id) DO NOTHING`,
+          [workspaceId, groupId, connectionId, actor.userId],
+        );
+        inserted = res.rowCount ?? 0;
+      } catch (err) {
+        if (pgCode(err) === FK_VIOLATION) throw new NotFoundException(`connection ${connectionId} not found`);
+        throw err;
+      }
+      if (inserted === 0) throw new ConflictException("connection is already assigned to this group");
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.connection_assigned",
+        targetType: "group",
+        targetId: groupId,
+        diff: { connectionId },
+      });
+      return { ...await this.summary(client, groupId), token: await issueSessionInTenant(client, workspaceId, actor.userId) };
+    });
+  }
+
+  async unassignConnection(workspaceId: string, groupId: string, connectionId: string, actor: GroupActor): Promise<GroupSummary & GroupMembershipResult> {
+    return withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const res = await client.query("DELETE FROM group_connections WHERE group_id = $1 AND connection_id = $2", [
+        groupId,
+        connectionId,
+      ]);
+      if ((res.rowCount ?? 0) === 0) throw new NotFoundException("connection is not assigned to this group");
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.connection_unassigned",
+        targetType: "group",
+        targetId: groupId,
+        diff: { connectionId },
+      });
+      return { ...await this.summary(client, groupId), token: await issueSessionInTenant(client, workspaceId, actor.userId) };
+    });
+  }
+
+  async assignAsset(workspaceId: string, groupId: string, assetId: string, actor: GroupActor): Promise<GroupSummary> {
+    const cleanAssetId = assetId.trim();
+    if (cleanAssetId === "") throw new BadRequestException("assetId must be a non-empty string");
+    return withTenant(workspaceId, async (client) => {
+      await this.summary(client, groupId);
+      const res = await client.query(
+        `INSERT INTO group_assets (workspace_id, group_id, asset_id, assigned_by) VALUES ($1, $2, $3, $4)
+         ON CONFLICT (group_id, asset_id) DO NOTHING`,
+        [workspaceId, groupId, cleanAssetId, actor.userId],
+      );
+      if ((res.rowCount ?? 0) === 0) throw new ConflictException("asset is already assigned to this group");
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.asset_assigned",
+        targetType: "group",
+        targetId: groupId,
+        diff: { assetId: cleanAssetId },
+      });
+      return this.summary(client, groupId);
+    });
+  }
+
+  async unassignAsset(workspaceId: string, groupId: string, assetId: string, actor: GroupActor): Promise<GroupSummary> {
+    return withTenant(workspaceId, async (client) => {
+      const res = await client.query("DELETE FROM group_assets WHERE group_id = $1 AND asset_id = $2", [groupId, assetId]);
+      if ((res.rowCount ?? 0) === 0) throw new NotFoundException("asset is not assigned to this group");
+      await audit(client, workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "group.asset_unassigned",
+        targetType: "group",
+        targetId: groupId,
+        diff: { assetId },
+      });
+      return this.summary(client, groupId);
+    });
+  }
+
+  async listGroups(workspaceId: string): Promise<GroupSummary[]> {
+    const res = await withTenant(workspaceId, (client) => client.query(`${GROUP_SELECT} ORDER BY g.name ASC`));
+    return (res.rows as GroupRow[]).map(summaryFromRow);
+  }
+
+  async getGroupDetail(workspaceId: string, groupId: string): Promise<GroupDetail> {
+    return withTenant(workspaceId, async (client) => {
+      const summary = await this.summary(client, groupId);
+      const members = await client.query(
+        `SELECT gm.user_id, u.email, u.display_name, gm.added_by, gm.created_at
+         FROM group_members gm JOIN users u ON u.id = gm.user_id
+         WHERE gm.group_id = $1 ORDER BY gm.created_at ASC`,
+        [groupId],
+      );
+      const connections = await client.query(
+        `SELECT gc.connection_id, c.provider, c.channel_id, gc.assigned_by, gc.created_at
+         FROM group_connections gc JOIN connections c ON c.id = gc.connection_id
+         WHERE gc.group_id = $1 ORDER BY gc.created_at ASC`,
+        [groupId],
+      );
+      const assets = await client.query(
+        "SELECT asset_id, assigned_by, created_at FROM group_assets WHERE group_id = $1 ORDER BY created_at ASC",
+        [groupId],
+      );
+      return {
+        ...summary,
+        members: (
+          members.rows as Array<{ user_id: string; email: string; display_name: string; added_by: string | null; created_at: Date }>
+        ).map((r) => ({ userId: r.user_id, email: r.email, displayName: r.display_name, addedBy: r.added_by, addedAt: iso(r.created_at) })),
+        connections: (
+          connections.rows as Array<{ connection_id: string; provider: string; channel_id: string; assigned_by: string | null; created_at: Date }>
+        ).map((r) => ({
+          connectionId: r.connection_id,
+          provider: r.provider,
+          channelId: r.channel_id,
+          assignedBy: r.assigned_by,
+          assignedAt: iso(r.created_at),
+        })),
+        assets: (assets.rows as Array<{ asset_id: string; assigned_by: string | null; created_at: Date }>).map((r) => ({
+          assetId: r.asset_id,
+          assignedBy: r.assigned_by,
+          assignedAt: iso(r.created_at),
+        })),
+      };
+    });
+  }
+
+  async getUserGroups(workspaceId: string, userId: string): Promise<GroupSummary[]> {
+    const res = await withTenant(workspaceId, (client) =>
+      client.query(
+        `${GROUP_SELECT} WHERE EXISTS (SELECT 1 FROM group_members gm WHERE gm.group_id = g.id AND gm.user_id = $1)
+         ORDER BY g.name ASC`,
+        [userId],
+      ),
+    );
+    return (res.rows as GroupRow[]).map(summaryFromRow);
+  }
+
+  async getVisibleConnections(workspaceId: string, userId: string, isOwnerOrAdmin: boolean): Promise<VisibleConnections> {
+    return withTenant(workspaceId, async (client) => {
+      if (isOwnerOrAdmin) {
+        const res = await client.query("SELECT id FROM connections ORDER BY created_at ASC");
+        return { scope: "workspace", connectionIds: (res.rows as Array<{ id: string }>).map((r) => r.id) };
+      }
+      const res = await client.query(
+        `SELECT c.id FROM connections c
+         WHERE EXISTS (
+           SELECT 1 FROM group_connections gc
+           JOIN group_members gm ON gm.group_id = gc.group_id
+           WHERE gc.connection_id = c.id AND gm.user_id = $1
+         )
+         ORDER BY c.created_at ASC`,
+        [userId],
+      );
+      return { scope: "groups", connectionIds: (res.rows as Array<{ id: string }>).map((r) => r.id) };
+    });
+  }
+
+  private async summary(client: PoolClient, groupId: string, lock = false): Promise<GroupSummary> {
+    const res = await client.query(`${GROUP_SELECT} WHERE g.id = $1${lock ? " FOR UPDATE OF g" : ""}`, [groupId]);
+    const row = res.rows[0] as GroupRow | undefined;
+    if (row === undefined) throw new NotFoundException(`group ${groupId} not found`);
+    return summaryFromRow(row);
+  }
+}
+
+/**
+ * Guard-side check (same tenant client): can this user publish through this
+ * connection? Role is read from the DB, not the token, so it is the live value.
+ */
+export async function userCanUseConnection(
+  client: PoolClient,
+  workspaceId: string,
+  userId: string,
+  connectionId: string,
+): Promise<boolean> {
+  const res = await client.query(
+    `SELECT 1 FROM memberships m
+     WHERE m.workspace_id = $1 AND m.user_id = $2 AND m.status = 'active'
+       AND (
+         m.role = ANY($4::text[])
+         OR EXISTS (
+           SELECT 1 FROM group_connections gc
+           JOIN group_members gm ON gm.group_id = gc.group_id
+           WHERE gc.connection_id = $3 AND gm.user_id = m.user_id
+         )
+       )`,
+    [workspaceId, userId, connectionId, WORKSPACE_WIDE_ROLES],
+  );
+  return (res.rowCount ?? 0) > 0;
+}
diff --git a/apps/api/src/groups/groups.test.ts b/apps/api/src/groups/groups.test.ts
new file mode 100644
index 0000000..a9f95bc
--- /dev/null
+++ b/apps/api/src/groups/groups.test.ts
@@ -0,0 +1,336 @@
+import { BadRequestException, ConflictException, ForbiddenException, NotFoundException, type ExecutionContext } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import type { QueryResult } from "pg";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+// vi.mock calls below are hoisted above these imports.
+import { issueSession } from "../auth/session.js";
+import { GROUP_ACCESS_KEY, PERMISSION_KEY, RbacGuard } from "../rbac/rbac.guard.js";
+import { GroupsService, hasWorkspaceWideAccess } from "./groups.service.js";
+
+/**
+ * Unit tests: the tenant client is faked so we can assert on the exact SQL
+ * parameters and the in-transaction audit_append call. Live-DB behaviour
+ * (RLS, epoch trigger, FK scoping) is in groups.integration.test.ts — that
+ * file cannot share this one because vi.mock is file-wide.
+ */
+
+type Row = Record<string, unknown>;
+interface Call {
+  sql: string;
+  values: readonly unknown[];
+}
+
+const fake = vi.hoisted(() => ({
+  calls: [] as Array<{ sql: string; values: readonly unknown[] }>,
+  responders: [] as Array<(sql: string, values: readonly unknown[]) => Array<Record<string, unknown>> | Error | undefined>,
+  tenants: [] as string[],
+  epoch: 7,
+}));
+
+function result(rows: Row[]): QueryResult<Row> {
+  return { command: "", rowCount: rows.length, oid: 0, fields: [], rows };
+}
+
+const client = {
+  async query(sql: string, values: readonly unknown[] = []): Promise<QueryResult<Row>> {
+    fake.calls.push({ sql, values });
+    for (const respond of fake.responders) {
+      const out = respond(sql, values);
+      if (out instanceof Error) throw out;
+      if (out !== undefined) return result(out);
+    }
+    return result([]);
+  },
+};
+
+vi.mock("../db/client.js", () => ({
+  pool: {
+    query: async (sql: string, values: readonly unknown[] = []) => client.query(sql, values),
+  },
+  withTenant: async <T>(workspaceId: string, fn: (c: typeof client) => Promise<T>): Promise<T> => {
+    fake.tenants.push(workspaceId);
+    return fn(client);
+  },
+  withSystem: async <T>(fn: (c: typeof client) => Promise<T>): Promise<T> => fn(client),
+}));
+
+vi.mock("../auth/auth.service.js", () => ({
+  issueSessionInTenant: async (_c: unknown, workspaceId: string, userId: string) => `token:${workspaceId}:${userId}:${fake.epoch}`,
+}));
+
+
+const ws = "10000000-0000-4000-8000-000000000001";
+const groupId = "20000000-0000-4000-8000-000000000002";
+const userId = "30000000-0000-4000-8000-000000000003";
+const connectionId = "40000000-0000-4000-8000-000000000004";
+const actor = { userId: "50000000-0000-4000-8000-000000000005", role: "Admin" };
+
+const groupRow = (over: Row = {}): Row => ({
+  id: groupId,
+  name: "Newsroom",
+  description: "",
+  created_at: new Date("2026-10-06T10:00:00.000Z"),
+  member_count: "1",
+  connection_count: "2",
+  asset_count: "0",
+  ...over,
+});
+
+function pgError(code: string): Error {
+  return Object.assign(new Error(`pg ${code}`), { code });
+}
+
+function respond(match: RegExp, out: Row[] | Error | ((values: readonly unknown[]) => Row[] | Error)): void {
+  fake.responders.push((sql, values) => (match.test(sql) ? (typeof out === "function" ? out(values) : out) : undefined));
+}
+
+function auditCalls(): Call[] {
+  return fake.calls.filter((c) => c.sql.includes("audit_append"));
+}
+
+function insertCall(table: string): Call {
+  const call = fake.calls.find((c) => c.sql.includes(`INSERT INTO ${table}`));
+  if (call === undefined) throw new Error(`no INSERT INTO ${table}`);
+  return call;
+}
+
+beforeEach(() => {
+  fake.calls.length = 0;
+  fake.responders.length = 0;
+  fake.tenants.length = 0;
+});
+
+describe("GroupsService (unit)", () => {
+  const service = new GroupsService();
+
+  it("createGroup inserts under the tenant, trims the name, audits group.created on the same client", async () => {
+    respond(/INSERT INTO groups/, [{ id: groupId }]);
+    respond(/FROM groups g WHERE g.id/, [groupRow({ member_count: 0, connection_count: 0 })]);
+    const created = await service.createGroup(ws, "  Newsroom ", "desk", actor);
+
+    expect(created).toMatchObject({ id: groupId, name: "Newsroom", memberCount: 0, connectionCount: 0 });
+    expect(fake.tenants).toEqual([ws]);
+    expect(insertCall("groups").values).toEqual([ws, "Newsroom", "desk"]);
+    expect(auditCalls()).toHaveLength(1);
+    expect(auditCalls()[0]?.values).toEqual([ws, actor.userId, "Admin", "group.created", "group", groupId, { name: "Newsroom", description: "desk" }]);
+  });
+
+  it("createGroup maps a duplicate name to 409 and writes no audit", async () => {
+    respond(/INSERT INTO groups/, pgError("23505"));
+    await expect(service.createGroup(ws, "Newsroom", "", actor)).rejects.toBeInstanceOf(ConflictException);
+    expect(auditCalls()).toHaveLength(0);
+  });
+
+  it("createGroup rejects a blank name before touching the DB", async () => {
+    await expect(service.createGroup(ws, "   ", "", actor)).rejects.toBeInstanceOf(BadRequestException);
+    expect(fake.calls).toHaveLength(0);
+  });
+
+  it("renameGroup audits only the fields that changed", async () => {
+    let renamed = false;
+    respond(/UPDATE groups SET/, () => {
+      renamed = true;
+      return [];
+    });
+    respond(/FROM groups g WHERE g.id/, () => [groupRow(renamed ? { name: "Desk" } : {})]);
+    const after = await service.renameGroup(ws, groupId, { name: "Desk" }, actor);
+
+    expect(after.name).toBe("Desk");
+    const update = fake.calls.find((c) => c.sql.includes("UPDATE groups SET"));
+    expect(update?.values).toEqual([groupId, "Desk", null]);
+    expect(auditCalls()[0]?.values.slice(3)).toEqual(["group.renamed", "group", groupId, { name: ["Newsroom", "Desk"] }]);
+  });
+
+  it("renameGroup with nothing to change is a 400", async () => {
+    await expect(service.renameGroup(ws, groupId, {}, actor)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it("deleteGroup audits the cascade counts and returns a replacement token", async () => {
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    const out = await service.deleteGroup(ws, groupId, actor);
+    expect(out.token).toBe(`token:${ws}:${actor.userId}:7`);
+    expect(fake.calls.some((c) => c.sql.includes("FOR UPDATE OF g"))).toBe(true);
+    expect(fake.calls.find((c) => c.sql.startsWith("DELETE FROM groups"))?.values).toEqual([groupId]);
+    expect(auditCalls()[0]?.values.slice(3)).toEqual([
+      "group.deleted",
+      "group",
+      groupId,
+      { name: "Newsroom", memberCount: 1, connectionCount: 2, assetCount: 0 },
+    ]);
+  });
+
+  it("deleteGroup on an unknown/foreign group is a 404 (RLS hides it)", async () => {
+    await expect(service.deleteGroup(ws, groupId, actor)).rejects.toBeInstanceOf(NotFoundException);
+    expect(auditCalls()).toHaveLength(0);
+  });
+
+  it("addMember inserts with workspace + actor, audits group.member_added, returns a fresh token", async () => {
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/INSERT INTO group_members/, [{}]);
+    const out = await service.addMember(ws, groupId, userId, actor);
+
+    expect(insertCall("group_members").values).toEqual([ws, groupId, userId, actor.userId]);
+    expect(auditCalls()[0]?.values).toEqual([ws, actor.userId, "Admin", "group.member_added", "group", groupId, { userId }]);
+    expect(out.token).toContain(actor.userId);
+  });
+
+  it("addMember: non-workspace user (composite FK) is a 400; duplicate is a 409", async () => {
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/INSERT INTO group_members/, pgError("23503"));
+    await expect(service.addMember(ws, groupId, userId, actor)).rejects.toBeInstanceOf(BadRequestException);
+
+    fake.responders.length = 0;
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/INSERT INTO group_members/, []);
+    await expect(service.addMember(ws, groupId, userId, actor)).rejects.toBeInstanceOf(ConflictException);
+    expect(auditCalls()).toHaveLength(0);
+  });
+
+  it("removeMember deletes by (group, user) and audits group.member_removed", async () => {
+    respond(/DELETE FROM group_members/, [{}]);
+    const out = await service.removeMember(ws, groupId, userId, actor);
+    expect(fake.calls.find((c) => c.sql.includes("DELETE FROM group_members"))?.values).toEqual([groupId, userId]);
+    expect(auditCalls()[0]?.values.slice(3)).toEqual(["group.member_removed", "group", groupId, { userId }]);
+    expect(out.token).toBeTruthy();
+  });
+
+  it("removeMember of a non-member is a 404 with no audit", async () => {
+    await expect(service.removeMember(ws, groupId, userId, actor)).rejects.toBeInstanceOf(NotFoundException);
+    expect(auditCalls()).toHaveLength(0);
+  });
+
+  it("assignConnection / unassignConnection pass the right params and audit", async () => {
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/INSERT INTO group_connections/, [{}]);
+    respond(/DELETE FROM group_connections/, [{}]);
+    await service.assignConnection(ws, groupId, connectionId, actor);
+    await service.unassignConnection(ws, groupId, connectionId, actor);
+
+    expect(insertCall("group_connections").values).toEqual([ws, groupId, connectionId, actor.userId]);
+    expect(fake.calls.find((c) => c.sql.includes("DELETE FROM group_connections"))?.values).toEqual([groupId, connectionId]);
+    expect(auditCalls().map((c) => c.values[3])).toEqual(["group.connection_assigned", "group.connection_unassigned"]);
+    expect(auditCalls().map((c) => c.values[6])).toEqual([{ connectionId }, { connectionId }]);
+  });
+
+  it("assignConnection of a connection outside the workspace (composite FK) is a 404", async () => {
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/INSERT INTO group_connections/, pgError("23503"));
+    await expect(service.assignConnection(ws, groupId, connectionId, actor)).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it("assignAsset / unassignAsset audit with the asset id", async () => {
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/INSERT INTO group_assets/, [{}]);
+    respond(/DELETE FROM group_assets/, [{}]);
+    await service.assignAsset(ws, groupId, " media/ab12.png ", actor);
+    await service.unassignAsset(ws, groupId, "media/ab12.png", actor);
+
+    expect(insertCall("group_assets").values).toEqual([ws, groupId, "media/ab12.png", actor.userId]);
+    expect(auditCalls().map((c) => [c.values[3], c.values[6]])).toEqual([
+      ["group.asset_assigned", { assetId: "media/ab12.png" }],
+      ["group.asset_unassigned", { assetId: "media/ab12.png" }],
+    ]);
+  });
+
+  it("listGroups maps counts to numbers", async () => {
+    respond(/FROM groups g ORDER BY/, [groupRow(), groupRow({ id: "x", name: "Ops", member_count: "0" })]);
+    const list = await service.listGroups(ws);
+    expect(list.map((g) => [g.name, g.memberCount, g.connectionCount])).toEqual([
+      ["Newsroom", 1, 2],
+      ["Ops", 0, 2],
+    ]);
+  });
+
+  it("getUserGroups filters by the user's membership", async () => {
+    respond(/FROM groups g WHERE EXISTS/, [groupRow()]);
+    const mine = await service.getUserGroups(ws, userId);
+    expect(mine).toHaveLength(1);
+    expect(fake.calls[0]?.values).toEqual([userId]);
+  });
+
+  it("getGroupDetail returns members, connections and assets", async () => {
+    const at = new Date("2026-10-06T11:00:00.000Z");
+    respond(/FROM groups g WHERE g.id/, [groupRow()]);
+    respond(/FROM group_members gm JOIN users/, [{ user_id: userId, email: "a@x.io", display_name: "A", added_by: actor.userId, created_at: at }]);
+    respond(/FROM group_connections gc JOIN connections/, [
+      { connection_id: connectionId, provider: "mock-social", channel_id: "ch", assigned_by: null, created_at: at },
+    ]);
+    respond(/FROM group_assets/, [{ asset_id: "media/1", assigned_by: null, created_at: at }]);
+    const detail = await service.getGroupDetail(ws, groupId);
+    expect(detail.members).toEqual([{ userId, email: "a@x.io", displayName: "A", addedBy: actor.userId, addedAt: at.toISOString() }]);
+    expect(detail.connections[0]).toMatchObject({ connectionId, provider: "mock-social", channelId: "ch" });
+    expect(detail.assets[0]?.assetId).toBe("media/1");
+  });
+
+  it("getVisibleConnections: Owner/Admin get the whole workspace; others get the group-scoped query", async () => {
+    respond(/SELECT id FROM connections/, [{ id: "c1" }, { id: "c2" }]);
+    respond(/JOIN group_members gm/, [{ id: "c1" }]);
+
+    expect(await service.getVisibleConnections(ws, userId, true)).toEqual({ scope: "workspace", connectionIds: ["c1", "c2"] });
+    expect(await service.getVisibleConnections(ws, userId, false)).toEqual({ scope: "groups", connectionIds: ["c1"] });
+    expect(fake.calls[1]?.values).toEqual([userId]);
+  });
+
+  it("hasWorkspaceWideAccess is Owner/Admin only", () => {
+    expect(["Owner", "Admin", "Publisher", "Editor"].map(hasWorkspaceWideAccess)).toEqual([true, true, false, false]);
+  });
+});
+
+describe("RbacGuard @RequireGroupAccess (unit)", () => {
+  const token = issueSession({ userId, workspaceId: ws, role: "Publisher", authzEpoch: 3 });
+
+  function context(opts: { permission?: string; groupAccess?: boolean; params?: Record<string, string> }): {
+    ctx: ExecutionContext;
+    reflector: Reflector;
+  } {
+    const handler = (): void => undefined;
+    if (opts.permission !== undefined) Reflect.defineMetadata(PERMISSION_KEY, opts.permission, handler);
+    if (opts.groupAccess === true) Reflect.defineMetadata(GROUP_ACCESS_KEY, true, handler);
+    const req = { headers: { authorization: `Bearer ${token}` }, params: opts.params ?? {} };
+    const ctx = { getHandler: () => handler, switchToHttp: () => ({ getRequest: () => req }) } as unknown as ExecutionContext;
+    return { ctx, reflector: new Reflector() };
+  }
+
+  async function run(opts: Parameters<typeof context>[0]): Promise<true | string> {
+    const { ctx, reflector } = context(opts);
+    try {
+      return (await new RbacGuard(reflector).canActivate(ctx)) as true;
+    } catch (err) {
+      return (err as Error).constructor.name;
+    }
+  }
+
+  beforeEach(() => {
+    respond(/SELECT authz_epoch FROM workspaces/, [{ authz_epoch: "3" }]);
+    respond(/FROM role_permissions rp/, [{ "?column?": 1 }]);
+  });
+
+  it("routes without the decorator are unchanged: no group query runs", async () => {
+    expect(await run({ permission: "publication.publish", params: { connectionId } })).toBe(true);
+    expect(fake.calls.some((c) => c.sql.includes("group_connections"))).toBe(false);
+  });
+
+  it("passes when the membership/group query matches, with (workspace, user, connection, roles) params", async () => {
+    respond(/group_connections gc/, [{ "?column?": 1 }]);
+    expect(await run({ permission: "publication.publish", groupAccess: true, params: { connectionId } })).toBe(true);
+    const check = fake.calls.find((c) => c.sql.includes("group_connections gc"));
+    expect(check?.values).toEqual([ws, userId, connectionId, ["Owner", "Admin"]]);
+  });
+
+  it("forbids when the user is neither Owner/Admin nor in a group holding the connection", async () => {
+    expect(await run({ permission: "publication.publish", groupAccess: true, params: { connectionId } })).toBe(ForbiddenException.name);
+  });
+
+  it("fails closed when the route has no :connectionId, and 400s a non-UUID", async () => {
+    expect(await run({ groupAccess: true })).toBe(ForbiddenException.name);
+    expect(await run({ groupAccess: true, params: { connectionId: "nope" } })).toBe(BadRequestException.name);
+  });
+
+  it("still enforces the permission before the group check", async () => {
+    fake.responders.length = 0;
+    respond(/SELECT authz_epoch FROM workspaces/, [{ authz_epoch: "3" }]);
+    respond(/group_connections gc/, [{ "?column?": 1 }]);
+    expect(await run({ permission: "publication.publish", groupAccess: true, params: { connectionId } })).toBe(ForbiddenException.name);
+    expect(fake.calls.some((c) => c.sql.includes("group_connections"))).toBe(false);
+  });
+});
diff --git a/apps/api/src/health/health.controller.ts b/apps/api/src/health/health.controller.ts
new file mode 100644
index 0000000..394e532
--- /dev/null
+++ b/apps/api/src/health/health.controller.ts
@@ -0,0 +1,26 @@
+import { Controller, Get, Res, Inject } from "@nestjs/common";
+import type { Response } from "express";
+import { HealthService, type ComponentHealth } from "./health.service";
+
+interface ReadinessBody {
+  status: "ready" | "degraded";
+  components: Record<string, ComponentHealth>;
+}
+
+@Controller()
+export class HealthController {
+  constructor(@Inject(HealthService) private readonly health: HealthService) {}
+
+  @Get("healthz")
+  liveness(@Res() res: Response): void {
+    res.status(200).json({ status: "alive" });
+  }
+
+  @Get("readyz")
+  async readiness(@Res() res: Response): Promise<void> {
+    const components = await this.health.components();
+    const ready = Object.values(components).every((c) => c.status === "up");
+    const body: ReadinessBody = { status: ready ? "ready" : "degraded", components };
+    res.status(ready ? 200 : 503).json(body);
+  }
+}
diff --git a/apps/api/src/health/health.deps.ts b/apps/api/src/health/health.deps.ts
new file mode 100644
index 0000000..c53924a
--- /dev/null
+++ b/apps/api/src/health/health.deps.ts
@@ -0,0 +1,2 @@
+export { Injectable } from "@nestjs/common";
+export { logger } from "../telemetry/logger";
diff --git a/apps/api/src/health/health.module.ts b/apps/api/src/health/health.module.ts
new file mode 100644
index 0000000..1b5c1fa
--- /dev/null
+++ b/apps/api/src/health/health.module.ts
@@ -0,0 +1,10 @@
+import { Module } from "@nestjs/common";
+import { HealthController } from "./health.controller";
+import { HealthService } from "./health.service";
+
+@Module({
+  providers: [HealthService],
+  controllers: [HealthController],
+  exports: [HealthService],
+})
+export class HealthModule {}
diff --git a/apps/api/src/health/health.service.ts b/apps/api/src/health/health.service.ts
new file mode 100644
index 0000000..91defdb
--- /dev/null
+++ b/apps/api/src/health/health.service.ts
@@ -0,0 +1,50 @@
+import { assertPublishingSchema } from "@tactical-media-broadcast-hub/publishing-execution";
+import { pool } from "../db/client.js";
+import * as net from "net";
+import { Injectable } from "@nestjs/common";
+
+export type ComponentStatus = "up" | "down";
+
+export interface ComponentHealth {
+  status: ComponentStatus;
+}
+
+interface ServiceEndpoint {
+  host: string;
+  port: number;
+}
+
+const serviceEnv: Record<string, ServiceEndpoint> = {
+  postgres: { host: process.env.POSTGRES_HOST ?? "localhost", port: Number(process.env.POSTGRES_PORT ?? 5433) },
+  redis: { host: process.env.REDIS_HOST ?? "localhost", port: Number(process.env.REDIS_PORT ?? 6379) },
+  temporal: { host: process.env.TEMPORAL_HOST ?? "localhost", port: Number(process.env.TEMPORAL_PORT ?? 7233) },
+};
+
+function probeTcp(host: string, port: number, timeoutMs: number): Promise<boolean> {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const done = (ok: boolean): void => {
+      socket.destroy();
+      resolve(ok);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => done(true));
+    socket.once("timeout", () => done(false));
+    socket.once("error", () => done(false));
+    socket.connect(port, host);
+  });
+}
+
+@Injectable()
+export class HealthService {
+  async components(): Promise<Record<string, ComponentHealth>> {
+    const entries = await Promise.all(
+      Object.entries(serviceEnv).map(async ([name, { host, port }]) => {
+        const up = await probeTcp(host, port, 1500);
+        return [name, { status: up ? "up" : "down" } as ComponentHealth] as const;
+      }),
+    );
+    const schema = await assertPublishingSchema(pool).then(() => "up" as const).catch(() => "down" as const);
+    return { ...Object.fromEntries(entries), publishing_schema: { status: schema } };
+  }
+}
diff --git a/apps/api/src/http/validation.ts b/apps/api/src/http/validation.ts
new file mode 100644
index 0000000..89382b4
--- /dev/null
+++ b/apps/api/src/http/validation.ts
@@ -0,0 +1,79 @@
+import { BadRequestException } from "@nestjs/common";
+import type { SessionPayload } from "../auth/session.js";
+import type { AuthenticatedRequest } from "../rbac/rbac.guard.js";
+
+/** Shared request-shape guards for controllers that take `unknown` bodies. */
+
+export function requireSession(request: AuthenticatedRequest): SessionPayload {
+  if (request.session === undefined) throw new Error("unreachable: RBAC guard did not attach a session");
+  return request.session;
+}
+
+export function requireObject(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BadRequestException(`${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+export function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new BadRequestException(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+export function optionalString(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  return requireString(value, field);
+}
+
+const EMAIL = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+
+export function requireEmail(value: unknown, field = "email"): string {
+  const email = requireString(value, field).trim().toLowerCase();
+  if (!EMAIL.test(email) || email.length > 254) throw new BadRequestException(`${field} must be an email address`);
+  return email;
+}
+
+export function optionalEmail(value: unknown, field = "email"): string | undefined {
+  const email = optionalString(value, field);
+  return email === undefined ? undefined : requireEmail(email, field);
+}
+
+export const USERNAME_PATTERN = /^[a-z0-9][a-z0-9_.-]{1,31}$/;
+
+export function requireUsername(value: unknown, field = "username"): string {
+  const username = requireString(value, field).trim().toLowerCase();
+  if (!USERNAME_PATTERN.test(username)) {
+    throw new BadRequestException(`${field} must be 2-32 characters: lowercase letters, digits, dot, underscore or hyphen`);
+  }
+  return username;
+}
+
+/** Positive integer within an inclusive cap (e.g. expiresInHours 1..720, maxUses 1..10000). */
+export function requirePositiveInt(value: unknown, field: string, max: number): number {
+  const n = typeof value === "number" ? value : NaN;
+  if (!Number.isInteger(n) || n < 1 || n > max) {
+    throw new BadRequestException(`${field} must be an integer between 1 and ${max}`);
+  }
+  return n;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function isUuid(value: string): boolean {
+  return UUID.test(value);
+}
+
+export function parseId(value: string, field = "id"): string {
+  if (!isUuid(value)) throw new BadRequestException(`${field} must be a UUID`);
+  return value;
+}
+
+export function parseLimit(value: unknown, fallback: number, max: number): number {
+  if (value === undefined || value === "") return fallback;
+  const n = typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isInteger(n) || n < 1) throw new BadRequestException("limit must be a positive integer");
+  return Math.min(n, max);
+}
diff --git a/apps/api/src/intake/adapters/adapter.ts b/apps/api/src/intake/adapters/adapter.ts
new file mode 100644
index 0000000..e703923
--- /dev/null
+++ b/apps/api/src/intake/adapters/adapter.ts
@@ -0,0 +1,114 @@
+/**
+ * Intake adapter contracts.
+ *
+ * One shape in, one shape out:
+ *
+ *  - `IntakeAdapter` consumes a source row (kind + params + carried adapter
+ *    state) and emits `RawIntakeItem`s — provider-shaped, pre-normalize.
+ *  - `RawIntakeItem` is deliberately the `FeedItem` shape from
+ *    @tactical-media-broadcast-hub/core plus the P0c options, because the task mandate is
+ *    that intake items flow through feeds/feed-normalize.ts unchanged: the
+ *    adapter builds a `ConnectorConnection` stand-in for its (provider, host)
+ *    pair, `normalizeFeedItem` parses the text/html through the safe-content
+ *    allowlist, mints the authorRef and proxied media refs, and the service
+ *    derives `text` (the FTS corpus) from `astToPlainText(content)`.
+ *
+ * Fetch surface: `IntakeFetch` is the injectable egress client seam. Tests
+ * install a fake that records (url, hostClass) draws so budget accounting is
+ * asserted; production binds `intakeEgress()`.
+ */
+import type { ConnectorConnection, FeedItem } from "@tactical-media-broadcast-hub/core";
+import type { NormalizeFeedItemOptions } from "../../feeds/feed-normalize.js";
+import { HOST_CLASS_BY_KIND, PROVIDER_BY_KIND, type IntakeKind } from "../intake-kinds.js";
+import type { IntakeParams } from "../intake-params.js";
+import { IntakeHttpError } from "../intake-egress.js";
+
+/** The egress fetch surface an adapter draws on. */
+export interface IntakeFetch {
+  /**
+   * One budgeted outbound GET. `hostClass` selects the budget row class;
+   * non-2xx resolves to a thrown `IntakeHttpError` carrying status/headers,
+   * except 304 which the caller classifies (free revalidation, not an error
+   * path for the scheduler).
+   */
+  fetch(url: string | URL, options: { headers?: Record<string, string>; hostClass: string }): Promise<Response>;
+}
+
+/** Per-source adapter state carried in intake_sources.state (etag etc.). */
+export type AdapterState = Record<string, unknown>;
+
+/** Provider-shaped item an adapter emits, pre-normalization. */
+export interface RawIntakeItem extends FeedItem {
+  /** P0c options: content kind (html for Mastodon/RSS summaries) + permalink. */
+  normalize: NormalizeFeedItemOptions;
+  /** Platform-native id (guid, status id, yt:video:…, url#hash). Defaults to remoteId. */
+  remoteRef?: string;
+  /** attribution jsonb written to intake_items (author, url, title, extras). */
+  attribution: Record<string, unknown>;
+  /** Harvestable media: direct file URLs, fetched+stored when policy allows. */
+  media?: Array<{ url: string; kind: "image" | "video" }>;
+}
+
+export interface AdapterPollResult {
+  items: RawIntakeItem[];
+  /** Next carried state (etag/lastModified/lastContentHash/lastRemoteRef). */
+  state: AdapterState;
+  /** True when upstream returned 304/unchanged — a clean, cheap poll. */
+  unchanged?: boolean;
+}
+
+export interface AdapterContext {
+  workspaceId: string;
+  sourceId: string;
+  params: IntakeParams["params"];
+  kind: IntakeKind;
+  state: AdapterState;
+  fetch: IntakeFetch;
+}
+
+export interface IntakeAdapter {
+  readonly kind: IntakeKind;
+  poll(context: AdapterContext): Promise<AdapterPollResult>;
+}
+
+/**
+ * The ConnectorConnection stand-in handed to normalizeFeedItem: provider is
+ * the per-kind platform id (so authorRef renders `{provider}:{handle@host}`)
+ * and `fields.instanceUrl` carries the federated instance origin when the
+ * kind has one — exactly the field feed-normalize already reads.
+ */
+export function connectionFor(kind: IntakeKind, params: IntakeParams["params"], connectionId: string, workspaceId: string): ConnectorConnection {
+  const fields: Record<string, string> = {};
+  if ("instance" in params && typeof params.instance === "string") fields.instanceUrl = params.instance;
+  if ("url" in params && typeof params.url === "string") fields.instanceUrl = new URL(params.url).origin;
+  return {
+    id: connectionId,
+    workspaceId,
+    provider: PROVIDER_BY_KIND[kind],
+    channelId: connectionId,
+    credentialId: { kind: "credential-ref", id: connectionId },
+    fields,
+    createdAt: new Date(0),
+  };
+}
+
+/** The host class an adapter's own feed fetch draws on. */
+export function hostClassFor(kind: IntakeKind): string {
+  return HOST_CLASS_BY_KIND[kind];
+}
+
+/** Budgeted GET with JSON parsing; throws IntakeHttpError on bad status. */
+export async function fetchJson<T>(fetcher: IntakeFetch, url: string | URL, hostClass: string, headers?: Record<string, string>): Promise<{ body: T; response: Response }> {
+  const response = await fetcher.fetch(url, { headers: { accept: "application/json", ...headers }, hostClass });
+  if (!response.ok) throw new IntakeHttpError(response.status, response.headers, String(url));
+  const body = JSON.parse(await response.text()) as T;
+  return { body, response };
+}
+
+/** Budgeted GET with text body; 304 resolves as `{ unchanged: true }`. */
+export async function fetchText(fetcher: IntakeFetch, url: string | URL, hostClass: string, headers?: Record<string, string>): Promise<{ text: string; response: Response; unchanged: boolean }> {
+  const response = await fetcher.fetch(url, { headers: { accept: "application/xml, text/xml, text/html;q=0.9, */*;q=0.8", ...headers }, hostClass });
+  if (response.status === 304) return { text: "", response, unchanged: true };
+  if (!response.ok) throw new IntakeHttpError(response.status, response.headers, String(url));
+  return { text: await response.text(), response, unchanged: false };
+}
diff --git a/apps/api/src/intake/adapters/adapters.test.ts b/apps/api/src/intake/adapters/adapters.test.ts
new file mode 100644
index 0000000..403a2d4
--- /dev/null
+++ b/apps/api/src/intake/adapters/adapters.test.ts
@@ -0,0 +1,415 @@
+/**
+ * Intake adapter unit tests — fixtures per source kind (task requirement 7).
+ * No DB, no network: every adapter runs against a recording fake egress
+ * client so per-request budget draws are asserted, and the RSS/Atom/Mastodon
+ * fixtures are the payloads the research appendix verified live.
+ */
+import { describe, expect, it } from "vitest";
+import { createHash } from "node:crypto";
+import { parseFeed } from "./rss-parse.js";
+import { feedToItems, RssAdapter } from "./rss.adapter.js";
+import { MastodonAccountAdapter, MastodonTagAdapter, carryState, freshItems, statusesToItems } from "./mastodon.adapter.js";
+import { PeerTubeChannelAdapter, videosToItems } from "./peertube.adapter.js";
+import { YouTubeChannelAdapter } from "./youtube.adapter.js";
+import { WebWatchAdapter, normalizePageText, pageHash } from "./web-watch.adapter.js";
+import { BlueskyKeywordAdapter, TelegramChannelAdapter, matchesKeywords } from "./push-seams.js";
+import { adapterFor } from "./index.js";
+import type { AdapterContext, IntakeFetch } from "./adapter.js";
+import { itemContentHash, collapseText } from "../intake-ingest.js";
+import { parseIntakeParams, paramsHash, canonicalParams, egressOrigin } from "../intake-params.js";
+import { isIntakeKind, KIND_TELEGRAM_CHANNEL, INTAKE_KINDS } from "../intake-kinds.js";
+import { DEFAULT_POLL_INTERVAL_SEC, HOST_CLASS_BY_KIND, PROVIDER_BY_KIND } from "../intake-kinds.js";
+import { backoffDelayMs, jitteredIntervalMs } from "../intake.service.js";
+import { intakeRetryAfterMs, IntakeHttpError } from "../intake-egress.js";
+
+/** Recording fake: every draw + its host class, fixture-served. */
+class FakeEgress implements IntakeFetch {
+  readonly draws: Array<{ url: string; hostClass: string }> = [];
+  constructor(private readonly routes: Record<string, () => Response | { status: number; headers: Record<string, string>; body?: string }>) {}
+
+  async fetch(url: string | URL, options: { headers?: Record<string, string>; hostClass: string }): Promise<Response> {
+    const key = String(url);
+    this.draws.push({ url: key, hostClass: options.hostClass });
+    const route = Object.entries(this.routes).find(([prefix]) => key.startsWith(prefix));
+    if (route === undefined) return new Response("not found", { status: 404 });
+    const result = route[1]();
+    if (result instanceof Response) return result;
+    if (result.status === 204 || result.status === 304) return new Response(null, { status: 304, headers: result.headers });
+    return new Response(result.body ?? "", { status: result.status, headers: result.headers });
+  }
+}
+
+function context(kind: string, params: Record<string, unknown>, state: Record<string, unknown> = {}, fetcher: IntakeFetch): AdapterContext {
+  return {
+    workspaceId: "ws", sourceId: "src",
+    kind: kind as AdapterContext["kind"],
+    params: params as unknown as AdapterContext["params"],
+    state, fetch: fetcher,
+  };
+}
+
+const RSS_FIXTURE = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:media="http://search.yahoo.com/mrss/">
+  <channel>
+    <title>Water Working Group</title>
+    <link>https://example.org/water</link>
+    <item>
+      <title>Water rights are a community responsibility</title>
+      <link>https://example.org/water/2026-10-09</link>
+      <guid isPermaLink="true">https://example.org/water/2026-10-09</guid>
+      <pubDate>Fri, 09 Oct 2026 12:00:00 GMT</pubDate>
+      <dc:creator xmlns:dc="http://purl.org/dc/elements/1.1/">Water WG</dc:creator>
+      <description><![CDATA[<p>The hearing is postponed to February.</p>]]></description>
+      <media:thumbnail url="https://example.org/water.jpg" />
+    </item>
+    <item>
+      <title>Repair caf&eacute; this Saturday</title>
+      <link>https://example.org/water/repair</link>
+      <guid>repair-2</guid>
+      <pubDate>Thu, 08 Oct 2026 09:00:00 GMT</pubDate>
+      <description>Bring your bikes and sewing machines.</description>
+      <enclosure url="https://example.org/repair.jpg" type="image/jpeg" length="1000" />
+    </item>
+  </channel>
+</rss>`;
+
+const MASTODON_TAG_FIXTURE = JSON.stringify([
+  {
+    id: "110001", uri: "https://social.example/users/alice/statuses/110001", url: "https://social.example/@alice/110001",
+    created_at: "2026-10-09T11:00:00.000Z",
+    content: "<p>Solidarity with the <a href=\"https://social.example/tags/water\" class=\"mention hashtag\" rel=\"tag\">#<span>water</span></a> strikers &amp; their families</p>",
+    account: { id: "1", acct: "alice", display_name: "Alice", username: "alice" },
+    media_attachments: [{ id: "9", url: "https://files.social.example/media/9.png", preview_url: "https://files.social.example/media/9_small.png", type: "image", mime_type: "image/png" }],
+    visibility: "public",
+  },
+  { id: "110002", created_at: "2026-10-09T10:00:00.000Z", content: "<p>unrelated post</p>", account: { acct: "bob@example.social", username: "bob" }, visibility: "public" },
+]);
+
+const PEERTUBE_FIXTURE = JSON.stringify({
+  total: 2,
+  data: [
+    { uuid: "9c1de6de-8df0-4e3a-97a6-7e3a1d6e9a11", name: "General assembly recording", publishedAt: "2026-10-08T18:00:00.000Z", channel: { displayName: "Collective Media", name: "collective" }, thumbnailPath: "/static/thumbnails/a11.jpg", duration: 5400 },
+    { uuid: "0b2ef7ef-9e01-4f4b-88b7-8f4b2e7f9b22", name: "Street medics training", publishedAt: "2026-10-07T18:00:00.000Z", channel: { displayName: "Collective Media" }, isLive: false },
+  ],
+});
+
+const YOUTUBE_FIXTURE = `<?xml version="1.0" encoding="UTF-8"?>
+<feed xmlns:yt="http://www.youtube.com/xml/schemas/2015" xmlns="http://www.w3.org/2005/Atom">
+  <link rel="self" href="https://www.youtube.com/feeds/videos.xml?channel_id=UCtest0000000000000000"/>
+  <title>Collective Channel</title>
+  <entry>
+    <id>yt:video:AAAAAAAAAAA</id>
+    <yt:videoId>AAAAAAAAAAA</yt:videoId>
+    <yt:channelId>UCtest0000000000000000</yt:channelId>
+    <title>Community assembly livestream</title>
+    <link rel="alternate" href="https://www.youtube.com/watch?v=AAAAAAAAAAA"/>
+    <published>2026-10-09T08:00:00.000Z</published>
+    <updated>2026-10-09T08:00:00.000Z</updated>
+    <author><name>Collective Channel</name></author>
+    <media:group xmlns:media="http://search.yahoo.com/mrss/">
+      <media:thumbnail url="https://i.ytimg.com/vi/AAAAAAAAAAA/hqdefault.jpg"/>
+    </media:group>
+  </entry>
+</feed>`;
+
+const WEB_PAGE_A = `<!doctype html><html><head><style>.x{color:red}</style></head>
+<body><div id="main"><p>Next hearing scheduled for March 2027 at the courthouse.</p>
+<span data-token="9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c"></span></div></body></html>`;
+const WEB_PAGE_B = `<!doctype html><html><body><div id="main"><p>Next hearing scheduled for April 2027 at the courthouse.</p>
+<span data-token="1a2b3c4d5e6f708192a3b4c5d6e7f809"></span></div></body></html>`;
+
+describe("intake params validation + canonicalization", () => {
+  it("validates and canonicalizes per kind", () => {
+    const a = parseIntakeParams("rss", { url: "https://example.org/feed.xml" });
+    const b = parseIntakeParams("rss", { url: "https://example.org/feed.xml#" });
+    expect(paramsHash(a)).toBe(paramsHash(b)); // hash-stripped
+    const c = parseIntakeParams("mastodon_tag", { instance: "Mastodon.Social", tag: "Water" });
+    expect(c.params).toEqual({ instance: "https://mastodon.social", tag: "water" });
+    const d = parseIntakeParams("mastodon_account", { instance: "https://mastodon.social", accountId: "000123", handle: "@Alice@mastodon.social" });
+    expect(d.params).toEqual({ instance: "https://mastodon.social", accountId: "000123", handle: "alice@mastodon.social" });
+    expect(() => parseIntakeParams("mastodon_account", { instance: "https://mastodon.social", accountId: "abc" })).toThrow();
+    expect(() => parseIntakeParams("rss", { url: "file:///etc/passwd" })).toThrow();
+    expect(() => parseIntakeParams("rss", { url: "https://user:pass@example.org/f" })).toThrow();
+    expect(() => parseIntakeParams("youtube_channel", { channelId: "not-a-channel" })).toThrow();
+    expect(() => parseIntakeParams("nope", {})).toThrow();
+    expect(() => parseIntakeParams("telegram_channel", { channelId: "@durov" })).toThrow();
+    const e = parseIntakeParams("peertube_channel", { instance: "https://video.example", handle: "@collective@video.example" });
+    expect(e.params).toEqual({ instance: "https://video.example", handle: "collective@video.example" });
+    const w = parseIntakeParams("web_watch", { url: "https://example.org/page", selector: "#main" });
+    expect(w.params).toEqual({ url: "https://example.org/page", selector: "#main" });
+  });
+
+  it("canonical form is key-order independent", () => {
+    const left = parseIntakeParams("mastodon_tag", { tag: "water", instance: "https://mastodon.social" });
+    const right = parseIntakeParams("mastodon_tag", { instance: "https://mastodon.social", tag: "water" });
+    expect(canonicalParams(left)).toBe(canonicalParams(right));
+  });
+
+  it("maps kinds to poll defaults, host classes, and providers", () => {
+    expect(DEFAULT_POLL_INTERVAL_SEC.telegram_channel).toBe(0);
+    expect(DEFAULT_POLL_INTERVAL_SEC.bluesky_keyword).toBe(0);
+    expect(DEFAULT_POLL_INTERVAL_SEC.rss).toBeGreaterThan(0);
+    expect(HOST_CLASS_BY_KIND.mastodon_tag).toBe("intake-social");
+    expect(PROVIDER_BY_KIND.mastodon_tag).toBe("mastodon");
+    expect(PROVIDER_BY_KIND.web_watch).toBe("web");
+    for (const kind of INTAKE_KINDS) expect(isIntakeKind(kind)).toBe(true);
+    expect(egressOrigin(parseIntakeParams("youtube_channel", { channelId: "UCtest0000000000000000" })))
+      .toBe("https://www.youtube.com");
+    expect(egressOrigin(parseIntakeParams("rss", { url: "https://example.org/f.xml" }))).toBe("https://example.org");
+  });
+});
+
+describe("rss parse + adapter", () => {
+  it("parses RSS 2.0 with CDATA, entities, dc:creator, media:thumbnail", () => {
+    const feed = parseFeed(RSS_FIXTURE);
+    expect(feed.type).toBe("rss");
+    expect(feed.channelTitle).toBe("Water Working Group");
+    expect(feed.entries).toHaveLength(2);
+    const first = feed.entries[0]!;
+    expect(first.title).toBe("Water rights are a community responsibility");
+    expect(first.link).toBe("https://example.org/water/2026-10-09");
+    expect(first.publishedAt?.toISOString()).toBe("2026-10-09T12:00:00.000Z");
+    expect(first.author).toBe("Water WG");
+    expect(first.contentHtml).toContain("postponed to February");
+    expect(first.mediaThumbnails).toEqual(["https://example.org/water.jpg"]);
+    expect(feed.entries[1]!.title).toBe("Repair café this Saturday");
+    expect(feed.entries[1]!.enclosures[0]?.type).toBe("image/jpeg");
+  });
+
+  it("parses Atom (YouTube shape) with yt:videoId", () => {
+    const feed = parseFeed(YOUTUBE_FIXTURE);
+    expect(feed.type).toBe("atom");
+    expect(feed.channelTitle).toBe("Collective Channel");
+    expect(feed.entries[0]!.videoId).toBe("AAAAAAAAAAA");
+    expect(feed.entries[0]!.link).toBe("https://www.youtube.com/watch?v=AAAAAAAAAAA");
+  });
+
+  it("classifies enclosure + thumbnail media kinds", () => {
+    const items = feedToItems(parseFeed(RSS_FIXTURE), new Date("2026-10-09T12:00:00Z"));
+    expect(items[0]?.media).toEqual([{ url: "https://example.org/water.jpg", kind: "image" }]);
+    expect(items[1]?.media?.some((entry) => entry.url === "https://example.org/repair.jpg")).toBe(true);
+    expect(items[0]?.remoteId).toBe("https://example.org/water/2026-10-09");
+    expect(items).toHaveLength(2);
+  });
+
+  it("conditional GET: 304 is free and emits nothing; etag carries", async () => {
+    let etag = "\"v1\"";
+    const egress = new FakeEgress({
+      "https://example.org/feed.xml": () => ({ status: 200, headers: { etag, "content-type": "application/xml" }, body: RSS_FIXTURE }),
+    });
+    const adapter = new RssAdapter();
+    const first = await adapter.poll(context("rss", { url: "https://example.org/feed.xml" }, {}, egress));
+    expect(first.items).toHaveLength(2);
+    expect(first.state.etag).toBe(etag);
+    expect(egress.draws[0]!.hostClass).toBe("intake-rss");
+
+    etag = "\"v2\"";
+    const second = await adapter.poll(context("rss", { url: "https://example.org/feed.xml" }, { etag: "\"v1\"" },
+      new FakeEgress({ "https://example.org/feed.xml": () => ({ status: 304, headers: {} }) })));
+    expect(second.unchanged).toBe(true);
+    expect(second.items).toHaveLength(0);
+  });
+
+  it("is total over malformed XML", () => {
+    const feed = parseFeed("<rss><channel><item><title>only");
+    expect(feed.entries).toHaveLength(1);
+    expect(parseFeed("").entries).toHaveLength(0);
+    expect(parseFeed("not xml at all").entries).toHaveLength(0);
+  });
+});
+
+describe("mastodon adapters", () => {
+  it("tag timeline: html status → items with attachments, budget class intake-social", async () => {
+    const egress = new FakeEgress({
+      "https://mastodon.social/api/v1/timelines/tag/water": () => new Response(MASTODON_TAG_FIXTURE, { headers: { "content-type": "application/json", "x-ratelimit-limit": "300" } }),
+    });
+    const adapter = new MastodonTagAdapter();
+    const result = await adapter.poll(context("mastodon_tag", { instance: "https://mastodon.social", tag: "water" }, {}, egress));
+    expect(result.items).toHaveLength(2);
+    expect(egress.draws[0]!.hostClass).toBe("intake-social");
+    expect(egress.draws[0]!.url).toContain("/api/v1/timelines/tag/water?limit=40");
+    const first = result.items[0]!;
+    expect(first.remoteId).toBe("110001");
+    expect(first.media![0]).toEqual({ url: "https://files.social.example/media/9.png", kind: "image" });
+    expect(first.attribution.authorHandle).toBe("alice");
+    // remote federation: acct carries @host
+    expect(result.items[1]!.attribution.authorHandle).toBe("bob@example.social");
+    const state = carryState(result.items, {});
+    expect(state.lastRemoteRef).toBe("110001");
+  });
+
+  it("account timeline: exclude_replies + freshness window from carried state", async () => {
+    const egress = new FakeEgress({
+      "https://mastodon.social/api/v1/accounts/000123/statuses": () => new Response(MASTODON_TAG_FIXTURE, { headers: { "content-type": "application/json" } }),
+    });
+    const adapter = new MastodonAccountAdapter();
+    const first = await adapter.poll(context("mastodon_account", { instance: "https://mastodon.social", accountId: "000123" }, {}, egress));
+    expect(first.items).toHaveLength(2);
+    expect(egress.draws[0]!.url).toContain("exclude_replies=true");
+    // Second delivery of the same window: the high-water mark (110001, the
+    // newest) is present, so nothing newer exists and 110002 was already
+    // delivered in the first poll — zero new items.
+    const second = await adapter.poll(context("mastodon_account", { instance: "https://mastodon.social", accountId: "000123" },
+      { lastRemoteRef: "110001", lastSeenIds: ["110001", "110002"] }, egress));
+    expect(second.items).toHaveLength(0);
+  });
+
+  it("freshItems cuts at the high-water mark and dedups seen ids", () => {
+    const items = statusesToItems([
+      { id: "3", created_at: "2026-10-09T11:00:00Z", content: "c" },
+      { id: "2", created_at: "2026-10-09T10:00:00Z", content: "b" },
+      { id: "1", created_at: "2026-10-09T09:00:00Z", content: "a" },
+    ], new Date());
+    expect(freshItems(items, "2", ["1"]).map((i) => i.remoteId)).toEqual(["3"]);
+    expect(freshItems(items, undefined, ["1", "2"]).map((i) => i.remoteId)).toEqual(["3"]);
+  });
+
+  it("drops private/direct statuses", () => {
+    const items = statusesToItems([
+      { id: "1", visibility: "private", content: "x" },
+      { id: "2", visibility: "direct", content: "x" },
+      { id: "3", visibility: "public", content: "x" },
+    ], new Date());
+    expect(items).toHaveLength(1);
+  });
+});
+
+describe("peertube adapter", () => {
+  it("channel videos via public REST, thumbnail media, duration metric", async () => {
+    const egress = new FakeEgress({
+      "https://video.example/api/v1/video-channels/collective%40video.example/videos": () => new Response(PEERTUBE_FIXTURE, { headers: { "content-type": "application/json" } }),
+    });
+    const adapter = new PeerTubeChannelAdapter();
+    const result = await adapter.poll(context("peertube_channel", { instance: "https://video.example", handle: "collective@video.example" }, {}, egress));
+    expect(result.items).toHaveLength(2);
+    expect(egress.draws[0]!.hostClass).toBe("intake-peertube");
+    expect(result.items[0]!.remoteId).toBe("9c1de6de-8df0-4e3a-97a6-7e3a1d6e9a11");
+    expect(result.items[0]!.media![0]!.url).toBe("https://video.example/static/thumbnails/a11.jpg");
+    expect(result.items[0]!.metrics.durationSec).toBe(5400);
+    const second = await adapter.poll(context("peertube_channel", { instance: "https://video.example", handle: "collective@video.example" }, result.state, egress));
+    expect(second.items).toHaveLength(0); // seen-set window
+  });
+
+  it("videosToItems tolerates missing uuid/dates", () => {
+    expect(videosToItems([{ name: "no id" }], "https://video.example", new Date())).toHaveLength(0);
+    const one = videosToItems([{ uuid: "x", name: "n" }], "https://video.example", new Date("2026-10-09T00:00:00Z"));
+    expect(one[0]!.createdAt).toEqual(new Date("2026-10-09T00:00:00Z"));
+  });
+});
+
+describe("youtube adapter", () => {
+  it("channel Atom: videoId remote ref, watch URL, thumbnail; seen window suppresses re-emission", async () => {
+    const egress = new FakeEgress({
+      "https://www.youtube.com/feeds/videos.xml": () => new Response(YOUTUBE_FIXTURE, { headers: { "content-type": "application/atom+xml", etag: "\"yt1\"" } }),
+    });
+    const adapter = new YouTubeChannelAdapter();
+    const result = await adapter.poll(context("youtube_channel", { channelId: "UCtest0000000000000000" }, {}, egress));
+    expect(result.items).toHaveLength(1);
+    const item = result.items[0]!;
+    expect(item.remoteRef).toBe("yt:video:AAAAAAAAAAA");
+    expect(item.attribution.url).toBe("https://www.youtube.com/watch?v=AAAAAAAAAAA");
+    expect(item.media![0]!.kind).toBe("image");
+    expect(result.state.etag).toBe("\"yt1\"");
+    const second = await adapter.poll(context("youtube_channel", { channelId: "UCtest0000000000000000" }, result.state, egress));
+    expect(second.items).toHaveLength(0);
+  });
+});
+
+describe("web watch adapter", () => {
+  it("diff normalization strips churn and hash only moves on real change", () => {
+    const a = normalizePageText(WEB_PAGE_A);
+    const b = normalizePageText(WEB_PAGE_B);
+    const churn = normalizePageText(WEB_PAGE_A.replace("9f8e7d6c5b4a3f2e1d0c9b8a7f6e5d4c", "ffffffffffffffffffffffffffffffff").replace("March", "March"));
+    expect(pageHash(a)).toBe(pageHash(churn)); // token + identical text → same hash
+    expect(pageHash(a)).not.toBe(pageHash(b)); // March → April
+    expect(a).toContain("courthouse");
+    expect(a).not.toContain("csrf");
+    expect(a).not.toContain("color:red");
+  });
+
+  it("first fetch seeds the baseline without emitting; change emits one item", async () => {
+    let body = WEB_PAGE_A;
+    const egress = new FakeEgress({ "https://example.org/hearing": () => new Response(body, { headers: { "content-type": "text/html" } }) });
+    const adapter = new WebWatchAdapter();
+    const params = { url: "https://example.org/hearing", selector: "#main" };
+    const seed = await adapter.poll(context("web_watch", params, {}, egress));
+    expect(seed.items).toHaveLength(0);
+    expect(typeof seed.state.contentHash).toBe("string");
+    body = WEB_PAGE_B;
+    const changed = await adapter.poll(context("web_watch", params, seed.state, egress));
+    expect(changed.items).toHaveLength(1);
+    expect(changed.items[0]!.attribution.diffHash).toBe(changed.state.contentHash);
+    const stable = await adapter.poll(context("web_watch", params, changed.state, egress));
+    expect(stable.unchanged).toBe(true);
+  });
+});
+
+describe("push-only seams", () => {
+  it("bluesky keyword gate is exact-substring, multi-term AND", () => {
+    expect(matchesKeywords("Water rights now", "water rights")).toBe(true);
+    expect(matchesKeywords("Water rights now", "water luxury")).toBe(false);
+    expect(matchesKeywords("WATER RIGHTS", "water")).toBe(true);
+    expect(matchesKeywords("anything", "")).toBe(false);
+    const adapter = new BlueskyKeywordAdapter();
+    expect(adapter.gate("solidarity with water strikers", { keywords: ["water strikers"] })).toBe(true);
+    expect(adapter.gate("unrelated", { keywords: ["water strikers"] })).toBe(false);
+  });
+
+  it("telegram + bluesky poll() are clean no-ops", async () => {
+    for (const Adapter of [TelegramChannelAdapter, BlueskyKeywordAdapter]) {
+      const egress = new FakeEgress({});
+      const result = await new Adapter().poll(context("telegram_channel", { channelId: "-100123" }, {}, egress));
+      expect(result.items).toHaveLength(0);
+      expect(result.unchanged).toBe(true);
+      expect(egress.draws).toHaveLength(0); // never fetches
+    }
+  });
+});
+
+describe("adapter registry", () => {
+  it("is total over kinds", () => {
+    for (const kind of INTAKE_KINDS) {
+      const adapter = adapterFor(kind);
+      expect(adapter.kind).toBe(kind);
+    }
+  });
+});
+
+describe("content hash + text collapse", () => {
+  it("collapses whitespace and NFKC before hashing; media identity is sorted+unique", () => {
+    expect(collapseText("  a\u00a0 b  ")).toBe("a b");
+    const h1 = itemContentHash("same text", ["https://b.example/x", "https://a.example/y"]);
+    const h2 = itemContentHash("same  text", ["https://a.example/y", "https://b.example/x", "https://a.example/y"]);
+    expect(h1).toBe(h2); // whitespace + order + duplicates do not matter
+    expect(h1).not.toBe(itemContentHash("same text", []));
+    expect(h1).toMatch(/^[0-9a-f]{64}$/);
+  });
+});
+
+describe("scheduler math + error classification helpers", () => {
+  it("backoff curve: 2^n capped at 15 min", () => {
+    expect(backoffDelayMs(1, 60_000)).toBe(60_000);
+    expect(backoffDelayMs(2, 60_000)).toBe(120_000);
+    expect(backoffDelayMs(7, 60_000)).toBe(900_000); // 60s·2^6 = 64 min → capped at 15 min
+    expect(backoffDelayMs(1, 60_000)).toBeLessThanOrEqual(15 * 60_000);
+  });
+
+  it("jitter stays within ±20 % and validates inputs", () => {
+    expect(jitteredIntervalMs(100, 0)).toBe(80);
+    expect(jitteredIntervalMs(100, 1)).toBe(120);
+    expect(jitteredIntervalMs(100, 0.5)).toBe(100);
+    expect(() => jitteredIntervalMs(0, 0.5)).toThrow();
+    expect(() => jitteredIntervalMs(100, 1.5)).toThrow();
+  });
+
+  it("retry-after parses seconds and HTTP-date", () => {
+    const seconds = new Headers({ "retry-after": "30" });
+    expect(intakeRetryAfterMs(seconds, 0)).toBe(30_000);
+    const past = new Headers({ "retry-after": new Date(0).toUTCString() });
+    expect(intakeRetryAfterMs(past, 10_000)).toBe(0);
+    expect(intakeRetryAfterMs(new Headers(), 0)).toBe(0);
+    const err = new IntakeHttpError(429, new Headers({ "retry-after": "5" }), "https://x");
+    expect(err.rateLimited && err.transient).toBe(true);
+    expect(new IntakeHttpError(410, new Headers(), "https://x").gone).toBe(true);
+  });
+});
diff --git a/apps/api/src/intake/adapters/index.ts b/apps/api/src/intake/adapters/index.ts
new file mode 100644
index 0000000..7c1615c
--- /dev/null
+++ b/apps/api/src/intake/adapters/index.ts
@@ -0,0 +1,29 @@
+/**
+ * The per-kind adapter registry — one entry per intake kind, mirroring the
+ * feed-registry composition boundary. Adding a source kind = one adapter +
+ * one registry line; the scheduler and service never branch on kind.
+ */
+import type { IntakeAdapter } from "./adapter.js";
+import { RssAdapter } from "./rss.adapter.js";
+import { MastodonAccountAdapter, MastodonTagAdapter } from "./mastodon.adapter.js";
+import { PeerTubeChannelAdapter } from "./peertube.adapter.js";
+import { YouTubeChannelAdapter } from "./youtube.adapter.js";
+import { WebWatchAdapter } from "./web-watch.adapter.js";
+import { BlueskyKeywordAdapter, TelegramChannelAdapter } from "./push-seams.js";
+import type { IntakeKind } from "../intake-kinds.js";
+
+export const INTAKE_ADAPTERS: Readonly<Record<IntakeKind, () => IntakeAdapter>> = {
+  rss: () => new RssAdapter(),
+  mastodon_tag: () => new MastodonTagAdapter(),
+  mastodon_account: () => new MastodonAccountAdapter(),
+  bluesky_keyword: () => new BlueskyKeywordAdapter(),
+  telegram_channel: () => new TelegramChannelAdapter(),
+  peertube_channel: () => new PeerTubeChannelAdapter(),
+  youtube_channel: () => new YouTubeChannelAdapter(),
+  web_watch: () => new WebWatchAdapter(),
+};
+
+/** A fresh adapter per source poll (adapters are stateless; context carries state). */
+export function adapterFor(kind: IntakeKind): IntakeAdapter {
+  return INTAKE_ADAPTERS[kind]();
+}
diff --git a/apps/api/src/intake/adapters/mastodon.adapter.ts b/apps/api/src/intake/adapters/mastodon.adapter.ts
new file mode 100644
index 0000000..48f8c90
--- /dev/null
+++ b/apps/api/src/intake/adapters/mastodon.adapter.ts
@@ -0,0 +1,141 @@
+/**
+ * Mastodon adapters — public anon tag + account timelines.
+ *
+ * Verified facts (research §1.3, 2026-10-09): `/api/v1/timelines/tag/{tag}`
+ * and `/api/v1/accounts/{id}/statuses` answer 200 anonymously; the federated
+ * public/local timelines are 422 for anon users, so this adapter never builds
+ * on those. Budget: `x-ratelimit-limit: 300` per 5 min per IP — modeled by the
+ * intake-social host class (1 req/s ceiling), and `X-RateLimit-Remaining` /
+ * `Retry-After` headers are already honored by the shared egress bucket's
+ * observe() path, which parks the host on 429/0-remaining.
+ *
+ * Status HTML runs through the P0c allowlist parser (`contentKind: "html"`);
+ * `media_attachments[].url` (directly fetchable, no auth) become harvest
+ * candidates alongside the proxied preview refs.
+ */
+import { createHash } from "node:crypto";
+import { fetchJson, hostClassFor, type AdapterContext, type AdapterPollResult, type IntakeAdapter, type RawIntakeItem } from "./adapter.js";
+import { KIND_MASTODON_ACCOUNT, KIND_MASTODON_TAG } from "../intake-kinds.js";
+import type { MastodonAccountParams, MastodonTagParams } from "../intake-params.js";
+
+export const MASTODON_PAGE_LIMIT = 40;
+
+interface MastodonStatus {
+  id: string;
+  uri?: string;
+  url?: string | null;
+  created_at?: string;
+  content?: string;
+  account?: { id?: string; acct?: string; display_name?: string; url?: string; username?: string };
+  media_attachments?: Array<{ id?: string; url?: string | null; preview_url?: string | null; type?: string; mime_type?: string }>;
+  reblog?: MastodonStatus | null;
+  visibility?: string;
+}
+
+const isStatus = (value: unknown): value is MastodonStatus =>
+  typeof value === "object" && value !== null && typeof (value as MastodonStatus).id === "string";
+
+const MEDIA_KIND: Record<string, "image" | "video"> = { image: "image", gifv: "image", video: "video", audio: "video" };
+
+export function statusesToItems(statuses: MastodonStatus[], now: Date): RawIntakeItem[] {
+  const out: RawIntakeItem[] = [];
+  for (const status of statuses) {
+    if (!isStatus(status) || status.visibility === "private" || status.visibility === "direct") continue;
+    const author = status.account?.acct ?? status.account?.username ?? "unknown";
+    const host = author.includes("@") ? author.split("@").at(-1) : null;
+    const media: Array<{ url: string; kind: "image" | "video" }> = [];
+    for (const attachment of status.media_attachments ?? []) {
+      const url = typeof attachment.url === "string" ? attachment.url : attachment.preview_url;
+      if (typeof url === "string" && url !== "") {
+        media.push({ url, kind: MEDIA_KIND[attachment.type ?? ""] ?? (/^video\//i.test(attachment.mime_type ?? "") ? "video" : "image") });
+      }
+    }
+    const url = status.url ?? status.uri ?? null;
+    out.push({
+      id: status.id,
+      remoteId: status.id,
+      remoteRef: status.id,
+      provider: "mastodon",
+      authorHandle: author,
+      text: status.content ?? "",
+      mediaUrls: media.map((entry) => entry.url),
+      createdAt: parseDate(status.created_at) ?? now,
+      metrics: {},
+      normalize: { contentKind: "html", url: url ?? undefined },
+      attribution: {
+        authorHandle: author,
+        authorRef: host ? `mastodon:${author}` : `mastodon:${author}`,
+        url,
+        provider: "mastodon",
+        statusId: status.id,
+      },
+      media,
+    });
+  }
+  return out;
+}
+
+function parseDate(raw: string | undefined): Date | null {
+  if (typeof raw !== "string") return null;
+  const date = new Date(raw);
+  return Number.isFinite(date.getTime()) ? date : null;
+}
+
+/** Only statuses newer than the carried high-water mark are emitted. */
+export function freshItems(items: RawIntakeItem[], lastRemoteRef: string | undefined, lastSeenIds: string[] | undefined): RawIntakeItem[] {
+  const seen = new Set(lastSeenIds ?? []);
+  const refOf = (item: RawIntakeItem): string => item.remoteRef ?? item.remoteId;
+  if (lastRemoteRef !== undefined && lastRemoteRef !== "") {
+    const cut = items.findIndex((item) => refOf(item) === lastRemoteRef);
+    if (cut >= 0) return items.slice(0, cut).filter((item) => !seen.has(refOf(item)));
+  }
+  return items.filter((item) => !seen.has(refOf(item)));
+}
+
+export function carryState(items: RawIntakeItem[], previous: Record<string, unknown>): Record<string, unknown> {
+  const priorIds = Array.isArray(previous.lastSeenIds) ? previous.lastSeenIds.filter((id): id is string => typeof id === "string") : [];
+  const priorRef = typeof previous.lastRemoteRef === "string" ? previous.lastRemoteRef : undefined;
+  const ids = [...priorIds, ...items.map((item) => item.remoteRef ?? item.remoteId)].slice(-80);
+  return { lastRemoteRef: items[0] !== undefined ? (items[0].remoteRef ?? items[0].remoteId) : priorRef, lastSeenIds: ids };
+}
+
+export class MastodonTagAdapter implements IntakeAdapter {
+  readonly kind = KIND_MASTODON_TAG;
+
+  async poll(context: AdapterContext): Promise<AdapterPollResult> {
+    const params = context.params as MastodonTagParams;
+    const { body } = await fetchJson<unknown>(
+      context.fetch,
+      `${params.instance}/api/v1/timelines/tag/${encodeURIComponent(params.tag)}?limit=${MASTODON_PAGE_LIMIT}&local=false`,
+      hostClassFor(KIND_MASTODON_TAG),
+    );
+    const statuses = Array.isArray(body) ? body.filter(isStatus) : [];
+    const items = freshItems(statusesToItems(statuses, new Date()),
+      typeof context.state.lastRemoteRef === "string" ? context.state.lastRemoteRef : undefined,
+      Array.isArray(context.state.lastSeenIds) ? context.state.lastSeenIds.filter((id): id is string => typeof id === "string") : undefined);
+    return { items, state: carryState(items, context.state) };
+  }
+}
+
+export class MastodonAccountAdapter implements IntakeAdapter {
+  readonly kind = KIND_MASTODON_ACCOUNT;
+
+  async poll(context: AdapterContext): Promise<AdapterPollResult> {
+    const params = context.params as MastodonAccountParams;
+    const { body } = await fetchJson<unknown>(
+      context.fetch,
+      `${params.instance}/api/v1/accounts/${encodeURIComponent(params.accountId)}/statuses?limit=${MASTODON_PAGE_LIMIT}&exclude_replies=true`,
+      hostClassFor(KIND_MASTODON_ACCOUNT),
+    );
+    const statuses = Array.isArray(body) ? body.filter(isStatus) : [];
+    const items = freshItems(statusesToItems(statuses, new Date()),
+      typeof context.state.lastRemoteRef === "string" ? context.state.lastRemoteRef : undefined,
+      Array.isArray(context.state.lastSeenIds) ? context.state.lastSeenIds.filter((id): id is string => typeof id === "string") : undefined);
+    return { items, state: carryState(items, context.state) };
+  }
+}
+
+/** Deterministic per-status scratch id (tests + dedup helpers). */
+export function statusScratchId(status: MastodonStatus): string {
+  return createHash("sha256").update(status.id).digest("hex").slice(0, 16);
+}
diff --git a/apps/api/src/intake/adapters/peertube.adapter.ts b/apps/api/src/intake/adapters/peertube.adapter.ts
new file mode 100644
index 0000000..6d4ee34
--- /dev/null
+++ b/apps/api/src/intake/adapters/peertube.adapter.ts
@@ -0,0 +1,96 @@
+/**
+ * PeerTube channel adapter — public channel videos over the same REST the
+ * connector and the live-monitor use: `GET /api/v1/video-channels/{handle}/videos`
+ * (anonymous, per research §1.5; instance default 50 req/10 s per IP, our
+ * intake-peertube host class runs stricter at 5/10 s). No webhooks exist
+ * upstream (verified), so polling is the only path.
+ *
+ * Media policy is thumbnail-first (research §2.5): the thumbnail is a harvest
+ * candidate; the full webseed file is only a candidate when the source opted
+ * into full-harvest, which the media policy gate in the service enforces.
+ */
+import { fetchJson, hostClassFor, type AdapterContext, type AdapterPollResult, type IntakeAdapter, type RawIntakeItem } from "./adapter.js";
+import { KIND_PEERTUBE_CHANNEL } from "../intake-kinds.js";
+import type { PeerTubeChannelParams } from "../intake-params.js";
+
+interface PtVideo {
+  uuid?: string;
+  shortUUID?: string;
+  name?: string;
+  createdAt?: string;
+  publishedAt?: string;
+  account?: { name?: string; displayName?: string };
+  channel?: { displayName?: string; name?: string };
+  thumbnailPath?: string;
+  previewPath?: string;
+  isLive?: boolean;
+  duration?: number;
+}
+
+interface PtList { total?: number; data?: PtVideo[] }
+
+function dateOf(...values: Array<string | undefined>): Date | null {
+  for (const value of values) {
+    if (typeof value !== "string") continue;
+    const date = new Date(value);
+    if (Number.isFinite(date.getTime())) return date;
+  }
+  return null;
+}
+
+export function videosToItems(videos: PtVideo[], instance: string, now: Date): RawIntakeItem[] {
+  const out: RawIntakeItem[] = [];
+  for (const video of videos) {
+    const uuid = video.uuid ?? video.shortUUID;
+    if (typeof uuid !== "string" || uuid === "") continue;
+    const url = `${instance}/videos/watch/${uuid}`;
+    const thumb = typeof video.thumbnailPath === "string" && video.thumbnailPath !== ""
+      ? `${instance}${video.thumbnailPath}` : typeof video.previewPath === "string" && video.previewPath !== ""
+        ? `${instance}${video.previewPath}` : null;
+    const handle = video.channel?.displayName ?? video.channel?.name ?? video.account?.name ?? "channel";
+    out.push({
+      id: uuid,
+      remoteId: uuid,
+      remoteRef: uuid,
+      provider: "peertube",
+      authorHandle: handle,
+      text: video.name ?? "",
+      mediaUrls: thumb ? [thumb] : [],
+      createdAt: dateOf(video.publishedAt, video.createdAt) ?? now,
+      metrics: typeof video.duration === "number" ? { durationSec: video.duration } : {},
+      normalize: { contentKind: "text", url },
+      attribution: {
+        title: video.name ?? null,
+        url,
+        channelTitle: video.channel?.displayName ?? null,
+        videoId: uuid,
+        provider: "peertube",
+        ...(video.isLive === true ? { live: true } : {}),
+      },
+      media: thumb ? [{ url: thumb, kind: "image" }] : [],
+    });
+  }
+  return out;
+}
+
+export class PeerTubeChannelAdapter implements IntakeAdapter {
+  readonly kind = KIND_PEERTUBE_CHANNEL;
+
+  async poll(context: AdapterContext): Promise<AdapterPollResult> {
+    const params = context.params as PeerTubeChannelParams;
+    const { body } = await fetchJson<PtList>(
+      context.fetch,
+      `${params.instance}/api/v1/video-channels/${encodeURIComponent(params.handle)}/videos?count=25&sort=-publishedAt`,
+      hostClassFor(KIND_PEERTUBE_CHANNEL),
+    );
+    const videos = Array.isArray(body.data) ? body.data : [];
+    const seen = new Set(Array.isArray(context.state.seenVideoIds)
+      ? context.state.seenVideoIds.filter((id): id is string => typeof id === "string") : []);
+    const items = videosToItems(videos, params.instance, new Date()).filter((item) => !seen.has(item.remoteRef ?? item.remoteId));
+    for (const item of items) seen.add(item.remoteRef ?? item.remoteId);
+    return {
+      items,
+      state: { ...context.state, seenVideoIds: [...seen].slice(-50) },
+    };
+  }
+}
diff --git a/apps/api/src/intake/adapters/push-seams.ts b/apps/api/src/intake/adapters/push-seams.ts
new file mode 100644
index 0000000..67dc429
--- /dev/null
+++ b/apps/api/src/intake/adapters/push-seams.ts
@@ -0,0 +1,69 @@
+/**
+ * Push-only seams (research §1.2/§1.4): these kinds are never poll-due
+ * (DEFAULT_POLL_INTERVAL_SEC = 0). The adapters exist so the scheduler has a
+ * complete registry and so the ingest halves are testable now:
+ *
+ *  - bluesky_keyword: the keyword gate consumed by the Jetstream WS worker.
+ *    `matchesKeywords(text, keywords)` is the exact predicate the future
+ *    consumer applies to every firehose event (~52 posts/s measured); it is
+ *    exported and unit-tested so the seam is honest, not a stub that always
+ *    returns true.
+ *
+ *  - telegram_channel: intake rows for the EXISTING archive webhook path.
+ *    The webhook already normalizes posts, harvests media and upserts into
+ *    archived_feed_items (apps/api/src/archive/normalizer.ts + service);
+ *    this adapter's poll() is unreachable by design, and the service's
+ *    ingest path bridges archive items into intake rows (see
+ *    IntakeService.ingestArchiveItem).
+ */
+import type { AdapterContext, AdapterPollResult, IntakeAdapter } from "./adapter.js";
+import { KIND_BLUESKY_KEYWORD, KIND_TELEGRAM_CHANNEL } from "../intake-kinds.js";
+import type { BlueskyKeywordParams } from "../intake-params.js";
+
+/**
+ * Case/diacritic-folded substring gate. Multi-term keywords require BOTH
+ * terms (AND) — the research noise mitigation: one common word alone must
+ * not pull a trending meme into intake.
+ */
+export function matchesKeywords(text: string, keyword: string): boolean {
+  const needle = keyword.trim().toLowerCase();
+  if (needle === "") return false;
+  const terms = needle.split(/\s+/).filter((term) => term !== "");
+  if (terms.length === 0) return false;
+  const haystack = text.toLowerCase();
+  return terms.every((term) => haystack.includes(term));
+}
+
+export function filterByKeywords<T>(items: T[], textOf: (item: T) => string, keywords: readonly string[]): T[] {
+  return items.filter((item) => {
+    const text = textOf(item);
+    return keywords.some((keyword) => matchesKeywords(text, keyword));
+  });
+}
+
+export class BlueskyKeywordAdapter implements IntakeAdapter {
+  readonly kind = KIND_BLUESKY_KEYWORD;
+
+  async poll(_context: AdapterContext): Promise<AdapterPollResult> {
+    // Push-only: the Jetstream WS consumer owns this kind's write path; poll()
+    // exists so the registry is total over kinds and always answers a
+    // misconfigured cadence with a clean no-op instead of a fetch.
+    return { items: [], state: _context.state, unchanged: true };
+  }
+
+  /** The gate the WS worker applies per firehose event. */
+  gate(text: string, params: BlueskyKeywordParams): boolean {
+    return params.keywords.some((keyword) => matchesKeywords(text, keyword));
+  }
+}
+
+export class TelegramChannelAdapter implements IntakeAdapter {
+  readonly kind = KIND_TELEGRAM_CHANNEL;
+
+  async poll(_context: AdapterContext): Promise<AdapterPollResult> {
+    // Push-only: telegram rows arrive through the existing archive webhook
+    // (bot-admin channels) and the future MTProto sidecar; see the service's
+    // ingestArchiveItem bridge.
+    return { items: [], state: _context.state, unchanged: true };
+  }
+}
diff --git a/apps/api/src/intake/adapters/rss-parse.ts b/apps/api/src/intake/adapters/rss-parse.ts
new file mode 100644
index 0000000..b152439
--- /dev/null
+++ b/apps/api/src/intake/adapters/rss-parse.ts
@@ -0,0 +1,276 @@
+/**
+ * Minimal RSS 2.0 / Atom / RSS-in-HTML-entity parser for the intake adapters.
+ *
+ * In-process by the research verdict ("rss-parser in-process is ~100 lines;
+ * Miniflux only if feed edge-cases bite"). No external dependency: feeds are
+ * a closed, well-known XML subset, and the extractor below is total over
+ * arbitrary input — unknown elements are ignored, missing dates fall back to
+ * fetch time, and the caller (feed-normalize) owns all safety-critical
+ * parsing of text/URLs.
+ *
+ * XML entity decoding covers the five predefined entities plus numeric
+ * references; unknown entities pass through verbatim (a literal "&foo;" in a
+ * title is not a decoding failure).
+ */
+const ENTITY: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'",
+  nbsp: "\u00a0", eacute: "é", egrave: "è", agrave: "à", ccedil: "ç", auml: "ä", ouml: "ö", uuml: "ü",
+  laquo: "«", raquo: "»", ldquo: "\u201c", rdquo: "\u201d", lsquo: "\u2018", rsquo: "\u2019",
+  ndash: "–", mdash: "—", hellip: "…", rsquo2: "’" };
+
+export function decodeEntities(text: string): string {
+  return text.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (whole, entity: string) => {
+    if (entity.startsWith("#x") || entity.startsWith("#X")) {
+      const code = Number.parseInt(entity.slice(2), 16);
+      return Number.isInteger(code) && code > 0 && code <= 0x10ffff ? safeCodePoint(code) : whole;
+    }
+    if (entity.startsWith("#")) {
+      const code = Number.parseInt(entity.slice(1), 10);
+      return Number.isInteger(code) && code > 0 && code <= 0x10ffff ? safeCodePoint(code) : whole;
+    }
+    return ENTITY[entity] ?? whole;
+  });
+}
+
+function safeCodePoint(code: number): string {
+  try { return String.fromCodePoint(code); } catch { return "\uFFFD"; }
+}
+
+interface XmlNode {
+  tag: string;
+  attrs: Record<string, string>;
+  children: XmlNode[];
+  text: string;
+}
+
+const TAG_TOKEN = /<!--[\s\S]*?-->|<!\[CDATA\[([\s\S]*?)\]\]>|<\/( [a-zA-Z][a-zA-Z0-9:_-]* )\s*>|<([a-zA-Z][a-zA-Z0-9:_-]*)((?:\s+[^<>]*?)?)(\/?)>/g;
+const NAME_RE = /^([a-zA-Z][a-zA-Z0-9:_-]*)\s*$/;
+
+/** Strip any namespace prefix: "dc:creator" -> "creator". */
+function localName(tag: string): string {
+  const at = tag.indexOf(":");
+  return at > 0 ? tag.slice(at + 1) : tag;
+}
+
+function parseAttrs(raw: string | undefined): Record<string, string> {
+  const attrs: Record<string, string> = {};
+  if (!raw) return attrs;
+  for (const match of raw.matchAll(/([a-zA-Z_:][a-zA-Z0-9_:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g)) {
+    attrs[match[1]!.toLowerCase()] = decodeEntities(match[2] ?? match[3] ?? "");
+  }
+  return attrs;
+}
+
+/**
+ * Tolerant single-pass scan into a flat tree: one regex walks every tag token
+ * in document order, a stack tracks open elements, text between tags
+ * accumulates on the current node. Malformed markup (unterminated tags,
+ * mismatched closes) degrades to whatever structure is recoverable — never
+ * an exception, because feeds in the wild are routinely broken.
+ */
+export function parseXml(input: string): XmlNode {
+  const root: XmlNode = { tag: "#root", attrs: {}, children: [], text: "" };
+  const stack: XmlNode[] = [root];
+  let cursor = 0;
+  let textChunk = "";
+  const flush = (): void => {
+    if (textChunk !== "") {
+      stack[stack.length - 1]!.text += decodeEntities(textChunk);
+      textChunk = "";
+    }
+  };
+  const token = /<!--[\s\S]*?-->|<!\[CDATA\[([\s\S]*?)\]\]>|<\/([a-zA-Z][a-zA-Z0-9:_-]*)\s*>|<([a-zA-Z][a-zA-Z0-9:_-]*)((?:\s+[^<>]*?)?)(\/?)>/g;
+  for (const match of input.matchAll(token)) {
+    textChunk += input.slice(cursor, match.index);
+    cursor = match.index! + match[0].length;
+    if (match[1] !== undefined) { textChunk += match[1]; continue; } // CDATA: raw text
+    if (match[0].startsWith("<!")) continue;                         // comment / doctype
+    if (match[2] !== undefined) {                                    // closing tag
+      flush();
+      const close = localName(match[2].toLowerCase());
+      const at = stack.map((node) => node.tag).lastIndexOf(close);
+      if (at > 0) stack.length = at;                                 // pop to the matching open; stray closes are ignored
+      continue;
+    }
+    // Local-name only (dc:creator -> creator, yt:videoId -> videoid,
+    // media:thumbnail -> thumbnail): feed namespaces are decorative for the
+    // fields this extractor reads, and matching on the local name keeps every
+    // lookup below prefix-agnostic.
+    const tag = localName(match[3]!.toLowerCase());
+    flush();
+    const node: XmlNode = { tag, attrs: parseAttrs(match[4]), children: [], text: "" };
+    stack[stack.length - 1]!.children.push(node);
+    if (match[5] !== "/") stack.push(node);                          // not self-closing: descend
+  }
+  textChunk += input.slice(cursor);
+  flush();
+  return root;
+}
+
+function findFirst(node: XmlNode, tag: string): XmlNode | undefined {
+  for (const child of node.children) {
+    if (child.tag === tag) return child;
+    const nested = findFirst(child, tag);
+    if (nested) return nested;
+  }
+  return undefined;
+}
+
+function findAll(node: XmlNode, tag: string): XmlNode[] {
+  const out: XmlNode[] = [];
+  const walk = (current: XmlNode): void => {
+    for (const child of current.children) {
+      if (child.tag === tag) out.push(child);
+      walk(child);
+    }
+  };
+  walk(node);
+  return out;
+}
+
+/** text of a child tag by name, "" when absent — keeps author lookups flat. */
+function childText(node: XmlNode, tag: string): string {
+  return textOf(childTag(node, tag));
+}
+
+/** Raw inner text (entities decoded, whitespace preserved) — CDATA HTML. */
+function rawText(node: XmlNode): string {
+  return decodeEntities(node.text);
+}
+
+/** Inner text of a node across nested markup, whitespace-collapsed. */
+function textOf(node: XmlNode | undefined): string {
+  if (!node) return "";
+  let out = node.text;
+  for (const child of node.children) out += " " + textOf(child);
+  return out.replace(/\s+/g, " ").trim();
+}
+
+export interface FeedEntry {
+  id: string;
+  title: string;
+  link: string | null;
+  contentHtml: string | null;
+  contentText: string | null;
+  publishedAt: Date | null;
+  updatedAt: Date | null;
+  author: string | null;
+  enclosures: Array<{ url: string; type: string }>;
+  mediaThumbnails: string[];
+  /** youtube atom: yt:videoId */
+  videoId: string | null;
+}
+
+export interface ParsedFeed {
+  type: "rss" | "atom";
+  channelTitle: string | null;
+  channelLink: string | null;
+  entries: FeedEntry[];
+}
+
+function childTag(node: XmlNode, tag: string): XmlNode | undefined {
+  return node.children.find((child) => child.tag === tag);
+}
+
+/** RSS <author><name>…</name></author> / Atom author/name text. */
+function authorNameOf(node: XmlNode): string {
+  const author = childTag(node, "author");
+  return author === undefined ? "" : textOf(childTag(author, "name") ?? author);
+}
+
+function linkOf(item: XmlNode, channelLink: string | null): string | null {
+  // Atom: <link rel="alternate" href="…"/> wins; rel absent is alternate too.
+  // Self/service links (rel="self") are skipped. RSS: <link>text</link>.
+  const links = item.children.filter((child) => child.tag === "link");
+  for (const link of links) {
+    const rel = link.attrs.rel;
+    const href = link.attrs.href;
+    if (href !== undefined && (rel === undefined || rel === "alternate")) return href;
+  }
+  const plain = links.map((link) => textOf(link)).find((text) => text !== "");
+  if (plain) return plain;
+  const guid = childTag(item, "guid");
+  if (guid && /^https?:\/\//i.test(guid.text.trim())) return guid.text.trim();
+  return channelLink;
+}
+
+function dateOf(...candidates: Array<XmlNode | undefined>): Date | null {
+  for (const node of candidates) {
+    const raw = textOf(node);
+    if (raw === "") continue;
+    const parsed = new Date(raw);
+    if (Number.isFinite(parsed.getTime())) return parsed;
+    // RFC822 without timezone ("Thu, 09 Oct 2026 12:00:00") is common in the wild
+    const zoned = new Date(`${raw} GMT`);
+    if (Number.isFinite(zoned.getTime())) return zoned;
+  }
+  return null;
+}
+
+export function parseFeed(xml: string): ParsedFeed {
+  const root = parseXml(xml);
+  const rssChannel = findFirst(root, "channel");
+  const atomFeed = root.children.find((child) => child.tag === "feed");
+  if (rssChannel) {
+    const channelTitle = textOf(childTag(rssChannel, "title")) || null;
+    const channelLink = textOf(childTag(rssChannel, "link")) || null;
+    const entries = findAll(rssChannel, "item").map((item): FeedEntry => {
+      const encoded = childTag(item, "encoded"); // content:encoded (local name)
+      const description = childTag(item, "description");
+      // A description carrying markup IS provider HTML (CDATA-wrapped in
+      // practice); plain descriptions stay text so P0c parses them as text.
+      const descriptionHtml = encoded !== undefined ? textOf(encoded)
+        : description !== undefined && /<\s*[a-zA-Z]/.test(rawText(description)) ? rawText(description) : null;
+      const enclosures = item.children.filter((child) => child.tag === "enclosure")
+        .map((enclosure) => ({ url: enclosure.attrs.url ?? "", type: enclosure.attrs.type ?? "" }))
+        .filter((entry) => entry.url !== "");
+      const group = findFirst(item, "group"); // media:group
+      const thumbnails = [...findAll(item, "thumbnail"), ...(group ? findAll(group, "thumbnail") : [])]
+        .map((thumb) => thumb.attrs.url ?? "").filter((url) => url !== "");
+      return {
+        id: textOf(childTag(item, "guid")) || textOf(childTag(item, "link")) || "",
+        title: textOf(childTag(item, "title")),
+        link: linkOf(item, channelLink),
+        contentHtml: descriptionHtml,
+        contentText: descriptionHtml === null && description !== undefined ? textOf(description) : null,
+        publishedAt: dateOf(childTag(item, "pubdate"), childTag(item, "date"), childTag(item, "published")),
+        updatedAt: dateOf(childTag(item, "updated")),
+        author: textOf(childTag(item, "creator")) || childText(item, "author") || authorNameOf(item) || null,
+        enclosures,
+        mediaThumbnails: thumbnails,
+        videoId: null,
+      };
+    });
+    return { type: "rss", channelTitle, channelLink, entries };
+  }
+  if (atomFeed) {
+    const channelTitle = textOf(childTag(atomFeed, "title")) || null;
+    const channelLink = linkOf(atomFeed, null);
+    const entries = findAll(atomFeed, "entry").map((entry): FeedEntry => {
+      const contentHtml = textOf(childTag(entry, "content"));
+      const summary = textOf(childTag(entry, "summary"));
+      const enclosures = entry.children.filter((child) => child.tag === "link" && child.attrs.rel === "enclosure")
+        .map((link) => ({ url: link.attrs.href ?? "", type: link.attrs.type ?? "" }))
+        .filter((item) => item.url !== "");
+      const videoIdNode = entry.children.find((child) => child.tag === "videoid");
+      // yt:videoId is a leaf: raw text only (no nested aggregation).
+      const group = findFirst(entry, "group");
+      const thumbnails = [...findAll(entry, "thumbnail"), ...(group ? findAll(group, "thumbnail") : [])]
+        .map((thumb) => thumb.attrs.url ?? "").filter((url) => url !== "");
+      return {
+        id: textOf(childTag(entry, "id")) || "",
+        title: textOf(childTag(entry, "title")),
+        link: linkOf(entry, channelLink),
+        contentHtml: contentHtml !== "" ? contentHtml : null,
+        contentText: contentHtml === "" && summary !== "" ? summary : null,
+        publishedAt: dateOf(childTag(entry, "published"), childTag(entry, "updated")),
+        updatedAt: dateOf(childTag(entry, "updated")),
+        author: authorNameOf(entry) || childText(entry, "name") || null,
+        enclosures,
+        mediaThumbnails: thumbnails,
+        videoId: videoIdNode ? videoIdNode.text.trim() || null : null,
+      };
+    });
+    return { type: "atom", channelTitle, channelLink, entries };
+  }
+  return { type: "rss", channelTitle: null, channelLink: null, entries: [] };
+}
diff --git a/apps/api/src/intake/adapters/rss.adapter.ts b/apps/api/src/intake/adapters/rss.adapter.ts
new file mode 100644
index 0000000..8b4c2cc
--- /dev/null
+++ b/apps/api/src/intake/adapters/rss.adapter.ts
@@ -0,0 +1,78 @@
+/**
+ * RSS/Atom adapter — conditional GET via ETag / Last-Modified.
+ *
+ * The feed is fetched once per poll through the egress client (one budget
+ * draw); when upstream answers 304 the poll is free and emits nothing, and
+ * the carried ETag/Last-Modified state rides in intake_sources.state. Text
+ * lands as sanitized HTML through the P0c allowlist parser (feed summaries
+ * are HTML in practice), enclosures/thumbnails become harvest candidates.
+ */
+import { createHash } from "node:crypto";
+import { fetchText, type AdapterContext, type AdapterPollResult, type IntakeAdapter, type RawIntakeItem } from "./adapter.js";
+import { parseFeed, type ParsedFeed } from "./rss-parse.js";
+import { hostClassFor } from "./adapter.js";
+import { KIND_RSS } from "../intake-kinds.js";
+import type { RssParams } from "../intake-params.js";
+
+export const MAX_FEED_ITEMS = 100;
+
+function stateHeaders(state: Record<string, unknown>): Record<string, string> {
+  const headers: Record<string, string> = {};
+  if (typeof state.etag === "string" && state.etag !== "") headers["if-none-match"] = state.etag;
+  if (typeof state.lastModified === "string" && state.lastModified !== "") headers["if-modified-since"] = state.lastModified;
+  return headers;
+}
+
+export function feedToItems(feed: ParsedFeed, publishedFallback: Date): RawIntakeItem[] {
+  return feed.entries.slice(0, MAX_FEED_ITEMS).map((entry) => {
+    const media: Array<{ url: string; kind: "image" | "video" }> = [];
+    for (const enclosure of entry.enclosures) {
+      if (/^video\//i.test(enclosure.type)) media.push({ url: enclosure.url, kind: "video" });
+      else if (/^image\//i.test(enclosure.type) || /\.(?:png|jpe?g|webp|gif)(?:[?#]|$)/i.test(enclosure.url)) media.push({ url: enclosure.url, kind: "image" });
+      else if (/^audio\//i.test(enclosure.type)) media.push({ url: enclosure.url, kind: "video" });
+    }
+    for (const thumb of entry.mediaThumbnails.slice(0, 4)) media.push({ url: thumb, kind: "image" });
+    const text = entry.contentHtml ?? entry.contentText ?? entry.title;
+    const scratch = createHash("sha256").update(text).digest("hex").slice(0, 32);
+    const ref = entry.id || entry.link || `sha256:${scratch}`;
+    return {
+      id: entry.id || entry.link || scratch,
+      remoteId: ref,
+      remoteRef: ref,
+      provider: "rss",
+      authorHandle: entry.author ?? feed.channelTitle ?? "feed",
+      text,
+      mediaUrls: media.map((entry_media) => entry_media.url),
+      createdAt: entry.publishedAt ?? entry.updatedAt ?? publishedFallback,
+      metrics: {},
+      normalize: { contentKind: entry.contentHtml !== null ? "html" : "text", url: entry.link ?? undefined },
+      attribution: {
+        title: entry.title || null,
+        url: entry.link ?? null,
+        author: entry.author ?? null,
+        channelTitle: feed.channelTitle,
+        provider: "rss",
+        ...(entry.publishedAt ? { publishedAt: entry.publishedAt.toISOString() } : {}),
+      },
+      media,
+    };
+  });
+}
+
+export class RssAdapter implements IntakeAdapter {
+  readonly kind = KIND_RSS;
+
+  async poll(context: AdapterContext): Promise<AdapterPollResult> {
+    const params = context.params as RssParams;
+    const hostClass = hostClassFor(KIND_RSS);
+    const { text, response, unchanged } = await fetchText(context.fetch, params.url, hostClass, stateHeaders(context.state));
+    const state: Record<string, unknown> = { ...context.state };
+    const etag = response.headers.get("etag");
+    const lastModified = response.headers.get("last-modified");
+    if (etag !== null) state.etag = etag;
+    if (lastModified !== null) state.lastModified = lastModified;
+    if (unchanged) return { items: [], state, unchanged: true };
+    const feed = parseFeed(text);
+    return { items: feedToItems(feed, new Date()), state };
+  }
+}
diff --git a/apps/api/src/intake/adapters/web-watch.adapter.ts b/apps/api/src/intake/adapters/web-watch.adapter.ts
new file mode 100644
index 0000000..96881bb
--- /dev/null
+++ b/apps/api/src/intake/adapters/web-watch.adapter.ts
@@ -0,0 +1,100 @@
+/**
+ * Page-watch adapter — the changedetection.io pattern in ~100 lines
+ * (research §1.8): fetch the page through the egress budget, normalize the
+ * text (strip scripts/styles, collapse whitespace, strip rotating
+ * timestamps/CSRF nonces), hash, and emit an item only when the hash moves.
+ *
+ * Plain fetch only — no headless browser (per the task's "no headless"
+ * bound); a page that needs JS renders as its static DOM, which is the right
+ * default for press pages and gazettes.
+ */
+import { createHash } from "node:crypto";
+import { fetchText, hostClassFor, type AdapterContext, type AdapterPollResult, type IntakeAdapter, type RawIntakeItem } from "./adapter.js";
+import { KIND_WEB_WATCH } from "../intake-kinds.js";
+import type { WebWatchParams } from "../intake-params.js";
+
+/**
+ * Diff normalization: what changes on a page without changing its content —
+ * numbers (counts, timestamps), long hex/base64 tokens (CSRF, cache busters).
+ * Hashing the normalized text is what keeps phantom diffs out of the archive.
+ */
+export function normalizePageText(html: string, selector?: string): string {
+  let work = html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<noscript[\s\S]*?<\/noscript>/gi, " ")
+    .replace(/<!--[\s\S]*?-->/g, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/&nbsp;/gi, " ")
+    .replace(/&amp;/gi, "&")
+    .replace(/&lt;/gi, "<")
+    .replace(/&gt;/gi, ">")
+    .replace(/&quot;/gi, '"')
+    .replace(/&#0?39;/g, "'");
+  if (selector !== undefined && selector.trim() !== "") {
+    // Cheap id/class containment: keep only lines containing the selector's
+    // leaf token when the selector looks like #id or .class (a full CSS
+    // engine is out of scope for phase 1; a wrong selector degrades to the
+    // whole page's diff, which is still correct — just noisier).
+    const leaf = selector.trim().split(/[ >]+/).at(-1) ?? "";
+    const match = /^([#.])([\w-]+)$/.exec(leaf);
+    if (match) {
+      // Extract the region around the marker token from the raw HTML instead.
+      const marker = match[1] === "#" ? `id="${match[2]}"` : `class="${match[2]}"`;
+      const at = html.toLowerCase().indexOf(marker.toLowerCase());
+      if (at >= 0) {
+        const from = html.lastIndexOf("<", at);
+        const to = html.indexOf("</body>", at);
+        work = normalizePageText(html.slice(from > 0 ? from : 0, to > 0 ? to : undefined));
+      }
+    }
+  }
+  return work
+    .replace(/\b[0-9]{2,}\b/g, " ")          // counts, epochs, timestamps
+    .replace(/\b[0-9a-f]{16,}\b/gi, " ")     // CSRF tokens, digests
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+export function pageHash(normalized: string): string {
+  return createHash("sha256").update(normalized).digest("hex");
+}
+
+export class WebWatchAdapter implements IntakeAdapter {
+  readonly kind = KIND_WEB_WATCH;
+
+  async poll(context: AdapterContext): Promise<AdapterPollResult> {
+    const params = context.params as WebWatchParams;
+    const { text, unchanged } = await fetchText(context.fetch, params.url, hostClassFor(KIND_WEB_WATCH), {
+      "cache-control": "no-cache",
+    });
+    if (unchanged) return { items: [], state: context.state, unchanged: true };
+    const normalized = normalizePageText(text, params.selector);
+    const hash = pageHash(normalized);
+    if (typeof context.state.contentHash === "string" && context.state.contentHash === hash) {
+      return { items: [], state: context.state, unchanged: true };
+    }
+    const now = new Date();
+    const items: RawIntakeItem[] = [];
+    if (typeof context.state.contentHash === "string") {
+      // First fetch seeds the baseline; only a CHANGED page (second fetch
+      // onward) emits — a new subscription never manufactures an item for a
+      // page that was already in that state.
+      items.push({
+        id: hash.slice(0, 24),
+        remoteId: hash.slice(0, 24),
+        remoteRef: `${params.url}#${hash.slice(0, 16)}`,
+        provider: "web",
+        authorHandle: new URL(params.url).hostname,
+        text: normalized.slice(0, 8_000),
+        mediaUrls: [],
+        createdAt: now,
+        metrics: {},
+        normalize: { contentKind: "text", url: params.url },
+        attribution: { url: params.url, provider: "web", changedAt: now.toISOString(), diffHash: hash },
+        media: [],
+      });
+    }
+    return { items, state: { ...context.state, contentHash: hash, lastChangedAt: now.toISOString() } };
+  }
+}
diff --git a/apps/api/src/intake/adapters/youtube.adapter.ts b/apps/api/src/intake/adapters/youtube.adapter.ts
new file mode 100644
index 0000000..625a917
--- /dev/null
+++ b/apps/api/src/intake/adapters/youtube.adapter.ts
@@ -0,0 +1,59 @@
+/**
+ * YouTube channel adapter — the channel Atom feed, no key, no quota
+ * (verified live, research §1.1/§1.6: `feeds/videos.xml?channel_id=…`
+ * returns Atom with yt:videoId, media thumbnails; 15-entry window, ~15 min
+ * freshness → poll ≤ every 10 min). The Data API is deliberately NOT used
+ * here: search.list costs 100 units against a 10k/day project budget while
+ * the feed is free.
+ */
+import { fetchText, hostClassFor, type AdapterContext, type AdapterPollResult, type IntakeAdapter, type RawIntakeItem } from "./adapter.js";
+import { parseFeed } from "./rss-parse.js";
+import { KIND_YOUTUBE_CHANNEL, YOUTUBE_FEED_URL } from "../intake-kinds.js";
+import type { YouTubeChannelParams } from "../intake-params.js";
+
+export class YouTubeChannelAdapter implements IntakeAdapter {
+  readonly kind = KIND_YOUTUBE_CHANNEL;
+
+  async poll(context: AdapterContext): Promise<AdapterPollResult> {
+    const params = context.params as YouTubeChannelParams;
+    const { text, response, unchanged } = await fetchText(context.fetch, YOUTUBE_FEED_URL(params.channelId), hostClassFor(KIND_YOUTUBE_CHANNEL));
+    const state: Record<string, unknown> = { ...context.state };
+    const etag = response.headers.get("etag");
+    if (etag !== null) state.etag = etag;
+    if (unchanged) return { items: [], state, unchanged: true };
+    const feed = parseFeed(text);
+    const seen = new Set(Array.isArray(state.seenVideoIds)
+      ? state.seenVideoIds.filter((id): id is string => typeof id === "string") : []);
+    const items: RawIntakeItem[] = [];
+    for (const entry of feed.entries) {
+      const videoId = entry.videoId ?? (entry.id.startsWith("yt:video:") ? entry.id.slice("yt:video:".length) : null);
+      if (videoId === null || seen.has(videoId)) continue;
+      const watchUrl = `https://www.youtube.com/watch?v=${videoId}`;
+      items.push({
+        id: videoId,
+        remoteId: `yt:video:${videoId}`,
+        remoteRef: `yt:video:${videoId}`,
+        provider: "youtube",
+        authorHandle: entry.author ?? feed.channelTitle ?? params.channelId,
+        text: entry.title,
+        mediaUrls: entry.mediaThumbnails.slice(0, 1),
+        createdAt: entry.publishedAt ?? entry.updatedAt ?? new Date(),
+        metrics: {},
+        normalize: { contentKind: "text", url: watchUrl },
+        attribution: {
+          title: entry.title || null,
+          url: watchUrl,
+          channelTitle: feed.channelTitle,
+          channelId: params.channelId,
+          videoId,
+          provider: "youtube",
+        },
+        // metadata-only default: the thumbnail is harvested, never the video.
+        media: entry.mediaThumbnails.slice(0, 1).map((url) => ({ url, kind: "image" as const })),
+      });
+      seen.add(videoId);
+    }
+    state.seenVideoIds = [...seen].slice(-30);
+    return { items, state };
+  }
+}
diff --git a/apps/api/src/intake/intake-egress.ts b/apps/api/src/intake/intake-egress.ts
new file mode 100644
index 0000000..1bfbb51
--- /dev/null
+++ b/apps/api/src/intake/intake-egress.ts
@@ -0,0 +1,108 @@
+/**
+ * Intake egress binding — THE single outbound surface for every intake
+ * adapter (task requirement 2: all outbound through packages/egress per-host
+ * budgets).
+ *
+ * Same shape as live-monitor/poller/egress.ts and virtual-channels/
+ * import-egress.ts: the egress package is ESM-only while the API emits
+ * CommonJS, so it is type-imported (erased at build) and loaded natively at
+ * runtime. Every request drawn by an adapter goes through `egressFetch`,
+ * which means SSRF policy (private-address denial, scheme/port policy), the
+ * global timeout, the response-size cap and — the point — the shared
+ * `host_budgets` rows all apply. Two replicas polling mastodon.social contend
+ * for one bucket; a 429 parks that host for every caller.
+ *
+ * `IntakeHttpError` carries the status + headers so adapters can classify
+ * 304-not-modified (free), 429/Retry-After (budget/park) and 5xx (backoff)
+ * the way the monitor poller's BackoffPollDriver does.
+ */
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { pool } from "../db/client.js";
+import { INTAKE_HOST_CLASSES } from "./intake-kinds.js";
+// Type-only (erased in the CommonJS build); loaded natively below.
+import type { createEgressClient, EgressError, EgressPolicy } from "../../../../packages/egress/src/index.js";
+
+type EgressPackage = typeof import("../../../../packages/egress/src/index.js");
+
+export interface IntakeEgress {
+  egressFetch: ReturnType<typeof createEgressClient>["egressFetch"];
+  policy: EgressPolicy;
+  isEgressError(error: unknown): error is EgressError;
+}
+
+/** Response body cap for feed/page/JSON fetches (not media downloads). */
+export const INTAKE_MAX_BYTES = 8 * 1024 * 1024;
+export const INTAKE_TIMEOUT_MS = 20_000;
+/** Media harvest ceiling per file (research §2.5 default image cap). */
+export const INTAKE_MEDIA_MAX_BYTES = 50 * 1024 * 1024;
+
+const nativeImport = new Function("specifier", "return import(specifier)") as (specifier: string) => Promise<EgressPackage>;
+let shared: Promise<IntakeEgress> | undefined;
+
+function resolveEgressPackage(): string {
+  for (const start of [process.cwd(), __dirname]) {
+    for (let root = start; ; root = dirname(root)) {
+      const directory = resolve(root, "packages/egress");
+      const files = process.env.NODE_ENV === "production" ? ["dist/index.js"] : ["src/index.ts", "dist/index.js"];
+      for (const file of files) {
+        const candidate = resolve(directory, file);
+        if (existsSync(candidate)) return candidate;
+      }
+      if (dirname(root) === root) break;
+    }
+  }
+  throw new Error("Build packages/egress before starting intake");
+}
+
+/** Process-wide egress client shared by every intake adapter. */
+export function intakeEgress(): Promise<IntakeEgress> {
+  shared ??= (async () => {
+    const pkg = await nativeImport(pathToFileURL(resolveEgressPackage()).href);
+    const client = pkg.createEgressClient({
+      pool,
+      timeoutMs: INTAKE_TIMEOUT_MS,
+      maxResponseBytes: INTAKE_MAX_BYTES,
+      hostClasses: INTAKE_HOST_CLASSES,
+    });
+    return { ...client, isEgressError: (error: unknown): error is EgressError => error instanceof pkg.EgressError };
+  })();
+  return shared;
+}
+
+/** Non-2xx/3xx egress response surfaced with its headers (Retry-After, ETag…). */
+export class IntakeHttpError extends Error {
+  constructor(readonly status: number, readonly headers: Headers, readonly url: string) {
+    super(`intake HTTP ${status}`);
+    this.name = "IntakeHttpError";
+  }
+  get notModified(): boolean { return this.status === 304; }
+  get gone(): boolean { return this.status === 404 || this.status === 410; }
+  get rateLimited(): boolean { return this.status === 429; }
+  get transient(): boolean { return this.status === 429 || this.status >= 500; }
+}
+
+/** Retry-After as a lower-bound delay in ms, including HTTP-date form. */
+export function intakeRetryAfterMs(headers: Headers, now: number): number {
+  const raw = headers.get("retry-after");
+  if (raw === null) return 0;
+  if (/^\d+(?:\.\d+)?$/.test(raw.trim())) {
+    const delay = Number(raw) * 1000;
+    return Number.isFinite(delay) ? delay : 0;
+  }
+  const deadline = Date.parse(raw);
+  return Number.isFinite(deadline) ? Math.max(0, deadline - now) : 0;
+}
+
+/** Reads a response body to a string under the shared size cap. */
+export async function readBodyText(response: Response): Promise<string> {
+  return response.text();
+}
+
+/** Reads a response body to a Buffer under the media cap, before S3 put. */
+export async function readBodyBytes(response: Response): Promise<Buffer> {
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.byteLength > INTAKE_MEDIA_MAX_BYTES) throw new Error("intake media exceeds size cap");
+  return bytes;
+}
diff --git a/apps/api/src/intake/intake-ingest.ts b/apps/api/src/intake/intake-ingest.ts
new file mode 100644
index 0000000..51b6a43
--- /dev/null
+++ b/apps/api/src/intake/intake-ingest.ts
@@ -0,0 +1,122 @@
+/**
+ * The intake ingest funnel: raw adapter items → P0c normalize → content-hash
+ * → idempotent upsert into intake_items (027).
+ *
+ * Every item passes `normalizeFeedItem` (task requirement 3), so `content`
+ * lands as the closed safe-content AST — never raw provider HTML — and media
+ * as proxy-minted refs. `text` (the FTS corpus) is derived from the AST via
+ * `astToPlainText`, never the raw provider string.
+ *
+ * `content_hash` is the schema's dedup key — UNIQUE (workspace_id,
+ * content_hash): sha256 of the NFKC + whitespace-collapsed AST plain text
+ * plus the sorted media origin identity. The same statement arriving via RSS
+ * and a Mastodon boost (or the same URL watched twice) hashes equal and
+ * stores once; first writer wins, later deliveries no-op.
+ */
+import { createHash } from "node:crypto";
+import type { PoolClient } from "pg";
+import { normalizeFeedItem, astToPlainText, type MediaRef, type NormalizedFeedItem } from "../feeds/feed-normalize.js";
+import { connectionFor, type RawIntakeItem } from "./adapters/adapter.js";
+import { PROVIDER_BY_KIND, type IntakeKind } from "./intake-kinds.js";
+import type { IntakeParams } from "./intake-params.js";
+import type { HarvestedMedia } from "./media-harvest.js";
+
+export type IntakeMediaRef = MediaRef & {
+  /** S3 content-addressed key when the harvest stored the origin file. */
+  storageKey?: string;
+  hash?: string;
+  sizeBytes?: number;
+  contentType?: string;
+  harvestStatus?: "stored" | "skipped" | "too_large" | "failed";
+  originUrl?: string;
+};
+
+export interface NormalizeOutcome {
+  normalized: NormalizedFeedItem | null;
+  plainText: string;
+  contentHash: string;
+}
+
+/** NFKC + whitespace-collapse, per the 027 content_hash note. */
+export function collapseText(plainText: string): string {
+  return plainText.normalize("NFKC").replace(/\s+/g, " ").trim();
+}
+
+/** sha256(collapsed plain text + sorted unique media origin URLs). */
+export function itemContentHash(plainText: string, mediaUrls: readonly string[]): string {
+  const origins = [...new Set(mediaUrls.filter((url) => typeof url === "string" && url !== ""))].sort();
+  return createHash("sha256")
+    .update(JSON.stringify([collapseText(plainText), origins]))
+    .digest("hex");
+}
+
+/** Normalize one raw item; normalized = null when the funnel's validation drops it. */
+export function normalizeRawItem(raw: RawIntakeItem, kind: IntakeKind, params: IntakeParams["params"],
+  workspaceId: string, sourceId: string): NormalizeOutcome {
+  const connection = connectionFor(kind, params, sourceId, workspaceId);
+  const normalized = normalizeFeedItem(raw, connection, raw.normalize);
+  if (normalized === null) return { normalized: null, plainText: "", contentHash: "" };
+  const plainText = astToPlainText(normalized.content);
+  return { normalized, plainText, contentHash: itemContentHash(plainText, raw.mediaUrls) };
+}
+
+/** Merge the P0c proxied media refs with the harvest outcome per origin URL. */
+export function mergeMediaRefs(normalized: NormalizedFeedItem, harvested: HarvestedMedia[]): IntakeMediaRef[] {
+  const byUrl = new Map(harvested.map((entry) => [entry.url, entry]));
+  return normalized.media.map((ref): IntakeMediaRef => {
+    const origin = originOfProxyUrl(ref.proxyUrl);
+    const hit = origin === null ? undefined : byUrl.get(origin);
+    if (!hit) return ref;
+    return {
+      ...ref,
+      originUrl: hit.url,
+      ...(hit.status === "stored" ? {
+        storageKey: hit.storageKey,
+        hash: hit.hash,
+        sizeBytes: hit.sizeBytes,
+        contentType: hit.contentType,
+        harvestStatus: "stored" as const,
+      } : { harvestStatus: hit.status }),
+    };
+  });
+}
+
+/** Extracts the origin URL back out of a media-proxy URL. */
+export function originOfProxyUrl(proxyUrl: string): string | null {
+  const marker = "url=";
+  const at = proxyUrl.indexOf(marker);
+  if (at < 0) return null;
+  try { return decodeURIComponent(proxyUrl.slice(at + marker.length)); } catch { return null; }
+}
+
+export interface UpsertResult {
+  inserted: number;
+  unchanged: number;
+}
+
+/**
+ * Idempotent upsert inside the caller's tenant transaction. The conflict
+ * target is the content-addressed key — (workspace_id, content_hash) — so a
+ * re-poll that yields the same content writes nothing, and cross-source
+ * duplicates (RSS + Mastodon boost of the same statement) collapse too.
+ */
+export async function upsertItems(client: PoolClient, workspaceId: string, sourceId: string, kind: IntakeKind,
+  rows: Array<{ raw: RawIntakeItem; outcome: NormalizeOutcome; harvested: HarvestedMedia[] }>): Promise<UpsertResult> {
+  const result: UpsertResult = { inserted: 0, unchanged: 0 };
+  for (const entry of rows) {
+    const { normalized, plainText, contentHash } = entry.outcome;
+    if (normalized === null) continue;
+    const mediaRefs = mergeMediaRefs(normalized, entry.harvested);
+    const attribution: Record<string, unknown> = { ...entry.raw.attribution, provider: PROVIDER_BY_KIND[kind] };
+    const inserted = await client.query(
+      `INSERT INTO intake_items (workspace_id, source_id, remote_ref, content_hash, published_at,
+         text, content, media_refs, attribution)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+       ON CONFLICT (workspace_id, content_hash) DO NOTHING`,
+      [workspaceId, sourceId, entry.raw.remoteRef, contentHash, normalized.createdAt.toISOString(),
+        plainText, JSON.stringify(normalized.content), JSON.stringify(mediaRefs), JSON.stringify(attribution)]);
+    if ((inserted.rowCount ?? 0) > 0) result.inserted += 1;
+    else result.unchanged += 1;
+  }
+  return result;
+}
diff --git a/apps/api/src/intake/intake-kinds.ts b/apps/api/src/intake/intake-kinds.ts
new file mode 100644
index 0000000..dd9adaa
--- /dev/null
+++ b/apps/api/src/intake/intake-kinds.ts
@@ -0,0 +1,128 @@
+/**
+ * Intake source kinds (migration 027 CHECK) and the per-kind maps the rest of
+ * the module keys off.
+ *
+ * This file is the ONE place provider-named string literals live outside the
+ * connector packages — the same standing as archive's ARCHIVE_PROVIDER
+ * boundary: the intake adapters ARE the provider integration surface for
+ * keyless public sources, so naming the platform they adapt is the boundary,
+ * not provider branching. Everything else in apps/api/src/intake references
+ * these constants; nothing else declares the literals.
+ */
+/* eslint-disable no-restricted-syntax -- intake kinds name the platform they adapt; this file is the provider boundary (archive ARCHIVE_PROVIDER pattern). */
+
+export const INTAKE_KINDS = [
+  "rss", "mastodon_tag", "mastodon_account", "bluesky_keyword",
+  "telegram_channel", "peertube_channel", "youtube_channel", "web_watch",
+] as const;
+
+export type IntakeKind = (typeof INTAKE_KINDS)[number];
+
+export function isIntakeKind(value: unknown): value is IntakeKind {
+  return typeof value === "string" && (INTAKE_KINDS as readonly string[]).includes(value);
+}
+
+export const KIND_RSS: IntakeKind = "rss";
+export const KIND_MASTODON_TAG: IntakeKind = "mastodon_tag";
+export const KIND_MASTODON_ACCOUNT: IntakeKind = "mastodon_account";
+export const KIND_BLUESKY_KEYWORD: IntakeKind = "bluesky_keyword";
+export const KIND_TELEGRAM_CHANNEL: IntakeKind = "telegram_channel";
+export const KIND_PEERTUBE_CHANNEL: IntakeKind = "peertube_channel";
+export const KIND_YOUTUBE_CHANNEL: IntakeKind = "youtube_channel";
+export const KIND_WEB_WATCH: IntakeKind = "web_watch";
+
+/** Kinds whose default posture is push-only (poll_interval_sec = 0, never due). */
+export const PUSH_ONLY_KINDS: readonly IntakeKind[] = [KIND_BLUESKY_KEYWORD, KIND_TELEGRAM_CHANNEL];
+
+/**
+ * The provider id handed to the P0c `normalizeFeedItem` funnel, so intake
+ * items carry the same canonical `{provider}:{handle@host}` authorRef shape
+ * every other feed item does.
+ */
+export const PROVIDER_BY_KIND: Record<IntakeKind, string> = {
+  rss: "rss",
+  mastodon_tag: "mastodon",
+  mastodon_account: "mastodon",
+  bluesky_keyword: "bluesky",
+  telegram_channel: "telegram",
+  peertube_channel: "peertube",
+  youtube_channel: "youtube",
+  web_watch: "web",
+};
+
+/**
+ * Default poll cadence per kind (seconds), from the firehose research source
+ * inventory: RSS 5–15 min, YouTube channel RSS ≤10 min (15-entry window),
+ * Mastodon 300/5min budget comfortably supports 60 s hashtags, PeerTube 10 min,
+ * page-watch hourly. 0 = push-only (never due; the telegram webhook bridge and
+ * the Jetstream seam park there).
+ */
+export const DEFAULT_POLL_INTERVAL_SEC: Record<IntakeKind, number> = {
+  rss: 900,
+  mastodon_tag: 300,
+  mastodon_account: 300,
+  bluesky_keyword: 0,
+  telegram_channel: 0,
+  peertube_channel: 600,
+  youtube_channel: 600,
+  web_watch: 3_600,
+};
+
+/**
+ * Egress host class per kind — the budget row class every outbound request of
+ * that adapter draws from (packages/egress HostBudgets, shared host_budgets
+ * rows deployment-wide). intake-social runs at capacity 3 / refill 10 per 10 s
+ * = 1 req/s ceiling = exactly the verified Mastodon 300/5min-per-IP budget.
+ */
+export const HOST_CLASS_BY_KIND: Record<IntakeKind, string> = {
+  rss: "intake-rss",
+  mastodon_tag: "intake-social",
+  mastodon_account: "intake-social",
+  bluesky_keyword: "intake-jetstream",
+  telegram_channel: "intake-telegram",
+  peertube_channel: "intake-peertube",
+  youtube_channel: "intake-rss",
+  web_watch: "intake-web",
+};
+
+/** Host-class budget shapes handed to createEgressClient. */
+export const INTAKE_HOST_CLASSES = {
+  "intake-rss": { capacity: 3, refillPerInterval: 10 },
+  "intake-social": { capacity: 3, refillPerInterval: 10 },
+  "intake-peertube": { capacity: 3, refillPerInterval: 5 },
+  "intake-web": { capacity: 2, refillPerInterval: 2 },
+  "intake-telegram": { capacity: 3, refillPerInterval: 10 },
+  "intake-jetstream": { capacity: 1, refillPerInterval: 1 },
+} as const;
+
+/**
+ * Media policy defaults per kind (research §2.5): images are cheap and safe to
+ * harvest; full video files are opt-in per source because YouTube-class full
+ * harvest is the storage wildcard.
+ */
+export type MediaPolicy = "metadata" | "images" | "full";
+
+export const DEFAULT_MEDIA_POLICY: Record<IntakeKind, MediaPolicy> = {
+  rss: "images",
+  mastodon_tag: "images",
+  mastodon_account: "images",
+  bluesky_keyword: "metadata",
+  telegram_channel: "metadata",
+  peertube_channel: "images",
+  youtube_channel: "metadata",
+  web_watch: "images",
+};
+
+/**
+ * Public endpoints the adapters poll. Verified keyless/live in the firehose
+ * research appendix (2026-10-09): YouTube channel Atom feed (no key, no
+ * quota), the Telegram Bot API base.
+ */
+export const YOUTUBE_FEED_URL = (channelId: string): string =>
+  `https://www.youtube.com/feeds/videos.xml?channel_id=${encodeURIComponent(channelId)}`;
+
+export const TELEGRAM_API_ORIGIN = "https://api.telegram.org";
+
+export const YOUTUBE_ORIGIN = "https://www.youtube.com";
+
+/* eslint-enable no-restricted-syntax */
diff --git a/apps/api/src/intake/intake-params.ts b/apps/api/src/intake/intake-params.ts
new file mode 100644
index 0000000..bb1bc6c
--- /dev/null
+++ b/apps/api/src/intake/intake-params.ts
@@ -0,0 +1,169 @@
+/**
+ * Per-kind source params: validation, canonicalization, and the params_hash
+ * identity half of UNIQUE (workspace_id, kind, params_hash) (migration 027).
+ *
+ * The DB only backstops "params is an object" — everything shape-related is
+ * validated here so a bad subscription is a 400/422 at the API edge, never a
+ * CHECK violation at insert time. Canonicalization is deterministic and total
+ * over the validated shape (sorted keys, trimmed strings, normalized URLs), so
+ * two subscriptions that differ only by `https://x/` vs `https://x` collide on
+ * the unique key instead of double-polling one feed.
+ */
+import { createHash } from "node:crypto";
+import { BadRequestException } from "@nestjs/common";
+import {
+  isIntakeKind, KIND_MASTODON_ACCOUNT, KIND_MASTODON_TAG, KIND_PEERTUBE_CHANNEL,
+  KIND_RSS, KIND_TELEGRAM_CHANNEL, KIND_WEB_WATCH, KIND_YOUTUBE_CHANNEL,
+  TELEGRAM_API_ORIGIN, YOUTUBE_ORIGIN, type IntakeKind,
+} from "./intake-kinds.js";
+
+export interface RssParams { url: string }
+export interface MastodonTagParams { instance: string; tag: string }
+export interface MastodonAccountParams { instance: string; accountId: string; handle?: string }
+export interface BlueskyKeywordParams { keywords: string[] }
+export interface TelegramChannelParams { channelId: string }
+export interface PeerTubeChannelParams { instance: string; handle: string }
+export interface YouTubeChannelParams { channelId: string }
+export interface WebWatchParams { url: string; selector?: string }
+
+export type IntakeParams =
+  | { kind: typeof KIND_RSS; params: RssParams }
+  | { kind: typeof KIND_MASTODON_TAG; params: MastodonTagParams }
+  | { kind: typeof KIND_MASTODON_ACCOUNT; params: MastodonAccountParams }
+  | { kind: "bluesky_keyword"; params: BlueskyKeywordParams }
+  | { kind: typeof KIND_TELEGRAM_CHANNEL; params: TelegramChannelParams }
+  | { kind: typeof KIND_PEERTUBE_CHANNEL; params: PeerTubeChannelParams }
+  | { kind: typeof KIND_YOUTUBE_CHANNEL; params: YouTubeChannelParams }
+  | { kind: typeof KIND_WEB_WATCH; params: WebWatchParams };
+
+const URL_MAX = 2_048;
+const STRING_MAX = 512;
+const TAG = /^[\p{L}\p{N}_]{1,64}$/u;
+const ACCOUNT_ID = /^[0-9]{1,19}$/;
+const TELEGRAM_CHANNEL_ID = /^-?\d{3,}$/;
+const YOUTUBE_CHANNEL = /^UC[\p{L}\p{N}_-]{20,24}$/u;
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requireString(value: unknown, field: string, max = STRING_MAX): string {
+  if (typeof value !== "string") throw new BadRequestException(`${field} must be a string`);
+  const trimmed = value.trim();
+  if (trimmed === "") throw new BadRequestException(`${field} must not be empty`);
+  if (trimmed.length > max) throw new BadRequestException(`${field} must be at most ${max} characters`);
+  return trimmed;
+}
+
+/** Origin-only instance URL (`https://mastodon.social`) — never a path/query. */
+function requireInstance(value: unknown, field: string): string {
+  const raw = requireString(value, field, 2_048);
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `https://${raw}`;
+  let url: URL;
+  try { url = new URL(withScheme); } catch { throw new BadRequestException(`${field} must be a valid host or URL`); }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new BadRequestException(`${field} must be http(s)`);
+  if (!url.hostname.includes(".")) throw new BadRequestException(`${field} must be a public host`);
+  return `${url.protocol}//${url.hostname.toLowerCase()}${url.port ? `:${url.port}` : ""}`;
+}
+
+function requireHttpUrl(value: unknown, field: string): string {
+  const raw = requireString(value, field, URL_MAX);
+  let url: URL;
+  try { url = new URL(raw); } catch { throw new BadRequestException(`${field} must be an absolute URL`); }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new BadRequestException(`${field} must be an http(s) URL`);
+  if (url.username !== "" || url.password !== "") throw new BadRequestException(`${field} must not carry credentials`);
+  if (!url.hostname.includes(".")) throw new BadRequestException(`${field} must be a public host`);
+  url.hash = "";
+  return url.toString();
+}
+
+/** Parse + canonicalize the per-kind params object. Throws BadRequest on shape. */
+export function parseIntakeParams(kind: unknown, raw: unknown): IntakeParams {
+  if (!isIntakeKind(kind)) throw new BadRequestException("kind must be a supported intake kind");
+  if (!isObject(raw)) throw new BadRequestException("params must be an object");
+  switch (kind) {
+    case KIND_RSS:
+      return { kind, params: { url: requireHttpUrl(raw.url, "params.url") } };
+    case KIND_MASTODON_TAG: {
+      const tag = requireString(raw.tag, "params.tag", 64);
+      if (!TAG.test(tag)) throw new BadRequestException("params.tag must be 1-64 word characters");
+      return { kind, params: { instance: requireInstance(raw.instance, "params.instance"), tag: tag.toLowerCase() } };
+    }
+    case KIND_MASTODON_ACCOUNT: {
+      const accountId = requireString(raw.accountId, "params.accountId", 19);
+      if (!ACCOUNT_ID.test(accountId)) throw new BadRequestException("params.accountId must be the numeric account id");
+      const params: MastodonAccountParams = { instance: requireInstance(raw.instance, "params.instance"), accountId };
+      const handle = raw.handle;
+      if (handle !== undefined && handle !== null && handle !== "") {
+        params.handle = requireString(handle, "params.handle", 64).replace(/^@+/, "").toLowerCase();
+      }
+      return { kind, params };
+    }
+    case "bluesky_keyword": {
+      const keywords = raw.keywords;
+      if (!Array.isArray(keywords) || keywords.length === 0 || keywords.length > 32) {
+        throw new BadRequestException("params.keywords must be a non-empty array (max 32)");
+      }
+      return { kind, params: { keywords: keywords.map((k) => requireString(k, "params.keywords[]", 100).toLowerCase()) } };
+    }
+    case KIND_TELEGRAM_CHANNEL: {
+      const channelId = requireString(raw.channelId, "params.channelId", 32);
+      if (!TELEGRAM_CHANNEL_ID.test(channelId)) throw new BadRequestException("params.channelId must be a numeric Telegram chat id");
+      return { kind, params: { channelId } };
+    }
+    case KIND_PEERTUBE_CHANNEL: {
+      const handle = requireString(raw.handle, "params.handle", 253).replace(/^@+/, "");
+      if (!/^[\p{L}\p{N}_.-]+(@[\p{L}\p{N}.-]+)?$/u.test(handle)) throw new BadRequestException("params.handle must be a channel handle");
+      return { kind, params: { instance: requireInstance(raw.instance, "params.instance"), handle } };
+    }
+    case KIND_YOUTUBE_CHANNEL: {
+      const channelId = requireString(raw.channelId, "params.channelId", 32);
+      if (!YOUTUBE_CHANNEL.test(channelId)) throw new BadRequestException("params.channelId must be a UC… channel id");
+      return { kind, params: { channelId } };
+    }
+    case KIND_WEB_WATCH: {
+      const params: WebWatchParams = { url: requireHttpUrl(raw.url, "params.url") };
+      if (raw.selector !== undefined && raw.selector !== null && raw.selector !== "") {
+        params.selector = requireString(raw.selector, "params.selector", 512);
+      }
+      return { kind, params };
+    }
+    default: {
+      throw new BadRequestException("kind must be a supported intake kind");
+    }
+  }
+}
+
+/** Deterministic key-sorted JSON — the canonical form hashing reads. */
+export function canonicalParams(input: IntakeParams): string {
+  const sorted = (value: unknown): unknown => {
+    if (Array.isArray(value)) return value.map(sorted);
+    if (isObject(value)) {
+      return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]));
+    }
+    return value;
+  };
+  return JSON.stringify(sorted({ kind: input.kind, params: input.params }));
+}
+
+/** sha256 of the canonical serialization — migration 027's params_hash. */
+export function paramsHash(input: IntakeParams): string {
+  return createHash("sha256").update(canonicalParams(input)).digest("hex");
+}
+
+/** Parse params already stored on a row (trusted shape, still coerced). */
+export function storedParams(kind: IntakeKind, raw: unknown): IntakeParams["params"] {
+  return parseIntakeParams(kind, isObject(raw) ? raw : {}).params;
+}
+
+/** The outbound host a kind+params pair polls — the egress budget key base. */
+export function egressOrigin(input: IntakeParams): string {
+  const params = input.params;
+  if ("instance" in params && typeof params.instance === "string") return params.instance;
+  if ("url" in params && typeof params.url === "string") return originOf(params.url);
+  return input.kind === KIND_YOUTUBE_CHANNEL ? YOUTUBE_ORIGIN : TELEGRAM_API_ORIGIN;
+}
+
+function originOf(url: string): string {
+  try { return new URL(url).origin; } catch { return "https://invalid.example"; }
+}
diff --git a/apps/api/src/intake/intake-search.ts b/apps/api/src/intake/intake-search.ts
new file mode 100644
index 0000000..79557b9
--- /dev/null
+++ b/apps/api/src/intake/intake-search.ts
@@ -0,0 +1,193 @@
+/**
+ * Intake search + listing (task requirement 5) — the 025 archive-search
+ * pattern applied to intake_items: Postgres FTS `websearch_to_tsquery`
+ * ORed with pg_trgm similarity per token for typo tolerance, RLS-scoped via
+ * withTenant (FORCE binds — there is no system path), keyset pagination with
+ * a base64url JSON cursor and an N+1 fetch.
+ *
+ * Ranking: ts_rank dominates (weight-A title hits outrank body hits via the
+ * 027 trigger's setweight), trigram similarity breaks ties. The no-query
+ * path keysets on (published_at, id).
+ */
+import { BadRequestException } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import type { StorageService } from "../storage/storage.js";
+import { searchTokens } from "../archive/archive-search.js";
+
+export interface IntakeQueryFilters {
+  q: string | null;
+  sourceId: string | null;
+  kind: string | null;
+  cursor: string | undefined;
+  limit: number;
+}
+
+export const SEARCH_DEFAULT_LIMIT = 20;
+export const SEARCH_MAX_LIMIT = 100;
+
+export interface IntakeItemRow {
+  id: string;
+  source_id: string;
+  remote_ref: string;
+  content_hash: string;
+  published_at: Date;
+  text: string;
+  content: Record<string, unknown>;
+  media_refs: Array<{ storageKey?: string; proxyUrl?: string; kind?: string }>;
+  attribution: Record<string, unknown>;
+  fetched_at: Date;
+  created_at: Date;
+  source_kind: string;
+  rank?: number;
+}
+
+const UUID_SHAPE = /^[0-9a-f-]{36}$/i;
+const ISO_TIMESTAMP = /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+
+interface Params {
+  values: unknown[];
+  bind(value: unknown): number;
+}
+
+function params(): Params {
+  const values: unknown[] = [];
+  return {
+    values,
+    bind(value: unknown): number { values.push(value); return values.length; },
+  };
+}
+
+function decodeCursor<T>(cursor: string | undefined, what: string, shape: (v: Record<string, unknown>) => T): T {
+  if (cursor === undefined) throw new BadRequestException(`invalid cursor: ${what}`);
+  let value: unknown;
+  try { value = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")); }
+  catch { throw new BadRequestException(`invalid cursor: ${what}`); }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BadRequestException(`invalid cursor: ${what}`);
+  }
+  return shape(value as Record<string, unknown>);
+}
+
+const ITEM_FIELDS = "intake_items.id, intake_items.source_id, intake_items.remote_ref, intake_items.content_hash, intake_items.published_at, intake_items.text, intake_items.content, intake_items.media_refs, intake_items.attribution, intake_items.fetched_at, intake_items.created_at";
+
+function filterConds(p: Params, filters: IntakeQueryFilters): string[] {
+  const conds: string[] = [];
+  if (filters.sourceId !== null) conds.push(`source_id = $${p.bind(filters.sourceId)}::uuid`);
+  if (filters.kind !== null) conds.push(`s.kind = $${p.bind(filters.kind)}`);
+  return conds;
+}
+
+/**
+ * Word-level fuzzy predicate. `text % $token` compares the WHOLE corpus
+ * string to the token, so a single misspelled word inside a long post scores
+ * ~0.1 and never clears pg_trgm's 0.3 threshold. Splitting first makes the
+ * comparison word-vs-word, where a one-letter typo still scores ~0.67 —
+ * that is the typo tolerance the spec asks pg_trgm for.
+ */
+function fuzzyPredicate(p: Params, tokens: string[]): string {
+  if (tokens.length === 0) return "false";
+  return tokens.map((token) => {
+    const ti = p.bind(token);
+    return `(EXISTS (SELECT 1 FROM regexp_split_to_table(intake_items.text, ' ') w WHERE w % $${ti})`
+      + ` OR coalesce(intake_items.attribution->>'title', '') % $${ti})`;
+  }).join(" OR ");
+}
+
+function rankExpression(p: Params, q: string, tokens: string[]): string {
+  const qi = p.bind(q);
+  const textSims = tokens.map((token) => `(SELECT max(similarity(w, $${p.bind(token)})) FROM regexp_split_to_table(intake_items.text, ' ') w)`);
+  const titleSims = tokens.map((token) => `similarity(coalesce(intake_items.attribution->>'title',''), $${p.bind(token)})`);
+  return `(ts_rank(intake_items.search_vector, websearch_to_tsquery('simple', $${qi})) * 2`
+    + (textSims.length > 0 ? ` + GREATEST(${textSims.join(", ")})` : "")
+    + (titleSims.length > 0 ? ` + GREATEST(${titleSims.join(", ")})` : "")
+    + `)`;
+}
+
+export function searchIntake(workspaceId: string, filters: IntakeQueryFilters,
+  storage: StorageService): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+  return runQuery(workspaceId, filters, storage, true);
+}
+
+export function listIntakeItems(workspaceId: string, filters: IntakeQueryFilters,
+  storage: StorageService): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+  // Listing without q is the plain keyset path; a q present upgrades it to search.
+  return runQuery(workspaceId, filters, storage, filters.q !== null);
+}
+
+async function runQuery(workspaceId: string, filters: IntakeQueryFilters,
+  storage: StorageService, ranked: boolean): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+  const p = params();
+  const tokens = filters.q !== null ? searchTokens(filters.q) : [];
+  let sql: string;
+  let cursorValue: { rk: number; id: string } | null = null;
+  let cursorPosted: { at: string; id: string } | null = null;
+  if (ranked && filters.q !== null) {
+    const rank = rankExpression(p, filters.q, tokens);
+    const conds = filterConds(p, filters);
+    const qi = p.bind(filters.q);
+    conds.push(`(intake_items.search_vector @@ websearch_to_tsquery('simple', $${qi}) OR ${fuzzyPredicate(p, tokens)})`);
+    if (filters.cursor !== undefined) {
+      cursorValue = decodeCursor(filters.cursor, "rank", (v) => {
+        if (typeof v.rk !== "number" || !Number.isFinite(v.rk) || typeof v.id !== "string" || !UUID_SHAPE.test(v.id)) {
+          throw new BadRequestException("invalid cursor: rank");
+        }
+        return { rk: v.rk, id: v.id };
+      });
+      conds.push(`(${rank}, intake_items.id) < ($${p.bind(cursorValue.rk)}::real, $${p.bind(cursorValue.id)}::uuid)`);
+    }
+    sql = `SELECT ranked.*, s.kind AS source_kind FROM
+             (SELECT ${ITEM_FIELDS}, ${rank} AS rank
+                FROM intake_items JOIN intake_sources s ON s.id = intake_items.source_id
+               WHERE ${conds.join(" AND ")}) ranked
+             JOIN intake_sources s ON s.id = ranked.source_id
+           ORDER BY ranked.rank DESC, ranked.id ASC LIMIT $${p.bind(filters.limit + 1)}`;
+  } else {
+    const conds = filterConds(p, filters);
+    if (filters.cursor !== undefined) {
+      cursorPosted = decodeCursor(filters.cursor, "published", (v) => {
+        if (typeof v.at !== "string" || !ISO_TIMESTAMP.test(v.at) || !Number.isFinite(Date.parse(v.at))
+          || typeof v.id !== "string" || !UUID_SHAPE.test(v.id)) {
+          throw new BadRequestException("invalid cursor: published");
+        }
+        return { at: v.at, id: v.id };
+      });
+      conds.push(`(intake_items.published_at, intake_items.id) < ($${p.bind(cursorPosted.at)}::timestamptz, $${p.bind(cursorPosted.id)}::uuid)`);
+    }
+    sql = `SELECT ${ITEM_FIELDS}, s.kind AS source_kind FROM intake_items
+             JOIN intake_sources s ON s.id = intake_items.source_id
+            WHERE ${conds.length > 0 ? conds.join(" AND ") : "true"}
+            ORDER BY intake_items.published_at DESC, intake_items.id DESC LIMIT $${p.bind(filters.limit + 1)}`;
+  }
+  const result = await withTenant(workspaceId, (client) => client.query<IntakeItemRow>(sql, p.values));
+  const page = result.rows.slice(0, filters.limit);
+  const last = page.at(-1);
+  const items = await Promise.all(page.map(async (row) => {
+    const media = await Promise.all((row.media_refs ?? []).map(async (media) => ({
+      ...media,
+      thumbUrl: media.storageKey ? await storage.presign(media.storageKey, 900) : null,
+    })));
+    return {
+      id: row.id,
+      sourceId: row.source_id,
+      remoteRef: row.remote_ref,
+      url: typeof row.attribution.url === "string" ? row.attribution.url : null,
+      contentHash: row.content_hash,
+      publishedAt: row.published_at.toISOString(),
+      text: row.text,
+      content: row.content,
+      media,
+      attribution: row.attribution,
+      kind: row.source_kind,
+      fetchedAt: row.fetched_at.toISOString(),
+      ...(row.rank !== undefined ? { rank: row.rank } : {}),
+    };
+  }));
+  const nextCursor = result.rows.length > filters.limit && last
+    ? Buffer.from(JSON.stringify(cursorShape(last, ranked && filters.q !== null))).toString("base64url")
+    : null;
+  return { items, nextCursor };
+}
+
+function cursorShape(last: IntakeItemRow, ranked: boolean): Record<string, string | number> {
+  return ranked ? { rk: last.rank ?? 0, id: last.id } : { at: last.published_at.toISOString(), id: last.id };
+}
diff --git a/apps/api/src/intake/intake.controller.ts b/apps/api/src/intake/intake.controller.ts
new file mode 100644
index 0000000..559f63d
--- /dev/null
+++ b/apps/api/src/intake/intake.controller.ts
@@ -0,0 +1,85 @@
+/**
+ * Intake API (task requirement 5).
+ *
+ *   POST   /intake/sources                    subscribe (kind + params)
+ *   GET    /intake/sources                    list subscriptions
+ *   GET    /intake/sources/:id                one subscription (+ state)
+ *   PATCH  /intake/sources/:id                pause / resume
+ *   DELETE /intake/sources/:id                unsubscribe
+ *   GET    /intake/search?q=…                 FTS + pg_trgm fuzzy, keyset
+ *   GET    /intake/items?sourceId=…           per-source listing, keyset
+ *
+ * Writes gate on `connection.manage` (subscribing an outbound poller is
+ * connection-shaped: it spends a shared host budget); reads stay on
+ * `draft.view` like /feeds and /archive, so every current reader keeps
+ * reading. RLS scoping is in the service layer (withTenant, FORCE).
+ */
+import { BadRequestException, Body, Controller, Delete, Get, Param, Patch, Post, Query, Req, UseGuards } from "@nestjs/common";
+import { parseId, requireObject, requireSession } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { IntakeService } from "./intake.service.js";
+import { INTAKE_KINDS } from "./intake-kinds.js";
+
+const KINDS_DOC = INTAKE_KINDS.join(", ");
+
+@Controller("intake")
+@UseGuards(RbacGuard)
+export class IntakeController {
+  constructor(private readonly intake: IntakeService) {}
+
+  @Post("sources")
+  @RequirePermission("connection.manage")
+  async create(@Req() request: AuthenticatedRequest, @Body() body: unknown): Promise<{ id: string; kind: string; health: string }> {
+    const input = requireObject(body, "body");
+    const kind = input.kind;
+    if (typeof kind !== "string" || kind === "") throw new BadRequestException(`kind must be one of: ${KINDS_DOC}`);
+    return this.intake.createSubscription(requireSession(request).workspaceId, kind,
+      input.params ?? {}, {
+        pollIntervalSec: input.pollIntervalSec,
+        mediaPolicy: input.mediaPolicy,
+      });
+  }
+
+  @Get("sources")
+  @RequirePermission("draft.view")
+  async list(@Req() request: AuthenticatedRequest): Promise<{ sources: Record<string, unknown>[] }> {
+    return { sources: await this.intake.listSources(requireSession(request).workspaceId) };
+  }
+
+  @Get("sources/:id")
+  @RequirePermission("draft.view")
+  async get(@Req() request: AuthenticatedRequest, @Param("id") id: string): Promise<Record<string, unknown>> {
+    return this.intake.getSource(requireSession(request).workspaceId, parseId(id));
+  }
+
+  @Patch("sources/:id")
+  @RequirePermission("connection.manage")
+  async patch(@Req() request: AuthenticatedRequest, @Param("id") id: string, @Body() body: unknown): Promise<{ ok: true }> {
+    const input = requireObject(body, "body");
+    const health = input.health;
+    if (health !== "active" && health !== "paused") throw new BadRequestException("health must be active or paused");
+    await this.intake.setSourceHealth(requireSession(request).workspaceId, parseId(id), health);
+    return { ok: true };
+  }
+
+  @Delete("sources/:id")
+  @RequirePermission("connection.manage")
+  async remove(@Req() request: AuthenticatedRequest, @Param("id") id: string): Promise<{ ok: true }> {
+    await this.intake.deleteSource(requireSession(request).workspaceId, parseId(id));
+    return { ok: true };
+  }
+
+  @Get("search")
+  @RequirePermission("draft.view")
+  async search(@Req() request: AuthenticatedRequest,
+    @Query() query: Record<string, unknown>): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    return this.intake.search(requireSession(request).workspaceId, query);
+  }
+
+  @Get("items")
+  @RequirePermission("draft.view")
+  async items(@Req() request: AuthenticatedRequest,
+    @Query() query: Record<string, unknown>): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    return this.intake.listItems(requireSession(request).workspaceId, query);
+  }
+}
diff --git a/apps/api/src/intake/intake.integration.test.ts b/apps/api/src/intake/intake.integration.test.ts
new file mode 100644
index 0000000..427d3a7
--- /dev/null
+++ b/apps/api/src/intake/intake.integration.test.ts
@@ -0,0 +1,467 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * Intake phase-1 integration against a live PostgreSQL, as sp_app (FORCE RLS
+ * binds both tables). Own scratch database (INTAKE_IT_DATABASE_URL +
+ * INTAKE_IT_SUPER_DATABASE_URL) per the local-db-sol pattern, because the
+ * shared-DB suites wipe every workspace and vitest runs files in parallel.
+ * Skipped when the URLs are unset.
+ *
+ * Covers the task's integration list: content-hash dedup, RLS cross-tenant
+ * denial, budget draws via fake egress, FTS + fuzzy matching, keyset
+ * pagination (both the ranked and the time-ordered path), the scheduler's
+ * poll/write-back cycle, and the source lifecycle (subscribe → pause →
+ * delete). Storage is a fake S3 that content-addresses in memory.
+ */
+const appUrl = process.env.INTAKE_IT_DATABASE_URL;
+const ownerUrl = process.env.INTAKE_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  service: typeof import("./intake.service.js");
+  ingest: typeof import("./intake-ingest.js");
+  search: typeof import("./intake-search.js");
+  kinds: typeof import("./intake-kinds.js");
+  adapter: typeof import("./adapters/adapter.js");
+  rss: typeof import("./adapters/rss.adapter.js");
+  db: typeof import("../db/client.js");
+};
+
+class FakeStorage {
+  readonly objects = new Map<string, { body: Buffer; contentType: string }>();
+  put(buffer: Buffer, contentType: string): { key: string; hash: string; sizeBytes: number } {
+    const { createHash } = require("node:crypto") as typeof import("node:crypto");
+    const hash = createHash("sha256").update(buffer).digest("hex");
+    const ext = contentType.split("/")[1]?.split("+")[0] ?? "bin";
+    const key = `sha256/${hash}.${ext}`;
+    this.objects.set(key, { body: buffer, contentType });
+    return { key, hash, sizeBytes: buffer.byteLength };
+  }
+  async putContent(buffer: Buffer, contentType: string) {
+    const info = this.put(buffer, contentType);
+    const deduplicated = this.objects.has(info.key);
+    return { ...info, contentType, deduplicated };
+  }
+  async presign(key: string): Promise<string> { return `https://fake-s3/${key}?sig=test`; }
+}
+
+/** Recording fake egress with fixture routes + Retry-After budget behavior. */
+class FakeEgress {
+  readonly draws: Array<{ url: string; hostClass: string }> = [];
+  constructor(private readonly routes: Record<string, () => { status: number; headers?: Record<string, string>; body?: string }>) {}
+  async egressFetch(url: string | URL, options: { headers?: Record<string, string> }, config: { hostClass: string }): Promise<Response> {
+    const key = String(url);
+    this.draws.push({ url: key, hostClass: config.hostClass });
+    const route = Object.entries(this.routes).find(([prefix]) => key.startsWith(prefix));
+    if (route === undefined) return new Response("not found", { status: 404 });
+    const r = route[1]();
+    return new Response(r.body ?? "", { status: r.status, headers: r.headers ?? {} });
+  }
+  readonly policy = { timeoutMs: 1000, maxResponseBytes: 1024 * 1024 } as never;
+  isEgressError(): boolean { return false; }
+}
+
+const RSS_BODY = `<?xml version="1.0"?><rss version="2.0" xmlns:media="http://search.yahoo.com/mrss/"><channel><title>Water WG</title>
+<item><title>Water rights are a community responsibility</title><link>https://example.org/w1</link><guid>w1</guid>
+<pubDate>Fri, 09 Oct 2026 12:00:00 GMT</pubDate><description>Water rights are a community responsibility, not a commodity.</description>
+<media:thumbnail url="https://cdn.example.org/water.jpg" /></item>
+<item><title>Bicycle repair night</title><link>https://example.org/w2</link><guid>w2</guid>
+<pubDate>Thu, 08 Oct 2026 09:00:00 GMT</pubDate><description>Bring your bicycles to the tool library Thursday.</description></item>
+</channel></rss>`;
+
+const MASTODON_BODY = JSON.stringify([
+  { id: "s1", created_at: "2026-10-09T11:00:00.000Z",
+    content: "<p>Water rights update: the hearing is postponed</p>",
+    account: { acct: "alice", username: "alice" }, url: "https://social.example/@alice/s1",
+    media_attachments: [{ url: "https://files.social.example/s1.png", type: "image", mime_type: "image/png" }], visibility: "public" },
+  { id: "s2", created_at: "2026-10-08T10:00:00.000Z",
+    content: "<p>Water rights are a community responsibility, not a commodity for markets.</p>",
+    account: { acct: "bob@example.social", username: "bob" }, visibility: "public" },
+]);
+
+const IMAGE_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 1, 2, 3, 4]);
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("intake phase 1 (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  let storage: FakeStorage;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let wsA: string;
+  let wsB: string;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try { return await fn(client); } finally { client.release(); }
+  }
+
+  let service: InstanceType<Modules["service"]["IntakeService"]>;
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      service: await import("./intake.service.js"),
+      ingest: await import("./intake-ingest.js"),
+      search: await import("./intake-search.js"),
+      kinds: await import("./intake-kinds.js"),
+      adapter: await import("./adapters/adapter.js"),
+      rss: await import("./adapters/rss.adapter.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    await asOwner(async (c) => {
+      const mk = async (name: string): Promise<string> =>
+        String((await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", [name, `${name}-${suffix}`])).rows[0].id);
+      wsA = await mk("intake-a");
+      wsB = await mk("intake-b");
+    });
+
+    storage = new FakeStorage();
+    process.env.S3_BUCKET = "intake-test";
+    // Silence the sweep timer: this suite drives polls explicitly.
+    service = new m.service.IntakeService({
+      egress: new FakeEgress({}) as never,
+      storage: storage as never,
+      random: () => 0.5,
+      now: () => new Date(),
+      sweepMs: 3_600_000,
+    });
+    service.onApplicationShutdown().catch(() => undefined);
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => { await c.query("DELETE FROM workspaces WHERE id = ANY($1::uuid[])", [[wsA, wsB]]); });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  // -----------------------------------------------------------------------
+  // Source lifecycle + params identity
+  // -----------------------------------------------------------------------
+
+  it("subscribes with canonical params identity; duplicates collapse; push-only parks unsupported", async () => {
+    const first = await service.createSubscription(wsA, "rss", { url: "https://example.org/feed.xml" }, { mediaPolicy: "images" });
+    expect(first.kind).toBe("rss");
+    expect(first.health).toBe("active");
+    // hash-stripped variant collides on (workspace, kind, params_hash)
+    const dupe = await service.createSubscription(wsA, "rss", { url: "https://example.org/feed.xml#fragment" });
+    expect(dupe.id).toBe(first.id);
+    const other = await service.createSubscription(wsA, "rss", { url: "https://other.example/feed.xml" });
+    expect(other.id).not.toBe(first.id);
+    const tg = await service.createSubscription(wsA, "telegram_channel", { channelId: "-1001234567890" });
+    expect(tg.health).toBe("unsupported"); // 027: push-only kinds park
+    const list = await service.listSources(wsA);
+    expect(list).toHaveLength(3);
+    // push-only kinds cannot opt into polling
+    await expect(service.createSubscription(wsA, "bluesky_keyword", { keywords: ["water"] }, { pollIntervalSec: 60 }))
+      .rejects.toThrow(/push-only/);
+  });
+
+  it("validates params shapes at the API edge", async () => {
+    await expect(service.createSubscription(wsA, "mastodon_account", { instance: "https://mastodon.social", accountId: "not-numeric" })).rejects.toThrow();
+    await expect(service.createSubscription(wsA, "youtube_channel", { channelId: "XD" })).rejects.toThrow();
+    await expect(service.createSubscription(wsA, "rss", { url: "file:///etc/passwd" })).rejects.toThrow();
+    await expect(service.createSubscription(wsA, "nope", {})).rejects.toThrow();
+  });
+
+  it("pauses, resumes and deletes sources", async () => {
+    const src = await service.createSubscription(wsA, "web_watch", { url: "https://example.org/watched" });
+    await service.setSourceHealth(wsA, src.id, "paused");
+    let row = await service.getSource(wsA, src.id) as { health: string };
+    expect(row.health).toBe("paused");
+    await service.setSourceHealth(wsA, src.id, "active");
+    row = await service.getSource(wsA, src.id) as { health: string };
+    expect(row.health).toBe("active");
+    await service.deleteSource(wsA, src.id);
+    await expect(service.getSource(wsA, src.id)).rejects.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // Poll + ingest + dedup + media harvest
+  // -----------------------------------------------------------------------
+
+  it("polls an rss source end-to-end: budget draws, P0c AST, media to S3, dedup on re-poll", async () => {
+    const egress = new FakeEgress({
+      "https://example.org/feed.xml": () => ({ status: 200, headers: { "content-type": "application/xml", etag: "\"v1\"" }, body: RSS_BODY }),
+      "https://cdn.example.org/water.jpg": () => ({ status: 200, headers: { "content-type": "image/png" }, body: IMAGE_BYTES.toString("latin1") }),
+    });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    const src = await service.createSubscription(wsA, "rss", { url: "https://example.org/feed.xml" });
+    const due = await poller.pollWorkspaceDue(wsA);
+    expect(due.polled).toBeGreaterThanOrEqual(1);
+    // Feed draw went through the egress client with the intake-rss host class.
+    expect(egress.draws.some((d) => d.url.startsWith("https://example.org/feed.xml") && d.hostClass === "intake-rss")).toBe(true);
+    // Media draw billed to the shared media class.
+    expect(egress.draws.some((d) => d.url.startsWith("https://cdn.example.org/water.jpg") && d.hostClass === "intake-web")).toBe(true);
+    const items = await service.listItems(wsA, { sourceId: src.id, limit: 50 });
+    expect(items.items).toHaveLength(2);
+    const first = items.items[0] as Record<string, unknown>;
+    // P0c AST landed — never raw HTML.
+    const content = first.content as { type: string; children: unknown[] };
+    expect(content.type).toBe("doc");
+    // text derived from the AST is the searchable corpus
+    expect(String(first.text)).toMatch(/community responsibility/);
+    // media ref carries the S3 storage key (content-addressed) + proxy URL
+    const media = first.media as Array<Record<string, unknown>>;
+    expect(media.length).toBeGreaterThanOrEqual(1);
+    expect(String(media[0]!.storageKey)).toMatch(/^sha256\/[0-9a-f]{64}\./);
+    // state carries the etag for conditional GET
+    const row = await service.getSource(wsA, src.id) as { state: { etag?: string }; nextPollAt: string | null };
+    expect(row.state.etag).toBe("\"v1\"");
+    expect(row.nextPollAt).not.toBeNull();
+
+    // Re-poll with identical content: zero inserts (content-hash dedup).
+    const before = await service.listItems(wsA, { sourceId: src.id, limit: 50 });
+    await poller.pollWorkspaceDue(wsA);
+    const after = await service.listItems(wsA, { sourceId: src.id, limit: 50 });
+    expect(after.items).toHaveLength(before.items.length);
+  });
+
+  it("cross-source dedup: the same statement via rss and mastodon stores once", async () => {
+    const statement = "Water rights are a community responsibility, not a commodity for markets.";
+    const rssBody = `<?xml version="1.0"?><rss version="2.0"><channel><title>x</title>
+      <item><title>Statement</title><link>https://example.org/x</link><guid>x1</guid>
+      <pubDate>Fri, 09 Oct 2026 12:00:00 GMT</pubDate><description>${statement}</description></item></channel></rss>`;
+    const mastodonBody = JSON.stringify([
+      { id: "m1", created_at: "2026-10-09T13:00:00.000Z", content: `<p>${statement}</p>`,
+        account: { acct: "relay", username: "relay" }, visibility: "public" },
+    ]);
+    const egress = new FakeEgress({
+      "https://dedup.example.org/rss": () => ({ status: 200, headers: { "content-type": "application/xml" }, body: rssBody }),
+      "https://mastodon.social/api/v1/timelines/tag/water": () => ({ status: 200, headers: { "content-type": "application/json" }, body: mastodonBody }),
+    });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    const rssSrc = await service.createSubscription(wsA, "rss", { url: "https://dedup.example.org/rss" });
+    const mdSrc = await service.createSubscription(wsA, "mastodon_tag", { instance: "https://mastodon.social", tag: "water" }, { mediaPolicy: "metadata" });
+    await poller.pollWorkspaceDue(wsA);
+    const rssItems = await service.listItems(wsA, { sourceId: rssSrc.id, limit: 10 });
+    const mdItems = await service.listItems(wsA, { sourceId: mdSrc.id, limit: 10 });
+    // First writer wins: the row is attributed to whichever source landed it.
+    expect(rssItems.items.length + mdItems.items.length).toBe(1);
+    // and the mastodon poll drew from the intake-social class
+    expect(egress.draws.some((d) => d.hostClass === "intake-social")).toBe(true);
+  });
+
+  it("mastodon items carry html-parsed AST + authorRef attribution", async () => {
+    const egress = new FakeEgress({
+      "https://mastodon.social/api/v1/timelines/tag/hearing": () => ({ status: 200, headers: { "content-type": "application/json" }, body: MASTODON_BODY }),
+      "https://files.social.example/s1.png": () => ({ status: 200, headers: { "content-type": "image/png" }, body: IMAGE_BYTES.toString("latin1") }),
+    });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    const src = await service.createSubscription(wsA, "mastodon_tag", { instance: "https://mastodon.social", tag: "hearing" });
+    await poller.pollWorkspaceDue(wsA);
+    const items = await service.listItems(wsA, { sourceId: src.id, limit: 10 });
+    expect(items.items.length).toBeGreaterThanOrEqual(1);
+    const newest = items.items.find((i) => (i as { remoteRef: string }).remoteRef === "s1") as Record<string, unknown>;
+    const attribution = newest.attribution as Record<string, string>;
+    expect(attribution.authorHandle).toBe("alice");
+    expect(attribution.authorRef).toBe("mastodon:alice");
+    expect(String(newest.url ?? "")).toContain("/@alice/s1");
+  });
+
+  it("poll failure: 429 parks the source in backoff with retry-after honored, then recovers", async () => {
+    let fail = true;
+    const body = `<?xml version="1.0"?><rss version="2.0"><channel><title>x</title>
+      <item><title>Recovered</title><link>https://example.org/r1</link><guid>r1</guid>
+      <pubDate>Fri, 09 Oct 2026 15:00:00 GMT</pubDate><description>recovered content</description></item></channel></rss>`;
+    const egress = new FakeEgress({
+      "https://backoff.example.org/feed": (): { status: number; headers: Record<string, string>; body?: string } => fail
+        ? { status: 429, headers: { "retry-after": "1" } }
+        : { status: 200, headers: { "content-type": "application/xml" }, body },
+    });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    const src = await service.createSubscription(wsA, "rss", { url: "https://backoff.example.org/feed" });
+    const firstPass = await poller.pollWorkspaceDue(wsA);
+    expect(firstPass.failed).toBeGreaterThanOrEqual(1);
+    let row = await service.getSource(wsA, src.id) as { health: string; lastError: string | null; consecutiveFailures: number };
+    expect(row.health).toBe("backoff");
+    expect(row.lastError).toMatch(/transient: http 429/);
+    expect(row.consecutiveFailures).toBe(1);
+    // Retry-After (1 s) becomes the next_poll_at floor — not due immediately.
+    const again = await poller.pollWorkspaceDue(wsA);
+    expect(again.polled).toBe(0);
+    // force-recover: clear backoff + due immediately
+    await asOwner(async (c) => { await c.query("UPDATE intake_sources SET next_poll_at = now(), health='active' WHERE id = $1", [src.id]); });
+    fail = false;
+    const third = await poller.pollWorkspaceDue(wsA);
+    expect(third.polled).toBeGreaterThanOrEqual(1);
+    row = await service.getSource(wsA, src.id) as { health: string; consecutiveFailures: number; lastError: string | null };
+    expect(row.health).toBe("active");
+    expect(row.consecutiveFailures).toBe(0);
+  });
+
+  it("permanent 410 parks the source in error, not backoff", async () => {
+    const egress = new FakeEgress({ "https://gone.example.org/feed": () => ({ status: 410 }) });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    const src = await service.createSubscription(wsA, "rss", { url: "https://gone.example.org/feed" });
+    await poller.pollWorkspaceDue(wsA);
+    const row = await service.getSource(wsA, src.id) as { health: string; lastError: string | null };
+    expect(row.health).toBe("error");
+    expect(row.lastError).toMatch(/permanent: http 410/);
+  });
+
+  // -----------------------------------------------------------------------
+  // RLS
+  // -----------------------------------------------------------------------
+
+  it("RLS: cross-tenant reads see nothing; writes are scoped", async () => {
+    // Distinct content from earlier feeds: dedup is content-addressed per
+    // workspace, so a re-delivery of RSS_BODY would (correctly) no-op.
+    const body = `<?xml version="1.0"?><rss version="2.0"><channel><title>rls</title>
+      <item><title>RLS probe</title><link>https://example.org/rls1</link><guid>rls1</guid>
+      <pubDate>Fri, 09 Oct 2026 16:00:00 GMT</pubDate><description>Tenant isolation probe statement.</description></item></channel></rss>`;
+    const egress = new FakeEgress({
+      "https://rls.example.org/feed": () => ({ status: 200, headers: { "content-type": "application/xml" }, body }),
+    });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    const srcA = await service.createSubscription(wsA, "rss", { url: "https://rls.example.org/feed" });
+    await poller.pollWorkspaceDue(wsA);
+    // wsB never subscribed; its listing + search are empty even though wsA has rows.
+    const inB = await service.listItems(wsB, { limit: 100 });
+    expect(inB.items).toHaveLength(0);
+    const searchB = await service.search(wsB, { q: "community responsibility" });
+    expect(searchB.items).toHaveLength(0);
+    await expect(service.getSource(wsB, srcA.id)).rejects.toThrow();
+    await expect(service.deleteSource(wsB, srcA.id)).rejects.toThrow();
+    const inA = await service.listItems(wsA, { sourceId: srcA.id, limit: 10 });
+    expect(inA.items.length).toBeGreaterThan(0);
+  });
+
+  // -----------------------------------------------------------------------
+  // Search: FTS, fuzzy, keyset
+  // -----------------------------------------------------------------------
+
+  // Seeds the corpus the three suites below read: a timestamped feed so each
+  // run's rows are unique (content-hash dedup is workspace-wide and this
+  // database is recreated per CI run, but re-runs against a kept database
+  // stay honest too).
+  let seeded = false;
+  it("seeds the search corpus via full polls", async () => {
+    if (seeded) return;
+    const stamp = Date.now();
+    const rssA = `<?xml version="1.0"?><rss version="2.0"><channel><title>Corpus</title>
+      <item><title>Community responsibility statement ${stamp}</title><link>https://example.org/c1</link><guid>c1-${stamp}</guid>
+      <pubDate>Fri, 09 Oct 2026 12:00:00 GMT</pubDate><description>Water rights are a community responsibility held in trust for the watershed ${stamp}.</description></item>
+      <item><title>Hearing update ${stamp}</title><link>https://example.org/c2</link><guid>c2-${stamp}</guid>
+      <pubDate>Fri, 09 Oct 2026 13:00:00 GMT</pubDate><description>The eviction hearing is postponed until February for the tenants union ${stamp}.</description></item>
+      <item><title>Tool library ${stamp}</title><link>https://example.org/c3</link><guid>c3-${stamp}</guid>
+      <pubDate>Fri, 09 Oct 2026 14:00:00 GMT</pubDate><description>Bicycle repair night at the tool library on Thursday evening ${stamp}.</description></item></channel></rss>`;
+    const egress = new FakeEgress({
+      "https://corpus.example.org/feed": () => ({ status: 200, headers: { "content-type": "application/xml" }, body: rssA }),
+    });
+    const poller = new m.service.IntakeService({
+      egress: egress as never, storage: storage as never,
+      random: () => 0.5, now: () => new Date(), sweepMs: 3_600_000,
+    });
+    await service.createSubscription(wsA, "rss", { url: "https://corpus.example.org/feed" });
+    const pass = await poller.pollWorkspaceDue(wsA);
+    expect(pass.polled).toBeGreaterThanOrEqual(1);
+    const seededRows = await service.listItems(wsA, { limit: 100 });
+    expect(seededRows.items.length).toBeGreaterThanOrEqual(3);
+    seeded = true;
+  });
+
+  it("FTS matches websearch_to_tsquery; fuzzy tolerates typos via pg_trgm", async () => {
+    const exact = await service.search(wsA, { q: "watershed" });
+    expect(exact.items.some((item) => /watershed/i.test(String(item.text)))).toBe(true);
+    // Typo tolerance: "responsability" matches the corpus item whose text has
+    // "responsibility" (word-level trigram), alongside the FTS hit above.
+    const fuzzy = await service.search(wsA, { q: "responsability" });
+    expect(fuzzy.items.some((item) => /responsibility/i.test(String(item.text)))).toBe(true);
+    const phrase = await service.search(wsA, { q: '"hearing is postponed"' });
+    expect(phrase.items.length).toBeGreaterThanOrEqual(1);
+    const nothing = await service.search(wsA, { q: "zzzzqqqq" });
+    expect(nothing.items).toHaveLength(0);
+  });
+
+  it("search filters by kind and rejects bad cursors", async () => {
+    const byKind = await service.search(wsA, { q: null, kind: "rss" });
+    expect(byKind.items.length).toBeGreaterThan(0);
+    for (const item of byKind.items) expect(item.kind).toBe("rss");
+    await expect(service.search(wsA, { q: "x", cursor: "not-a-cursor!" })).rejects.toThrow();
+    await expect(service.search(wsA, { q: "x".repeat(300) })).rejects.toThrow();
+    await expect(service.search(wsA, { limit: 1000 })).rejects.toThrow();
+  });
+
+  it("keyset pagination walks time-ordered listings without overlap", async () => {
+    let cursor: string | null = null;
+    const seen = new Set<string>();
+    let pages = 0;
+    for (;;) {
+      const page = await service.listItems(wsA, { limit: 2, ...(cursor ? { cursor } : {}) });
+      pages += 1;
+      for (const item of page.items) expect(seen.add(String(item.id))).toBe(true);
+      cursor = page.nextCursor;
+      if (cursor === null) break;
+      expect(pages).toBeLessThan(20);
+    }
+    const all = await service.listItems(wsA, { limit: 100 });
+    expect(seen.size).toBe(all.items.length);
+  });
+
+  it("keyset pagination on the ranked search path", async () => {
+    let cursor: string | null = null;
+    const seen = new Set<string>();
+    let pages = 0;
+    for (;;) {
+      const page = await service.search(wsA, { q: "water rights", limit: 2, ...(cursor ? { cursor } : {}) });
+      pages += 1;
+      for (const item of page.items) expect(seen.add(String(item.id))).toBe(true);
+      cursor = page.nextCursor;
+      if (cursor === null) break;
+      expect(pages).toBeLessThan(20);
+    }
+    expect(seen.size).toBeGreaterThanOrEqual(2);
+  });
+
+  // -----------------------------------------------------------------------
+  // Push-only bridge
+  // -----------------------------------------------------------------------
+
+  it("telegram bridge: archive item becomes an intake row for the subscribed channel", async () => {
+    const channelId = "-1009876543210";
+    const src = await service.createSubscription(wsA, "telegram_channel", { channelId });
+    expect(src.health).toBe("unsupported"); // never polled
+    // Seed an archive item directly (the webhook path owns that write).
+    let archiveId = "";
+    await asOwner(async (c) => {
+      c.query("SELECT set_config('app.workspace_id', $1, true)", [wsA]);
+      const row = await c.query(
+        `INSERT INTO archived_feed_items
+           (workspace_id, remote_ref, channel_id, message_id, text_content, content_hash, posted_at, attribution)
+         VALUES ($1, $2, $3, 5001, $4, encode(sha256($5::bytea), 'hex'), now(), $6::jsonb) RETURNING id`,
+        [wsA, `${channelId}:5001`, channelId, "Telegram harvest: water rights hearing moved.",
+          `tg-${suffix}`, JSON.stringify({ channelUsername: "water_wg", author: "Water WG" })]);
+      archiveId = String(row.rows[0].id);
+    });
+    await service.ingestArchiveItem(wsA, archiveId);
+    const items = await service.listItems(wsA, { sourceId: src.id, limit: 10 });
+    expect(items.items).toHaveLength(1);
+    const found = await service.search(wsA, { q: "harvest water" });
+    expect(found.items.length).toBeGreaterThanOrEqual(1);
+  });
+});
diff --git a/apps/api/src/intake/intake.module.ts b/apps/api/src/intake/intake.module.ts
new file mode 100644
index 0000000..09436a8
--- /dev/null
+++ b/apps/api/src/intake/intake.module.ts
@@ -0,0 +1,35 @@
+/**
+ * Intake module wiring: production providers bind the process-wide egress
+ * client, the S3 storage service and the real Redis lease surface.
+ *
+ * The egress package is ESM-only while the API emits CommonJS, so the client
+ * is constructed through the native-import binding in intake-egress.ts (same
+ * pattern as live-monitor/poller/egress.ts) inside a factory — the DI token
+ * carries the already-loaded surface.
+ */
+import { Module } from "@nestjs/common";
+import { IntakeController } from "./intake.controller.js";
+import { INTAKE_DEPENDENCIES, IntakeService } from "./intake.service.js";
+import { intakeEgress } from "./intake-egress.js";
+import { S3Storage, s3ConfigFromEnv } from "../storage/storage.js";
+import { RespControlRedis } from "../media-control/redis.js";
+
+@Module({
+  controllers: [IntakeController],
+  providers: [
+    IntakeService,
+    {
+      provide: INTAKE_DEPENDENCIES,
+      useFactory: async () => ({
+        egress: await intakeEgress(),
+        storage: new S3Storage(s3ConfigFromEnv()),
+        redis: new RespControlRedis(process.env.REDIS_URL ?? "redis://127.0.0.1:6379"),
+        random: Math.random,
+        now: () => new Date(),
+        sweepMs: 15_000,
+      }),
+    },
+  ],
+  exports: [IntakeService],
+})
+export class IntakeModule {}
diff --git a/apps/api/src/intake/intake.service.ts b/apps/api/src/intake/intake.service.ts
new file mode 100644
index 0000000..1b39e5d
--- /dev/null
+++ b/apps/api/src/intake/intake.service.ts
@@ -0,0 +1,432 @@
+/**
+ * IntakeService — subscriptions, the poll scheduler, ingest, and the search
+ * surface (firehose phase 1).
+ *
+ * Scheduler = the live-monitor pattern (task requirement 1): one serialized
+ * sweep, per-source state in the DB (`next_poll_at` / `consecutive_failures`
+ * / `health`), exponential backoff 2^n capped at 15 min, +/−20 % jitter on
+ * every schedule so a fleet of replicas never thundering-herds one host, and
+ * a Redis lease + cooldown per source so replicas never double-poll. Sources
+ * self-schedule via next_poll_at; the sweep only has to notice.
+ *
+ * Failures classify exactly like BackoffPollDriver: transient (429/5xx/
+ * budget/DNS) → backoff with Retry-After as a lower bound, health='backoff';
+ * policy denials and permanent shapes (404/410, bad params) → health='error'
+ * with the much longer cap; push-only kinds (poll_interval_sec = 0) are
+ * never due and park in 'unsupported' when first seen (027 note).
+ */
+import { BadRequestException, Inject, Injectable, Logger, NotFoundException, Optional, type OnApplicationBootstrap, type OnApplicationShutdown } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
+import { pool, withTenant } from "../db/client.js";
+import { S3Storage, s3ConfigFromEnv, type StorageService } from "../storage/storage.js";
+import type { ControlRedis } from "../media-control/redis.js";
+import { MemoryFeedRedis } from "../feeds/testing.js";
+import { intakeEgress, IntakeHttpError, intakeRetryAfterMs, type IntakeEgress } from "./intake-egress.js";
+import { DEFAULT_MEDIA_POLICY, DEFAULT_POLL_INTERVAL_SEC, HOST_CLASS_BY_KIND, isIntakeKind, KIND_TELEGRAM_CHANNEL, PROVIDER_BY_KIND, type IntakeKind, type MediaPolicy } from "./intake-kinds.js";
+import { parseIntakeParams, paramsHash, storedParams, type IntakeParams } from "./intake-params.js";
+import { adapterFor } from "./adapters/index.js";
+import type { AdapterState } from "./adapters/adapter.js";
+import { MediaHarvester, type HarvestedMedia } from "./media-harvest.js";
+import { itemContentHash, normalizeRawItem, upsertItems, type UpsertResult } from "./intake-ingest.js";
+import { searchIntake, listIntakeItems, type IntakeQueryFilters } from "./intake-search.js";
+
+export const INTAKE_DEPENDENCIES = Symbol("INTAKE_DEPENDENCIES");
+
+export interface IntakeDependencies {
+  egress: IntakeEgress;
+  storage: StorageService;
+  redis: Pick<ControlRedis, "get" | "set" | "eval">;
+  random(): number;
+  now(): Date;
+  /** Sweep period; defaults to 15 s (min cadence is 60 s, so this is ample). */
+  sweepMs?: number;
+}
+
+/** Backoff curve caps (live-monitor: 2^n; intake polls are slower, cap 15 min). */
+export const BACKOFF_CAP_MS = 15 * 60_000;
+export const PERMANENT_ERROR_MS = 6 * 60 * 60_000;
+export const LEASE_MS = 60_000;
+
+const RENEW_LEASE = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('PEXPIRE', KEYS[1], ARGV[2]) else return 0 end";
+const RELEASE_LEASE = "if redis.call('GET', KEYS[1]) == ARGV[1] then return redis.call('DEL', KEYS[1]) else return 0 end";
+
+interface SourceRow {
+  id: string;
+  workspace_id: string;
+  kind: IntakeKind;
+  params: Record<string, unknown>;
+  poll_interval_sec: number;
+  state: AdapterState;
+  health: string;
+  consecutive_failures: number;
+}
+
+export function backoffDelayMs(failures: number, intervalMs: number): number {
+  return Math.min(BACKOFF_CAP_MS, Math.max(intervalMs, 1_000) * 2 ** Math.min(6, Math.max(0, failures - 1)));
+}
+
+/** +/−20 % jitter (live-monitor jitteredInterval shape). */
+export function jitteredIntervalMs(intervalMs: number, random: number): number {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error("interval must be positive");
+  if (!Number.isFinite(random) || random < 0 || random > 1) throw new Error("random must be between 0 and 1");
+  return Math.round(intervalMs * (0.8 + random * 0.4));
+}
+
+function defaults(): IntakeDependencies {
+  return {
+    egress: undefined as never, // bound lazily by ensureDeps
+    storage: new S3Storage(s3ConfigFromEnv()),
+    redis: new MemoryFeedRedis(),
+    random: Math.random,
+    now: () => new Date(),
+    sweepMs: 15_000,
+  };
+}
+
+@Injectable()
+export class IntakeService implements OnApplicationBootstrap, OnApplicationShutdown {
+  private readonly logger = new Logger(IntakeService.name);
+  private readonly deps: IntakeDependencies;
+  private readonly egress: IntakeEgress | undefined;
+  private running = false;
+  private timer?: ReturnType<typeof setTimeout>;
+  private active?: Promise<void>;
+  private harvester?: MediaHarvester;
+
+  constructor(@Optional() @Inject(INTAKE_DEPENDENCIES) dependencies?: Partial<IntakeDependencies>) {
+    const base = defaults();
+    this.deps = { ...base, ...dependencies };
+    // The egress client binds lazily (native ESM import); tests inject a fake.
+    if (dependencies?.egress !== undefined) this.egress = dependencies.egress;
+    if (this.egress !== undefined) {
+      const nowMs = (): number => this.deps.now().getTime();
+      this.harvester = new MediaHarvester(this.egress, this.deps.storage, nowMs);
+    }
+  }
+
+  onApplicationBootstrap(): void {
+    this.running = true;
+    this.schedule(0);
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    this.running = false;
+    if (this.timer) clearTimeout(this.timer);
+    await this.active;
+  }
+
+  get isRunning(): boolean { return this.running; }
+
+  private schedule(delayMs: number): void {
+    if (!this.running) return;
+    const sweep = this.deps.sweepMs ?? 15_000;
+    this.timer = setTimeout(() => {
+      this.timer = undefined;
+      this.active = this.pollDueSources().catch((error: unknown) => {
+        this.logger.error(`intake sweep failed: ${String(error)}`);
+      }).then(() => undefined).finally(() => {
+        this.active = undefined;
+        this.schedule(jitteredIntervalMs(sweep, this.deps.random()));
+      });
+    }, delayMs);
+    this.timer.unref();
+  }
+
+  // -------------------------------------------------------------------------
+  // Subscriptions
+  // -------------------------------------------------------------------------
+
+  async createSubscription(workspaceId: string, kind: unknown, paramsRaw: unknown,
+    options: { pollIntervalSec?: unknown; mediaPolicy?: unknown } = {}): Promise<{ id: string; kind: IntakeKind; health: string }> {
+    const parsed = parseIntakeParams(kind, paramsRaw);
+    const hash = paramsHash(parsed);
+    const kindDefaults = DEFAULT_POLL_INTERVAL_SEC[parsed.kind];
+    const mediaPolicy = parseMediaPolicy(options.mediaPolicy, DEFAULT_MEDIA_POLICY[parsed.kind]);
+    let interval = kindDefaults;
+    const rawInterval: unknown = options.pollIntervalSec;
+    if (rawInterval !== undefined && rawInterval !== null && rawInterval !== "") {
+      const n = typeof rawInterval === "number" ? rawInterval : typeof rawInterval === "string" ? Number(rawInterval) : NaN;
+      if (!Number.isInteger(n) || n < 0 || n > 86_400) throw new BadRequestException("pollIntervalSec must be an integer 0..86400 (0 = push-only)");
+      if (kindDefaults === 0 && n > 0) throw new BadRequestException("this kind is push-only; pollIntervalSec must be 0");
+      interval = n > 0 ? Math.max(60, Math.min(n, 86_400)) : 0;
+    }
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query<{ id: string; health: string }>(
+        `INSERT INTO intake_sources (workspace_id, kind, params, params_hash, poll_interval_sec, state, health)
+         VALUES ($1,$2,$3,$4,$5,$6,$7)
+         ON CONFLICT (workspace_id, kind, params_hash) DO UPDATE SET updated_at = now()
+         RETURNING id, health`,
+        [workspaceId, parsed.kind, JSON.stringify({ ...parsed.params, mediaPolicy }), hash, interval, JSON.stringify(mediaPolicy ? { mediaPolicy } : {}),
+          kindDefaults === 0 ? "unsupported" : "active"]);
+      const row = result.rows[0];
+      if (!row) throw new Error("intake source insert failed");
+      return { id: String(row.id), kind: parsed.kind, health: row.health };
+    });
+  }
+
+  async listSources(workspaceId: string): Promise<Record<string, unknown>[]> {
+    return withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT id, kind, params, poll_interval_sec, health, last_error, last_polled_at, next_poll_at,
+                consecutive_failures, created_at, updated_at
+           FROM intake_sources WHERE workspace_id = $1 ORDER BY created_at`, [workspaceId]);
+      return result.rows.map((row) => ({
+        id: String(row.id), kind: row.kind, params: row.params,
+        pollIntervalSec: Number(row.poll_interval_sec), health: row.health,
+        lastError: row.last_error, lastPolledAt: row.last_polled_at?.toISOString() ?? null,
+        nextPollAt: row.next_poll_at?.toISOString() ?? null,
+        consecutiveFailures: Number(row.consecutive_failures),
+        createdAt: row.created_at.toISOString(), updatedAt: row.updated_at.toISOString(),
+      }));
+    });
+  }
+
+  async getSource(workspaceId: string, sourceId: string): Promise<Record<string, unknown>> {
+    const rows = await withTenant(workspaceId, async (client) => client.query(
+      "SELECT * FROM intake_sources WHERE workspace_id = $1 AND id = $2", [workspaceId, sourceId]));
+    const row = rows.rows[0];
+    if (!row) throw new NotFoundException("intake source not found");
+    return {
+      id: String(row.id), kind: row.kind, params: row.params,
+      pollIntervalSec: Number(row.poll_interval_sec), health: row.health,
+      lastError: row.last_error, lastPolledAt: row.last_polled_at?.toISOString() ?? null,
+      nextPollAt: row.next_poll_at?.toISOString() ?? null, state: row.state,
+      consecutiveFailures: Number(row.consecutive_failures),
+      createdAt: row.created_at.toISOString(), updatedAt: row.updated_at.toISOString(),
+    };
+  }
+
+  async setSourceHealth(workspaceId: string, sourceId: string, health: "active" | "paused"): Promise<void> {
+    if (health !== "active" && health !== "paused") throw new BadRequestException("health must be active or paused");
+    await withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        `UPDATE intake_sources SET health = $3, updated_at = now(),
+           next_poll_at = CASE WHEN $3 = 'active' THEN now() ELSE next_poll_at END
+         WHERE workspace_id = $1 AND id = $2`, [workspaceId, sourceId, health]);
+      if (result.rowCount === 0) throw new NotFoundException("intake source not found");
+    });
+  }
+
+  async deleteSource(workspaceId: string, sourceId: string): Promise<void> {
+    await withTenant(workspaceId, async (client) => {
+      const result = await client.query(
+        "DELETE FROM intake_sources WHERE workspace_id = $1 AND id = $2", [workspaceId, sourceId]);
+      if (result.rowCount === 0) throw new NotFoundException("intake source not found");
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Polling
+  // -------------------------------------------------------------------------
+
+  /** One sweep over every workspace's due sources; per-source failures never abort the sweep. */
+  async pollDueSources(): Promise<{ polled: number; skipped: number; failed: number }> {
+    if (this.egress === undefined) return { polled: 0, skipped: 0, failed: 0 };
+    const workspaces = await pool.query<{ id: string }>("SELECT id FROM workspaces ORDER BY id");
+    const totals = { polled: 0, skipped: 0, failed: 0 };
+    for (const { id } of workspaces.rows) {
+      const pass = await this.pollWorkspaceDue(id);
+      totals.polled += pass.polled;
+      totals.skipped += pass.skipped;
+      totals.failed += pass.failed;
+    }
+    return totals;
+  }
+
+  async pollWorkspaceDue(workspaceId: string): Promise<{ polled: number; skipped: number; failed: number }> {
+    const due = await withTenant(workspaceId, async (client) => client.query<SourceRow>(
+      `SELECT id, workspace_id, kind, params, poll_interval_sec, state, health, consecutive_failures
+         FROM intake_sources
+        WHERE workspace_id = $1
+          AND health NOT IN ('paused','unsupported')
+          AND poll_interval_sec > 0
+          AND (next_poll_at IS NULL OR next_poll_at <= now())
+        ORDER BY COALESCE(next_poll_at, created_at), created_at`, [workspaceId]));
+    const totals = { polled: 0, skipped: 0, failed: 0 };
+    for (const row of due.rows) {
+      const outcome = await this.pollSource(workspaceId, row);
+      totals[outcome] += 1;
+    }
+    return totals;
+  }
+
+  /**
+   * Poll one source under its Redis lease. The lease makes a multi-replica
+   * deployment safe (one owner at a time; renewed on a heartbeat, released on
+   * completion, expires on crash). Spacing between polls is enforced solely
+   * by next_poll_at in the DB — the single source of truth the scheduler
+   * reads — so a manual due-reset (or an ops force-poll) is honored rather
+   * than silently eaten by a side-channel cooldown.
+   */
+  async pollSource(workspaceId: string, row: SourceRow): Promise<"polled" | "skipped" | "failed"> {
+    if (this.egress === undefined || this.harvester === undefined) return "skipped";
+    const intervalMs = Math.max(60_000, row.poll_interval_sec * 1_000);
+    const leaseKey = `intake:${workspaceId}:${row.id}:lease`;
+    const owner = randomUUID();
+    if (!await this.deps.redis.set(leaseKey, owner, { nx: true, pxMs: LEASE_MS })) return "skipped";
+    let renew: Promise<unknown> = Promise.resolve();
+    let heartbeat: ReturnType<typeof setInterval> | undefined;
+    try {
+      heartbeat = setInterval(() => {
+        renew = this.deps.redis.eval(RENEW_LEASE, [leaseKey], [owner, String(LEASE_MS)]).catch(() => {
+          this.logger.warn("intake poll lease renewal unavailable");
+        });
+      }, LEASE_MS / 3);
+      heartbeat.unref();
+
+      const params = storedParams(row.kind, row.params);
+      const adapter = adapterFor(row.kind);
+      const fetcher = {
+        fetch: (url: string | URL, options: { headers?: Record<string, string>; hostClass: string }) =>
+          this.egress!.egressFetch(url, { headers: options.headers ?? {} }, { hostClass: options.hostClass }),
+      };
+      const result = await adapter.poll({
+        workspaceId, sourceId: row.id, params, kind: row.kind, state: row.state ?? {}, fetch: fetcher,
+      });
+
+      // Harvest media per the source's policy, then normalize + upsert.
+      const policy = sourceMediaPolicy(row);
+      const harvested: HarvestedMedia[][] = [];
+      for (const item of result.items) {
+        harvested.push(await this.harvester.harvestAll(policy, item.media ?? []));
+      }
+      const rows = result.items.map((raw, index) => ({
+        raw,
+        outcome: normalizeRawItem(raw, row.kind, params, workspaceId, row.id),
+        harvested: harvested[index] ?? [],
+      }));
+      const upsert: UpsertResult = await withTenant(workspaceId, async (client) =>
+        upsertItems(client, workspaceId, row.id, row.kind, rows));
+      void upsert;
+      await withTenant(workspaceId, async (client) => client.query(
+        `UPDATE intake_sources SET state = $3, health = 'active', last_error = NULL, last_polled_at = now(),
+           consecutive_failures = 0, next_poll_at = now() + ($4::bigint * interval '1 millisecond'), updated_at = now()
+         WHERE workspace_id = $1 AND id = $2`,
+        [workspaceId, row.id, JSON.stringify(result.state), jitteredIntervalMs(intervalMs, this.deps.random())]));
+      return "polled";
+    } catch (error) {
+      await this.recordFailure(workspaceId, row, error, intervalMs);
+      return "failed";
+    } finally {
+      if (heartbeat) clearInterval(heartbeat);
+      await renew;
+      await this.deps.redis.eval(RELEASE_LEASE, [leaseKey], [owner]).catch(() => undefined);
+    }
+  }
+
+  private async recordFailure(workspaceId: string, row: SourceRow, error: unknown, intervalMs: number): Promise<void> {
+    const now = this.deps.now().getTime();
+    const http = error instanceof IntakeHttpError ? error : undefined;
+    const egress = this.egress?.isEgressError(error) === true ? error : undefined;
+    const retryAfter = http !== undefined
+      ? intakeRetryAfterMs(http.headers, now)
+      : egress !== undefined ? egress.retryAfterMs ?? 0 : 0;
+    const transient = (http !== undefined && http.transient)
+      || egress !== undefined && ["BUDGET_EXHAUSTED", "BUDGET_UNAVAILABLE", "TIMEOUT", "NETWORK_ERROR", "ABORTED", "DNS_FAILED"].includes(egress.code)
+      || http === undefined && egress === undefined; // network shape unknown → benefit of the doubt
+    const permanent = (http !== undefined && http.gone)
+      || egress !== undefined && ["DENIED_PRIVATE_ADDRESS", "SCHEME_DENIED", "PORT_DENIED", "ORIGIN_DENIED", "INVALID_URL"].includes(egress.code);
+    const failures = row.consecutive_failures + 1;
+    const base = permanent ? PERMANENT_ERROR_MS : transient ? backoffDelayMs(failures, intervalMs) : PERMANENT_ERROR_MS;
+    const delay = Math.max(retryAfter, jitteredIntervalMs(base, this.deps.random()));
+    const reason = permanent ? "permanent" : transient ? "transient" : "unknown";
+    const message = http !== undefined ? `http ${http.status}`
+      : egress !== undefined ? `egress:${egress.code}`
+        : error instanceof Error ? error.message.slice(0, 240) : "poll failed";
+    await withTenant(workspaceId, async (client) => client.query(
+      `UPDATE intake_sources SET health = $3, last_error = $4, last_polled_at = now(),
+         consecutive_failures = $5, next_poll_at = now() + ($6::bigint * interval '1 millisecond'), updated_at = now()
+       WHERE workspace_id = $1 AND id = $2`,
+      [workspaceId, row.id, permanent ? "error" : "backoff", `${reason}: ${message}`, failures, delay],
+    )).catch(() => this.logger.warn("intake source state write-back unavailable"));
+  }
+
+  // -------------------------------------------------------------------------
+  // Telegram archive bridge (task requirement: reuse the existing harvest)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Bridges an archived_feed_items row into intake_items. The archive webhook
+   * path (apps/api/src/archive) already normalized the post, harvested media
+   * into S3 content-addressed keys and enforced revisions — intake stores the
+   * reference, it never re-fetches.
+   */
+  async ingestArchiveItem(workspaceId: string, archiveItemId: string): Promise<void> {
+    const found = await withTenant(workspaceId, async (client) => client.query<{
+      id: string; remote_ref: string; channel_id: string; message_id: string; text_content: string;
+      media_refs: Array<{ storageKey?: string; contentType?: string; sizeBytes?: number | null }>;
+      attribution: Record<string, unknown>; posted_at: Date;
+    }>("SELECT * FROM archived_feed_items WHERE id = $1", [archiveItemId]));
+    const item = found.rows[0];
+    if (!item) throw new NotFoundException("archive item not found");
+    const channelId = String(item.channel_id);
+    await withTenant(workspaceId, async (client) => {
+      const source = await client.query<{ id: string; params: Record<string, unknown> }>(
+        `SELECT id, params FROM intake_sources WHERE workspace_id = $1 AND kind = $2
+           AND params->>'channelId' = $3`, [workspaceId, KIND_TELEGRAM_CHANNEL, channelId]);
+      const sourceRow = source.rows[0];
+      if (!sourceRow) return; // not subscribed in intake — nothing to do
+      const mediaKeys = (item.media_refs ?? []).map((media) => media.storageKey ?? "").filter((key) => key !== "");
+      const bridgeHash = itemContentHash(item.text_content, mediaKeys);
+      await client.query(
+        `INSERT INTO intake_items (workspace_id, source_id, remote_ref, content_hash, published_at,
+           text, content, media_refs, attribution)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9)
+         ON CONFLICT (workspace_id, content_hash) DO NOTHING`,
+        [workspaceId, sourceRow.id, item.remote_ref, bridgeHash,
+          item.posted_at.toISOString(), item.text_content,
+          JSON.stringify({ type: "doc", version: 1, children: [{ type: "paragraph", children: [{ type: "text", text: item.text_content }] }], truncated: false }),
+          JSON.stringify(item.media_refs.map((media) => ({ kind: "image", proxyUrl: "", storageKey: media.storageKey ?? null, contentType: media.contentType ?? null, sizeBytes: media.sizeBytes ?? null }))),
+          JSON.stringify({ ...item.attribution, provider: PROVIDER_BY_KIND[KIND_TELEGRAM_CHANNEL], archiveItemId: item.id })]);
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Read surface (search + per-source listing)
+  // -------------------------------------------------------------------------
+
+  search(workspaceId: string, query: Record<string, unknown>): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    return searchIntake(workspaceId, parseSearchQuery(query), this.deps.storage);
+  }
+
+  listItems(workspaceId: string, query: Record<string, unknown>): Promise<{ items: Record<string, unknown>[]; nextCursor: string | null }> {
+    return listIntakeItems(workspaceId, parseSearchQuery(query), this.deps.storage);
+  }
+}
+
+function parseMediaPolicy(value: unknown, fallback: MediaPolicy): MediaPolicy {
+  if (value === undefined || value === null || value === "") return fallback;
+  if (value !== "metadata" && value !== "images" && value !== "full") {
+    throw new BadRequestException("mediaPolicy must be metadata, images, or full");
+  }
+  return value;
+}
+
+function sourceMediaPolicy(row: SourceRow): MediaPolicy {
+  const fromParams = row.params.mediaPolicy;
+  if (fromParams === "metadata" || fromParams === "images" || fromParams === "full") return fromParams;
+  return DEFAULT_MEDIA_POLICY[row.kind];
+}
+
+/** Shared query parsing for /intake/search and /intake/items. */
+export function parseSearchQuery(query: Record<string, unknown>): IntakeQueryFilters {
+  const rawQ = query.q;
+  const q = typeof rawQ === "string" && rawQ.trim() !== "" ? rawQ.trim() : null;
+  if (q !== null && q.length > 256) throw new BadRequestException("q must be at most 256 characters");
+  const rawSource = query.sourceId;
+  const sourceId = rawSource === undefined || rawSource === null || rawSource === "" ? null
+    : typeof rawSource === "string" && /^[0-9a-f-]{36}$/i.test(rawSource) ? rawSource : (() => { throw new BadRequestException("sourceId must be a UUID"); })();
+  const rawKind = query.kind;
+  const kind = rawKind === undefined || rawKind === null || rawKind === "" ? null
+    : isIntakeKind(rawKind) ? rawKind : (() => { throw new BadRequestException("kind is not a supported intake kind"); })();
+  const cursor = typeof query.cursor === "string" && query.cursor !== "" ? query.cursor : undefined;
+  if (cursor !== undefined && (cursor.length > 256 || !/^[A-Za-z0-9_-]+$/.test(cursor))) throw new BadRequestException("invalid cursor");
+  let limit = 20;
+  if (query.limit !== undefined && query.limit !== "") {
+    const n = typeof query.limit === "string" ? Number(query.limit)
+      : typeof query.limit === "number" ? query.limit : NaN;
+    if (!Number.isInteger(n) || n < 1 || n > 100) throw new BadRequestException("limit must be an integer between 1 and 100");
+    limit = n;
+  }
+  return { q, sourceId, kind, cursor, limit };
+}
diff --git a/apps/api/src/intake/media-harvest.ts b/apps/api/src/intake/media-harvest.ts
new file mode 100644
index 0000000..f1694d0
--- /dev/null
+++ b/apps/api/src/intake/media-harvest.ts
@@ -0,0 +1,107 @@
+/**
+ * Intake media harvest — the archive StorageService pattern verbatim
+ * (task requirement 4): direct GET through the egress budget →
+ * `putContent(bytes, contentType)` → content-addressed `sha256/<hash>.<ext>`
+ * key, AES-256-GCM envelope encryption, dedup by plaintext hash. A blob
+ * already in the bucket is a no-op (`deduplicated: true`), so the same image
+ * seen via RSS and Mastodon stores once.
+ *
+ * Policy gate (research §2.5): `metadata` harvests nothing; `images` accepts
+ * image candidates only; `full` accepts video/audio too. Size caps are
+ * enforced twice (declared content-length and actual bytes).
+ */
+import { HOST_CLASS_BY_KIND, type IntakeKind, type MediaPolicy } from "./intake-kinds.js";
+import { INTAKE_MEDIA_MAX_BYTES, IntakeHttpError, intakeRetryAfterMs, type IntakeEgress } from "./intake-egress.js";
+import type { StorageService, StoredObject } from "../storage/storage.js";
+
+export interface HarvestRequest {
+  url: string;
+  kind: "image" | "video";
+}
+
+export interface HarvestedMedia {
+  url: string;
+  kind: "image" | "video";
+  status: "stored" | "skipped" | "too_large" | "failed";
+  storageKey?: string;
+  hash?: string;
+  sizeBytes?: number;
+  contentType?: string;
+  deduplicated?: boolean;
+  error?: string;
+}
+
+const IMAGE_TYPES = /^image\//i;
+/** Download budget for media files is the shared intake-web class (polite). */
+const MEDIA_HOST_CLASS = "intake-web";
+
+export function accepts(policy: MediaPolicy, kind: "image" | "video"): boolean {
+  if (policy === "metadata") return false;
+  if (policy === "images") return kind === "image";
+  return true;
+}
+
+export class MediaHarvester {
+  constructor(
+    private readonly egress: IntakeEgress,
+    private readonly storage: StorageService,
+    private readonly now: () => number = Date.now,
+    private readonly maxBytes: number = INTAKE_MEDIA_MAX_BYTES,
+  ) {}
+
+  async harvestAll(policy: MediaPolicy, requests: HarvestRequest[]): Promise<HarvestedMedia[]> {
+    const out: HarvestedMedia[] = [];
+    for (const request of requests) {
+      out.push(await this.harvest(policy, request));
+    }
+    return out;
+  }
+
+  async harvest(policy: MediaPolicy, request: HarvestRequest): Promise<HarvestedMedia> {
+    if (!accepts(policy, request.kind)) {
+      return { url: request.url, kind: request.kind, status: "skipped" };
+    }
+    try {
+      const response = await this.egress.egressFetch(request.url, { headers: { accept: "*/*" } }, { hostClass: MEDIA_HOST_CLASS });
+      if (!response.ok) throw new IntakeHttpError(response.status, response.headers, request.url);
+      const declared = Number(response.headers.get("content-length") ?? "0");
+      if (Number.isFinite(declared) && declared > this.maxBytes) {
+        return { url: request.url, kind: request.kind, status: "too_large", sizeBytes: declared };
+      }
+      const contentType = normalizeContentType(response.headers.get("content-type"), request.kind);
+      const bytes = Buffer.from(await response.arrayBuffer());
+      if (bytes.byteLength > this.maxBytes) {
+        return { url: request.url, kind: request.kind, status: "too_large", sizeBytes: bytes.byteLength };
+      }
+      const stored: StoredObject & { deduplicated: boolean } = await this.storage.putContent(bytes, contentType);
+      return {
+        url: request.url, kind: request.kind, status: "stored",
+        storageKey: stored.key, hash: stored.hash, sizeBytes: stored.sizeBytes,
+        contentType: stored.contentType, deduplicated: stored.deduplicated,
+      };
+    } catch (error) {
+      const retryAfter = error instanceof IntakeHttpError ? intakeRetryAfterMs(error.headers, this.now()) : 0;
+      return {
+        url: request.url, kind: request.kind, status: "failed",
+        error: retryAfter > 0 ? `http ${error instanceof IntakeHttpError ? error.status : "network"} (retry-after ${Math.round(retryAfter / 1000)}s)` : error instanceof Error ? error.message.slice(0, 120) : "harvest failed",
+      };
+    }
+  }
+}
+
+function normalizeContentType(raw: string | null, kind: "image" | "video"): string {
+  const value = (raw ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
+  if (value !== "") {
+    if (kind === "image" && IMAGE_TYPES.test(value)) return value;
+    if (kind === "video" && (value.startsWith("video/") || value === "application/octet-stream" || value.startsWith("audio/"))) return value;
+    if (value === "application/octet-stream") return value;
+    if (IMAGE_TYPES.test(value)) return value;
+    if (value.startsWith("video/") || value.startsWith("audio/")) return value;
+  }
+  return kind === "image" ? "image/jpeg" : "video/mp4";
+}
+
+/** The host class a kind's feed fetch draws on (re-exported for the service). */
+export function feedHostClassFor(kind: IntakeKind): string {
+  return HOST_CLASS_BY_KIND[kind];
+}
diff --git a/apps/api/src/live-chat/adapters.test.ts b/apps/api/src/live-chat/adapters.test.ts
new file mode 100644
index 0000000..4de36ef
--- /dev/null
+++ b/apps/api/src/live-chat/adapters.test.ts
@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createMockLivestreamConnector } from "@tactical-media-broadcast-hub/connector-mock-livestream";
+import { TwitchChatTransport, twitchToEvent } from "./twitch-adapter.js";
+import { SharedChatPollers } from "./shared-poller.js";
+import { SendGovernors } from "./governors.js";
+import { LiveChatHubService } from "./live-chat.service.js";
+
+afterEach(() => vi.useRealTimers());
+describe("Twitch adapter with injected Helix", () => {
+  it("maps the existing connector event and preserves reply/moderation arguments", async () => {
+    const ws = randomUUID(), channelId = randomUUID(), connectionId = randomUUID();
+    const options = { workspaceId: ws, channelId, connectionId, liveRemoteId: "remote" };
+    expect(twitchToEvent(options, { id: "provider-msg", provider: "twitch", liveStreamId: "remote", authorHandle: "viewer", text: "hi", sentAt: new Date(0), isModerated: false })).toMatchObject({ channelId, connectionId, providerMessageId: "provider-msg", author: { handle: "viewer" } });
+    const helix = { send: vi.fn(async (_request: unknown) => ({ providerMessageId: "sent", sentAt: new Date(1) })), moderate: vi.fn(async (_request: unknown) => undefined) };
+    const transport = new TwitchChatTransport(createMockLivestreamConnector(), helix);
+    await expect(transport.send({ connectionId, liveRemoteId: "remote", text: "reply", replyTo: "provider-msg" })).resolves.toMatchObject({ providerMessageId: "sent" });
+    expect(helix.send).toHaveBeenCalledWith({ connectionId, liveRemoteId: "remote", text: "reply", replyTo: "provider-msg" });
+    await transport.moderate({ connectionId, liveRemoteId: "remote", messageRemoteId: "provider-msg", authorHandle: "viewer", action: "timeout", durationSeconds: 600 });
+    expect(helix.moderate).toHaveBeenCalledWith(expect.objectContaining({ action: "timeout", durationSeconds: 600, authorHandle: "viewer" }));
+  });
+});
+describe("shared provider long poll", () => {
+  it("shares one poll chain, charges list=1, and honors pollingIntervalMillis and cursor", async () => {
+    vi.useFakeTimers();
+    const pollers = new SharedChatPollers(), fetch = vi.fn(async (_cursor?: string) => ({ events: [], nextPageToken: "next", pollingIntervalMillis: 5000 })), ingest = vi.fn(async () => ({ inserted: [], duplicates: [] }));
+    const governors = new SendGovernors({ quotas: { youtube: { budget: 100, costPerCall: 50 } } });
+    const options = { workspaceId: "ws", broadcastId: "live", provider: "youtube", fetch, ingest, governors };
+    const one = pollers.acquire(options), two = pollers.acquire(options);
+    await vi.advanceTimersByTimeAsync(0); expect(fetch).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(4999); expect(fetch).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(1); expect(fetch).toHaveBeenCalledTimes(2); expect(fetch).toHaveBeenLastCalledWith("next");
+    expect(governors.take("youtube").allowed).toBe(true); // two list units leave 98 units for a 50-unit send
+    one(); two(); await vi.advanceTimersByTimeAsync(10000); expect(fetch).toHaveBeenCalledTimes(2); pollers.close();
+  });
+  it("never polls below quota and exposes paused reason", async () => {
+    vi.useFakeTimers(); const fetch = vi.fn(), paused = vi.fn(), pollers = new SharedChatPollers();
+    const release = pollers.acquire({ workspaceId: "ws", broadcastId: "live", provider: "youtube", fetch, paused, ingest: async () => ({ inserted: [], duplicates: [] }), governors: new SendGovernors({ quotas: { youtube: { budget: 0 } } }) });
+    await vi.advanceTimersByTimeAsync(0); expect(fetch).not.toHaveBeenCalled(); expect(paused).toHaveBeenCalledWith("daily quota exhausted"); release();
+  });
+});
+describe("hub display filters", () => {
+  it("applies commands, bots, muted provider handles and words before sequencing", async () => {
+    const transaction = vi.fn();
+    const hub = new LiveChatHubService({ transaction, filters: { hideCommands: true, hideBots: true, mutedHandles: ["mock-livestream:muted"], words: ["blocked"] } });
+    const base = { provider: "mock-livestream", connectionId: "connection", channelId: "channel", providerMessageId: "msg", author: { handle: "viewer" }, text: "hi", sentAt: new Date() };
+    expect(await hub.ingest("ws", [{ ...base, text: "!command" }, { ...base, author: { handle: "bot", isBot: true } }, { ...base, author: { handle: "muted" } }, { ...base, text: "BLOCKED word" }])).toEqual({ inserted: [], duplicates: [] });
+    expect(transaction).not.toHaveBeenCalled();
+  });
+});
+
+describe("registry capability probing and comments fallback", () => {
+  it("degrades to read-only embed, then labelled comments, without claiming XMPP support", async () => {
+    const { probeChatCapability } = await import("./capability-probe.js");
+    const { MockLivestreamDriver } = await import("./mock-driver.js");
+    const connector = createMockLivestreamConnector(), manifest = connector.manifest();
+    connector.manifest = () => ({ ...manifest, capabilities: { ...manifest.capabilities, liveChatRead: false, comments: true } });
+    connector.getComments = async () => ({ items: [{ id: "comment", provider: manifest.id, remoteId: "comment", onRemoteId: "live", authorHandle: "viewer", text: "comment text", createdAt: new Date(0) }] });
+    const connection = { id: randomUUID(), workspaceId: randomUUID(), provider: manifest.id, channelId: "remote", credentialId: { kind: "credential-ref" as const, id: "ref" }, fields: {}, createdAt: new Date() };
+    expect(probeChatCapability(connector, connection, "https://chat.example/embed")).toMatchObject({ mode: "readonly-embed", capability: { reply: false, moderate: false } });
+    expect(probeChatCapability(connector, connection)).toMatchObject({ mode: "comments-only", capability: { read: true, state: "degraded", reason: "comments only" } });
+    const driver = new MockLivestreamDriver(connector, { workspaceId: connection.workspaceId, channelId: "live", connectionId: connection.id, liveRemoteId: "live", connection, commentsOnly: true });
+    const ingest = vi.fn(async () => ({ inserted: [], duplicates: [] }));
+    await driver.start(ingest); expect(ingest).toHaveBeenCalledWith(connection.workspaceId, [expect.objectContaining({ source: "social-reply", text: "comment text" })]); await driver.stop();
+  });
+});
diff --git a/apps/api/src/live-chat/auth.ts b/apps/api/src/live-chat/auth.ts
new file mode 100644
index 0000000..740f907
--- /dev/null
+++ b/apps/api/src/live-chat/auth.ts
@@ -0,0 +1,37 @@
+import type { PoolClient } from "pg";
+import { verifyDeviceToken } from "./devices.js";
+import { verifySession, type SessionPayload } from "../auth/session.js";
+import { isUuid } from "../http/validation.js";
+
+export function chatSession(token: string): SessionPayload | null { try { return verifySession(token); } catch { return null; } }
+
+export function tokenWorkspace(token: string): string | null {
+  return chatSession(token)?.workspaceId ?? verifyDeviceToken(token)?.workspaceId ?? null;
+}
+/** Current membership and workspace epoch always fence both credential kinds. */
+export async function authorizeChat(client: PoolClient, token: string, workspaceId: string, permission: string): Promise<SessionPayload | null> {
+  const session = chatSession(token);
+  const device = session ? null : verifyDeviceToken(token);
+  const principal = session ?? device;
+  if (!principal || principal.workspaceId !== workspaceId || !isUuid(workspaceId) || !isUuid(principal.userId)) return null;
+  await client.query("BEGIN");
+  try {
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const member = await client.query<{ role: string; authz_epoch: string | number }>(
+      `SELECT m.role, w.authz_epoch FROM memberships m JOIN workspaces w ON w.id=m.workspace_id
+       JOIN role_permissions rp ON rp.role=m.role AND rp.permission=$3
+       WHERE m.workspace_id=$1 AND m.user_id=$2 AND m.status='active'`, [workspaceId, principal.userId, permission]);
+    const row = member.rows[0];
+    if (!row || !Number.isSafeInteger(Number(row.authz_epoch))) return null;
+    if (session && session.authzEpoch !== Number(row.authz_epoch)) return null;
+    if (device) {
+      if (!device.scopes.includes(permission)) return null;
+      const found = await client.query<{ epoch: string | number; scopes: string[]; authz_epoch: string | number }>(
+        "SELECT epoch, scopes, authz_epoch FROM devices WHERE workspace_id=$1 AND id=$2 AND user_id=$3 AND revoked_at IS NULL",
+        [workspaceId, device.deviceId, device.userId]);
+      const stored = found.rows[0];
+      if (!stored || Number(stored.epoch) !== device.epoch || Number(stored.authz_epoch) !== Number(row.authz_epoch) || !stored.scopes.includes(permission)) return null;
+    }
+    return { userId: principal.userId, workspaceId, role: row.role, authzEpoch: Number(row.authz_epoch), issuedAt: principal.issuedAt, expiresAt: principal.expiresAt };
+  } finally { await client.query("ROLLBACK"); }
+}
diff --git a/apps/api/src/live-chat/bridge.ts b/apps/api/src/live-chat/bridge.ts
new file mode 100644
index 0000000..ec72eed
--- /dev/null
+++ b/apps/api/src/live-chat/bridge.ts
@@ -0,0 +1,29 @@
+import { Injectable, Inject, Optional, OnModuleDestroy } from "@nestjs/common";
+import { RespControlRedis, type ControlRedis } from "../media-control/redis.js";
+import type { LiveChatPublish } from "./live-chat.service.js";
+
+export const CHAT_SINK = Symbol("CHAT_SINK");
+export type ChatSink = LiveChatPublish;
+export const chatTopic = (workspaceId: string, liveId: string): string => `chat:${workspaceId}:${liveId}`;
+export const chatWindowKey = (workspaceId: string, liveId: string): string => `${chatTopic(workspaceId, liveId)}:window`;
+// Atomic durable resume window + notification. Scores preserve hub ingress order.
+export const CHAT_PUBLISH_SCRIPT = `
+redis.call('ZADD', KEYS[1], ARGV[1], ARGV[2])
+local count = redis.call('ZCARD', KEYS[1])
+if count > 500 then redis.call('ZREMRANGEBYRANK', KEYS[1], 0, count - 501) end
+redis.call('EXPIRE', KEYS[1], 86400)
+return redis.call('PUBLISH', KEYS[2], ARGV[2])`;
+export const CHAT_WINDOW_SCRIPT = `return redis.call('ZRANGE', KEYS[1], 0, -1)`;
+
+@Injectable()
+export class ChatRealtimeBridge implements OnModuleDestroy {
+  private readonly redis: ControlRedis;
+  constructor(@Optional() @Inject(CHAT_SINK) private readonly sink?: ChatSink, redis?: ControlRedis) {
+    this.redis = redis ?? new RespControlRedis(process.env.REDIS_URL ?? "redis://localhost:6379");
+  }
+  publish: LiveChatPublish = async (workspaceId, channelId, frame): Promise<void> => {
+    if (this.sink) { await this.sink(workspaceId, channelId, frame); return; }
+    await this.redis.eval(CHAT_PUBLISH_SCRIPT, [chatWindowKey(workspaceId, channelId), chatTopic(workspaceId, channelId)], [String(frame.seq), JSON.stringify(frame)]);
+  };
+  onModuleDestroy(): void { this.redis.close(); }
+}
diff --git a/apps/api/src/live-chat/capability-probe.ts b/apps/api/src/live-chat/capability-probe.ts
new file mode 100644
index 0000000..bbf32b3
--- /dev/null
+++ b/apps/api/src/live-chat/capability-probe.ts
@@ -0,0 +1,22 @@
+import type { ConnectorConnection, LiveChatCapability } from "@tactical-media-broadcast-hub/core";
+import type { PlatformConnector } from "@tactical-media-broadcast-hub/connector-sdk";
+
+export interface ChatCapabilityProbe {
+  capability: LiveChatCapability;
+  mode: "native" | "readonly-embed" | "comments-only" | "none";
+  embedUrl?: string;
+}
+/** Registry-based probing covers PeerTube degradation without provider branches.
+ * XMPP is intentionally reserved for a later registered native adapter. */
+export function probeChatCapability(connector: PlatformConnector, connection: ConnectorConnection, embedUrl?: string): ChatCapabilityProbe {
+  const manifest = connector.manifest(), caps = manifest.capabilities;
+  const base = { connectionId: connection.id, provider: manifest.id };
+  if (caps.liveChatRead && connector.getLiveChat) return { mode: "native", capability: { ...base, read: true, reply: Boolean(caps.liveChatWrite && connector.sendLiveChatMessage), moderate: Boolean(caps.liveChatModeration && connector.moderateLiveChat), state: "ok" } };
+  if (embedUrl) {
+    const url = new URL(embedUrl);
+    if (url.protocol !== "https:") throw new Error("read-only chat embed must use HTTPS");
+    return { mode: "readonly-embed", embedUrl, capability: { ...base, read: true, reply: false, moderate: false, state: "degraded", reason: "read-only web embed" } };
+  }
+  if (caps.comments && connector.getComments) return { mode: "comments-only", capability: { ...base, read: true, reply: Boolean(connector.reply), moderate: false, state: "degraded", reason: "comments only" } };
+  return { mode: "none", capability: { ...base, read: false, reply: false, moderate: false, state: "degraded", reason: "chat unavailable" } };
+}
diff --git a/apps/api/src/live-chat/chat-fanout.ts b/apps/api/src/live-chat/chat-fanout.ts
new file mode 100644
index 0000000..ab05e93
--- /dev/null
+++ b/apps/api/src/live-chat/chat-fanout.ts
@@ -0,0 +1,14 @@
+/**
+ * Gateway-side chat sink: lets the live-chat hub push `kind:"chat"` frames to
+ * the /realtime gateway WITHOUT the hub importing the gateway (S3 owns the
+ * gateway; the slice boundary stays clean and no cycle forms).
+ *
+ * The realtime module registers an implementation at bootstrap. Chat frames
+ * ride the same per-channel topic as state events: the same subscribe/ack
+ * handshake, the same bounded resume ring, the same authz eviction. This file
+ * only declares the port.
+ */
+import type { LiveChatPublish } from "../live-chat/live-chat.service.js";
+
+export const CHAT_FANOUT = Symbol("CHAT_FANOUT");
+export type ChatFanout = LiveChatPublish;
diff --git a/apps/api/src/live-chat/devices.test.ts b/apps/api/src/live-chat/devices.test.ts
new file mode 100644
index 0000000..8e8d955
--- /dev/null
+++ b/apps/api/src/live-chat/devices.test.ts
@@ -0,0 +1,69 @@
+import { randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { describe, expect, it } from "vitest";
+import { DEVICE_SCOPES } from "@tactical-media-broadcast-hub/core";
+import { DeviceService, issueDeviceToken, verifyDeviceToken } from "./devices.js";
+import { authorizeChat } from "./auth.js";
+
+const WS = randomUUID(), USER = randomUUID();
+function fixture() {
+  const pairings: Array<{ workspace_id: string; user_id: string; code: string; scopes: string[]; expires_at: Date; redeemed_at: Date | null; device_id: string | null }> = [];
+  const devices = new Map<string, { epoch: number; revoked_at: Date | null }>();
+  let now = Date.now();
+  const client = { query: async (sql: string, args: unknown[]) => {
+    if (sql.includes("INSERT INTO device_pairings")) {
+      pairings.push({ workspace_id: String(args[0]), user_id: String(args[1]), code: String(args[2]), scopes: args[5] as string[], expires_at: args[4] as Date, redeemed_at: null, device_id: null }); return { rows: [], rowCount: 1 };
+    }
+    if (sql.includes("SELECT * FROM device_pairings")) return { rows: pairings.filter(row => row.workspace_id === args[0] && row.code === args[1]) };
+    if (sql.includes("INSERT INTO devices")) { const id = randomUUID(); devices.set(id, { epoch: 1, revoked_at: null }); return { rows: [{ id }] }; }
+    if (sql.includes("UPDATE device_pairings")) { const row = pairings.find(row => row.code === args[1]); if (row) { row.redeemed_at = new Date(now); row.device_id = String(args[2]); } return { rows: [] }; }
+    if (sql.includes("UPDATE devices")) { const row = devices.get(String(args[1])); if (!row || row.revoked_at) return { rows: [], rowCount: 0 }; row.epoch += 1; row.revoked_at = new Date(now); return { rows: [row], rowCount: 1 }; }
+    if (sql.includes("SELECT epoch")) { const row = devices.get(String(args[1])); return { rows: row ? [row] : [] }; }
+    throw new Error(`unexpected device SQL: ${sql}`);
+  } } as unknown as PoolClient;
+  let pending = Promise.resolve();
+  const service = new DeviceService({ serverUrl: "https://studio.example", now: () => new Date(now), transaction: async (_ws, fn) => {
+    const previous = pending; let release: () => void = () => undefined;
+    pending = new Promise<void>(resolve => { release = resolve; }); await previous;
+    try { return await fn(client); } finally { release(); }
+  } });
+  return { service, advance: (ms: number) => { now += ms; } };
+}
+describe("device pairing and revocation", () => {
+  it("code → signed scoped token, wrong workspace rejected, single-use code, revoke fences epoch", async () => {
+    const f = fixture(), issued = await f.service.issuePairing(WS, USER);
+    expect(JSON.parse(issued.qrPayload)).toEqual({ serverUrl: "https://studio.example", pairingCode: issued.pairingCode });
+    await expect(f.service.redeem(randomUUID(), issued.pairingCode, "phone")).rejects.toThrow("invalid pairing code");
+    const result = await f.service.redeem(WS, issued.pairingCode, "phone");
+    const claims = verifyDeviceToken(result.deviceToken);
+    expect(claims).toMatchObject({ workspaceId: WS, userId: USER, scopes: [...DEVICE_SCOPES], epoch: 1 });
+    if (!claims) throw new Error("missing token claims");
+    expect(await f.service.epochOf(WS, claims.deviceId)).toBe(1);
+    await expect(f.service.redeem(WS, issued.pairingCode, "other")).rejects.toThrow("already redeemed");
+    await f.service.revoke(WS, claims.deviceId); expect(await f.service.epochOf(WS, claims.deviceId)).toBeNull();
+  });
+  it("expires at five minutes, including the boundary", async () => {
+    const f = fixture(), issued = await f.service.issuePairing(WS, USER);
+    f.advance(300000); await expect(f.service.redeem(WS, issued.pairingCode, "phone")).rejects.toThrow("expired");
+  });
+  it("only one concurrent redemption succeeds", async () => {
+    const f = fixture(), issued = await f.service.issuePairing(WS, USER);
+    const results = await Promise.allSettled([f.service.redeem(WS, issued.pairingCode, "one"), f.service.redeem(WS, issued.pairingCode, "two")]);
+    expect(results.filter(result => result.status === "fulfilled")).toHaveLength(1);
+  });
+  it("rejects tampering, expired tokens, and malformed signed claims", () => {
+    const token = issueDeviceToken({ deviceId: randomUUID(), workspaceId: WS, userId: USER, scopes: [...DEVICE_SCOPES], epoch: 1 });
+    expect(verifyDeviceToken(`${token}x`)).toBeNull();
+    expect(verifyDeviceToken(issueDeviceToken({ deviceId: randomUUID(), workspaceId: WS, userId: USER, scopes: [...DEVICE_SCOPES], epoch: 1 }, -1))).toBeNull();
+    expect(verifyDeviceToken(issueDeviceToken({ deviceId: "bad", workspaceId: WS, userId: USER, scopes: [...DEVICE_SCOPES], epoch: 1 }))).toBeNull();
+  });
+  it("auth checks device epoch, current membership/scopes, and the workspace role epoch", async () => {
+    const deviceId = randomUUID(), token = issueDeviceToken({ deviceId, workspaceId: WS, userId: USER, scopes: [...DEVICE_SCOPES], epoch: 1 });
+    let deviceEpoch = 1, workspaceEpoch = 7, active = true;
+    const client = { query: async (sql: string) => ({ rows: sql.includes("FROM memberships") ? (active ? [{ role: "Operator", authz_epoch: workspaceEpoch }] : []) : sql.includes("FROM devices") ? [{ epoch: deviceEpoch, scopes: [...DEVICE_SCOPES], authz_epoch: 7 }] : [] }) } as unknown as PoolClient;
+    expect(await authorizeChat(client, token, WS, "livechat.view")).toMatchObject({ userId: USER });
+    deviceEpoch += 1; expect(await authorizeChat(client, token, WS, "livechat.view")).toBeNull();
+    deviceEpoch = 1; workspaceEpoch += 1; expect(await authorizeChat(client, token, WS, "livechat.view")).toBeNull();
+    workspaceEpoch = 7; active = false; expect(await authorizeChat(client, token, WS, "livechat.view")).toBeNull();
+  });
+});
diff --git a/apps/api/src/live-chat/devices.ts b/apps/api/src/live-chat/devices.ts
new file mode 100644
index 0000000..994e894
--- /dev/null
+++ b/apps/api/src/live-chat/devices.ts
@@ -0,0 +1,180 @@
+/**
+ * Device pairing (§3.4): the web UI mints a single-use, TTL'd code; the app
+ * redeems it for an epoch-gated device token bound to (workspace, user).
+ *
+ * Tokens use a separate HMAC domain and current device/workspace epochs fence
+ * every REST request and active socket. Pairing codes expire after five minutes.
+ */
+import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { Injectable, Inject, Optional, UnauthorizedException, NotFoundException, ConflictException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import type { DeviceTokenPayload } from "@tactical-media-broadcast-hub/core";
+import { idempotentChat } from "./idempotency.js";
+import { pool, withTenant } from "../db/client.js";
+import { isUuid } from "../http/validation.js";
+import { DEVICE_SCOPES } from "@tactical-media-broadcast-hub/core";
+
+export const DEVICE_DEPENDENCIES = Symbol("DEVICE_DEPENDENCIES");
+
+export interface DeviceTransaction {
+  <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T>;
+}
+
+export interface DeviceDependencies {
+  transaction: DeviceTransaction;
+  now?: () => Date;
+  /** TTL of an unredeemed pairing code, ms (default 5 min, §3.4). */
+  pairingTtlMs?: number;
+  /** Lifetime of a device token, seconds (default 30 days). */
+  tokenTtlSeconds?: number;
+  /** Base URL the QR payload points at. */
+  serverUrl?: string;
+  lookupWorkspace?: (code: string) => Promise<string | null>;
+}
+
+export interface PairingIssued {
+  pairingCode: string;
+  qrPayload: string;
+  expiresAt: string;
+}
+
+export interface RedeemResult {
+  deviceToken: string;
+  workspaceId: string;
+}
+
+interface PairingRow {
+  id: string; workspace_id: string; user_id: string; code: string; qr_payload: string;
+  scopes: string[]; expires_at: Date; redeemed_at: Date | null; device_id: string | null;
+}
+
+function pairingCode(): string {
+  const alphabet = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+  const group = (): string => Array.from(randomBytes(4), b => alphabet[b % alphabet.length]).join("");
+  return `${group()}-${group()}`;
+}
+
+function deviceSecret(): string {
+  const s = process.env.SESSION_SECRET;
+  if (s !== undefined && s !== "") return s;
+  if (process.env.NODE_ENV === "production") throw new Error("SESSION_SECRET required in production");
+  return "dev-session-secret";
+}
+
+function sign(body: string): string {
+  return createHmac("sha256", `${deviceSecret()}:device-v1`).update(body).digest("base64url");
+}
+
+export function issueDeviceToken(payload: Omit<DeviceTokenPayload, "issuedAt" | "expiresAt">, ttlSeconds = 30 * 24 * 3600): string {
+  const full: DeviceTokenPayload = { ...payload, issuedAt: Math.floor(Date.now() / 1000), expiresAt: Math.floor(Date.now() / 1000) + ttlSeconds };
+  const body = Buffer.from(JSON.stringify(full)).toString("base64url");
+  return `${body}.${sign(body)}`;
+}
+
+export function verifyDeviceToken(token: string): DeviceTokenPayload | null {
+  const dot = token.lastIndexOf(".");
+  if (dot === -1) return null;
+  const body = token.slice(0, dot);
+  const mac = token.slice(dot + 1);
+  const expected = sign(body);
+  if (Buffer.byteLength(mac) !== Buffer.byteLength(expected) || !timingSafeEqual(Buffer.from(mac), Buffer.from(expected))) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(body, "base64url").toString("utf-8")) as DeviceTokenPayload;
+    if (!isUuid(payload.deviceId) || !isUuid(payload.workspaceId) || !isUuid(payload.userId) ||
+      !Number.isSafeInteger(payload.epoch) || payload.epoch < 1 || !Number.isSafeInteger(payload.expiresAt) ||
+      payload.expiresAt <= Math.floor(Date.now() / 1000) || !Array.isArray(payload.scopes) ||
+      !payload.scopes.every(scope => typeof scope === "string" && DEVICE_SCOPES.some(allowed => allowed === scope))) return null;
+    return payload;
+  } catch { return null; }
+}
+
+@Injectable()
+export class DeviceService {
+  private readonly deps: Required<Omit<DeviceDependencies, "now">> & { now: () => Date };
+  constructor(@Optional() @Inject(DEVICE_DEPENDENCIES) dependencies?: DeviceDependencies) {
+    const now = dependencies?.now ?? (() => new Date());
+    this.deps = {
+      transaction: dependencies?.transaction ?? withTenant,
+      pairingTtlMs: dependencies?.pairingTtlMs ?? 5 * 60 * 1000,
+      tokenTtlSeconds: dependencies?.tokenTtlSeconds ?? 30 * 24 * 3600,
+      serverUrl: dependencies?.serverUrl ?? process.env.PUBLIC_ORIGIN ?? "",
+      lookupWorkspace: dependencies?.lookupWorkspace ?? (async code => {
+        const lookup = await pool.query<{ workspace_id: string }>("SELECT device_pairing_workspace($1) AS workspace_id", [code]);
+        return lookup.rows[0]?.workspace_id ?? null;
+      }),
+      now,
+    };
+  }
+
+  /** Mint a pairing code for (workspace, user). TTL 5 minutes, single use. */
+  async issuePairing(workspaceId: string, userId: string, scopes: readonly string[] = DEVICE_SCOPES): Promise<PairingIssued> {
+    if (!scopes.every(scope => DEVICE_SCOPES.some(allowed => allowed === scope))) throw new UnauthorizedException("invalid device scopes");
+    const code = pairingCode();
+    const expiresAt = new Date(this.deps.now().getTime() + this.deps.pairingTtlMs);
+    const qrPayload = JSON.stringify({ serverUrl: this.deps.serverUrl, pairingCode: code });
+    await this.deps.transaction(workspaceId, async client => {
+      await client.query(
+        `INSERT INTO device_pairings (workspace_id, user_id, code, qr_payload, expires_at, scopes) VALUES ($1,$2,$3,$4,$5,$6)`,
+        [workspaceId, userId, code, qrPayload, expiresAt, [...scopes]]);
+    });
+    return { pairingCode: code, qrPayload, expiresAt: expiresAt.toISOString() };
+  }
+
+  async redeemCode(code: string, deviceName: string, key: string | undefined, expectedWorkspace?: string): Promise<RedeemResult> {
+    if (!/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(code)) throw new UnauthorizedException("invalid pairing code");
+    const workspaceId = await this.deps.lookupWorkspace(code);
+    if (!workspaceId || (expectedWorkspace !== undefined && expectedWorkspace !== workspaceId)) throw new UnauthorizedException("invalid pairing code");
+    const owner = await this.deps.transaction(workspaceId, async client => {
+      const result = await client.query<{ user_id: string }>("SELECT user_id FROM device_pairings WHERE workspace_id=$1 AND code=$2", [workspaceId, code]);
+      return result.rows[0]?.user_id;
+    });
+    if (!owner) throw new UnauthorizedException("invalid pairing code");
+    return idempotentChat(this.deps.transaction, workspaceId, owner, `redeem:${createHash("sha256").update(code).digest("hex")}`, key, { deviceName }, () => this.redeem(workspaceId, code, deviceName));
+  }
+
+  /** Redeem within an explicit tenant, rejecting codes from other workspaces. */
+  async redeem(workspaceId: string, code: string, deviceName: string): Promise<RedeemResult> {
+    if (!/^[A-Z0-9]{4}-[A-Z0-9]{4}$/.test(code)) throw new UnauthorizedException("invalid pairing code");
+    return this.deps.transaction(workspaceId, async client => {
+      const found = await client.query<PairingRow>(
+        `SELECT * FROM device_pairings WHERE workspace_id=$1 AND code=$2 FOR UPDATE`, [workspaceId, code]);
+      const row = found.rows[0];
+      if (!row) throw new UnauthorizedException("invalid pairing code");
+      if (row.redeemed_at !== null) throw new ConflictException("pairing code already redeemed");
+      if (row.expires_at.getTime() <= this.deps.now().getTime()) throw new UnauthorizedException("pairing code expired");
+      const device = await client.query<{ id: string }>(
+        `INSERT INTO devices (workspace_id, user_id, name, scopes, authz_epoch) SELECT $1,$2,$3,$4,authz_epoch FROM workspaces WHERE id=$1 RETURNING id`,
+        [workspaceId, row.user_id, deviceName, row.scopes]);
+      const deviceId = device.rows[0]?.id;
+      if (!deviceId) throw new UnauthorizedException("pairing workspace no longer exists");
+      await client.query(`UPDATE device_pairings SET redeemed_at = now(), device_id = $3 WHERE workspace_id=$1 AND code=$2`,
+        [workspaceId, code, deviceId]);
+      const token = issueDeviceToken({ deviceId, workspaceId, userId: row.user_id, scopes: row.scopes, epoch: 1 }, this.deps.tokenTtlSeconds);
+      return { deviceToken: token, workspaceId };
+    });
+  }
+
+  /** Revoke: bumps the epoch, so every outstanding token fails closed. */
+  async revoke(workspaceId: string, deviceId: string): Promise<void> {
+    const result = await this.deps.transaction(workspaceId, async client => {
+      const updated = await client.query<{ epoch: string | number }>(
+        `UPDATE devices SET revoked_at = now(), epoch = epoch + 1 WHERE workspace_id=$1 AND id=$2 AND revoked_at IS NULL RETURNING epoch`,
+        [workspaceId, deviceId]);
+      return updated.rowCount ?? 0;
+    });
+    if (result === 0) throw new NotFoundException("device not found or already revoked");
+  }
+
+  /** Epoch check for a presented device token. */
+  async epochOf(workspaceId: string, deviceId: string): Promise<number | null> {
+    return this.deps.transaction(workspaceId, async client => {
+      const row = await client.query<{ epoch: string | number; revoked_at: Date | null }>(
+        `SELECT epoch, revoked_at FROM devices WHERE workspace_id=$1 AND id=$2`, [workspaceId, deviceId]);
+      const found = row.rows[0];
+      if (!found || found.revoked_at !== null) return null;
+      return Number(found.epoch);
+    });
+  }
+}
+
+export const deviceTokenFingerprint = (token: string): string => createHash("sha256").update(token).digest("hex").slice(0, 16);
diff --git a/apps/api/src/live-chat/governors.ts b/apps/api/src/live-chat/governors.ts
new file mode 100644
index 0000000..2c7387a
--- /dev/null
+++ b/apps/api/src/live-chat/governors.ts
@@ -0,0 +1,102 @@
+/**
+ * Send governors (§3.2): per-provider token buckets in front of every
+ * outbound chat call, plus a YouTube-style daily quota ledger.
+ *
+ * A send below budget is REFUSED with a paused reason — it never queues and
+ * never throws, so a fan-out keeps going for the targets that still have
+ * budget (§3.5 "an incapable target is refused with its reason").
+ */
+export interface GovernorVerdict {
+  allowed: boolean;
+  /** Present only when refused. */
+  reason?: string;
+  state?: "ok" | "paused:rate" | "paused:quota" | "degraded";
+}
+
+export interface TokenBucketOptions {
+  /** Burst capacity (tokens). */
+  capacity: number;
+  /** Refill per second. */
+  refillPerSecond: number;
+  /** Virtual clock, overridable in tests. */
+  now?: () => number;
+}
+
+/** Classic token bucket: `capacity` burst, continuous refill. */
+export class TokenBucket {
+  private tokens: number;
+  private last: number;
+  constructor(private readonly options: TokenBucketOptions) {
+    if (!Number.isInteger(options.capacity) || options.capacity < 1) throw new Error("capacity must be a positive integer");
+    if (!(options.refillPerSecond > 0)) throw new Error("refillPerSecond must be positive");
+    this.tokens = options.capacity;
+    this.last = options.now?.() ?? Date.now();
+  }
+  /** Peek without consuming. */
+  available(): number { this.refill(); return this.tokens; }
+  /** Try to consume one token. */
+  tryTake(): boolean { this.refill(); if (this.tokens < 1) return false; this.tokens -= 1; return true; }
+  private refill(): void {
+    const now = this.options.now?.() ?? Date.now();
+    const elapsed = (now - this.last) / 1000;
+    if (elapsed > 0) { this.tokens = Math.min(this.options.capacity, this.tokens + elapsed * this.options.refillPerSecond); this.last = now; }
+  }
+}
+
+/** Daily unit ledger (YouTube quota: list=1, insert/delete/ban=50, 10 000/day). */
+export class QuotaLedger {
+  private spent = 0;
+  private day: string;
+  constructor(private readonly dailyBudget: number, private readonly costPerCall = 1, private readonly now: () => number = Date.now) {
+    this.day = this.currentDay();
+    if (!Number.isFinite(dailyBudget) || dailyBudget < 0 || !Number.isFinite(costPerCall) || costPerCall < 0) throw new Error("invalid quota budget/cost");
+  }
+  private currentDay(): string { return new Date(this.now()).toISOString().slice(0, 10); }
+  private reset(): void { const day = this.currentDay(); if (day !== this.day) { this.spent = 0; this.day = day; } }
+  get used(): number { this.reset(); return this.spent; }
+  get budget(): number { return this.dailyBudget; }
+  canAfford(cost = this.costPerCall): boolean { this.reset(); return Number.isFinite(cost) && cost >= 0 && this.spent + cost <= this.dailyBudget; }
+  /** Record a spend; returns false (and records nothing) when over budget. */
+  charge(cost = this.costPerCall): boolean {
+    if (!this.canAfford(cost)) return false;
+    this.spent += cost;
+    return true;
+  }
+}
+
+export interface SendGovernorOptions {
+  /** Tokens per provider key, e.g. `twitch`, `youtube`, `mock-livestream`. */
+  buckets?: Record<string, TokenBucketOptions>;
+  /** Daily unit budgets per provider key (quota ledger). */
+  quotas?: Record<string, { budget: number; costPerCall?: number }>;
+  now?: () => number;
+}
+
+/** Per-provider send governor: token bucket + optional daily quota. */
+export class SendGovernors {
+  private readonly buckets = new Map<string, TokenBucket>();
+  private readonly quotas = new Map<string, QuotaLedger>();
+  constructor(options: SendGovernorOptions = {}) {
+    for (const [key, bucket] of Object.entries(options.buckets ?? {})) this.buckets.set(key, new TokenBucket({ ...bucket, now: bucket.now ?? options.now }));
+    for (const [key, quota] of Object.entries(options.quotas ?? {})) this.quotas.set(key, new QuotaLedger(quota.budget, quota.costPerCall ?? 1, options.now));
+  }
+  /** Probe a provider's outbound capacity without consuming anything. */
+  probe(provider: string): GovernorVerdict {
+    const quota = this.quotas.get(provider);
+    if (quota && !quota.canAfford()) return { allowed: false, reason: "daily quota exhausted", state: "paused:quota" };
+    const bucket = this.buckets.get(provider);
+    if (bucket && bucket.available() < 1) return { allowed: false, reason: "send rate budget exhausted", state: "paused:rate" };
+    return { allowed: true, state: "ok" };
+  }
+  /** Consume one send's worth of budget for `provider`. */
+  take(provider: string, cost?: number): GovernorVerdict {
+    const quota = this.quotas.get(provider);
+    if (quota && !quota.canAfford(cost)) return { allowed: false, reason: "daily quota exhausted", state: "paused:quota" };
+    const bucket = this.buckets.get(provider);
+    if (bucket && !bucket.tryTake()) return { allowed: false, reason: "send rate budget exhausted", state: "paused:rate" };
+    if (quota) quota.charge(cost);
+    return { allowed: true, state: "ok" };
+  }
+  /** A provider with no configured governor is unlimited (mock, local hubs). */
+  configured(provider: string): boolean { return this.buckets.has(provider) || this.quotas.has(provider); }
+}
diff --git a/apps/api/src/live-chat/hub.test.ts b/apps/api/src/live-chat/hub.test.ts
new file mode 100644
index 0000000..a9fae71
--- /dev/null
+++ b/apps/api/src/live-chat/hub.test.ts
@@ -0,0 +1,439 @@
+import type { PoolClient } from "pg";
+import { randomUUID } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import { ChatRingBuffer } from "./ring-buffer.js";
+import { SendGovernors } from "./governors.js";
+import { Duplex } from "node:stream";
+import type { Socket } from "node:net";
+import { createMockLivestreamConnector } from "@tactical-media-broadcast-hub/connector-mock-livestream";
+import { RealtimeService } from "../realtime/realtime.service.js";
+import { RealtimeSocket } from "../realtime/websocket.js";
+import { RespRedisSubscriptions } from "../realtime/subscribe.js";
+import { encode, parse, type ControlRedis } from "../media-control/redis.js";
+import { MediaControlService } from "../media-control/media-control.service.js";
+import { ChatRealtimeBridge, CHAT_PUBLISH_SCRIPT } from "./bridge.js";
+import { MockLivestreamDriver } from "./mock-driver.js";
+import { issueSession } from "../auth/session.js";
+import { LiveChatHubService, type LiveChatPublish } from "./live-chat.service.js";
+import type { ChatTarget, ChatTransport, NormalizedChatEvent } from "./types.js";
+
+const WS = randomUUID(), CH = randomUUID();
+
+/**
+ * SQL-semantics fake for the hub's three statements:
+ *   - live_chat_seq: FOR UPDATE serializes per (workspace, channel); the
+ *     create-or-lock pattern runs exactly as written in the service.
+ *   - live_chat_messages: UNIQUE(workspace_id, provider, provider_msg_id)
+ *     turns a replay into a no-op that returns nothing.
+ *   - cursor paging: seq > after ORDER BY seq ASC LIMIT n.
+ * The fake implements the CONSTRAINTS, not the text — the live-DB variant of
+ * these tests is live-chat.integration.test.ts.
+ */
+class SqlFake {
+  readonly messages: Array<Record<string, unknown> & { workspace_id: string; channel_id: string; seq: number; provider: string; provider_msg_id: string }> = [];
+  readonly seen = new Set<string>();
+  readonly seqRows = new Map<string, number>();
+  readonly locks = new Map<string, Promise<unknown>>();
+  readonly moderated: string[] = [];
+
+  async transaction<T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const key = workspaceId; // one lock per workspace fakes the row lock
+    const prior = [...this.locks.values()];
+    let unlock: () => void = () => undefined;
+    const gate = new Promise<void>(resolve => { unlock = resolve; });
+    this.locks.set(key, gate);
+    await Promise.all(prior);
+    try { return await fn(new Client(this) as unknown as PoolClient); } finally { unlock(); this.locks.delete(key); }
+  }
+}
+
+class Client {
+  constructor(private readonly db: SqlFake) {}
+  async query(sql: string, params: unknown[]): Promise<{ rows: Array<Record<string, unknown>>; rowCount: number }> {
+    if (sql.includes("INSERT INTO live_chat_seen_events")) {
+      const key = JSON.stringify(params);
+      if (this.db.seen.has(key)) return { rows: [], rowCount: 0 };
+      this.db.seen.add(key); return { rows: [{ provider_event_id: params[2] }], rowCount: 1 };
+    }
+    if (sql.includes("live_chat_seq") && sql.includes("INSERT")) {
+      const ws = String(params[0]), ch = String(params[1]);
+      if (!this.db.seqRows.has(`${ws}:${ch}`)) this.db.seqRows.set(`${ws}:${ch}`, 0);
+      return { rows: [], rowCount: 0 };
+    }
+    if (sql.includes("live_chat_seq") && sql.includes("FOR UPDATE")) {
+      const ws = String(params[0]), ch = String(params[1]);
+      return { rows: [{ seq: this.db.seqRows.get(`${ws}:${ch}`) ?? 0 }], rowCount: 1 };
+    }
+    if (sql.includes("live_chat_seq")) { // the GREATEST update
+      const ws = String(params[0]), ch = String(params[1]), seq = Number(params[2]);
+      const key = `${ws}:${ch}`;
+      this.db.seqRows.set(key, Math.max(this.db.seqRows.get(key) ?? 0, seq));
+      return { rows: [], rowCount: 1 };
+    }
+    if (sql.includes("INSERT INTO live_chat_messages")) {
+      const columns = Array.from({ length: 16 }, (_, i) => params[i] as unknown[]);
+      const inserted: Array<Record<string, unknown>> = [];
+      for (let i = 0; i < (columns[0]?.length ?? 0); i += 1) {
+        const row = {
+          id: randomUUID(), workspace_id: String(columns[0]?.[i]), channel_id: String(columns[1]?.[i]), connection_id: columns[2]?.[i],
+          provider: String(columns[3]?.[i]), provider_msg_id: String(columns[4]?.[i]), author_handle: columns[5]?.[i],
+          author_display_name: columns[6]?.[i], author_avatar_url: columns[7]?.[i], author_badges: JSON.parse(String(columns[8]?.[i])) as unknown,
+          author_color: columns[9]?.[i], body: columns[10]?.[i], reply_to: columns[11]?.[i], seq: Number(columns[12]?.[i]),
+          sent_at: columns[13]?.[i], received_at: columns[14]?.[i], source: columns[15]?.[i], is_moderated: false,
+        };
+        const dup = this.db.messages.some(m => m.workspace_id === row.workspace_id && m.provider === row.provider && m.provider_msg_id === row.provider_msg_id);
+        if (!dup) { this.db.messages.push(row); inserted.push(row); }
+      }
+      return { rows: inserted, rowCount: inserted.length };
+    }
+    if (sql.includes("SELECT") && sql.includes("live_chat_messages") && sql.includes("provider=$5")) {
+      const items = this.db.messages.filter(m => m.workspace_id === params[0] && m.channel_id === params[1] && Number(m.seq) > Number(params[2]) && m.provider === params[4])
+        .sort((a, b) => a.seq - b.seq).slice(0, Number(params[3]));
+      return { rows: items, rowCount: items.length };
+    }
+    if (sql.includes("SELECT") && sql.includes("live_chat_messages")) {
+      const after = sql.includes("id=$3")
+        ? this.db.messages.filter(m => m.workspace_id === params[0] && m.channel_id === params[1] && m.id === params[2])
+        : this.db.messages.filter(m => m.workspace_id === params[0] && m.channel_id === params[1] && Number(m.seq) > Number(params[2]))
+          .sort((a, b) => a.seq - b.seq).slice(0, Number(params[3]));
+      return { rows: after, rowCount: after.length };
+    }
+    if (sql.includes("UPDATE live_chat_messages")) {
+      const [ws, , provider, providerMsgId] = params;
+      let count = 0;
+      for (const m of this.db.messages) {
+        if (m.workspace_id === ws && m.provider === provider && m.provider_msg_id === providerMsgId) { m.is_moderated = true; count += 1; }
+      }
+      return { rows: [], rowCount: count };
+    }
+    throw new Error(`SqlFake: unexpected statement ${sql.slice(0, 60)}`);
+  }
+}
+
+function fixture(options?: {
+  targets?: ChatTarget[]; transports?: Record<string, ChatTransport>; governors?: SendGovernors; capacity?: number; publish?: LiveChatPublish;
+}) {
+  const db = new SqlFake();
+  const buffer = new ChatRingBuffer(options?.capacity ?? 500);
+  const published: Array<{ workspaceId: string; channelId: string; frame: Record<string, unknown> }> = [];
+  const transports = options?.transports ?? {};
+  const targets = options?.targets ?? [];
+  let clock = Date.parse("2026-10-07T10:00:00Z");
+  const hub = new LiveChatHubService({
+    transaction: (workspaceId, fn) => db.transaction(workspaceId, fn),
+    publish: async (workspaceId, channelId, frame) => { published.push({ workspaceId, channelId, frame }); await options?.publish?.(workspaceId, channelId, frame); },
+    buffer,
+    governors: options?.governors ?? new SendGovernors(),
+    targets: async () => targets,
+    transports,
+    now: () => new Date(clock += 7),
+  });
+  return { db, buffer, published, hub, transports, targets };
+}
+
+function event(overrides: Partial<NormalizedChatEvent> = {}): NormalizedChatEvent {
+  return {
+    provider: "mock-livestream", connectionId: "conn-1", channelId: CH, providerMessageId: `pm-${randomUUID().slice(0, 8)}`,
+    author: { handle: "viewer@example" }, text: "hello", sentAt: new Date("2026-10-07T10:00:00Z"), source: "live-chat", ...overrides,
+  };
+}
+
+function target(overrides: Partial<ChatTarget> = {}): ChatTarget {
+  return { connectionId: "conn-1", provider: "mock-livestream", liveRemoteId: "live-1", read: true, reply: true, moderate: true, state: "ok", ...overrides };
+}
+
+describe("ingestion: seq assignment, dedupe, fan-out", () => {
+  it("assigns monotonic per-channel seqs, stores rows, publishes one frame per insert", async () => {
+    const f = fixture();
+    const first = await f.hub.ingest(WS, [event({ text: "one" }), event({ text: "two" })]);
+    expect(first.inserted.map(m => m.seq)).toEqual([1, 2]);
+    expect(first.inserted.map(m => m.text)).toEqual(["one", "two"]);
+    expect(first.duplicates).toEqual([]);
+    expect(f.published).toHaveLength(2);
+    expect(f.published[0]?.frame).toMatchObject({ kind: "chat", seq: 1 });
+    const second = await f.hub.ingest(WS, [event({ text: "three" })]);
+    expect(second.inserted[0]?.seq).toBe(3); // continues the channel sequence
+  });
+
+  it("same provider id ingested twice = one row, one frame, and the replay is reported", async () => {
+    const f = fixture();
+    const original = event({ providerMessageId: "pm-dup" });
+    const first = await f.hub.ingest(WS, [original]);
+    const replay = await f.hub.ingest(WS, [original]);
+    expect(first.inserted).toHaveLength(1);
+    expect(replay.inserted).toHaveLength(0);
+    expect(replay.duplicates).toEqual(["pm-dup"]);
+    expect(f.db.messages).toHaveLength(1);           // one durable row
+    expect(f.published).toHaveLength(1);             // replay publishes nothing
+    expect(f.buffer.latest(CH)).toHaveLength(1);     // and does not enter the window
+  });
+
+  it("dedupe is scoped to (workspace, provider): same id, different provider, both stored", async () => {
+    const f = fixture();
+    await f.hub.ingest(WS, [event({ provider: "twitch", providerMessageId: "shared", connectionId: "conn-tw" })]);
+    const second = await f.hub.ingest(WS, [event({ provider: "youtube", providerMessageId: "shared", connectionId: "conn-yt" })]);
+    expect(second.inserted).toHaveLength(1);
+    expect(f.db.messages).toHaveLength(2);
+  });
+
+  it("cursor paging returns strictly-after rows in seq order and a next cursor", async () => {
+    const f = fixture();
+    await f.hub.ingest(WS, [event(), event(), event(), event(), event()]);
+    const page1 = await f.hub.messages(WS, CH, { limit: 3 });
+    expect(page1.items.map(m => m.seq)).toEqual([1, 2, 3]);
+    expect(page1.nextCursor).toBe(3);
+    const page2 = await f.hub.messages(WS, CH, { after: page1.nextCursor, limit: 3 });
+    expect(page2.items.map(m => m.seq)).toEqual([4, 5]);
+    expect(page2.nextCursor).toBeUndefined();
+  });
+
+  it("resume serves from the window while lastSeq is inside it, resync past its edge", async () => {
+    const f = fixture();
+    for (let i = 0; i < 5; i += 1) await f.hub.ingest(WS, [event()]);
+    const inside = f.hub.resume(CH, 3);
+    expect(inside.resync).toBe(false);
+    expect(inside.messages.map(m => m.seq)).toEqual([4, 5]);
+    expect(f.hub.resume(CH, 0).messages).toHaveLength(5);
+    const small = fixture({ capacity: 4 });
+    for (let i = 0; i < 6; i += 1) await small.hub.ingest(WS, [event()]);
+    expect(small.hub.resume(CH, 1).resync).toBe(true);
+    expect(small.hub.resume(CH, 2).messages.map(m => m.seq)).toEqual([3, 4, 5, 6]);
+  });
+});
+
+describe("system gap notices", () => {
+  it("stores one system notice and emits a distinct chat.gap sequence, deduping repeated gaps", async () => {
+    const f = fixture(), gap = event({ providerMessageId: "disconnect-1" });
+    await f.hub.gap(WS, gap, "provider disconnected");
+    expect(f.db.messages[0]?.source).toBe("system");
+    expect(f.published.at(-1)?.frame).toMatchObject({ seq: 2, provider: "mock-livestream", reason: "provider disconnected" });
+    await f.hub.gap(WS, gap, "provider disconnected"); expect(f.published).toHaveLength(2);
+  });
+});
+
+describe("reply fan-out with per-target Delivery rows", () => {
+  const transportsFor = (send: ChatTransport["send"]): Record<string, ChatTransport> => ({
+    "mock-livestream": { provider: "mock-livestream", send, moderate: async () => undefined },
+  });
+
+  it("fans out to every capable target with one Delivery row each and stores the echo", async () => {
+    const send = vi.fn(async () => ({ providerMessageId: "pm-ours", sentAt: new Date("2026-10-07T10:01:00Z") }));
+    const f = fixture({
+      targets: [target({ connectionId: "conn-a" }), target({ connectionId: "conn-b", provider: "twitch", liveRemoteId: "tw-1" })],
+      transports: { ...transportsFor(send), twitch: { provider: "twitch", send, moderate: async () => undefined } },
+    });
+    const outcome = await f.hub.send(WS, CH, { text: "hello from the studio", targets: "all", author: { handle: "studio" } });
+    expect(outcome.delivery).toHaveLength(2);
+    expect(outcome.delivery.every(d => d.status === "sent")).toBe(true);
+    expect(outcome.message?.text).toBe("hello from the studio");
+    expect(outcome.message?.providerMessageId).toBe("pm-ours");
+    expect(f.published.some(p => p.frame.delivery !== undefined)).toBe(true); // chat.delivery frame
+  });
+
+  it("an unsupported target never fails the batch (§3.5)", async () => {
+    const send = vi.fn(async () => ({ providerMessageId: "pm-ok", sentAt: new Date() }));
+    const f = fixture({
+      targets: [
+        target({ connectionId: "conn-ok" }),
+        target({ connectionId: "conn-no-reply", reply: false, reason: "live chat write not supported" }),
+      ],
+      transports: transportsFor(send as ChatTransport["send"]),
+    });
+    const outcome = await f.hub.send(WS, CH, { text: "hi", targets: "all", author: { handle: "studio" } });
+    expect(outcome.delivery).toHaveLength(2);
+    expect(outcome.delivery.find(d => d.connectionId === "conn-ok")).toMatchObject({ status: "sent" });
+    expect(outcome.delivery.find(d => d.connectionId === "conn-no-reply")).toMatchObject({ status: "unsupported", error: "live chat write not supported" });
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(outcome.message).not.toBeNull();
+  });
+
+  it("a transport failure is a failed Delivery row; the other target still sends", async () => {
+    const send = vi.fn(async (request: { connectionId: string }) => {
+      if (request.connectionId === "conn-bad") throw new Error("Helix 503");
+      return { providerMessageId: "pm-ok", sentAt: new Date() };
+    });
+    const f = fixture({
+      targets: [target({ connectionId: "conn-good" }), target({ connectionId: "conn-bad" })],
+      transports: transportsFor(send as ChatTransport["send"]),
+    });
+    const outcome = await f.hub.send(WS, CH, { text: "hi", targets: "all", author: { handle: "studio" } });
+    expect(outcome.delivery.find(d => d.connectionId === "conn-bad")).toMatchObject({ status: "failed", error: "Helix 503" });
+    expect(outcome.delivery.find(d => d.connectionId === "conn-good")).toMatchObject({ status: "sent" });
+  });
+
+  it("a reply below budget is REFUSED with a paused reason and nothing is sent", async () => {
+    const send = vi.fn(async () => ({ providerMessageId: "pm-x", sentAt: new Date() }));
+    const f = fixture({
+      targets: [target()],
+      transports: transportsFor(send as ChatTransport["send"]),
+      governors: new SendGovernors({ quotas: { "mock-livestream": { budget: 1, costPerCall: 2 } } }), // first take already over budget
+    });
+    const outcome = await f.hub.send(WS, CH, { text: "hi", targets: "all", author: { handle: "studio" } });
+    expect(send).not.toHaveBeenCalled();
+    expect(outcome.message).toBeNull();
+    expect(outcome.refused).toMatchObject({ state: "paused:quota", reason: expect.stringContaining("quota") });
+    expect(outcome.delivery[0]).toMatchObject({ status: "unsupported", error: expect.stringContaining("quota") });
+    expect(f.db.messages).toHaveLength(0); // refused means no echo row either
+  });
+
+  it("target selection honours an explicit target list", async () => {
+    const send = vi.fn(async (_request: Parameters<ChatTransport["send"]>[0]) => ({ providerMessageId: "pm-1", sentAt: new Date() }));
+    const f = fixture({
+      targets: [target({ connectionId: "conn-a" }), target({ connectionId: "conn-b" })],
+      transports: transportsFor(send as ChatTransport["send"]),
+    });
+    await f.hub.send(WS, CH, { text: "hi", targets: ["conn-b"], author: { handle: "studio" } });
+    expect(send).toHaveBeenCalledTimes(1);
+    expect(send.mock.calls[0]?.[0]?.connectionId).toBe("conn-b");
+    expect(outcomeOf(f)).toHaveLength(1);
+  });
+
+  it("resolves a hub replyTo id to the provider parent id before sending", async () => {
+    const send = vi.fn(async (_request: Parameters<ChatTransport["send"]>[0]) => ({ providerMessageId: "reply", sentAt: new Date() }));
+    const f = fixture({ targets: [target()], transports: transportsFor(send) });
+    const parent = (await f.hub.ingest(WS, [event({ providerMessageId: "parent-provider-id" })])).inserted[0];
+    if (!parent) throw new Error("missing parent");
+    await f.hub.send(WS, CH, { text: "threaded", targets: "all", replyTo: parent.id, author: { handle: "studio" } });
+    expect(send).toHaveBeenCalledWith(expect.objectContaining({ replyTo: "parent-provider-id" }));
+  });
+
+  it("no capable targets at all is a clean refusal, not an exception", async () => {
+    const f = fixture({ targets: [] });
+    const outcome = await f.hub.send(WS, CH, { text: "hi", targets: "all", author: { handle: "studio" } });
+    expect(outcome.refused).toMatchObject({ state: "degraded", reason: "no capable target" });
+    expect(outcome.delivery).toEqual([]);
+  });
+
+  function outcomeOf(f: { published: Array<{ frame: Record<string, unknown> }> }): unknown[] {
+    return f.published.filter(p => p.frame.delivery !== undefined).flatMap(p => p.frame.delivery as unknown[]);
+  }
+});
+
+describe("moderation fan-out", () => {
+  it("delete fans out, flags the local row and publishes a chat.moderated frame", async () => {
+    const moderate = vi.fn(async (_request: Parameters<ChatTransport["moderate"]>[0]) => undefined);
+    const f = fixture({
+      targets: [target(), target({ connectionId: "conn-no-mod", moderate: false })],
+      transports: { "mock-livestream": { provider: "mock-livestream", send: async () => ({ providerMessageId: "x", sentAt: new Date() }), moderate: moderate as ChatTransport["moderate"] } },
+    });
+    const stored = (await f.hub.ingest(WS, [event({ providerMessageId: "pm-victim" })])).inserted[0];
+    const outcome = await f.hub.moderate(WS, CH, {
+      action: "delete",
+      message: { provider: "mock-livestream", providerMessageId: "pm-victim", authorHandle: "viewer@example" },
+    });
+    expect(moderate).toHaveBeenCalledWith(expect.objectContaining({ messageRemoteId: "pm-victim", action: "delete" }));
+    expect(outcome.delivery.find(d => d.connectionId === "conn-no-mod")?.status).toBe("unsupported");
+    expect(outcome.delivery.find(d => d.connectionId === "conn-1")?.status).toBe("sent");
+    expect(f.db.messages[0]?.is_moderated).toBe(true);
+    const frame = f.published.at(-1)?.frame;
+    expect(frame).toMatchObject({ kind: "chat", action: "delete", targetMessageId: "pm-victim" });
+    void stored;
+  });
+
+  it("a failed deletion preserves the row and emits no moderation success frame", async () => {
+    const f = fixture({ targets: [target()], transports: { "mock-livestream": { provider: "mock-livestream", send: async () => ({ providerMessageId: "x", sentAt: new Date() }), moderate: async () => { throw new Error("provider refused"); } } } });
+    await f.hub.ingest(WS, [event({ providerMessageId: "victim" })]);
+    const outcome = await f.hub.moderate(WS, CH, { action: "delete", message: { provider: "mock-livestream", providerMessageId: "victim", authorHandle: "viewer" } });
+    expect(outcome.delivery[0]?.status).toBe("failed"); expect(f.db.messages[0]?.is_moderated).toBe(false);
+    expect(f.published).toHaveLength(1);
+  });
+
+  it("timeout passes durationSeconds to the transport", async () => {
+    const moderate = vi.fn(async (_request: Parameters<ChatTransport["moderate"]>[0]) => undefined);
+    const f = fixture({
+      targets: [target()],
+      transports: { "mock-livestream": { provider: "mock-livestream", send: async () => ({ providerMessageId: "x", sentAt: new Date() }), moderate: moderate as ChatTransport["moderate"] } },
+    });
+    await f.hub.moderate(WS, CH, { action: "timeout", durationSeconds: 600, message: { provider: "mock-livestream", providerMessageId: "pm-1", authorHandle: "a" } });
+    expect(moderate.mock.calls[0]?.[0]).toMatchObject({ action: "timeout", durationSeconds: 600 });
+  });
+});
+
+describe("capabilities endpoint shape", () => {
+  it("mirrors target rows with state and optional reason", async () => {
+    const f = fixture({ targets: [target(), target({ connectionId: "c2", reply: false, state: "paused:quota", reason: "daily quota exhausted" })] });
+    const caps = await f.hub.capabilities(WS, CH);
+    expect(caps).toEqual([
+      expect.objectContaining({ connectionId: "conn-1", read: true, reply: true, moderate: true, state: "ok" }),
+      expect.objectContaining({ connectionId: "c2", reply: false, state: "paused:quota", reason: "daily quota exhausted" }),
+    ]);
+  });
+});
+
+class RespChatSocket extends Duplex {
+  constructor() { super(); queueMicrotask(() => this.emit("connect")); }
+  override _read(): void {}
+  override _write(bytes: Buffer, _encoding: BufferEncoding, done: (error?: Error | null) => void): void {
+    const parts = parse(bytes)?.reply;
+    if (!Array.isArray(parts)) { done(new Error("invalid RESP")); return; }
+    queueMicrotask(() => this.emit("data", encode([String(parts[0]).toLowerCase(), String(parts[1]), "1"])));
+    done();
+  }
+  publish(topic: string, raw: string): void { const bytes = encode(["message", topic, raw]); this.emit("data", bytes.subarray(0, 7)); this.emit("data", bytes.subarray(7)); }
+}
+class ClientWire extends Duplex {
+  readonly frames: Array<Record<string, unknown>> = [];
+  override _read(): void {}
+  override _write(bytes: Buffer, _encoding: BufferEncoding, done: (error?: Error | null) => void): void {
+    if ((bytes[0] ?? 0) === 129) this.frames.push(JSON.parse(bytes.subarray((bytes[1] ?? 0) === 126 ? 4 : 2).toString()) as Record<string, unknown>);
+    done();
+  }
+  send(value: unknown): void {
+    const body = Buffer.from(JSON.stringify(value)), header = Buffer.alloc(body.length < 126 ? 6 : 8);
+    header[0] = 129;
+    if (body.length < 126) header[1] = 128 | body.length;
+    else { header[1] = 128 | 126; header.writeUInt16BE(body.length, 2); }
+    // A zero mask is valid; fragmentation exercises the incremental decoder.
+    const bytes = Buffer.concat([header, body]); this.emit("data", bytes.subarray(0, 5)); this.emit("data", bytes.subarray(5));
+  }
+}
+async function settle(): Promise<void> { await new Promise(resolve => setTimeout(resolve, 10)); }
+
+describe("mock connector → hub rows → Redis RESP → WS chat contract", () => {
+  it("dedupes, preserves ingress seq, resumes on a fresh gateway, and resyncs after 500-frame eviction", async () => {
+    let respSocket: RespChatSocket | null = null;
+    const subscriptions = new RespRedisSubscriptions("redis://localhost", () => undefined, () => { respSocket = new RespChatSocket(); return respSocket as unknown as Socket; });
+    const window: Record<string, unknown>[] = [];
+    const redis: ControlRedis = {
+      get: async () => null, mget: async () => [], set: async () => true, incr: async () => 1, sadd: async () => undefined, smembers: async () => [], publish: async () => 1, close: () => undefined,
+      eval: async (script, keys, args) => {
+        expect(script).toBe(CHAT_PUBLISH_SCRIPT);
+        const frame = JSON.parse(args[1] ?? "{}") as Record<string, unknown>;
+        window.push(frame); if (window.length > 500) window.shift();
+        respSocket?.publish(keys[1] ?? "", args[1] ?? ""); return 1;
+      },
+    };
+    const bridge = new ChatRealtimeBridge(undefined, redis), f = fixture({ publish: bridge.publish });
+    const connector = createMockLivestreamConnector();
+    const connection = { id: randomUUID(), workspaceId: WS, provider: connector.manifest().id, channelId: CH, credentialId: { kind: "credential-ref" as const, id: "mock" }, fields: {}, createdAt: new Date() };
+    const live = await connector.createLiveStream?.(connection, { channelId: CH, title: "test", permanent: false, saveReplay: false });
+    if (!live) throw new Error("mock live missing");
+    await connector.sendLiveChatMessage?.(connection, { liveRemoteId: live.remoteId, text: "hello through the wire" });
+    const driver = new MockLivestreamDriver(connector, { workspaceId: WS, channelId: CH, connectionId: connection.id, liveRemoteId: live.remoteId });
+    await driver.start((ws, events) => f.hub.ingest(ws, events));
+    await driver.poll(); expect(f.db.messages).toHaveLength(1); expect(window).toHaveLength(1);
+    const service = new RealtimeService(new MediaControlService({ signer: null, assignments: [] }), {
+      subscriptions, authorizeChat: async () => true, channelExists: async () => true, chatWindow: async () => window.slice(), status: async () => ({ channels: [] }),
+    });
+    const wires: ClientWire[] = [];
+    const open = (lastSeq: number) => {
+      const wire = new ClientWire(), peer = new RealtimeSocket(wire), handlers = service.attach(peer);
+      peer.onMessage = handlers.message; peer.onClose = handlers.close; wires.push(wire);
+      wire.send({ op: "auth", token: issueSession({ userId: randomUUID(), workspaceId: WS, role: "Operator", authzEpoch: 1 }) });
+      wire.send({ op: "subscribe", id: "chat", topic: "livechat", liveId: CH, lastSeq }); return wire;
+    };
+    try {
+      const first = open(0); await settle();
+      expect(first.frames).toContainEqual({ op: "ready" });
+      expect(first.frames).toContainEqual({ op: "ack", id: "chat", fromSeq: 1 });
+      expect(first.frames).toContainEqual(expect.objectContaining({ op: "msg", topic: "livechat", type: "chat.message", seq: 1, payload: expect.objectContaining({ seq: 1, message: expect.objectContaining({ seq: 1, text: "hello through the wire" }) }) }));
+      await f.hub.ingest(WS, [event()]);
+      expect(first.frames.filter(frame => frame.op === "msg").map(frame => frame.seq)).toEqual([1, 2]);
+      const resume = open(1); await settle(); expect(resume.frames.filter(frame => frame.op === "msg").map(frame => frame.seq)).toEqual([2]);
+      for (let i = 0; i < 500; i += 1) await f.hub.ingest(WS, [event()]);
+      const stale = open(1); await settle(); expect(stale.frames).toContainEqual({ op: "resync", topic: "livechat" });
+      expect(window).toHaveLength(500);
+      const page = await f.hub.messages(WS, CH, { after: 1, limit: 100 }); expect(page.items[0]?.seq).toBe(2);
+    } finally { await driver.stop(); service.onModuleDestroy(); bridge.onModuleDestroy(); for (const wire of wires) wire.destroy(); }
+  });
+});
diff --git a/apps/api/src/live-chat/idempotency.ts b/apps/api/src/live-chat/idempotency.ts
new file mode 100644
index 0000000..5634ca9
--- /dev/null
+++ b/apps/api/src/live-chat/idempotency.ts
@@ -0,0 +1,34 @@
+import { createHash } from "node:crypto";
+import { BadRequestException, ConflictException } from "@nestjs/common";
+import type { LiveChatDependencies } from "./live-chat.service.js";
+
+/** Reserve before contacting providers. A crash leaves a pending row, so an
+ * ambiguous external send is never repeated automatically under the same key. */
+export async function idempotentChat<T>(transaction: LiveChatDependencies["transaction"], workspaceId: string, userId: string, route: string, key: string | undefined, body: unknown, action: () => Promise<T>): Promise<T> {
+  if (!key || !/^[\x21-\x7e]{1,128}$/.test(key)) throw new BadRequestException("Idempotency-Key must contain 1..128 printable characters");
+  const hash = createHash("sha256").update(JSON.stringify(body)).digest("hex");
+  const existing = await transaction(workspaceId, async client => {
+    const claim = await client.query(
+      `INSERT INTO live_chat_requests (workspace_id,user_id,route,request_key,request_hash) VALUES ($1,$2,$3,$4,$5)
+       ON CONFLICT DO NOTHING RETURNING request_key`, [workspaceId, userId, route, key, hash]);
+    if (claim.rowCount) return null;
+    const row = await client.query<{ request_hash: string; status: string; response: T }>(
+      "SELECT request_hash,status,response FROM live_chat_requests WHERE workspace_id=$1 AND user_id=$2 AND route=$3 AND request_key=$4", [workspaceId, userId, route, key]);
+    return row.rows[0];
+  });
+  if (existing) {
+    if (existing.request_hash !== hash) throw new ConflictException("Idempotency-Key reused with different payload");
+    if (existing.status !== "complete") throw new ConflictException("chat request pending or failed; reconcile before retrying");
+    return existing.response;
+  }
+  try {
+    const result = await action();
+    await transaction(workspaceId, async client => { await client.query(
+      "UPDATE live_chat_requests SET status='complete',response=$5 WHERE workspace_id=$1 AND user_id=$2 AND route=$3 AND request_key=$4", [workspaceId, userId, route, key, JSON.stringify(result)]); });
+    return result;
+  } catch (error) {
+    await transaction(workspaceId, async client => { await client.query(
+      "UPDATE live_chat_requests SET status='failed' WHERE workspace_id=$1 AND user_id=$2 AND route=$3 AND request_key=$4", [workspaceId, userId, route, key]); }).catch(() => undefined);
+    throw error;
+  }
+}
diff --git a/apps/api/src/live-chat/live-chat.controller.test.ts b/apps/api/src/live-chat/live-chat.controller.test.ts
new file mode 100644
index 0000000..f253d73
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.controller.test.ts
@@ -0,0 +1,28 @@
+import "reflect-metadata";
+import { NestFactory } from "@nestjs/core";
+import { PATH_METADATA } from "@nestjs/common/constants.js";
+import { describe, expect, it, vi } from "vitest";
+import { LiveChatModule } from "./live-chat.module.js";
+import { LiveChatController } from "./live-chat.controller.js";
+import { LiveChatHubService } from "./live-chat.service.js";
+import { DeviceService } from "./devices.js";
+
+describe("standalone S5 module and REST routes", () => {
+  it("boots with injected drivers and shuts them down without central AppModule wiring", async () => {
+    const driver = { provider: "mock-livestream", start: vi.fn(async () => undefined), stop: vi.fn(async () => undefined) };
+    const app = await NestFactory.createApplicationContext(LiveChatModule.register({ drivers: [driver] }), { logger: false, abortOnError: false });
+    try { expect(app.get(LiveChatController)).toBeInstanceOf(LiveChatController); expect(driver.start).toHaveBeenCalledTimes(1); }
+    finally { await app.close(); }
+    expect(driver.stop).toHaveBeenCalledTimes(1);
+  });
+  it("matches §3.5 routes and rejects malformed redeem bodies before storage", async () => {
+    const proto = LiveChatController.prototype;
+    expect(Reflect.getMetadata(PATH_METADATA, proto.lives)).toBe("live-chat/lives");
+    expect(Reflect.getMetadata(PATH_METADATA, proto.messages)).toBe("live-chat/lives/:channelId/messages");
+    expect(Reflect.getMetadata(PATH_METADATA, proto.moderate)).toBe("live-chat/lives/:channelId/messages/:messageId/moderation");
+    expect(Reflect.getMetadata(PATH_METADATA, proto.capabilities)).toBe("live-chat/lives/:channelId/capabilities");
+    expect(Reflect.getMetadata(PATH_METADATA, proto.redeem)).toBe("devices/pairings/redeem");
+    const controller = new LiveChatController(new LiveChatHubService(), new DeviceService());
+    await expect(controller.redeem({ pairingCode: "ABCD-1234", deviceName: "" }, "key")).rejects.toThrow("deviceName");
+  });
+});
diff --git a/apps/api/src/live-chat/live-chat.controller.ts b/apps/api/src/live-chat/live-chat.controller.ts
new file mode 100644
index 0000000..057d8c6
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.controller.ts
@@ -0,0 +1,169 @@
+import { BadRequestException, Body, Controller, Delete, Get, Headers, HttpCode, Inject, Param, Post, Query, Req, UseGuards, NotFoundException, UnauthorizedException } from "@nestjs/common";
+import type { Request } from "express";
+import { idempotentChat } from "./idempotency.js";
+import { withTenant } from "../db/client.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { DEVICE_SCOPES } from "@tactical-media-broadcast-hub/core";
+import { parseId, parseLimit, requireObject, requireSession, requireString } from "../http/validation.js";
+import { RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { LiveChatGuard, SessionOnly } from "./live-chat.guard.js";
+import { tokenWorkspace } from "./auth.js";
+import { DeviceService } from "./devices.js";
+import { LiveChatHubService } from "./live-chat.service.js";
+
+/**
+ * §3.5 endpoints. No `/workspaces/{wid}` prefix — the workspace comes from the
+ * session (or device token) per repo convention.
+ */
+@Controller()
+export class LiveChatController {
+  constructor(@Inject(LiveChatHubService) private readonly hub: LiveChatHubService, @Inject(DeviceService) private readonly devices: DeviceService) {}
+
+  @Get("live-chat/lives")
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("stream.view")
+  async lives(@Req() request: Request & AuthenticatedRequest) {
+    return this.hub.lives(requireSession(request).workspaceId);
+  }
+
+  @Get("live-chat/lives/:channelId/messages")
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("livechat.view")
+  async messages(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("channelId") channelId: string,
+    @Query("after") after: string | undefined,
+    @Query("limit") limit: string | undefined,
+    @Query("platform") platform: string | undefined,
+  ) {
+    const session = requireSession(request);
+    return this.hub.messages(session.workspaceId, parseId(channelId, "channelId"), {
+      limit: parseLimit(limit, 100, 500),
+      ...(after === undefined || after === "" ? {} : { after: parseSeq(after) }),
+      ...(platform === undefined || platform === "" ? {} : { provider: platform }),
+    });
+  }
+
+  @Post("live-chat/lives/:channelId/messages")
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("livechat.send")
+  @HttpCode(202)
+  async send(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("channelId") channelId: string,
+    @Body() body: unknown,
+    @Headers("idempotency-key") key?: string,
+  ) {
+    const session = requireSession(request);
+    const parsed = requireObject(body, "body");
+    const text = requireString(parsed.text, "text");
+    if (text.length > 500) throw new BadRequestException("text must be 1..500 characters");
+    const targets = parseTargets(parsed.targets);
+    const liveId = parseId(channelId, "channelId");
+    const replyTo = parsed.replyTo === undefined ? undefined : parseId(requireString(parsed.replyTo, "replyTo"), "replyTo");
+    return idempotentChat(withTenant, session.workspaceId, session.userId, `send:${channelId}`, key, body, async () => {
+      const outcome = await this.hub.send(session.workspaceId, liveId, {
+        text, targets, ...(replyTo === undefined ? {} : { replyTo }),
+        author: { handle: `${session.role.toLowerCase()}:${session.userId.slice(0, 8)}` },
+    });
+    return { message: outcome.message, delivery: outcome.delivery, ...(outcome.refused ? { refused: outcome.refused } : {}) };
+    });
+  }
+
+  @Post("live-chat/lives/:channelId/messages/:messageId/moderation")
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("livechat.moderate")
+  @HttpCode(202)
+  async moderate(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("channelId") channelId: string,
+    @Param("messageId") messageId: string,
+    @Body() body: unknown,
+    @Headers("idempotency-key") key?: string,
+  ) {
+    const session = requireSession(request);
+    const parsed = requireObject(body, "body");
+    const action = parsed.action;
+    if (action !== "delete" && action !== "timeout" && action !== "ban") throw new BadRequestException("action must be delete, timeout or ban");
+    let durationSeconds: number | undefined;
+    if (parsed.durationSeconds !== undefined) {
+      if (typeof parsed.durationSeconds !== "number") throw new BadRequestException("durationSeconds must be a number");
+      durationSeconds = parsed.durationSeconds;
+      if (!Number.isInteger(durationSeconds) || durationSeconds < 1 || durationSeconds > 1209600) throw new BadRequestException("durationSeconds must be 1..1209600");
+    }
+    if (action === "timeout" && durationSeconds === undefined) throw new BadRequestException("timeout requires durationSeconds");
+    return idempotentChat(withTenant, session.workspaceId, session.userId, `moderate:${channelId}:${messageId}`, key, body, async () => {
+      const outcome = await this.hub.moderate(session.workspaceId, parseId(channelId, "channelId"), {
+        action,
+        ...(durationSeconds === undefined ? {} : { durationSeconds }),
+        message: await this.hubTarget(session.workspaceId, parseId(channelId, "channelId"), parseId(messageId, "messageId")),
+    });
+    await appendTenantAudit(session.workspaceId, { actorUserId: session.userId, actorRole: session.role, action: `livechat.${action}`,
+      targetType: "live_chat_message", targetId: messageId, diff: { delivery: outcome.delivery, durationSeconds } });
+    return { delivery: outcome.delivery };
+    });
+  }
+
+  @Get("live-chat/lives/:channelId/capabilities")
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("livechat.view")
+  async capabilities(@Req() request: Request & AuthenticatedRequest, @Param("channelId") channelId: string) {
+    const session = requireSession(request);
+    return this.hub.capabilities(session.workspaceId, parseId(channelId, "channelId"));
+  }
+
+  // -- Device pairing (§3.4) ------------------------------------------------
+
+  @Post("devices/pairings")
+  @SessionOnly()
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("livechat.send")
+  async issuePairing(@Req() request: Request & AuthenticatedRequest, @Headers("idempotency-key") key?: string): Promise<{ pairingCode: string; qrPayload: string; expiresAt: string }> {
+    const session = requireSession(request);
+    return idempotentChat(withTenant, session.workspaceId, session.userId, "pairing", key, {}, () => this.devices.issuePairing(session.workspaceId, session.userId, DEVICE_SCOPES));
+  }
+
+  @Post("devices/pairings/redeem")
+  @HttpCode(200)
+  async redeem(@Body() body: unknown, @Headers("idempotency-key") key?: string, @Headers("authorization") auth?: string): Promise<{ deviceToken: string; workspaceId: string }> {
+    const parsed = requireObject(body, "body");
+    const pairingCode = requireString(parsed.pairingCode, "pairingCode");
+    const deviceName = requireString(parsed.deviceName, "deviceName");
+    if (deviceName.length > 120) throw new BadRequestException("deviceName too long");
+    // The bearer pairing code resolves its issuing workspace; no session is needed.
+    const workspace = auth?.startsWith("Bearer ") ? tokenWorkspace(auth.slice(7)) : undefined;
+    if (auth && !workspace) throw new UnauthorizedException();
+    return this.devices.redeemCode(pairingCode, deviceName, key, workspace ?? undefined);
+  }
+
+  @Delete("devices/:deviceId")
+  @UseGuards(LiveChatGuard)
+  @RequirePermission("livechat.send")
+  async revoke(@Req() request: Request & AuthenticatedRequest, @Param("deviceId") deviceId: string) {
+    const session = requireSession(request);
+    await this.devices.revoke(session.workspaceId, parseId(deviceId, "deviceId"));
+    return { revoked: true };
+  }
+
+  private async hubTarget(workspaceId: string, channelId: string, messageId: string) {
+    const found = await this.hub.findMessage(workspaceId, channelId, messageId);
+    if (!found) throw new NotFoundException("message not found");
+    return { id: found.id, connectionId: found.connectionId, provider: found.provider, providerMessageId: found.providerMessageId, authorHandle: found.author.handle };
+  }
+}
+
+function parseSeq(value: string): number {
+  const n = Number(value);
+  if (!Number.isSafeInteger(n) || n < 0) throw new BadRequestException("after must be a non-negative integer seq");
+  return n;
+}
+
+function parseTargets(value: unknown): "all" | string[] {
+  if (value === "all") return "all";
+  if (!Array.isArray(value) || value.length === 0 || value.length > 32) throw new BadRequestException('targets must be "all" or 1..32 connection ids');
+  return value.map((entry): string => {
+    if (typeof entry !== "string") throw new BadRequestException("targets must contain connection ids");
+    return parseId(entry, "connectionId");
+  });
+}
+
diff --git a/apps/api/src/live-chat/live-chat.guard.ts b/apps/api/src/live-chat/live-chat.guard.ts
new file mode 100644
index 0000000..182f4ff
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.guard.ts
@@ -0,0 +1,26 @@
+import { CanActivate, ExecutionContext, Inject, Injectable, SetMetadata, UnauthorizedException, ForbiddenException } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { PERMISSION_KEY, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { pool } from "../db/client.js";
+import { authorizeChat, chatSession, tokenWorkspace } from "./auth.js";
+
+export const SessionOnly = (): MethodDecorator => SetMetadata("livechat.session_only", true) as MethodDecorator;
+
+@Injectable()
+export class LiveChatGuard implements CanActivate {
+  constructor(@Inject(Reflector) private readonly reflector: Reflector) {}
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const req = context.switchToHttp().getRequest<{ headers: Record<string, string | undefined> } & AuthenticatedRequest>();
+    const token = req.headers.authorization?.replace(/^Bearer /, "");
+    const workspaceId = token ? tokenWorkspace(token) : null;
+    if (!token || !workspaceId || !req.headers.authorization?.startsWith("Bearer ")) throw new UnauthorizedException();
+    if (this.reflector.get<boolean>("livechat.session_only", context.getHandler()) && !chatSession(token)) throw new UnauthorizedException("session user required");
+    const client = await pool.connect();
+    try {
+      const session = await authorizeChat(client, token, workspaceId, this.reflector.get<string>(PERMISSION_KEY, context.getHandler()) ?? "livechat.view");
+      if (!session) throw new ForbiddenException("chat permission or authorization epoch invalid");
+      req.session = session;
+      return true;
+    } finally { client.release(); }
+  }
+}
diff --git a/apps/api/src/live-chat/live-chat.integration.test.ts b/apps/api/src/live-chat/live-chat.integration.test.ts
new file mode 100644
index 0000000..b1e8826
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.integration.test.ts
@@ -0,0 +1,97 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+import { LiveChatHubService } from "./live-chat.service.js";
+import { DeviceService, verifyDeviceToken } from "./devices.js";
+import { idempotentChat } from "./idempotency.js";
+import type { NormalizedChatEvent } from "./types.js";
+
+// Deliberately isolated from the user's configured runtime database.
+const url = process.env.S5_TEST_DATABASE_URL;
+const db = new Pool({ connectionString: url });
+const WS = randomUUID(), OTHER = randomUUID(), USER = randomUUID(), CH = randomUUID(), CONN = randomUUID();
+async function tenant<T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await db.connect();
+  try {
+    await client.query("BEGIN"); await client.query("SET LOCAL ROLE sp_app");
+    await client.query("SELECT set_config('app.workspace_id',$1,true)", [workspaceId]);
+    const result = await fn(client); await client.query("COMMIT"); return result;
+  } catch (error) { await client.query("ROLLBACK"); throw error; }
+  finally { client.release(); }
+}
+const hub = new LiveChatHubService({ transaction: tenant, publish: () => undefined });
+function event(id: string, receivedAt = new Date()): NormalizedChatEvent {
+  return { provider: "mock-livestream", connectionId: CONN, channelId: CH, providerMessageId: id, author: { handle: "viewer" }, text: id, sentAt: receivedAt, receivedAt };
+}
+describe.skipIf(!url)("S5 PostgreSQL partitioning, row locks, RLS, pairing, and retention", () => {
+  beforeAll(async () => {
+    process.env.SUPER_DATABASE_URL = url;
+    await runMigrations(join(__dirname, "../../migrations"));
+    await db.query("INSERT INTO workspaces(id,name,slug) VALUES ($1::uuid,'S5',$1::text),($2::uuid,'S5 other',$2::text)", [WS, OTHER]);
+    await db.query("INSERT INTO users(id,external_id,email,display_name) VALUES ($1::uuid,$1::text,'s5@example.test','S5')", [USER]);
+    await db.query("INSERT INTO memberships(workspace_id,user_id,role) VALUES ($1,$2,'Owner')", [WS, USER]);
+    await db.query("INSERT INTO connections(id,workspace_id,provider,channel_id) VALUES ($1,$2,'mock-livestream','remote')", [CONN, WS]);
+    await db.query("INSERT INTO virtual_channels(id,workspace_id,slug,name) VALUES ($1,$2,'s5','S5')", [CH, WS]);
+    await db.query("INSERT INTO virtual_channel_sources(workspace_id,virtual_channel_id,kind,label,connection_id,remote_ref,hls_url) VALUES ($1,$2,'hls','S5',$3,'remote','https://example.test/live.m3u8')", [WS, CH, CONN]);
+  });
+  afterAll(async () => {
+    if (url) { await db.query("DELETE FROM workspaces WHERE id IN ($1,$2)", [WS, OTHER]); await db.query("DELETE FROM users WHERE id=$1", [USER]); }
+    await db.end();
+  });
+  it("concurrent ingress assigns unique seqs; duplicates claim exactly one durable row", async () => {
+    const results = await Promise.all([hub.ingest(WS, [event("same")]), hub.ingest(WS, [event("same")])]);
+    expect(results.flatMap(result => result.inserted)).toHaveLength(1);
+    expect(results.flatMap(result => result.duplicates)).toEqual(["same"]);
+    const more = await Promise.all(Array.from({ length: 8 }, (_, i) => hub.ingest(WS, [event(`unique-${i}`)])));
+    expect(more.flatMap(result => result.inserted.map(message => message.seq)).sort((a,b) => a-b)).toEqual([2,3,4,5,6,7,8,9]);
+    expect((await hub.messages(OTHER, CH, { limit: 100 })).items).toEqual([]);
+    expect((await hub.lives(WS)).items).toContainEqual(expect.objectContaining({ liveStreamId: CH, connectionId: CONN }));
+  });
+  it("RLS applies to direct partition access as well as parent access", async () => {
+    const partitions = await db.query<{ relname: string }>("SELECT c.relname FROM pg_inherits i JOIN pg_class c ON c.oid=i.inhrelid WHERE i.inhparent='live_chat_messages'::regclass");
+    for (const row of partitions.rows) {
+      if (!/^live_chat_messages_(default|[0-9]{6})$/.test(row.relname)) throw new Error("unexpected partition name");
+      const found = await tenant(OTHER, client => client.query(`SELECT * FROM ${row.relname}`)); expect(found.rowCount).toBe(0);
+    }
+    const client = await db.connect();
+    try { await client.query("BEGIN"); await client.query("SET LOCAL ROLE sp_app"); expect((await client.query("SELECT * FROM live_chat_messages")).rowCount).toBe(0); }
+    finally { await client.query("ROLLBACK"); client.release(); }
+  });
+  it("pairing lookup permits only a valid code; redemption is single use and workspace fenced", async () => {
+    const service = new DeviceService({ transaction: tenant, serverUrl: "https://studio.example", lookupWorkspace: async code => {
+      const row = await db.query<{ workspace_id: string }>("SELECT device_pairing_workspace($1) AS workspace_id", [code]); return row.rows[0]?.workspace_id ?? null;
+    } });
+    const pairing = await service.issuePairing(WS, USER);
+    const lookup = await tenant(OTHER, client => client.query<{ workspace_id: string }>("SELECT device_pairing_workspace($1) AS workspace_id", [pairing.pairingCode]));
+    expect(lookup.rows[0]?.workspace_id).toBe(WS);
+    await expect(service.redeem(OTHER, pairing.pairingCode, "phone")).rejects.toThrow("invalid pairing code");
+    await expect(service.redeemCode(pairing.pairingCode, "phone", "redeem-key", OTHER)).rejects.toThrow("invalid pairing code");
+    const result = await service.redeemCode(pairing.pairingCode, "phone", "redeem-key"), payload = verifyDeviceToken(result.deviceToken);
+    expect(payload).toMatchObject({ userId: USER, workspaceId: WS, epoch: 1 });
+    expect(await service.redeemCode(pairing.pairingCode, "phone", "redeem-key")).toEqual(result);
+    if (!payload) throw new Error("no token");
+    await expect(service.redeem(WS, pairing.pairingCode, "phone")).rejects.toThrow("already redeemed");
+    await service.revoke(WS, payload.deviceId); expect(await service.epochOf(WS, payload.deviceId)).toBeNull();
+  });
+  it("idempotency returns the recorded reply and refuses concurrent or changed requests", async () => {
+    let calls = 0;
+    const run = (body: unknown) => idempotentChat(tenant, WS, USER, "send:test", "retry-key", body, async () => ({ count: ++calls }));
+    expect(await run({ text: "hi" })).toEqual({ count: 1 });
+    expect(await run({ text: "hi" })).toEqual({ count: 1 }); expect(calls).toBe(1);
+    await expect(run({ text: "changed" })).rejects.toThrow("different payload");
+    const result = await Promise.allSettled([idempotentChat(tenant, WS, USER, "send:test", "concurrent", {}, async () => ({ count: ++calls })), idempotentChat(tenant, WS, USER, "send:test", "concurrent", {}, async () => ({ count: ++calls }))]);
+    expect(result.filter(item => item.status === "fulfilled").length).toBeGreaterThanOrEqual(1); expect(calls).toBe(2);
+  });
+  it("retention prunes old messages without pruning another tenant", async () => {
+    const old = new Date(Date.now() - 100 * 86400000);
+    await hub.ingest(WS, [event("old-retention", old)]);
+    const before = (await hub.messages(WS, CH, { limit: 100 })).items.length;
+    await tenant(OTHER, client => client.query("SELECT live_chat_prune($1,$2)", [OTHER, new Date()]));
+    expect((await hub.messages(WS, CH, { limit: 100 })).items).toHaveLength(before);
+    const removed = await tenant(WS, client => client.query<{ count: number }>("SELECT live_chat_prune($1,$2) AS count", [WS, new Date(Date.now() - 30 * 86400000)]));
+    expect(removed.rows[0]?.count).toBe(1);
+    expect((await hub.messages(WS, CH, { limit: 100 })).items.some(message => message.providerMessageId === "old-retention")).toBe(false);
+  });
+});
diff --git a/apps/api/src/live-chat/live-chat.module.ts b/apps/api/src/live-chat/live-chat.module.ts
new file mode 100644
index 0000000..4634afc
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.module.ts
@@ -0,0 +1,53 @@
+import { Module, type DynamicModule } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import { LIVE_CHAT_RUNTIME, LiveChatRuntime, type LiveChatRuntimeOptions } from "./runtime.js";
+import { ChatRealtimeBridge } from "./bridge.js";
+import { LiveChatGuard } from "./live-chat.guard.js";
+import { DeviceService } from "./devices.js";
+import { LiveChatController } from "./live-chat.controller.js";
+import { LiveChatHubService } from "./live-chat.service.js";
+import { ChatRingBuffer } from "./ring-buffer.js";
+import { RedisChatGovernors, type ChatGovernors } from "./redis-governors.js";
+import { SendGovernors } from "./governors.js";
+import type { ChatTarget } from "./types.js";
+
+/** Central review imports this module with credential-bound transports,
+ * capability targets and ingestion drivers via LiveChatModule.register(). */
+function defaultTargets(): (workspaceId: string, channelId: string) => Promise<ChatTarget[]> {
+  return async (workspaceId, channelId) => {
+    const result = await withTenant(workspaceId, client => client.query<{ connection_id: string; provider: string; live_remote_id: string | null }>(
+      `SELECT vc.id AS connection_id, vc.provider, vcs.remote_ref AS live_remote_id
+         FROM virtual_channel_sources vcs
+         JOIN connections vc ON vc.id = vcs.connection_id AND vc.workspace_id = vcs.workspace_id
+        WHERE vcs.workspace_id = $1 AND vcs.virtual_channel_id = $2`, [workspaceId, channelId]));
+    return result.rows.map(row => ({
+      connectionId: row.connection_id,
+      provider: row.provider,
+      liveRemoteId: row.live_remote_id ?? row.connection_id,
+      read: false, reply: false, moderate: false, state: "degraded" as const,
+      reason: "chat adapter not configured",
+    }));
+  };
+}
+
+@Module({
+  controllers: [LiveChatController],
+  providers: [
+    { provide: ChatRingBuffer, useValue: new ChatRingBuffer(500) },
+    { provide: SendGovernors, useFactory: () => new RedisChatGovernors({ buckets: { twitch: { capacity: 100, refillPerSecond: 100 / 30 } }, quotas: { youtube: { budget: 10000, costPerCall: 50 } } }) },
+    { provide: ChatRealtimeBridge, useFactory: () => new ChatRealtimeBridge() },
+    {
+      provide: LiveChatHubService,
+      useFactory: (buffer: ChatRingBuffer, governors: ChatGovernors, bridge: ChatRealtimeBridge, runtime?: LiveChatRuntimeOptions) =>
+        new LiveChatHubService({ buffer, governors, publish: bridge.publish, targets: defaultTargets(), ...runtime }),
+      inject: [ChatRingBuffer, SendGovernors, ChatRealtimeBridge, { token: LIVE_CHAT_RUNTIME, optional: true }],
+    },
+    DeviceService, LiveChatGuard, LiveChatRuntime,
+  ],
+  exports: [LiveChatHubService, DeviceService, ChatRealtimeBridge],
+})
+export class LiveChatModule {
+  static register(options: LiveChatRuntimeOptions): DynamicModule {
+    return { module: LiveChatModule, providers: [{ provide: LIVE_CHAT_RUNTIME, useValue: options }] };
+  }
+}
diff --git a/apps/api/src/live-chat/live-chat.service.ts b/apps/api/src/live-chat/live-chat.service.ts
new file mode 100644
index 0000000..12ce29b
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.service.ts
@@ -0,0 +1,353 @@
+/**
+ * Chat hub service: ingestion → seq assignment → persistence (dedupe) →
+ * fan-out on the realtime gateway, plus reply/moderation fan-out with
+ * per-target Delivery rows and send governors in front.
+ *
+ * Sequencing is per (workspace, channel) under a row lock on `live_chat_seq`
+ * (§3.2): the ingest transaction takes FOR UPDATE on that row, so concurrent
+ * ingests cannot interleave seqs for one channel. Provider message ids dedupe
+ * through UNIQUE(workspace_id, provider, provider_msg_id) — a replay is a
+ * no-op that publishes nothing.
+ *
+ * Every port has a working default (see the module), and tests inject
+ * overrides through LIVE_CHAT_DEPENDENCIES — same pattern as RealtimeService.
+ */
+import { Inject, Injectable, Optional, NotFoundException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { authorColor, type Delivery, type LiveChatCapability, type LiveSummary } from "@tactical-media-broadcast-hub/core";
+import { withTenant } from "../db/client.js";
+import { ChatRingBuffer } from "./ring-buffer.js";
+import type { ChatGovernors } from "./redis-governors.js";
+import { SendGovernors } from "./governors.js";
+import type {
+  ChatTarget, ChatTransport, IngestResult, MessagePage, MessageQuery, ModerateOutcome, NormalizedChatEvent, SendOutcome, StoredChatMessage,
+} from "./types.js";
+
+export const LIVE_CHAT_DEPENDENCIES = Symbol("LIVE_CHAT_DEPENDENCIES");
+
+export type LiveChatPublish = (workspaceId: string, channelId: string, frame: Record<string, unknown>) => void | Promise<void>;
+
+export interface LiveChatDependencies {
+  transaction: <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+  publish: LiveChatPublish;
+  buffer: ChatRingBuffer;
+  governors: ChatGovernors;
+  /** Resolve the send/moderate targets for a channel (capability rows). */
+  targets: (workspaceId: string, channelId: string) => Promise<ChatTarget[]>;
+  /** Transport per provider id. */
+  transports: Record<string, ChatTransport>;
+  /** Virtual clock for deterministic tests. */
+  now?: () => Date;
+  filters?: { hideCommands?: boolean; hideBots?: boolean; mutedHandles?: string[]; words?: string[] };
+}
+
+interface MessageRow {
+  id: string; workspace_id: string; channel_id: string; connection_id: string; provider: string; provider_msg_id: string;
+  author_handle: string; author_display_name: string | null; author_avatar_url: string | null; author_badges: unknown;
+  author_color: string; body: string; reply_to: string | null; seq: string | number; sent_at: Date; received_at: Date;
+  is_moderated: boolean; source: string;
+}
+
+function toStored(row: MessageRow): StoredChatMessage {
+  return {
+    id: row.id,
+    seq: Number(row.seq),
+    liveStreamId: row.channel_id,
+    connectionId: row.connection_id,
+    provider: row.provider,
+    providerMessageId: row.provider_msg_id,
+    author: {
+      handle: row.author_handle,
+      ...(row.author_display_name === null ? {} : { displayName: row.author_display_name }),
+      ...(row.author_avatar_url === null ? {} : { avatarUrl: row.author_avatar_url }),
+      badges: Array.isArray(row.author_badges) ? (row.author_badges as string[]) : [],
+      color: row.author_color,
+    },
+    text: row.body,
+    sentAt: new Date(row.sent_at).toISOString(),
+    receivedAt: new Date(row.received_at).toISOString(),
+    isModerated: row.is_moderated,
+    ...(row.reply_to === null ? {} : { replyTo: row.reply_to }),
+    source: row.source as StoredChatMessage["source"],
+  };
+}
+
+const SELECT_COLUMNS = `id, workspace_id, channel_id, connection_id, provider, provider_msg_id, author_handle,
+  author_display_name, author_avatar_url, author_badges, author_color, body, reply_to, seq, sent_at,
+  received_at, is_moderated, source`;
+
+const INSERT_SQL = `INSERT INTO live_chat_messages (workspace_id, channel_id, connection_id, provider, provider_msg_id,
+    author_handle, author_display_name, author_avatar_url, author_badges, author_color, body, reply_to,
+    seq, sent_at, received_at, source)
+  SELECT * FROM UNNEST($1::uuid[], $2::uuid[], $3::uuid[], $4::text[], $5::text[], $6::text[], $7::text[],
+    $8::text[], $9::jsonb[], $10::text[], $11::text[], $12::text[], $13::bigint[], $14::timestamptz[],
+    $15::timestamptz[], $16::text[])
+  RETURNING ${SELECT_COLUMNS}`;
+
+@Injectable()
+export class LiveChatHubService {
+  private readonly deps: LiveChatDependencies;
+  private readonly now: () => Date;
+  constructor(@Optional() @Inject(LIVE_CHAT_DEPENDENCIES) dependencies?: Partial<LiveChatDependencies>) {
+    this.deps = {
+      transaction: dependencies?.transaction ?? withTenant,
+      publish: dependencies?.publish ?? (() => undefined),
+      buffer: dependencies?.buffer ?? new ChatRingBuffer(500),
+      governors: dependencies?.governors ?? new SendGovernors(),
+      targets: dependencies?.targets ?? (async () => []),
+      transports: dependencies?.transports ?? {},
+      ...(dependencies?.now ? { now: dependencies.now } : {}),
+      ...(dependencies?.filters ? { filters: dependencies.filters } : {}),
+    };
+    this.now = this.deps.now ?? (() => new Date());
+  }
+
+  async lives(workspaceId: string): Promise<{ items: LiveSummary[] }> {
+    return this.deps.transaction(workspaceId, async client => {
+      const rows = await client.query<{ channel_id: string; connection_id: string; provider: string; title: string; state: LiveSummary["state"] }>(
+        `SELECT DISTINCT vc.id AS channel_id, c.id AS connection_id, c.provider, vc.name AS title,
+          CASE WHEN vc.observed_status='RUNNING' THEN 'live' WHEN vc.desired_status='RUNNING' THEN 'waiting' ELSE 'ended' END AS state
+         FROM virtual_channels vc JOIN virtual_channel_sources s ON s.virtual_channel_id=vc.id AND s.workspace_id=vc.workspace_id
+         JOIN connections c ON c.id=s.connection_id AND c.workspace_id=s.workspace_id
+         WHERE vc.workspace_id=$1 ORDER BY vc.id, c.id`, [workspaceId]);
+      return { items: rows.rows.map(row => ({ liveStreamId: row.channel_id, connectionId: row.connection_id, provider: row.provider, title: row.title, state: row.state })) };
+    });
+  }
+
+  private async nextSeq(workspaceId: string, channelId: string): Promise<number> {
+    return this.deps.transaction(workspaceId, async client => {
+      await client.query("INSERT INTO live_chat_seq (workspace_id, channel_id, seq) VALUES ($1,$2,0) ON CONFLICT DO NOTHING", [workspaceId, channelId]);
+      const locked = await client.query<{ seq: string | number }>("SELECT seq FROM live_chat_seq WHERE workspace_id=$1 AND channel_id=$2 FOR UPDATE", [workspaceId, channelId]);
+      const seq = Number(locked.rows[0]?.seq ?? 0) + 1;
+      await client.query("UPDATE live_chat_seq SET seq = GREATEST(seq, $3), updated_at = now() WHERE workspace_id=$1 AND channel_id=$2", [workspaceId, channelId, seq]);
+      return seq;
+    });
+  }
+
+  /** Ingest a batch: assign seqs under the channel row lock, insert, publish. */
+  async ingest(workspaceId: string, events: NormalizedChatEvent[]): Promise<IngestResult> {
+    if (events.length === 0) return { inserted: [], duplicates: [] };
+    const byChannel = new Map<string, NormalizedChatEvent[]>();
+    for (const event of events) {
+      const filters = this.deps.filters;
+      if ((filters?.hideCommands && event.text.startsWith("!")) || (filters?.hideBots && event.author.isBot) ||
+        filters?.mutedHandles?.includes(`${event.provider}:${event.author.handle}`) ||
+        filters?.words?.some(word => word.length > 0 && event.text.toLowerCase().includes(word.toLowerCase()))) continue;
+      const list = byChannel.get(event.channelId) ?? [];
+      list.push(event);
+      byChannel.set(event.channelId, list);
+    }
+    const inserted: StoredChatMessage[] = [];
+    const duplicates: string[] = [];
+    for (const [channelId, batch] of byChannel) {
+      const rows = await this.deps.transaction(workspaceId, async client => {
+        // Create-or-take the channel's seq row. INSERT ... ON CONFLICT first so
+        // two first-ever ingests cannot both see "no row" and deadlock-fail.
+        await client.query(
+          `INSERT INTO live_chat_seq (workspace_id, channel_id, seq) VALUES ($1,$2,0) ON CONFLICT DO NOTHING`,
+          [workspaceId, channelId]);
+        const locked = await client.query<{ seq: string | number }>(
+          "SELECT seq FROM live_chat_seq WHERE workspace_id=$1 AND channel_id=$2 FOR UPDATE", [workspaceId, channelId]);
+        const next = Number(locked.rows[0]?.seq ?? 0);
+        const claimed: NormalizedChatEvent[] = [];
+        for (const event of batch) {
+          const claim = await client.query(
+            "INSERT INTO live_chat_seen_events (workspace_id, provider, provider_event_id) VALUES ($1,$2,$3) ON CONFLICT DO NOTHING RETURNING provider_event_id",
+            [workspaceId, event.provider, `message:${event.providerMessageId}`]);
+          if (claim.rowCount) claimed.push(event);
+        }
+        if (claimed.length === 0) return [];
+        const values = claimed.map((event, index) => [
+          workspaceId, channelId, event.connectionId, event.provider, event.providerMessageId,
+          event.author.handle, event.author.displayName ?? null, event.author.avatarUrl ?? null,
+          JSON.stringify(event.author.badges ?? []), authorColor(event.provider, event.author.handle),
+          event.text, event.replyTo ?? null, next + index + 1, event.sentAt, event.receivedAt ?? this.now(),
+          event.source ?? "live-chat",
+        ]);
+        const columns = Array.from({ length: 16 }, (_, i) => values.map(row => row[i]));
+        const result = await client.query<MessageRow>(INSERT_SQL, columns);
+        await client.query(
+          "UPDATE live_chat_seq SET seq = GREATEST(seq, $3), updated_at = now() WHERE workspace_id=$1 AND channel_id=$2",
+          [workspaceId, channelId, next + claimed.length]);
+        return result.rows.map(toStored);
+      });
+      const insertedIds = new Map<string, number>();
+      for (const row of rows) { const key = `${row.provider}:${row.providerMessageId}`; insertedIds.set(key, (insertedIds.get(key) ?? 0) + 1); }
+      for (const message of rows) { this.deps.buffer.push(message); inserted.push(message); }
+      for (const event of batch) {
+        const key = `${event.provider}:${event.providerMessageId}`, count = insertedIds.get(key) ?? 0;
+        if (count === 0) duplicates.push(event.providerMessageId); else insertedIds.set(key, count - 1);
+      }
+      for (const message of rows) {
+        await this.deps.publish(workspaceId, channelId, {
+          kind: "chat", liveStreamId: channelId, channelId, seq: message.seq, message,
+        });
+      }
+    }
+    return { inserted, duplicates };
+  }
+
+  /** A provider disconnect is accepted explicitly, with a shared system notice. */
+  async gap(workspaceId: string, event: NormalizedChatEvent, reason: string): Promise<void> {
+    const result = await this.ingest(workspaceId, [{ ...event, text: `Chat gap: ${reason}`, source: "system" }]);
+    if (result.inserted.length > 0) await this.deps.publish(workspaceId, event.channelId, {
+      kind: "chat", liveStreamId: event.channelId, channelId: event.channelId,
+      seq: await this.nextSeq(workspaceId, event.channelId), provider: event.provider, reason,
+    });
+  }
+
+  /** Cursor page from the durable store (REST fallback path). */
+  async messages(workspaceId: string, channelId: string, query: MessageQuery): Promise<MessagePage> {
+    return this.deps.transaction(workspaceId, async client => {
+      const params: unknown[] = [workspaceId, channelId, query.after ?? 0, query.limit];
+      let filter = "";
+      if (query.provider !== undefined) { params.push(query.provider); filter = " AND provider=$5"; }
+      const result = await client.query<MessageRow>(
+        `SELECT ${SELECT_COLUMNS} FROM live_chat_messages WHERE workspace_id=$1 AND channel_id=$2 AND seq > $3${filter}
+         ORDER BY seq ASC LIMIT $4`, params);
+      const items = result.rows.map(toStored);
+      const nextCursor = items.length === query.limit ? items.at(-1)?.seq : undefined;
+      return { items, ...(nextCursor === undefined ? {} : { nextCursor }) };
+    });
+  }
+
+  /** One message by id (moderation target lookup). */
+  async findMessage(workspaceId: string, channelId: string, messageId: string): Promise<StoredChatMessage | null> {
+    return this.deps.transaction(workspaceId, async client => {
+      const result = await client.query<MessageRow>(
+        `SELECT ${SELECT_COLUMNS} FROM live_chat_messages WHERE workspace_id=$1 AND channel_id=$2 AND id=$3`,
+        [workspaceId, channelId, messageId]);
+      return result.rows[0] ? toStored(result.rows[0]) : null;
+    });
+  }
+
+  /** Latest window straight from the ring buffer (resume path). */
+  resume(liveStreamId: string, lastSeq: number, limit = 500): { messages: StoredChatMessage[]; resync: boolean } {
+    if (!this.deps.buffer.canResume(liveStreamId, lastSeq)) return { messages: [], resync: true };
+    return { messages: this.deps.buffer.after(liveStreamId, lastSeq, limit), resync: false };
+  }
+
+  /** Per-connection capabilities for a channel (§3.5 capabilities endpoint). */
+  async capabilities(workspaceId: string, channelId: string): Promise<LiveChatCapability[]> {
+    return Promise.all((await this.deps.targets(workspaceId, channelId)).map(async target => {
+      const governor = await Promise.resolve().then(() => this.deps.governors.probe(target.provider)).catch(() => ({ state: "degraded" as const, reason: "governor unavailable" }));
+      return {
+        connectionId: target.connectionId, provider: target.provider, read: target.read, reply: target.reply,
+        moderate: target.moderate, state: governor.state === "ok" ? target.state : governor.state ?? target.state,
+        ...(target.reason === undefined && governor.reason === undefined ? {} : { reason: governor.reason ?? target.reason }),
+      };
+    }));
+  }
+
+  /** Reply fan-out: governor per target, one Delivery row per target, and one
+   * stored hub message when at least one target accepted. An unsupported or
+   * failed target NEVER fails the batch (§3.5). */
+  async send(workspaceId: string, channelId: string, request: {
+    text: string; targets: "all" | string[]; replyTo?: string; author: { handle: string };
+  }): Promise<SendOutcome> {
+    const targets = await this.deps.targets(workspaceId, channelId);
+    const parent = request.replyTo ? await this.findMessage(workspaceId, channelId, request.replyTo) : null;
+    if (request.replyTo && !parent) throw new NotFoundException("reply target not found");
+    const selected = request.targets === "all" ? targets : targets.filter(t => request.targets.includes(t.connectionId));
+    if (selected.length === 0) return { message: null, delivery: [], refused: { reason: "no capable target", state: "degraded" } };
+    const delivery = new Map<string, Delivery>();
+    const accepted: ChatTarget[] = [];
+    let refused: SendOutcome["refused"];
+    for (const target of selected) {
+      if (!target.reply || !this.deps.transports[target.provider]) {
+        delivery.set(target.connectionId, { connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: target.reason ?? (!target.reply ? "reply not supported" : "no transport configured") });
+        continue;
+      }
+      const verdict = await Promise.resolve().then(() => this.deps.governors.take(target.provider)).catch(() => ({ allowed: false, state: "degraded" as const, reason: "governor unavailable" }));
+      if (!verdict.allowed) {
+        refused ??= { state: verdict.state ?? "degraded", reason: verdict.reason ?? "refused" };
+        delivery.set(target.connectionId, { connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: verdict.reason ?? "refused" });
+        continue;
+      }
+      delivery.set(target.connectionId, { connectionId: target.connectionId, provider: target.provider, status: "queued" });
+      accepted.push(target);
+    }
+    if (accepted.length === 0) {
+      const first = [...delivery.values()].find(d => d.error);
+      return { message: null, delivery: [...delivery.values()], refused: { reason: refused?.reason ?? first?.error ?? "no target accepted", state: refused?.state ?? "degraded" } };
+    }
+    const outcomes = new Map<string, { providerMessageId: string; sentAt: Date }>();
+    for (const target of accepted) {
+      const transport = this.deps.transports[target.provider];
+      if (!transport) {
+        delivery.set(target.connectionId, { connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: "no transport configured" });
+        continue;
+      }
+      try {
+        const result = await transport.send({ connectionId: target.connectionId, liveRemoteId: target.liveRemoteId, text: request.text, replyTo: parent?.connectionId === target.connectionId ? parent.providerMessageId : undefined });
+        outcomes.set(target.connectionId, result);
+        delivery.set(target.connectionId, { connectionId: target.connectionId, provider: target.provider, status: "sent" });
+      } catch (error) {
+        delivery.set(target.connectionId, { connectionId: target.connectionId, provider: target.provider, status: "failed", error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    // Store our own message once (echoed to every viewer).
+    const primary = accepted.find(t => delivery.get(t.connectionId)?.status === "sent");
+    if (!primary) return { message: null, delivery: [...delivery.values()], refused: { reason: "no transport accepted the send", state: "degraded" } };
+    const primaryResult = outcomes.get(primary.connectionId);
+    if (!primaryResult) throw new Error("missing primary delivery result");
+    const stored = await this.ingest(workspaceId, [{
+      provider: primary.provider,
+      connectionId: primary.connectionId,
+      channelId,
+      providerMessageId: primaryResult.providerMessageId,
+      author: request.author,
+      text: request.text,
+      sentAt: primaryResult.sentAt,
+      receivedAt: this.now(),
+      ...(request.replyTo === undefined ? {} : { replyTo: request.replyTo }),
+      source: "live-chat",
+    }]).then(result => result.inserted[0] ?? null);
+    const deliveryRows = [...delivery.values()];
+    if (stored) {
+      await this.deps.publish(workspaceId, channelId, {
+        kind: "chat", liveStreamId: channelId, channelId, seq: await this.nextSeq(workspaceId, channelId), messageId: stored.id, delivery: deliveryRows,
+      });
+    }
+    return { message: stored, delivery: deliveryRows };
+  }
+
+  /** Moderation fan-out: delete/timeout/ban on every capable target; the local
+   * row is flagged so the panel drops it immediately. */
+  async moderate(workspaceId: string, channelId: string, request: {
+    action: "delete" | "timeout" | "ban"; durationSeconds?: number;
+    message: { id?: string; connectionId?: string; provider: string; providerMessageId: string; authorHandle: string };
+  }): Promise<ModerateOutcome> {
+    const targets = await this.deps.targets(workspaceId, channelId);
+    const delivery: Delivery[] = [];
+    for (const target of targets) {
+      if (!target.moderate) { delivery.push({ connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: target.reason ?? "moderation not supported" }); continue; }
+      if (target.provider !== request.message.provider || (request.message.connectionId && target.connectionId !== request.message.connectionId)) {
+        delivery.push({ connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: "message belongs to another target" }); continue;
+      }
+      const verdict = await Promise.resolve().then(() => this.deps.governors.take(target.provider)).catch(() => ({ allowed: false, state: "degraded" as const, reason: "governor unavailable" }));
+      if (!verdict.allowed) { delivery.push({ connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: verdict.reason }); continue; }
+      const transport = this.deps.transports[target.provider];
+      if (!transport) { delivery.push({ connectionId: target.connectionId, provider: target.provider, status: "unsupported", error: "no transport configured" }); continue; }
+      try {
+        await transport.moderate({ connectionId: target.connectionId, liveRemoteId: target.liveRemoteId,
+          messageRemoteId: request.message.providerMessageId, authorHandle: request.message.authorHandle, action: request.action, ...(request.durationSeconds === undefined ? {} : { durationSeconds: request.durationSeconds }) });
+        delivery.push({ connectionId: target.connectionId, provider: target.provider, status: "sent" });
+      } catch (error) {
+        delivery.push({ connectionId: target.connectionId, provider: target.provider, status: "failed", error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+    if (request.action === "delete" && delivery.some(d => d.status === "sent")) {
+      await this.deps.transaction(workspaceId, async client => {
+        await client.query(
+          "UPDATE live_chat_messages SET is_moderated = true WHERE workspace_id=$1 AND channel_id=$2 AND provider=$3 AND provider_msg_id=$4",
+          [workspaceId, channelId, request.message.provider, request.message.providerMessageId]);
+      });
+    }
+    if (delivery.some(row => row.status === "sent")) await this.deps.publish(workspaceId, channelId, {
+      kind: "chat", liveStreamId: channelId, channelId, seq: await this.nextSeq(workspaceId, channelId),
+      action: request.action, targetMessageId: request.message.id ?? request.message.providerMessageId, targetHandle: request.message.authorHandle,
+    });
+    return { delivery };
+  }
+}
diff --git a/apps/api/src/live-chat/live-chat.units.test.ts b/apps/api/src/live-chat/live-chat.units.test.ts
new file mode 100644
index 0000000..f0f16a0
--- /dev/null
+++ b/apps/api/src/live-chat/live-chat.units.test.ts
@@ -0,0 +1,77 @@
+import { describe, expect, it } from "vitest";
+import { authorColor } from "@tactical-media-broadcast-hub/core";
+import { ChatRingBuffer } from "./ring-buffer.js";
+import { SendGovernors, TokenBucket } from "./governors.js";
+import type { StoredChatMessage } from "./types.js";
+
+describe("send governors", () => {
+  it("token bucket refuses beyond burst and refills over time", () => {
+    let t = 0;
+    const bucket = new TokenBucket({ capacity: 2, refillPerSecond: 1, now: () => t });
+    expect(bucket.tryTake()).toBe(true); expect(bucket.tryTake()).toBe(true);
+    expect(bucket.tryTake()).toBe(false);
+    t += 1000; expect(bucket.tryTake()).toBe(true);
+  });
+  it("quota ledger refuses a send below budget and reports paused:quota", () => {
+    const governors = new SendGovernors({ quotas: { youtube: { budget: 50, costPerCall: 50 } } });
+    expect(governors.take("youtube")).toMatchObject({ allowed: true, state: "ok" }); // insert: 50 of 50 units
+    expect(governors.take("youtube")).toMatchObject({ allowed: false, state: "paused:quota", reason: expect.stringContaining("quota") });
+    expect(governors.probe("youtube").state).toBe("paused:quota");
+  });
+  it("rate exhaustion surfaces paused:rate", () => {
+    const governors = new SendGovernors({ buckets: { twitch: { capacity: 1, refillPerSecond: 0.001 } } });
+    expect(governors.take("twitch").allowed).toBe(true);
+    expect(governors.take("twitch")).toMatchObject({ allowed: false, state: "paused:rate" });
+  });
+});
+
+describe("ring buffer", () => {
+  it("serves resume from the window and demands resync past its edge", () => {
+    const buffer = new ChatRingBuffer(4);
+    for (let seq = 1; seq <= 12; seq += 1) {
+      buffer.push({ ...message(seq), seq });
+    }
+    // The advertised capacity and the resumable window agree.
+    expect(buffer.latest("live-1", 100)).toHaveLength(4);
+    expect(buffer.latest("live-1", 100).at(0)?.seq).toBe(9);
+    expect(buffer.after("live-1", 10)).toHaveLength(2);
+    expect(buffer.canResume("live-1", 8)).toBe(true);   // everything >8 is retained
+    expect(buffer.canResume("live-1", 7)).toBe(false);  // fell out of the window
+    expect(buffer.canResume("live-1", 99)).toBe(false); // ahead of the hub
+  });
+});
+
+function message(seq: number): StoredChatMessage {
+  return {
+    id: `m-${seq}`, seq, liveStreamId: "live-1", connectionId: "conn-1", provider: "mock-livestream",
+    providerMessageId: `pm-${seq}`, author: { handle: `viewer-${seq}`, color: authorColor("mock-livestream", `viewer-${seq}`) },
+    text: `hello ${seq}`, sentAt: new Date(0).toISOString(), receivedAt: new Date(0).toISOString(),
+    isModerated: false, source: "live-chat",
+  };
+}
+
+describe("author identity colour", () => {
+  it("is a pure function of provider:handle", () => {
+    expect(authorColor("twitch", "ada")).toBe(authorColor("twitch", "ada"));
+    expect(authorColor("twitch", "ada")).not.toBe(authorColor("youtube", "ada"));
+    expect(authorColor("twitch", "ada")).toMatch(/^hsl\(\d+ 70% 62%\)$/);
+  });
+});
+
+
+describe("daily quota rollover", () => {
+  it("resets on the next UTC day without replacing the ledger", () => {
+    let now = Date.parse("2026-10-08T23:59:59Z");
+    const governors = new SendGovernors({ quotas: { youtube: { budget: 50, costPerCall: 50 } }, now: () => now });
+    expect(governors.take("youtube").allowed).toBe(true);
+    expect(governors.take("youtube").allowed).toBe(false);
+    now += 1000;
+    expect(governors.take("youtube").allowed).toBe(true);
+  });
+  it("does not charge quota when a token bucket refuses the send", () => {
+    const governors = new SendGovernors({ quotas: { youtube: { budget: 100, costPerCall: 50 } }, buckets: { youtube: { capacity: 1, refillPerSecond: 1 } }, now: () => 0 });
+    expect(governors.take("youtube").allowed).toBe(true);
+    expect(governors.take("youtube").state).toBe("paused:rate");
+    expect(governors.probe("youtube").state).toBe("paused:rate");
+  });
+});
diff --git a/apps/api/src/live-chat/mock-driver.ts b/apps/api/src/live-chat/mock-driver.ts
new file mode 100644
index 0000000..a496b06
--- /dev/null
+++ b/apps/api/src/live-chat/mock-driver.ts
@@ -0,0 +1,91 @@
+/**
+ * Mock-livestream ingestion driver: the deterministic contract/E2E harness
+ * (§3.2). Pulls `getLiveChat` pages from the mock connector and feeds the hub
+ * with normalized events; the connector's own dedupe-free buffer is the
+ * "provider", so replaying a page is exactly the dedupe test.
+ */
+import type { PlatformConnector } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ConnectorConnection, LiveChatMessage } from "@tactical-media-broadcast-hub/core";
+import { authorColor } from "@tactical-media-broadcast-hub/core";
+import type { ChatIngestDriver, IngestHandler, NormalizedChatEvent } from "./types.js";
+
+export interface MockDriverOptions {
+  workspaceId: string;
+  connectionId: string;
+  channelId: string;
+  liveRemoteId: string;
+  /** Poll interval; 0 disables the timer (tests call `poll()` by hand). */
+  intervalMs?: number;
+  onError?: (error: unknown) => void;
+  commentsOnly?: boolean;
+  connection?: ConnectorConnection;
+  pageSize?: number;
+  schedule?: (callback: () => void, delayMs: number) => ReturnType<typeof setInterval>;
+  cancel?: (timer: ReturnType<typeof setInterval>) => void;
+}
+
+export class MockLivestreamDriver implements ChatIngestDriver {
+  readonly provider: string;
+  private handler: IngestHandler | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private cursor: string | undefined;
+  private stopped = false;
+  private inFlight: Promise<NormalizedChatEvent[]> | null = null;
+  constructor(private readonly connector: PlatformConnector, private readonly options: MockDriverOptions) { this.provider = connector.manifest().id; }
+  async start(handler: IngestHandler): Promise<void> {
+    await this.stop();
+    this.handler = handler;
+    this.stopped = false;
+    const intervalMs = this.options.intervalMs ?? 0;
+    if (intervalMs > 0) {
+      const schedule = this.options.schedule ?? ((cb, ms) => setInterval(cb, ms));
+      this.timer = schedule(() => { void this.poll().catch(error => this.options.onError?.(error)); }, intervalMs);
+      this.timer.unref?.();
+    }
+    await this.poll();
+  }
+  /** One poll cycle → hub. Returns the events produced. */
+  poll(): Promise<NormalizedChatEvent[]> {
+    if (this.inFlight) return this.inFlight;
+    this.inFlight = this.pollOnce().finally(() => { this.inFlight = null; });
+    return this.inFlight;
+  }
+  private async pollOnce(): Promise<NormalizedChatEvent[]> {
+    if (!this.handler || this.stopped) return [];
+    const connection = this.options.connection ?? { id: this.options.connectionId, workspaceId: this.options.workspaceId, provider: this.provider,
+      channelId: this.options.channelId, credentialId: { kind: "credential-ref" as const, id: "mock" }, fields: {}, createdAt: new Date() };
+    const page = this.options.commentsOnly ? await this.connector.getComments?.(connection, { onRemoteId: this.options.liveRemoteId, cursor: this.cursor, limit: this.options.pageSize ?? 100 }).then(page => ({
+      ...page, items: page.items.map(comment => ({ id: comment.id, provider: comment.provider, liveStreamId: this.options.liveRemoteId, authorHandle: comment.authorHandle, text: comment.text, sentAt: comment.createdAt, isModerated: false })),
+    })) : await this.connector.getLiveChat?.(
+      connection,
+      { liveRemoteId: this.options.liveRemoteId, cursor: this.cursor, limit: this.options.pageSize ?? 100 },
+    );
+    if (!page || this.stopped || !this.handler) return [];
+    const events = page.items.map((message: LiveChatMessage) => ({ ...toEvent(this.options, message), source: this.options.commentsOnly ? "social-reply" as const : "live-chat" as const }));
+    if (events.length > 0) await this.handler(this.options.workspaceId, events);
+    this.cursor = page.nextCursor;
+    return events;
+  }
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.timer) { (this.options.cancel ?? clearInterval)(this.timer); this.timer = null; }
+    this.handler = null;
+  }
+}
+
+/** Map a connector `LiveChatMessage` to the hub's normalized event. */
+export function toEvent(options: Pick<MockDriverOptions, "connectionId" | "channelId">, message: LiveChatMessage): NormalizedChatEvent {
+  return {
+    provider: message.provider,
+    connectionId: options.connectionId,
+    channelId: options.channelId,
+    providerMessageId: message.id,
+    author: { handle: message.authorHandle },
+    text: message.text,
+    sentAt: message.sentAt,
+    receivedAt: new Date(),
+    source: "live-chat",
+  };
+}
+
+export const mockAuthorColor = authorColor;
diff --git a/apps/api/src/live-chat/redis-governors.ts b/apps/api/src/live-chat/redis-governors.ts
new file mode 100644
index 0000000..0ac6167
--- /dev/null
+++ b/apps/api/src/live-chat/redis-governors.ts
@@ -0,0 +1,41 @@
+import type { OnModuleDestroy } from "@nestjs/common";
+import { RespControlRedis, type ControlRedis } from "../media-control/redis.js";
+import type { GovernorVerdict, SendGovernorOptions } from "./governors.js";
+
+export interface ChatGovernors {
+  take(provider: string, cost?: number): GovernorVerdict | Promise<GovernorVerdict>;
+  probe(provider: string): GovernorVerdict | Promise<GovernorVerdict>;
+}
+/** One atomic check/charge for every API instance. UTC-day keys survive restarts. */
+export const CHAT_GOVERNOR_SCRIPT = `
+local now, capacity, refill, budget, cost, consume = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3]), tonumber(ARGV[4]), tonumber(ARGV[5]), tonumber(ARGV[6])
+local spent = tonumber(redis.call('GET', KEYS[1]) or '0')
+if budget >= 0 and spent + cost > budget then return {0, 'paused:quota', 'daily quota exhausted'} end
+local tokens = capacity
+if capacity > 0 then
+  local old = redis.call('HMGET', KEYS[2], 'tokens', 'at')
+  if old[1] then tokens = math.min(capacity, tonumber(old[1]) + math.max(0, now - tonumber(old[2])) * refill / 1000) end
+  if tokens < 1 then return {0, 'paused:rate', 'send rate budget exhausted'} end
+end
+if consume == 1 then
+  if capacity > 0 then redis.call('HSET', KEYS[2], 'tokens', tokens-1, 'at', now); redis.call('EXPIRE', KEYS[2], 172800) end
+  if budget >= 0 then redis.call('INCRBYFLOAT', KEYS[1], cost); redis.call('EXPIRE', KEYS[1], 172800) end
+end
+return {1, 'ok', ''}`;
+export class RedisChatGovernors implements ChatGovernors, OnModuleDestroy {
+  constructor(private readonly options: SendGovernorOptions, private readonly redis: ControlRedis = new RespControlRedis(process.env.REDIS_URL ?? "redis://localhost:6379")) {}
+  take(provider: string, cost?: number): Promise<GovernorVerdict> { return this.check(provider, true, cost); }
+  probe(provider: string): Promise<GovernorVerdict> { return this.check(provider, false); }
+  private async check(provider: string, consume: boolean, cost?: number): Promise<GovernorVerdict> {
+    const bucket = this.options.buckets?.[provider], quota = this.options.quotas?.[provider];
+    if (!bucket && !quota) return { allowed: true, state: "ok" };
+    const now = this.options.now?.() ?? Date.now(), day = new Date(now).toISOString().slice(0,10), key = encodeURIComponent(provider);
+    const result = await this.redis.eval(CHAT_GOVERNOR_SCRIPT, [`chat:quota:${key}:${day}`, `chat:rate:${key}`],
+      [String(now), String(bucket?.capacity ?? 0), String(bucket?.refillPerSecond ?? 0), String(quota?.budget ?? -1), String(cost ?? quota?.costPerCall ?? 1), consume ? "1" : "0"]);
+    if (!Array.isArray(result)) throw new Error("invalid governor response");
+    const allowed = result[0] === 1, state = result[1];
+    if (state !== "ok" && state !== "paused:rate" && state !== "paused:quota") throw new Error("invalid governor state");
+    return { allowed, state, ...(!allowed ? { reason: String(result[2]) } : {}) };
+  }
+  onModuleDestroy(): void { this.redis.close(); }
+}
diff --git a/apps/api/src/live-chat/ring-buffer.ts b/apps/api/src/live-chat/ring-buffer.ts
new file mode 100644
index 0000000..92ebe2c
--- /dev/null
+++ b/apps/api/src/live-chat/ring-buffer.ts
@@ -0,0 +1,49 @@
+/**
+ * Bounded latest-message window per channel ("ring buffer", §3.3): the hub
+ * keeps the last N stored messages so a `lastSeq` resume can be served
+ * in-process, and the fallback REST cursor path reads the same window.
+ *
+ * The public resume window is exactly N messages, including at eviction edges.
+ */
+import type { StoredChatMessage } from "./types.js";
+
+export class ChatRingBuffer {
+  private readonly map = new Map<string, StoredChatMessage[]>();
+  constructor(private readonly capacity: number = 500) {
+    if (!Number.isInteger(capacity) || capacity < 1) throw new Error("ring buffer capacity must be a positive integer");
+  }
+  push(message: StoredChatMessage): void {
+    const key = `${message.liveStreamId}`;
+    const items = this.map.get(key) ?? [];
+    items.push(message);
+    if (items.length > this.capacity) items.splice(0, items.length - this.capacity);
+    this.map.set(key, items);
+  }
+  /** Latest `limit` messages, oldest first. */
+  latest(liveStreamId: string, limit = this.capacity): StoredChatMessage[] {
+    const items = this.map.get(liveStreamId) ?? [];
+    return items.slice(Math.max(0, items.length - limit));
+  }
+  /** Messages strictly after `after`, oldest first, up to `limit`. */
+  after(liveStreamId: string, after: number, limit = this.capacity): StoredChatMessage[] {
+    return (this.map.get(liveStreamId) ?? []).filter(m => m.seq > after).slice(0, limit);
+  }
+  /** Oldest retained seq; undefined when the window is empty. */
+  oldestSeq(liveStreamId: string): number | undefined {
+    return this.map.get(liveStreamId)?.[0]?.seq;
+  }
+  highestSeq(liveStreamId: string): number {
+    return this.latest(liveStreamId, 1)[0]?.seq ?? 0;
+  }
+  /** Can a resume from `lastSeq` be served from the window? */
+  canResume(liveStreamId: string, lastSeq: number): boolean {
+    if (lastSeq < 0) return false;
+    const items = this.map.get(liveStreamId) ?? [];
+    const highest = items.at(-1)?.seq ?? 0;
+    if (lastSeq > highest) return false;
+    const oldest = items[0]?.seq ?? highest + 1;
+    return lastSeq >= oldest - 1;
+  }
+  drop(liveStreamId: string): void { this.map.delete(liveStreamId); }
+  get size(): number { return this.map.size; }
+}
diff --git a/apps/api/src/live-chat/runtime.ts b/apps/api/src/live-chat/runtime.ts
new file mode 100644
index 0000000..f3fed32
--- /dev/null
+++ b/apps/api/src/live-chat/runtime.ts
@@ -0,0 +1,17 @@
+import { Inject, Injectable, Optional, OnApplicationBootstrap, OnModuleDestroy } from "@nestjs/common";
+import type { LiveChatDependencies } from "./live-chat.service.js";
+import { LiveChatHubService } from "./live-chat.service.js";
+import type { ChatIngestDriver } from "./types.js";
+
+export const LIVE_CHAT_RUNTIME = Symbol("LIVE_CHAT_RUNTIME");
+export type LiveChatRuntimeOptions = Partial<Pick<LiveChatDependencies, "targets" | "transports" | "filters">> & { drivers?: ChatIngestDriver[] };
+@Injectable()
+export class LiveChatRuntime implements OnApplicationBootstrap, OnModuleDestroy {
+  constructor(@Inject(LiveChatHubService) private readonly hub: LiveChatHubService,
+    @Optional() @Inject(LIVE_CHAT_RUNTIME) private readonly options?: LiveChatRuntimeOptions) {}
+  async onApplicationBootstrap(): Promise<void> {
+    try { for (const driver of this.options?.drivers ?? []) await driver.start((workspaceId, events) => this.hub.ingest(workspaceId, events)); }
+    catch (error) { await this.onModuleDestroy(); throw error; }
+  }
+  async onModuleDestroy(): Promise<void> { await Promise.all((this.options?.drivers ?? []).map(driver => driver.stop())); }
+}
diff --git a/apps/api/src/live-chat/shared-poller.ts b/apps/api/src/live-chat/shared-poller.ts
new file mode 100644
index 0000000..62cb24b
--- /dev/null
+++ b/apps/api/src/live-chat/shared-poller.ts
@@ -0,0 +1,49 @@
+import type { IngestHandler, NormalizedChatEvent } from "./types.js";
+import type { ChatGovernors } from "./redis-governors.js";
+
+export interface SharedChatPollerOptions {
+  workspaceId: string;
+  broadcastId: string;
+  provider: string;
+  fetch: (cursor?: string) => Promise<{ events: NormalizedChatEvent[]; nextPageToken?: string; pollingIntervalMillis: number }>;
+  ingest: IngestHandler;
+  governors: ChatGovernors;
+  paused?: (reason: string) => void;
+}
+/** One poll chain per workspace/broadcast. Ref-counted consumers share list quota. */
+export class SharedChatPollers {
+  private readonly entries = new Map<string, { refs: number; stopped: boolean; timer: ReturnType<typeof setTimeout> | null }>();
+  acquire(options: SharedChatPollerOptions): () => void {
+    const key = `${options.workspaceId}:${options.broadcastId}`;
+    const existing = this.entries.get(key);
+    if (existing) { existing.refs += 1; return this.releaseOnce(key); }
+    const entry = { refs: 1, stopped: false, timer: null as ReturnType<typeof setTimeout> | null };
+    this.entries.set(key, entry);
+    let cursor: string | undefined;
+    const poll = async (): Promise<void> => {
+      if (entry.stopped) return;
+      let delay = 1000;
+      const verdict = await options.governors.take(options.provider, 1);
+      if (!verdict.allowed) { options.paused?.(verdict.reason ?? "polling paused"); delay = 60_000; }
+      else {
+        try {
+          const page = await options.fetch(cursor);
+          if (entry.stopped) return;
+          await options.ingest(options.workspaceId, page.events);
+          cursor = page.nextPageToken;
+          delay = Math.max(1, page.pollingIntervalMillis);
+        } catch (error) { options.paused?.(error instanceof Error ? error.message : "polling failed"); }
+      }
+      if (!entry.stopped) { entry.timer = setTimeout(() => { void poll(); }, delay); entry.timer.unref(); }
+    };
+    void poll();
+    return this.releaseOnce(key);
+  }
+  private releaseOnce(key: string): () => void { let active = true; return () => { if (active) { active = false; this.release(key); } }; }
+  private release(key: string): void {
+    const entry = this.entries.get(key);
+    if (!entry || --entry.refs > 0) return;
+    entry.stopped = true; if (entry.timer) clearTimeout(entry.timer); this.entries.delete(key);
+  }
+  close(): void { for (const [key, entry] of this.entries) { entry.refs = 1; this.release(key); } }
+}
diff --git a/apps/api/src/live-chat/twitch-adapter.ts b/apps/api/src/live-chat/twitch-adapter.ts
new file mode 100644
index 0000000..5f88901
--- /dev/null
+++ b/apps/api/src/live-chat/twitch-adapter.ts
@@ -0,0 +1,103 @@
+/**
+ * Twitch adapter: maps the connector's existing chat event shape into the
+ * hub's normalized event (§3.2 read side), and wraps Helix send/moderate
+ * behind the `ChatTransport` port so the hub never branches on a provider.
+ *
+ * The connector buffers EventSub `channel.chat.message` notifications for
+ * `getLiveChat`; that buffer is the read path here. Send/moderate go through
+ * the connector's `sendLiveChatMessage`/`moderateLiveChat` when present, or an
+ * injected Helix transport (contract-tested with mocks — no real creds).
+ */
+import type { PlatformConnector } from "@tactical-media-broadcast-hub/connector-sdk";
+import { MockLivestreamDriver } from "./mock-driver.js";
+import type { ConnectorConnection, LiveChatMessage } from "@tactical-media-broadcast-hub/core";
+import { CapabilityNotSupportedError } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ChatTransport, NormalizedChatEvent } from "./types.js";
+
+export interface TwitchAdapterOptions {
+  workspaceId: string;
+  connectionId: string;
+  channelId: string;
+  /** Provider's live (stream) id — the connector's `liveStreamId`. */
+  liveRemoteId: string;
+}
+
+/** Map a Twitch-shaped `LiveChatMessage` from the connector into the hub event. */
+export function twitchToEvent(options: TwitchAdapterOptions, message: LiveChatMessage): NormalizedChatEvent {
+  return {
+    provider: message.provider,
+    connectionId: options.connectionId,
+    channelId: options.channelId,
+    providerMessageId: message.id,
+    author: { handle: message.authorHandle },
+    text: message.text,
+    sentAt: message.sentAt,
+    receivedAt: new Date(),
+    source: "live-chat",
+  };
+}
+
+export interface HelixChatTransport {
+  /** POST /helix/chat/messages (or an injected fake in tests). */
+  send(request: { connectionId: string; liveRemoteId: string; text: string; replyTo?: string }):
+    Promise<{ providerMessageId: string; sentAt: Date }>;
+  /** DELETE /helix/moderation/chat, timeout/ban endpoints. */
+  moderate(request: {
+    connectionId: string;
+    liveRemoteId: string;
+    messageRemoteId: string;
+    authorHandle?: string;
+    action: "delete" | "timeout" | "ban";
+    durationSeconds?: number;
+  }): Promise<void>;
+}
+
+/**
+ * Twitch send/moderate transport. Prefers an injected Helix implementation
+ * (real creds, S5 phase 1 wiring); otherwise it delegates to the connector's
+ * own methods and surfaces `unsupported` when the connector declares the
+ * capability absent (its IRC adapter is not configured).
+ */
+export class TwitchChatTransport implements ChatTransport {
+  readonly provider: string;
+  constructor(private readonly connector: PlatformConnector, private readonly helix?: HelixChatTransport,
+    private readonly resolveConnection?: (connectionId: string) => Promise<ConnectorConnection>) {
+    this.provider = connector.manifest().id;
+  }
+  private async connection(connectionId: string): Promise<ConnectorConnection> {
+    if (!this.resolveConnection) throw new Error("chat adapter requires a connection resolver");
+    return this.resolveConnection(connectionId);
+  }
+  async send(request: { connectionId: string; liveRemoteId: string; text: string; replyTo?: string }):
+      Promise<{ providerMessageId: string; sentAt: Date }> {
+    if (this.helix) return this.helix.send(request);
+    if (request.replyTo) throw new CapabilityNotSupportedError(this.provider, "threaded reply requires Helix transport");
+    if (this.connector.sendLiveChatMessage) {
+      const sent = await this.connector.sendLiveChatMessage(await this.connection(request.connectionId), { liveRemoteId: request.liveRemoteId, text: request.text });
+      return { providerMessageId: sent.id, sentAt: sent.sentAt };
+    }
+    throw new CapabilityNotSupportedError(this.provider, "chat send");
+  }
+  async moderate(request: {
+    connectionId: string; liveRemoteId: string; messageRemoteId: string;
+    authorHandle?: string;
+    action: "delete" | "timeout" | "ban"; durationSeconds?: number;
+  }): Promise<void> {
+    if (this.helix) return this.helix.moderate(request);
+    if (request.action === "timeout") throw new CapabilityNotSupportedError(this.provider, "timed moderation requires Helix transport");
+    if (this.connector.moderateLiveChat) {
+      await this.connector.moderateLiveChat(await this.connection(request.connectionId), {
+        liveRemoteId: request.liveRemoteId, messageRemoteId: request.messageRemoteId, action: request.action,
+      });
+      return;
+    }
+    throw new CapabilityNotSupportedError(this.provider, "chat moderation");
+  }
+}
+
+/** The existing EventSub read buffer is consumed through the shared driver. */
+export class TwitchChatDriver extends MockLivestreamDriver {
+  constructor(connector: PlatformConnector, options: TwitchAdapterOptions, connection: ConnectorConnection) {
+    super(connector, { ...options, connection, intervalMs: 1000 });
+  }
+}
diff --git a/apps/api/src/live-chat/types.ts b/apps/api/src/live-chat/types.ts
new file mode 100644
index 0000000..ee57e01
--- /dev/null
+++ b/apps/api/src/live-chat/types.ts
@@ -0,0 +1,108 @@
+/**
+ * S5 chat hub — internal ports and normalized shapes.
+ *
+ * The wire contract itself lives in `@tactical-media-broadcast-hub/core` (chat-contract.ts)
+ * and is frozen. This module is the hub implementation: ingestion, sequencing,
+ * fan-out, send governors, device pairing.
+ */
+import type { Delivery, LiveChatCapability, LiveChatMessage, Page } from "@tactical-media-broadcast-hub/core";
+
+/** A provider chat event normalized at the connector boundary. */
+export interface NormalizedChatEvent {
+  provider: string;
+  connectionId: string;
+  channelId: string;
+  /** Provider's own message id — the dedupe key with (workspace, provider). */
+  providerMessageId: string;
+  author: { handle: string; isBot?: boolean; displayName?: string; avatarUrl?: string; badges?: string[] };
+  text: string;
+  sentAt: Date;
+  receivedAt?: Date;
+  replyTo?: string;
+  source?: "live-chat" | "social-reply" | "system";
+}
+
+/** Row written by the hub, already in wire shape. */
+export interface StoredChatMessage {
+  id: string;
+  seq: number;
+  liveStreamId: string;
+  connectionId: string;
+  provider: string;
+  providerMessageId: string;
+  author: { handle: string; displayName?: string; avatarUrl?: string; badges?: string[]; color: string };
+  text: string;
+  sentAt: string;
+  receivedAt: string;
+  isModerated: boolean;
+  replyTo?: string;
+  source: "live-chat" | "social-reply" | "system";
+}
+
+/** Result of ingesting one batch: only the rows actually inserted. */
+export interface IngestResult {
+  inserted: StoredChatMessage[];
+  /** Provider ids already present (dedupe hits) — never re-published. */
+  duplicates: string[];
+}
+
+export interface MessageQuery {
+  after?: number;
+  limit: number;
+  provider?: string;
+}
+
+export interface MessagePage {
+  items: StoredChatMessage[];
+  nextCursor?: number;
+}
+
+export type IngestHandler = (workspaceId: string, events: NormalizedChatEvent[]) => Promise<IngestResult>;
+
+/** Ingestion driver: a platform connection feeding the hub. */
+export interface ChatIngestDriver {
+  readonly provider: string;
+  start(handler: IngestHandler): Promise<void>;
+  stop(): Promise<void>;
+}
+
+/** Per-target send/moderate transport (Helix for Twitch, mock for tests). */
+export interface ChatTransport {
+  readonly provider: string;
+  send(request: { connectionId: string; liveRemoteId: string; text: string; replyTo?: string }):
+    Promise<{ providerMessageId: string; sentAt: Date }>;
+  moderate(request: {
+    connectionId: string;
+    liveRemoteId: string;
+    messageRemoteId: string;
+    authorHandle?: string;
+    action: "delete" | "timeout" | "ban";
+    durationSeconds?: number;
+  }): Promise<void>;
+}
+
+/** A capability-resolved target for a reply/moderation fan-out. */
+export interface ChatTarget {
+  connectionId: string;
+  provider: string;
+  liveRemoteId: string;
+  read: boolean;
+  reply: boolean;
+  moderate: boolean;
+  state: LiveChatCapability["state"];
+  reason?: string;
+}
+
+export interface SendOutcome {
+  message: StoredChatMessage | null;
+  delivery: Delivery[];
+  /** Refused before any transport call (governor or no capable target). */
+  refused?: { reason: string; state: LiveChatCapability["state"] };
+}
+
+export interface ModerateOutcome {
+  delivery: Delivery[];
+}
+
+/** Connector chat page shape (`PlatformConnector.getLiveChat`). */
+export type ConnectorChatPage = Page<LiveChatMessage>;
diff --git a/apps/api/src/live-monitor/README.md b/apps/api/src/live-monitor/README.md
new file mode 100644
index 0000000..ccb1c8f
--- /dev/null
+++ b/apps/api/src/live-monitor/README.md
@@ -0,0 +1,64 @@
+# Monitor signal sources
+
+`POST /live-monitor/webhooks/:endpointId` authenticates providers independently
+of browser sessions. The module installs a raw parser before Nest's JSON parser;
+the request cap is 64 KiB and compressed bodies are refused.
+
+Configure `MONITOR_WEBHOOK_ENDPOINTS` as a server-controlled JSON array:
+
+```json
+[
+  {
+    "endpointId": "<32 server-generated random bytes, encoded as 64 lowercase hex characters>",
+    "workspaceId": "<workspace UUID>",
+    "connectionId": "<connection UUID>",
+    "credentialId": "<credential UUID>",
+    "subscriptionId": "<provider subscription id>"
+  }
+]
+```
+
+The credential must belong to that workspace and connection, have kind
+`monitor-webhook`, and contain a secret of at least 32 bytes sealed with
+`vault.seal(workspaceId, connectionId, secret)`. Disconnection or credential
+revocation disables the endpoint. Mappings contain references, never secrets.
+
+Send these headers:
+
+- `X-Monitor-Event-Id`: a unique provider message id (up to 256 characters).
+- `X-Monitor-Timestamp`: an ISO UTC timestamp within five minutes of ingestion.
+- `X-Monitor-Signature`: `sha256=` followed by lowercase hex HMAC-SHA256 over
+  `eventId + timestamp + rawBody`, using the vaulted secret.
+
+The JSON body is `{ "subscriptionId": "...", "sourceId": "<UUID>",
+"outcome": "ok|fail|error|unavailable" }`. A supplied workspace or connection
+must also match the mapping. The source must belong to the mapped workspace
+and connection. Successful delivery returns 200, replay 409, authentication
+failure 401, unknown endpoint/source 404, invalid JSON 400, oversized body 413.
+
+Replay ids are namespaced by endpoint in `monitor_seen_events`. Verification,
+ownership checks, replay claim, reducer fold, state write and audit share a
+tenant transaction. Journal pruning must retain at least the full ten-minute
+timestamp acceptance span plus a clock margin; this module does not prune it.
+
+`MEDIA_POLLER_SOURCES` entries support `playbackUrl`. Provider `hls` probes that
+URL; provider `peertube` polls the video using the connection's `fields.instanceUrl`
+and also probes `playbackUrl` when supplied. Canonical `video:<id>@<host>` refs
+are supported. Existing mock configuration remains supported.
+
+HLS probes fetch one master and one variant, validate all child URIs through
+WP7, and emit `hls-probe` observations. Decoder reports retain `media-health`
+precedence. VOD/endlist/empty/missing playlists fail; stale segments fail after
+three target durations. Without program dates, successive playlist progression
+provides recency and an initial playlist has the same bounded grace period.
+
+Every outbound fetch uses the shared WP7 egress client and its database host
+bucket (`monitor-probe` or `monitor-api`), including redirect hops. Requests
+have a five-second total deadline, 256 KiB response cap, and 128-reference cap.
+Per-source drivers back off with exponential jitter after failures, honoring
+Retry-After seconds/dates and egress retry delays. Denied probe targets emit
+`unavailable` with a policy reason so the existing reducer can fall back.
+
+Production requires the built `packages/egress` artifact and its host-budget
+migration/grants. Those remain owned by WP7; this module performs no DDL and
+implements no additional limiter.
diff --git a/apps/api/src/live-monitor/live-monitor.controller.ts b/apps/api/src/live-monitor/live-monitor.controller.ts
new file mode 100644
index 0000000..8fcb3da
--- /dev/null
+++ b/apps/api/src/live-monitor/live-monitor.controller.ts
@@ -0,0 +1,84 @@
+import { BadRequestException, Body, Controller, Get, Inject, Param, Post, Query, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { parseId, parseLimit, requireObject, requireSession, requireString } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { LiveMonitorService, type MonitorPage } from "./live-monitor.service.js";
+import { LiveMonitorPoller } from "./poller/poller.js";
+import type { MonitorObservation, MonitorRowState, ObservationOutcome, SignalTier } from "./reducer.js";
+
+@Controller("live-monitor")
+@UseGuards(RbacGuard)
+export class LiveMonitorController {
+  constructor(
+    @Inject(LiveMonitorService) private readonly monitor: LiveMonitorService,
+    @Inject(LiveMonitorPoller) private readonly poller: LiveMonitorPoller,
+  ) {}
+
+  @Post("poller/:action")
+  @RequirePermission("media.manage")
+  async controlPoller(@Param("action") action: string): Promise<{ running: boolean }> {
+    if (action === "start") return this.poller.start();
+    if (action === "stop") return this.poller.stop();
+    throw new BadRequestException("action must be start or stop");
+  }
+
+  @Post(":sourceId/observations")
+  @RequirePermission("media.manage")
+  async record(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("sourceId") sourceId: string,
+    @Body() body: unknown,
+  ): Promise<MonitorRowState> {
+    const session = requireSession(request);
+    return this.monitor.recordObservation(session.workspaceId, parseId(sourceId, "sourceId"),
+      parseObservation(body), { userId: session.userId, role: session.role });
+  }
+
+  @Get()
+  @RequirePermission("media.view")
+  async list(
+    @Req() request: Request & AuthenticatedRequest,
+    @Query("cursor") cursor: string | undefined,
+    @Query("limit") limit: string | undefined,
+  ): Promise<MonitorPage> {
+    return this.monitor.listStates(requireSession(request).workspaceId, cursor, parseLimit(limit, 50, 200));
+  }
+
+  @Get(":id")
+  @RequirePermission("media.view")
+  async get(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+  ): Promise<MonitorRowState> {
+    return this.monitor.getState(requireSession(request).workspaceId, parseId(id));
+  }
+}
+
+function parseObservation(value: unknown): MonitorObservation {
+  const body = requireObject(value, "body");
+  const tier = body.tier;
+  if (tier !== "media-health" && tier !== "hls-probe" && tier !== "webhook" && tier !== "api-poll") {
+    throw new BadRequestException("tier is invalid");
+  }
+  const observedAt = requireString(body.observedAt, "observedAt");
+  if (!Number.isFinite(Date.parse(observedAt))) throw new BadRequestException("observedAt must be a timestamp");
+  const payload = requireObject(body.payload, "payload");
+  const outcome = payload.outcome;
+  if (outcome !== "ok" && outcome !== "fail" && outcome !== "error" && outcome !== "unavailable") {
+    throw new BadRequestException("outcome is invalid");
+  }
+  if (payload.mediaPresent !== undefined && typeof payload.mediaPresent !== "boolean") {
+    throw new BadRequestException("mediaPresent must be boolean");
+  }
+  return {
+    tier: tier as SignalTier,
+    observedAt,
+    receivedAt: new Date().toISOString(),
+    ...(body.providerEventId === undefined ? {} : { providerEventId: requireString(body.providerEventId, "providerEventId") }),
+    payload: {
+      outcome: outcome as ObservationOutcome,
+      ...(payload.reason === undefined ? {} : { reason: requireString(payload.reason, "reason") }),
+      ...(payload.mediaPresent === undefined ? {} : { mediaPresent: payload.mediaPresent as boolean }),
+    },
+  };
+}
diff --git a/apps/api/src/live-monitor/live-monitor.integration.test.ts b/apps/api/src/live-monitor/live-monitor.integration.test.ts
new file mode 100644
index 0000000..19cc5ca
--- /dev/null
+++ b/apps/api/src/live-monitor/live-monitor.integration.test.ts
@@ -0,0 +1,81 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+import { LiveMonitorService, type LiveMonitorDependencies } from "./live-monitor.service.js";
+
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+const appPool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+async function asTenant<T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await appPool.connect();
+  try {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+describe.skipIf(!dbAvailable)("live monitor CAS (live DB)", () => {
+  let workspaceId: string;
+  let sourceId: string;
+  let service: LiveMonitorService;
+
+  beforeAll(async () => {
+    await runMigrations(process.env.MIGRATIONS_DIR ?? join(process.cwd(), "migrations"));
+    const workspace = await ownerPool.query(
+      "INSERT INTO workspaces (name, slug) VALUES ('Monitor integration', $1) RETURNING id",
+      [`monitor-${randomUUID()}`],
+    );
+    workspaceId = String(workspace.rows[0]?.id);
+    sourceId = await asTenant(workspaceId, async (client) => {
+      const connection = await client.query(
+        "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-livestream', 'monitor') RETURNING id",
+        [workspaceId],
+      );
+      const source = await client.query(
+        "INSERT INTO source_monitor_states (workspace_id, connection_id, remote_ref) VALUES ($1, $2, 'live:cas') RETURNING id",
+        [workspaceId, connection.rows[0]?.id],
+      );
+      return String(source.rows[0]?.id);
+    });
+    const dependencies: LiveMonitorDependencies = { tenantTransaction: asTenant };
+    service = new LiveMonitorService(dependencies);
+  });
+
+  afterAll(async () => {
+    if (workspaceId !== undefined) await ownerPool.query("DELETE FROM workspaces WHERE id = $1", [workspaceId]);
+    await appPool.end();
+    await ownerPool.end();
+  });
+
+  it("serializes two recorders and keeps one transition per successful CAS", async () => {
+    const observedAt = new Date().toISOString();
+    const [first, second] = await Promise.all([
+      service.recordObservation(workspaceId, sourceId, {
+        tier: "api-poll", observedAt, receivedAt: observedAt, payload: { outcome: "ok" },
+      }),
+      service.recordObservation(workspaceId, sourceId, {
+        tier: "hls-probe", observedAt, receivedAt: observedAt, payload: { outcome: "ok" },
+      }),
+    ]);
+    expect([first.version, second.version].sort()).toEqual([1, 2]);
+    const current = await service.getState(workspaceId, sourceId);
+    expect(current.version).toBe(2);
+    expect(current.authoritativeTier).toBe("hls-probe");
+    const audit = await asTenant(workspaceId, (client) => client.query(
+      "SELECT count(*)::int AS count FROM audit_log WHERE action = 'monitor.state_changed' AND target_id = $1",
+      [sourceId],
+    ));
+    expect(audit.rows[0]?.count).toBe(1);
+  });
+});
diff --git a/apps/api/src/live-monitor/live-monitor.module.ts b/apps/api/src/live-monitor/live-monitor.module.ts
new file mode 100644
index 0000000..8931b4e
--- /dev/null
+++ b/apps/api/src/live-monitor/live-monitor.module.ts
@@ -0,0 +1,19 @@
+import { Inject, Module } from "@nestjs/common";
+import { HttpAdapterHost } from "@nestjs/core";
+import type { ExpressAdapter } from "@nestjs/platform-express";
+import { LiveMonitorController } from "./live-monitor.controller.js";
+import { LiveMonitorService } from "./live-monitor.service.js";
+import { LiveMonitorPoller } from "./poller/poller.js";
+import { MonitorWebhookController } from "./webhook.controller.js";
+import { MonitorWebhookService, WEBHOOK_MAX_BYTES } from "./webhook.service.js";
+
+@Module({ controllers: [LiveMonitorController, MonitorWebhookController], providers: [LiveMonitorService, LiveMonitorPoller, MonitorWebhookService], exports: [LiveMonitorService] })
+export class LiveMonitorModule {
+  constructor(@Inject(HttpAdapterHost) adapter: HttpAdapterHost) {
+    // Installed while Nest creates modules, before init registers its default JSON parser.
+    (adapter.httpAdapter as ExpressAdapter).useBodyParser("raw", false, {
+      type: (request: { url?: string }) => request.url?.startsWith("/live-monitor/webhooks/") === true,
+      limit: WEBHOOK_MAX_BYTES, inflate: false,
+    });
+  }
+}
diff --git a/apps/api/src/live-monitor/live-monitor.service.ts b/apps/api/src/live-monitor/live-monitor.service.ts
new file mode 100644
index 0000000..db6938e
--- /dev/null
+++ b/apps/api/src/live-monitor/live-monitor.service.ts
@@ -0,0 +1,181 @@
+import { BadRequestException, ConflictException, Inject, Injectable, NotFoundException, Optional } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+import { isUuid } from "../http/validation.js";
+import { applyObservation, type MonitorObservation, type MonitorRowState, type MonitorState,
+  type SignalTier, type TierStatus, type MonitorPolicy, DEFAULT_MONITOR_POLICY } from "./reducer.js";
+
+export interface MonitorActor { userId: string | null; role: string }
+export interface MonitorPage { items: MonitorRowState[]; nextCursor?: string }
+export interface LiveMonitorDependencies {
+  tenantTransaction: typeof withTenant;
+  policy?: Partial<MonitorPolicy>;
+}
+export const LIVE_MONITOR_DEPENDENCIES = Symbol("LIVE_MONITOR_DEPENDENCIES");
+
+@Injectable()
+export class LiveMonitorService {
+  private readonly dependencies: LiveMonitorDependencies;
+  private readonly policy: MonitorPolicy;
+
+  constructor(@Optional() @Inject(LIVE_MONITOR_DEPENDENCIES) dependencies?: Partial<LiveMonitorDependencies>) {
+    this.dependencies = { tenantTransaction: withTenant, ...dependencies };
+    this.policy = { ...DEFAULT_MONITOR_POLICY, ...dependencies?.policy };
+  }
+
+  async recordObservation(
+    workspaceId: string,
+    sourceId: string,
+    observation: MonitorObservation,
+    actor: MonitorActor = { userId: null, role: "monitor" },
+  ): Promise<MonitorRowState> {
+    validateObservation(observation);
+    return this.dependencies.tenantTransaction(workspaceId, (client) =>
+      this.recordObservationInTransaction(client, workspaceId, sourceId, observation, actor));
+  }
+
+  /** Webhook verification, durable replay claim and reduction share one transaction. */
+  async recordObservationInTransaction(
+    client: PoolClient, workspaceId: string, sourceId: string, observation: MonitorObservation,
+    actor: MonitorActor = { userId: null, role: "monitor" }, rejectReplay = false,
+  ): Promise<MonitorRowState> {
+    validateObservation(observation);
+    let seenInserted = false;
+    for (let attempt = 0; attempt < 5; attempt += 1) {
+      const locked = await client.query("SELECT * FROM source_monitor_states WHERE id = $1 FOR UPDATE", [sourceId]);
+      if (locked.rowCount !== 1) throw new NotFoundException(`live source ${sourceId} not found`);
+      const current = fromRow(locked.rows[0]);
+      if (observation.providerEventId !== undefined && !seenInserted) {
+        const seen = await client.query(
+          `INSERT INTO monitor_seen_events (workspace_id, provider_event_id, source_monitor_state_id)
+           VALUES ($1, $2, $3) ON CONFLICT (workspace_id, provider_event_id) DO NOTHING RETURNING provider_event_id`,
+          [workspaceId, observation.providerEventId, sourceId],
+        );
+        if (seen.rowCount === 0) {
+          if (rejectReplay) throw new ConflictException("webhook event already received");
+          return current;
+        }
+        seenInserted = true;
+      }
+      const reduction = applyObservation(current, observation, this.policy);
+      if (reduction.state === current) return current;
+      const next = reduction.state;
+      const changed = await client.query(
+        `UPDATE source_monitor_states SET state = $2, version = $3, authoritative_tier = $4,
+           last_media_health_at = $5, last_hls_probe_at = $6, last_webhook_at = $7,
+           last_api_poll_at = $8, tier_status = $9, ok_streak = $10, fail_streak = $11,
+           state_entered_at = $12, hold_until = $13, cooldown_until = $14,
+           previous_state = $15, last_transition_at = $16, last_transition_reason = $17,
+           updated_at = $18
+         WHERE id = $1 AND version = $19 RETURNING *`,
+        [sourceId, next.state, next.version, next.authoritativeTier, next.lastMediaHealthAt,
+          next.lastHlsProbeAt, next.lastWebhookAt, next.lastApiPollAt, next.tierStatus,
+          next.okStreak, next.failStreak, next.stateEnteredAt, next.holdUntil, next.cooldownUntil,
+          next.previousState, next.lastTransitionAt, next.lastTransitionReason, next.updatedAt, current.version],
+      );
+      if (changed.rowCount !== 1) continue;
+      if (reduction.transition !== undefined) {
+        await client.query(
+          "SELECT audit_append($1, $2, $3, 'monitor.state_changed', 'source_monitor_state', $4, $5)",
+          [workspaceId, actor.userId, actor.role, sourceId, {
+            from: reduction.transition.from, to: reduction.transition.to,
+            version: reduction.transition.version, reason: reduction.transition.reason,
+            tier: next.authoritativeTier,
+          }],
+        );
+      }
+      return fromRow(changed.rows[0]);
+    }
+    throw new Error(`live source ${sourceId} CAS conflict did not settle`);
+  }
+
+  async getState(workspaceId: string, sourceId: string): Promise<MonitorRowState> {
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const found = await client.query("SELECT * FROM source_monitor_states WHERE id = $1", [sourceId]);
+      if (found.rowCount !== 1) throw new NotFoundException(`live source ${sourceId} not found`);
+      return fromRow(found.rows[0]);
+    });
+  }
+
+  async getStates(workspaceId: string, sourceIds: string[]): Promise<MonitorRowState[]> {
+    if (sourceIds.length === 0) return [];
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const found = await client.query("SELECT * FROM source_monitor_states WHERE id = ANY($1::uuid[])", [sourceIds]);
+      return found.rows.map(fromRow);
+    });
+  }
+
+  async listStates(workspaceId: string, cursor?: string, limit = 50): Promise<MonitorPage> {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new BadRequestException("limit must be an integer between 1 and 200");
+    }
+    const decoded = cursor === undefined || cursor === "" ? undefined : decodeCursor(cursor);
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT * FROM source_monitor_states
+         WHERE ($1::timestamptz IS NULL OR (created_at, id) < ($1::timestamptz, $2::uuid))
+         ORDER BY created_at DESC, id DESC LIMIT $3`,
+        [decoded?.createdAt ?? null, decoded?.id ?? null, limit + 1],
+      );
+      const rows = result.rows.map(fromRow);
+      const items = rows.slice(0, limit);
+      const last = items[items.length - 1];
+      return { items, ...(rows.length > limit && last !== undefined
+        ? { nextCursor: Buffer.from(JSON.stringify({ createdAt: last.createdAt, id: last.id })).toString("base64url") }
+        : {}) };
+    });
+  }
+}
+
+function validateObservation(value: MonitorObservation): void {
+  if (!(["media-health", "hls-probe", "webhook", "api-poll"] as string[]).includes(value.tier)) {
+    throw new BadRequestException("invalid observation tier");
+  }
+  if (!Number.isFinite(Date.parse(value.observedAt)) || !Number.isFinite(Date.parse(value.receivedAt))) {
+    throw new BadRequestException("observation timestamps must be valid");
+  }
+  if (!(["ok", "fail", "error", "unavailable"] as string[]).includes(value.payload.outcome)) {
+    throw new BadRequestException("invalid observation outcome");
+  }
+  if (value.providerEventId !== undefined && value.providerEventId.trim() === "") {
+    throw new BadRequestException("providerEventId must be non-empty");
+  }
+}
+
+function fromRow(raw: unknown): MonitorRowState {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new Error("invalid monitor row");
+  const row = raw as Record<string, unknown>;
+  const version = Number(row.version);
+  if (!Number.isSafeInteger(version)) throw new Error("monitor version exceeds safe integer range");
+  return {
+    id: String(row.id), workspaceId: String(row.workspace_id), connectionId: String(row.connection_id),
+    remoteRef: String(row.remote_ref), state: row.state as MonitorState, version,
+    authoritativeTier: row.authoritative_tier as SignalTier | null,
+    lastMediaHealthAt: dateOrNull(row.last_media_health_at), lastHlsProbeAt: dateOrNull(row.last_hls_probe_at),
+    lastWebhookAt: dateOrNull(row.last_webhook_at), lastApiPollAt: dateOrNull(row.last_api_poll_at),
+    tierStatus: row.tier_status as Partial<Record<SignalTier, TierStatus>>,
+    okStreak: Number(row.ok_streak), failStreak: Number(row.fail_streak),
+    stateEnteredAt: dateOrNull(row.state_entered_at) ?? "",
+    holdUntil: dateOrNull(row.hold_until), cooldownUntil: dateOrNull(row.cooldown_until),
+    previousState: row.previous_state as MonitorState | null,
+    lastTransitionAt: dateOrNull(row.last_transition_at), lastTransitionReason: row.last_transition_reason as string | null,
+    createdAt: dateOrNull(row.created_at) ?? "", updatedAt: dateOrNull(row.updated_at) ?? "",
+  };
+}
+
+function dateOrNull(value: unknown): string | null {
+  return value === null || value === undefined ? null : new Date(String(value)).toISOString();
+}
+
+function decodeCursor(value: string): { createdAt: string; id: string } {
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(value, "base64url").toString("utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("invalid cursor");
+    const row = parsed as Record<string, unknown>;
+    if (typeof row.createdAt !== "string" || !Number.isFinite(Date.parse(row.createdAt))
+      || typeof row.id !== "string" || !isUuid(row.id)) throw new Error("invalid cursor");
+    return { createdAt: row.createdAt, id: row.id };
+  } catch {
+    throw new BadRequestException("cursor is invalid");
+  }
+}
diff --git a/apps/api/src/live-monitor/poller/backoff-driver.ts b/apps/api/src/live-monitor/poller/backoff-driver.ts
new file mode 100644
index 0000000..5676244
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/backoff-driver.ts
@@ -0,0 +1,39 @@
+import type { MonitorObservation, SignalTier } from "../reducer.js";
+import type { PollDriver } from "./driver.js";
+import { MonitorHttpError, retryAfterMs } from "./egress.js";
+
+/** Scheduling state only: all host admission/debits remain in packages/egress. */
+export class BackoffPollDriver implements PollDriver {
+  private failures = 0;
+  private retryAt = 0;
+  constructor(
+    private readonly driver: PollDriver, private readonly tier: SignalTier,
+    private readonly now: () => number = Date.now, private readonly random: () => number = Math.random,
+  ) {}
+  get nextAttemptAt(): number { return this.retryAt; }
+
+  async poll(): Promise<MonitorObservation[]> {
+    if (this.now() < this.retryAt) return [];
+    try {
+      const observations = await this.driver.poll();
+      this.failures = 0;
+      this.retryAt = 0;
+      return observations;
+    } catch (error) {
+      const now = this.now();
+      const metadata = error as { code?: string; retryAfterMs?: number } | null;
+      const transient = error instanceof MonitorHttpError && (error.status === 429 || error.status >= 500)
+        || metadata?.code === "BUDGET_EXHAUSTED" || metadata?.code === "BUDGET_UNAVAILABLE"
+        || metadata?.code === "NETWORK_ERROR" || metadata?.code === "TIMEOUT" || metadata?.code === "ABORTED";
+      this.failures += 1;
+      const delay = Math.min(120_000, 1000 * 2 ** Math.min(7, this.failures - 1));
+      const serverDelay = error instanceof MonitorHttpError ? retryAfterMs(error.headers, now) : metadata?.retryAfterMs ?? 0;
+      this.retryAt = now + Math.max(serverDelay, delay * (0.8 + this.random() * 0.4));
+      const policyDenied = ["DENIED_PRIVATE_ADDRESS", "SCHEME_DENIED", "PORT_DENIED", "ORIGIN_DENIED", "INVALID_URL", "DNS_FAILED"].includes(metadata?.code ?? "");
+      const timestamp = new Date(now).toISOString();
+      return [{ tier: this.tier, observedAt: timestamp, receivedAt: timestamp,
+        payload: { outcome: transient || policyDenied ? "unavailable" : "error",
+          reason: policyDenied ? `egress-policy:${metadata?.code}` : transient ? "monitor-backoff" : "monitor-probe-error" } }];
+    }
+  }
+}
diff --git a/apps/api/src/live-monitor/poller/driver.ts b/apps/api/src/live-monitor/poller/driver.ts
new file mode 100644
index 0000000..3316095
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/driver.ts
@@ -0,0 +1,7 @@
+import type { MonitorObservation } from "../reducer.js";
+
+/** A provider probe emits observations ordered by its own source clock. */
+export interface PollDriver {
+  poll(): Promise<MonitorObservation[]>;
+}
+
diff --git a/apps/api/src/live-monitor/poller/egress.ts b/apps/api/src/live-monitor/poller/egress.ts
new file mode 100644
index 0000000..fe3eddb
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/egress.ts
@@ -0,0 +1,96 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { pool } from "../../db/client.js";
+import type { createEgressClient, EgressPolicy, rewriteSegmentUris, validateMasterPlaylist } from "../../../../../packages/egress/src/index.js";
+
+type EgressPackage = typeof import("../../../../../packages/egress/src/index.js");
+export interface MonitorEgress {
+  egressFetch: ReturnType<typeof createEgressClient>["egressFetch"];
+  policy: EgressPolicy;
+  validateMasterPlaylist: typeof validateMasterPlaylist;
+  rewriteSegmentUris: typeof rewriteSegmentUris;
+}
+export const MONITOR_TIMEOUT_MS = 5_000;
+export const MONITOR_MAX_BYTES = 256 * 1024;
+
+const nativeImport = new Function("specifier", "return import(specifier)") as (specifier: string) => Promise<EgressPackage>;
+let shared: Promise<MonitorEgress> | undefined;
+
+/** ESM package is loaded natively because the API emits CommonJS. No local limiter. */
+export function monitorEgress(): Promise<MonitorEgress> {
+  shared ??= (async () => {
+    for (const start of [process.cwd(), __dirname]) {
+      for (let root = start; ; root = dirname(root)) {
+        const directory = resolve(root, "packages/egress");
+        const files = process.env.NODE_ENV === "production" ? ["dist/index.js"] : ["src/index.ts", "dist/index.js"];
+        for (const file of files) {
+          const path = resolve(directory, file);
+          if (!existsSync(path)) continue;
+          const pkg = await nativeImport(pathToFileURL(path).href);
+          const client = pkg.createEgressClient({ pool, timeoutMs: MONITOR_TIMEOUT_MS, maxResponseBytes: MONITOR_MAX_BYTES,
+            hostClasses: {
+              "monitor-probe": { capacity: 3, refillPerInterval: 10 },
+              "monitor-api": { capacity: 3, refillPerInterval: 10 },
+            } });
+          return { ...client, validateMasterPlaylist: pkg.validateMasterPlaylist, rewriteSegmentUris: pkg.rewriteSegmentUris };
+        }
+        if (dirname(root) === root) break;
+      }
+    }
+    throw new Error("Build packages/egress before starting the live monitor");
+  })();
+  return shared;
+}
+
+export class MonitorHttpError extends Error {
+  constructor(readonly status: number, readonly headers: Headers) { super(`monitor HTTP ${status}`); }
+}
+
+/** Retry-After remains a lower bound, including HTTP dates; never retry early. */
+export function retryAfterMs(headers: Headers, now: number): number {
+  const raw = headers.get("retry-after");
+  if (raw === null) return 0;
+  if (/^\d+(?:\.\d+)?$/.test(raw.trim())) {
+    const delay = Number(raw) * 1000;
+    return Number.isFinite(delay) ? delay : 0;
+  }
+  const deadline = Date.parse(raw);
+  return Number.isFinite(deadline) ? Math.max(0, deadline - now) : 0;
+}
+
+/** Caps body reads even for injected clients, which need not buffer like WP7. */
+export async function boundedText(response: Response, signal: AbortSignal): Promise<string> {
+  if (!response.body) return "";
+  const reader = response.body.getReader();
+  const chunks: Buffer[] = [];
+  let size = 0;
+  const cancel = () => { void reader.cancel().catch(() => undefined); };
+  signal.addEventListener("abort", cancel, { once: true });
+  try {
+    for (;;) {
+      if (signal.aborted) throw new Error("monitor deadline exceeded");
+      const part = await reader.read();
+      if (part.done) break;
+      size += part.value.byteLength;
+      if (size > MONITOR_MAX_BYTES) throw new Error("monitor response exceeds size cap");
+      chunks.push(Buffer.from(part.value));
+    }
+    if (signal.aborted) throw new Error("monitor deadline exceeded");
+    return Buffer.concat(chunks).toString("utf8");
+  } finally {
+    signal.removeEventListener("abort", cancel);
+    void reader.cancel().catch(() => undefined);
+  }
+}
+
+/** Covers DNS/URI validation as well as fetch and body consumption. */
+export async function monitorDeadline<T>(run: (signal: AbortSignal) => Promise<T>): Promise<T> {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_resolve, reject) => {
+    timer = setTimeout(() => { controller.abort(); reject(new Error("monitor deadline exceeded")); }, MONITOR_TIMEOUT_MS);
+  });
+  try { return await Promise.race([run(controller.signal), timeout]); }
+  finally { clearTimeout(timer); controller.abort(); }
+}
diff --git a/apps/api/src/live-monitor/poller/fixtures/live.m3u8 b/apps/api/src/live-monitor/poller/fixtures/live.m3u8
new file mode 100644
index 0000000..bdcd64a
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/fixtures/live.m3u8
@@ -0,0 +1,8 @@
+#EXTM3U
+#EXT-X-TARGETDURATION:6
+#EXT-X-MEDIA-SEQUENCE:20
+#EXT-X-PROGRAM-DATE-TIME:2026-01-01T00:00:00Z
+#EXTINF:6,
+segment20.ts
+#EXTINF:6,
+segment21.ts
diff --git a/apps/api/src/live-monitor/poller/fixtures/malformed.m3u8 b/apps/api/src/live-monitor/poller/fixtures/malformed.m3u8
new file mode 100644
index 0000000..4c28046
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/fixtures/malformed.m3u8
@@ -0,0 +1,4 @@
+#EXTM3U
+#EXT-X-TARGETDURATION:garbage
+#EXTINF:6,
+segment20.ts
diff --git a/apps/api/src/live-monitor/poller/fixtures/master.m3u8 b/apps/api/src/live-monitor/poller/fixtures/master.m3u8
new file mode 100644
index 0000000..a0ab2f3
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/fixtures/master.m3u8
@@ -0,0 +1,5 @@
+#EXTM3U
+#EXT-X-STREAM-INF:BANDWIDTH=800000
+live.m3u8
+#EXT-X-STREAM-INF:BANDWIDTH=2000000
+unused.m3u8
diff --git a/apps/api/src/live-monitor/poller/fixtures/offline.m3u8 b/apps/api/src/live-monitor/poller/fixtures/offline.m3u8
new file mode 100644
index 0000000..ba56782
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/fixtures/offline.m3u8
@@ -0,0 +1,6 @@
+#EXTM3U
+#EXT-X-PLAYLIST-TYPE:VOD
+#EXT-X-TARGETDURATION:6
+#EXTINF:6,
+segment20.ts
+#EXT-X-ENDLIST
diff --git a/apps/api/src/live-monitor/poller/hls-driver.ts b/apps/api/src/live-monitor/poller/hls-driver.ts
new file mode 100644
index 0000000..3e363ee
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/hls-driver.ts
@@ -0,0 +1,127 @@
+import type { MonitorObservation } from "../reducer.js";
+import type { PollDriver } from "./driver.js";
+import { boundedText, monitorDeadline, MonitorHttpError, type MonitorEgress } from "./egress.js";
+
+export interface HlsMediaPlaylist {
+  targetDuration: number;
+  sequence: number;
+  segments: Array<{ uri: string; duration: number; endAt?: number }>;
+  ended: boolean;
+  vod: boolean;
+}
+
+export function parseMediaPlaylist(text: string): HlsMediaPlaylist {
+  const lines = text.replace(/^\uFEFF/, "").split(/\r?\n/).map((line) => line.trim());
+  if (lines[0] !== "#EXTM3U" || text.includes("\0")) throw new Error("malformed HLS header");
+  let targetDuration = 0;
+  let sequence = 0;
+  let duration: number | undefined;
+  let programTime: number | undefined;
+  let ended = false;
+  let vod = false;
+  const segments: HlsMediaPlaylist["segments"] = [];
+  for (const line of lines.slice(1)) {
+    if (line.startsWith("#EXT-X-TARGETDURATION:")) {
+      const raw = line.slice(22);
+      if (targetDuration || !/^\d+$/.test(raw)) throw new Error("invalid HLS target duration");
+      targetDuration = Number(raw);
+    } else if (line.startsWith("#EXT-X-MEDIA-SEQUENCE:")) {
+      const raw = line.slice(22);
+      if (!/^\d+$/.test(raw) || !Number.isSafeInteger(Number(raw))) throw new Error("invalid HLS sequence");
+      sequence = Number(raw);
+    } else if (line.startsWith("#EXT-X-PLAYLIST-TYPE:")) {
+      const type = line.slice(21);
+      if (type !== "EVENT" && type !== "VOD") throw new Error("invalid HLS playlist type");
+      vod = type === "VOD";
+    } else if (line.startsWith("#EXT-X-PROGRAM-DATE-TIME:")) {
+      programTime = Date.parse(line.slice(25));
+      if (!Number.isFinite(programTime)) throw new Error("invalid HLS program time");
+    } else if (line.startsWith("#EXTINF:")) {
+      if (duration !== undefined) throw new Error("HLS segment URI missing");
+      const raw = line.slice(8).split(",")[0] ?? "";
+      if (!/^\d+(?:\.\d+)?$/.test(raw)) throw new Error("invalid HLS duration");
+      duration = Number(raw);
+      if (!Number.isFinite(duration) || duration <= 0) throw new Error("invalid HLS duration");
+    } else if (line === "#EXT-X-ENDLIST") ended = true;
+    else if (line && !line.startsWith("#")) {
+      if (duration === undefined) throw new Error("HLS segment duration missing");
+      if (programTime !== undefined) programTime += duration * 1000;
+      segments.push({ uri: line, duration, ...(programTime === undefined ? {} : { endAt: programTime }) });
+      duration = undefined;
+    }
+  }
+  if (duration !== undefined || !Number.isSafeInteger(targetDuration) || targetDuration <= 0 || targetDuration > 3600
+    || segments.some((segment) => Math.round(segment.duration) > targetDuration) || segments.length > 128) {
+    throw new Error("invalid HLS media playlist");
+  }
+  return { targetDuration, sequence, segments, ended, vod };
+}
+
+/** Playlist ground truth uses hls-probe, below decoder media-health and above provider signals. */
+export class HlsProbeDriver implements PollDriver {
+  private previous: { fingerprint: string; advancedAt: number; playlistUrl: string } | undefined;
+  constructor(private readonly playbackUrl: string, private readonly egress: MonitorEgress,
+    private readonly now: () => number = Date.now) {}
+
+  async poll(): Promise<MonitorObservation[]> {
+    return monitorDeadline(async (signal) => {
+      let url = this.playbackUrl;
+      let response = await this.fetch(url, signal);
+      if (response.status === 404 || response.status === 410) return [this.observation(false, "hls-missing")];
+      let text = await boundedText(response, signal);
+      url = response.url || url;
+      // Bound URI/DNS work before the WP7 helper validates every reference (including keys/maps).
+      this.capReferences(text);
+      if (/^#EXT-X-STREAM-INF:/m.test(text)) {
+        await this.egress.validateMasterPlaylist(text, url, this.egress.policy);
+        const lines = text.split(/\r?\n/).map((line) => line.trim());
+        const variantTag = lines.findIndex((line) => line.startsWith("#EXT-X-STREAM-INF:"));
+        const variant = lines.slice(variantTag + 1).find((line) => line && !line.startsWith("#"));
+        if (!variant) throw new Error("HLS master has no variant");
+        if (signal.aborted) throw new Error("monitor deadline exceeded");
+        url = new URL(variant, url).href;
+        response = await this.fetch(url, signal);
+        if (response.status === 404 || response.status === 410) return [this.observation(false, "hls-variant-missing")];
+        text = await boundedText(response, signal);
+        url = response.url || url;
+        this.capReferences(text);
+      }
+      const validated = await this.egress.rewriteSegmentUris(text, url, this.egress.policy);
+      if (signal.aborted) throw new Error("monitor deadline exceeded");
+      const playlist = parseMediaPlaylist(validated);
+      const now = this.now();
+      const latest = playlist.segments.at(-1);
+      if (playlist.ended || playlist.vod || !latest) return [this.observation(false, "hls-ended-or-empty")];
+      const fingerprint = JSON.stringify([playlist.sequence, playlist.segments.length, latest.uri]);
+      const old = this.previous;
+      if (!old || old.playlistUrl !== url || old.fingerprint !== fingerprint) {
+        this.previous = { fingerprint, advancedAt: now, playlistUrl: url };
+      }
+      // Three target durations allow one missed reload; unchanged windows eventually fail even without PDT.
+      const graceMs = playlist.targetDuration * 3 * 1000;
+      const fresh = latest.endAt === undefined
+        ? now - this.previous!.advancedAt <= graceMs
+        : latest.endAt >= now - graceMs && latest.endAt <= now + graceMs;
+      return [this.observation(fresh, fresh ? "hls-recent-segments" : "hls-stale-segments")];
+    });
+  }
+
+  private async fetch(url: string, signal: AbortSignal): Promise<Response> {
+    if (signal.aborted) throw new Error("monitor deadline exceeded");
+    const response = await this.egress.egressFetch(url, { signal, headers: { accept: "application/vnd.apple.mpegurl" } },
+      { hostClass: "monitor-probe" });
+    if (!response.ok && response.status !== 404 && response.status !== 410) throw new MonitorHttpError(response.status, response.headers);
+    return response;
+  }
+
+  private observation(live: boolean, reason: string): MonitorObservation {
+    const timestamp = new Date(this.now()).toISOString();
+    return { tier: "hls-probe", observedAt: timestamp, receivedAt: timestamp,
+      payload: { outcome: live ? "ok" : "fail", mediaPresent: live, reason } };
+  }
+
+  private capReferences(text: string): void {
+    if (text.split(/\r?\n/).filter((line) => line.trim() && !line.trim().startsWith("#")).length
+      + (text.match(/(?:SERVER-)?URI=/g)?.length ?? 0) > 128) throw new Error("too many HLS references");
+  }
+}
diff --git a/apps/api/src/live-monitor/poller/mock-driver.ts b/apps/api/src/live-monitor/poller/mock-driver.ts
new file mode 100644
index 0000000..d741d48
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/mock-driver.ts
@@ -0,0 +1,136 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { MonitorObservation } from "../reducer.js";
+import type { PollDriver } from "./driver.js";
+
+interface ScenarioStep {
+  source: "A" | "B" | "C";
+  action: "go-live" | "fail" | "recover" | "go-offline";
+  holdSeconds: number;
+}
+interface Scenario { steps: ScenarioStep[] }
+type MockLiveState = "created" | "waiting" | "live" | "ended";
+interface MockStream { remoteId: string; state: MockLiveState }
+interface MockConnection {
+  id: string;
+  workspaceId: string;
+  provider: string;
+  channelId: string;
+  credentialId: { kind: "credential-ref"; id: string };
+  fields: Record<string, string>;
+  createdAt: Date;
+}
+interface MockConnector {
+  manifest(): { id: string };
+  createLiveStream?(connection: MockConnection, request: {
+    channelId: string; title: string; permanent: boolean; saveReplay: boolean;
+  }): Promise<MockStream>;
+  getLiveStreams?(connection: MockConnection, request: { limit: number }): Promise<{ items: MockStream[] }>;
+}
+interface MockModule {
+  createMockLivestreamState(): unknown;
+  createMockLivestreamConnector(state: unknown): MockConnector;
+  transitionMockLive(state: unknown, remoteId: string, to: MockLiveState): void;
+}
+interface ScenarioModule { SCENARIOS: Record<string, Scenario> }
+export interface MockDriverPackages { scenarios: ScenarioModule; mock: MockModule }
+
+export interface MockDriverOptions {
+  scenario: string;
+  source: "A" | "B" | "C";
+  sourceRef: string;
+  workspaceId: string;
+  connectionId: string;
+  tickMs?: number;
+  epoch?: string;
+  ingestNow?: () => string;
+}
+
+/** Native import keeps the ESM simulator and mock connector usable from the CJS API build. */
+const nativeImport = new Function("specifier", "return import(specifier)") as (specifier: string) => Promise<unknown>;
+
+async function loadPackage<T>(packageName: string, file: string): Promise<T> {
+  const roots = [process.cwd(), resolve(process.cwd(), "../..")];
+  for (const root of roots) {
+    const built = resolve(root, "packages", packageName, "dist", file);
+    const source = resolve(root, "packages", packageName, "src", file.replace(/\.js$/, ".ts"));
+    const candidates = process.env.NODE_ENV === "production" ? [built, source] : [source, built];
+    for (const candidate of candidates) {
+      if (existsSync(candidate)) return await nativeImport(pathToFileURL(candidate).href) as T;
+    }
+  }
+  throw new Error(`missing ${packageName}/${file}; build the package before starting the poller`);
+}
+
+export class MockPollDriver implements PollDriver {
+  private elapsedMs = 0;
+  private nextStep = 0;
+  private nextStepAt = 0;
+  private tick = 0;
+  private action: ScenarioStep["action"] | null = null;
+
+  private constructor(
+    private readonly options: MockDriverOptions,
+    private readonly scenario: Scenario,
+    private readonly connector: MockConnector,
+    private readonly state: unknown,
+    private readonly transition: MockModule["transitionMockLive"],
+    private readonly connection: MockConnection,
+    private readonly stream: MockStream,
+  ) {}
+
+  static async create(options: MockDriverOptions, packages?: MockDriverPackages): Promise<MockPollDriver> {
+    const normalized = { ...options, epoch: options.epoch ?? new Date().toISOString() };
+    if (!Number.isFinite(Date.parse(normalized.epoch))) throw new Error("mock epoch must be a timestamp");
+    const [{ SCENARIOS }, mock] = packages === undefined ? await Promise.all([
+      loadPackage<ScenarioModule>("testing", "scenarios.js"),
+      loadPackage<MockModule>("connector-mock-livestream", "index.js"),
+    ]) : [packages.scenarios, packages.mock];
+    const scenario = SCENARIOS[normalized.scenario];
+    if (scenario === undefined) throw new Error(`unknown mock scenario ${normalized.scenario}`);
+    const state = mock.createMockLivestreamState();
+    const connector = mock.createMockLivestreamConnector(state);
+    const connection: MockConnection = {
+      id: normalized.connectionId, workspaceId: normalized.workspaceId, provider: connector.manifest().id,
+      channelId: normalized.sourceRef, credentialId: { kind: "credential-ref", id: "mock" },
+      fields: {}, createdAt: new Date(normalized.epoch),
+    };
+    if (connector.createLiveStream === undefined) throw new Error("mock connector has no live stream factory");
+    const stream = await connector.createLiveStream(connection, {
+      channelId: normalized.sourceRef, title: normalized.sourceRef, permanent: false, saveReplay: false,
+    });
+    return new MockPollDriver(normalized, scenario, connector, state, mock.transitionMockLive, connection, stream);
+  }
+
+  async poll(): Promise<MonitorObservation[]> {
+    const tickMs = this.options.tickMs ?? 10_000;
+    if (!Number.isFinite(tickMs) || tickMs <= 0) throw new Error("mock tickMs must be positive");
+    while (this.nextStep < this.scenario.steps.length && this.elapsedMs >= this.nextStepAt) {
+      const step = this.scenario.steps[this.nextStep];
+      if (step === undefined) break;
+      if (step.source === this.options.source) {
+        this.action = step.action;
+        const state: MockLiveState = step.action === "go-live" || step.action === "recover"
+          ? "live" : step.action === "fail" ? "waiting" : "ended";
+        this.transition(this.state, this.stream.remoteId, state);
+      }
+      this.nextStepAt += step.holdSeconds * 1000;
+      this.nextStep += 1;
+    }
+    if (this.connector.getLiveStreams === undefined) throw new Error("mock connector has no live stream query");
+    const page = await this.connector.getLiveStreams(this.connection, { limit: 100 });
+    const live = page.items.find((item) => item.remoteId === this.stream.remoteId);
+    if (live === undefined) throw new Error(`mock live ${this.stream.remoteId} disappeared`);
+    const observedAt = new Date(Date.parse(this.options.epoch ?? "") + this.elapsedMs).toISOString();
+    const outcome = this.action === "fail" ? "error" : live.state === "live" ? "ok" : "fail";
+    const observation: MonitorObservation = {
+      tier: "api-poll", observedAt, receivedAt: this.options.ingestNow?.() ?? new Date().toISOString(),
+      providerEventId: `mock:${this.options.workspaceId}:${this.options.connectionId}:${this.options.sourceRef}:${this.options.epoch}:${this.tick}`,
+      payload: { outcome, reason: this.action ?? "not-live", mediaPresent: live.state === "live" },
+    };
+    this.tick += 1;
+    this.elapsedMs += tickMs;
+    return [observation];
+  }
+}
diff --git a/apps/api/src/live-monitor/poller/peertube-driver.ts b/apps/api/src/live-monitor/poller/peertube-driver.ts
new file mode 100644
index 0000000..6bd8243
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/peertube-driver.ts
@@ -0,0 +1,44 @@
+import type { MonitorObservation } from "../reducer.js";
+import type { PollDriver } from "./driver.js";
+import { boundedText, monitorDeadline, MonitorHttpError, type MonitorEgress } from "./egress.js";
+
+/** Injectable provider surface; production uses the WP7-backed client below. */
+export interface PeerTubeProbeClient {
+  probe(videoId: string): Promise<MonitorObservation[]>;
+}
+
+export class EgressPeerTubeProbeClient implements PeerTubeProbeClient {
+  constructor(private readonly instanceUrl: string, private readonly egress: MonitorEgress,
+    private readonly now: () => number = Date.now) {}
+
+  async probe(videoId: string): Promise<MonitorObservation[]> {
+    return monitorDeadline(async (signal) => {
+      const url = new URL(`/api/v1/videos/${encodeURIComponent(videoId)}`, this.instanceUrl);
+      const response = await this.egress.egressFetch(url, { signal, headers: { accept: "application/json" } },
+        { hostClass: "monitor-api", pinnedOrigin: true });
+      const timestamp = new Date(this.now()).toISOString();
+      if (response.status === 404 || response.status === 410) return [{ tier: "api-poll", observedAt: timestamp,
+        receivedAt: timestamp, payload: { outcome: "fail", reason: "api-video-missing" } }];
+      if (!response.ok) throw new MonitorHttpError(response.status, response.headers);
+      const parsed: unknown = JSON.parse(await boundedText(response, signal));
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("invalid PeerTube response");
+      const video = parsed as { isLive?: unknown; state?: unknown };
+      const state = typeof video.state === "object" && video.state !== null
+        ? (video.state as { id?: unknown }).id : video.state;
+      if (typeof video.isLive !== "boolean" || !Number.isInteger(state)) throw new Error("invalid PeerTube live state");
+      // A running live remains PUBLISHED (1); WAITING_FOR_LIVE (4)/LIVE_ENDED (5) are offline.
+      const live = video.isLive && state === 1;
+      return [{ tier: "api-poll", observedAt: timestamp, receivedAt: timestamp,
+        payload: { outcome: live ? "ok" : "fail", reason: live ? "api-published-live" : "api-not-live" } }];
+    });
+  }
+}
+
+export class PeerTubePollDriver implements PollDriver {
+  constructor(private readonly videoId: string, private readonly egress?: PeerTubeProbeClient) {}
+
+  async poll(): Promise<MonitorObservation[]> {
+    if (this.egress === undefined) throw new Error("NOT_IMPLEMENTED: PeerTube poll requires WP7 egress client");
+    return await this.egress.probe(this.videoId);
+  }
+}
diff --git a/apps/api/src/live-monitor/poller/poller.test.ts b/apps/api/src/live-monitor/poller/poller.test.ts
new file mode 100644
index 0000000..e3570ec
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/poller.test.ts
@@ -0,0 +1,166 @@
+import type { PoolClient } from "pg";
+import { describe, expect, it, vi } from "vitest";
+import { LiveMonitorService, type LiveMonitorDependencies } from "../live-monitor.service.js";
+import type { MonitorObservation, MonitorRowState } from "../reducer.js";
+import { MockPollDriver, type MockDriverPackages } from "./mock-driver.js";
+import { PeerTubePollDriver } from "./peertube-driver.js";
+import { jitteredInterval, LiveMonitorPoller, parsePollSources, type PollerDependencies } from "./poller.js";
+
+const epoch = "2026-01-01T00:00:00.000Z";
+
+async function mockPackages(): Promise<MockDriverPackages> {
+  const [mock, scenarios] = await Promise.all([
+    vi.importActual<MockDriverPackages["mock"]>("../../../../../packages/connector-mock-livestream/src/index.js"),
+    vi.importActual<MockDriverPackages["scenarios"]>("../../../../../packages/testing/src/scenarios.js"),
+  ]);
+  return { mock, scenarios };
+}
+
+function fixture(): { service: LiveMonitorService; get: () => Promise<MonitorRowState>; audits: () => number } {
+  const row: Record<string, unknown> = {
+    id: "source", workspace_id: "workspace", connection_id: "connection", remote_ref: "live:1",
+    state: "OFFLINE", version: 0, authoritative_tier: null,
+    last_media_health_at: null, last_hls_probe_at: null, last_webhook_at: null, last_api_poll_at: null,
+    tier_status: {}, ok_streak: 0, fail_streak: 0, state_entered_at: epoch,
+    hold_until: null, cooldown_until: null, previous_state: null, last_transition_at: null,
+    last_transition_reason: null, created_at: epoch, updated_at: epoch,
+  };
+  const seen = new Set<string>();
+  let auditCount = 0;
+  const client = {
+    async query(sql: string, params: unknown[] = []) {
+      if (sql.startsWith("SELECT * FROM source_monitor_states")) return { rowCount: 1, rows: [{ ...row }] };
+      if (sql.startsWith("INSERT INTO monitor_seen_events")) {
+        const id = String(params[1]);
+        if (seen.has(id)) return { rowCount: 0, rows: [] };
+        seen.add(id);
+        return { rowCount: 1, rows: [{ provider_event_id: id }] };
+      }
+      if (sql.startsWith("UPDATE source_monitor_states")) {
+        if (Number(params[18]) !== Number(row.version)) return { rowCount: 0, rows: [] };
+        const columns = ["state", "version", "authoritative_tier", "last_media_health_at", "last_hls_probe_at",
+          "last_webhook_at", "last_api_poll_at", "tier_status", "ok_streak", "fail_streak", "state_entered_at",
+          "hold_until", "cooldown_until", "previous_state", "last_transition_at", "last_transition_reason", "updated_at"];
+        for (const [index, column] of columns.entries()) row[column] = params[index + 1];
+        return { rowCount: 1, rows: [{ ...row }] };
+      }
+      if (sql.startsWith("SELECT audit_append")) {
+        auditCount += 1;
+        return { rowCount: 1, rows: [{}] };
+      }
+      throw new Error(`unexpected query: ${sql}`);
+    },
+  } as unknown as PoolClient;
+  const dependencies: LiveMonitorDependencies = { tenantTransaction: async (_workspace, fn) => fn(client) };
+  const service = new LiveMonitorService(dependencies);
+  return { service, get: () => service.getState("workspace", "source"), audits: () => auditCount };
+}
+
+describe("live monitor poller", () => {
+  it("drives dod-flap through the service and reducer without rapid terminal cuts", async () => {
+    const { service, get, audits } = fixture();
+    const observations: MonitorObservation[] = [];
+    const driver = await MockPollDriver.create({
+      scenario: "dod-flap", source: "A", sourceRef: "live:1", workspaceId: "workspace",
+      connectionId: "connection", epoch,
+      ingestNow: () => new Date(Date.parse(epoch) + observations.length * 10_000).toISOString(),
+    }, await mockPackages());
+    const states: string[] = [];
+    for (let tick = 0; tick < 10; tick += 1) {
+      const [observation] = await driver.poll();
+      if (observation === undefined) throw new Error("mock poll emitted no observation");
+      observations.push(observation);
+      const state = await service.recordObservation("workspace", "source", observation);
+      expect(state.version).toBe(tick + 1);
+      states.push(state.state);
+    }
+    expect(states).toEqual(["PROBING", "LIVE", "LIVE", "LIVE", "ERROR", "ERROR", "ERROR", "PROBING", "LIVE", "LIVE"]);
+    expect(observations.map((item) => item.observedAt)).toEqual(
+      Array.from({ length: 10 }, (_, tick) => new Date(Date.parse(epoch) + tick * 10_000).toISOString()),
+    );
+    expect(observations.every((item) => item.tier === "api-poll")).toBe(true);
+    expect((await get()).version).toBe(10);
+    expect(audits()).toBe(5);
+    const replay = observations[8];
+    if (replay === undefined) throw new Error("missing replay event");
+    expect((await service.recordObservation("workspace", "source", replay)).version).toBe(10);
+    expect(audits()).toBe(5);
+  });
+
+  it("plays the single-live scenario and keeps a replayed event from confirming LIVE", async () => {
+    const { service } = fixture();
+    const driver = await MockPollDriver.create({
+      scenario: "single-live", source: "A", sourceRef: "live:1", workspaceId: "workspace",
+      connectionId: "connection", epoch,
+    }, await mockPackages());
+    const [first] = await driver.poll();
+    if (first === undefined) throw new Error("missing first observation");
+    expect((await service.recordObservation("workspace", "source", first)).state).toBe("PROBING");
+    expect((await service.recordObservation("workspace", "source", first)).version).toBe(1);
+    const [second] = await driver.poll();
+    if (second === undefined) throw new Error("missing second observation");
+    const live = await service.recordObservation("workspace", "source", second);
+    expect(live.state).toBe("LIVE");
+    expect(live.version).toBe(2);
+  });
+
+  it("applies the same provider event only once across two poll ticks", async () => {
+    const { service, get } = fixture();
+    const observation: MonitorObservation = {
+      tier: "api-poll", observedAt: epoch, receivedAt: epoch, providerEventId: "same-event",
+      payload: { outcome: "ok" },
+    };
+    const poller = new LiveMonitorPoller(service, {
+      enabled: false,
+      sources: [{ provider: "mock-livestream", sourceRef: "live:1", workspaceId: "workspace", connectionId: "connection" }],
+      schedule: () => 1 as unknown as ReturnType<typeof setTimeout>,
+      cancel: () => undefined,
+      resolveSourceId: async () => "source",
+      makeDriver: async () => ({ poll: async () => [observation] }),
+    });
+    poller.start();
+    await poller.pollOnce();
+    await poller.pollOnce();
+    expect((await get()).version).toBe(1);
+    expect((await get()).state).toBe("PROBING");
+    await poller.stop();
+  });
+
+  it("uses a 10 second interval with bounded ±20% jitter and schedules the next tick", async () => {
+    expect([0, 0.5, 1].map((value) => jitteredInterval(10_000, value))).toEqual([8_000, 10_000, 12_000]);
+    const scheduled: Array<{ callback: () => void; delay: number }> = [];
+    const recorded: MonitorObservation[] = [];
+    const observation: MonitorObservation = {
+      tier: "api-poll", observedAt: epoch, receivedAt: epoch, providerEventId: "event-1",
+      payload: { outcome: "ok" },
+    };
+    const monitor = { recordObservation: async (_workspace: string, _source: string, value: MonitorObservation) => {
+      recorded.push(value);
+    } } as unknown as LiveMonitorService;
+    const overrides: Partial<PollerDependencies> = {
+      enabled: false, intervalMs: 10_000, random: () => 0,
+      sources: [{ provider: "mock-livestream", sourceRef: "live:1", workspaceId: "workspace", connectionId: "connection" }],
+      schedule: (callback, delay) => {
+        scheduled.push({ callback, delay });
+        return 1 as unknown as ReturnType<typeof setTimeout>;
+      },
+      cancel: () => undefined,
+      resolveSourceId: async () => "source",
+      makeDriver: async () => ({ poll: async () => [observation] }),
+    };
+    const poller = new LiveMonitorPoller(monitor, overrides);
+    poller.start();
+    expect(scheduled[0]?.delay).toBe(0);
+    scheduled[0]?.callback();
+    await new Promise((resolve) => setImmediate(resolve));
+    expect(recorded).toEqual([observation]);
+    expect(scheduled[1]?.delay).toBe(8_000);
+    await poller.stop();
+  });
+
+  it("parses source config and leaves the real probe stubbed", async () => {
+    expect(parsePollSources(JSON.stringify([{ provider: "mock-livestream", sourceRef: "live:1",
+      workspaceId: "workspace", connectionId: "connection" }]))).toHaveLength(1);
+    await expect(new PeerTubePollDriver("video-id").poll()).rejects.toThrow("NOT_IMPLEMENTED");
+  });
+});
diff --git a/apps/api/src/live-monitor/poller/poller.ts b/apps/api/src/live-monitor/poller/poller.ts
new file mode 100644
index 0000000..cb86f11
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/poller.ts
@@ -0,0 +1,215 @@
+import { Inject, Injectable, Logger, NotFoundException, OnApplicationBootstrap, OnApplicationShutdown, Optional } from "@nestjs/common";
+import { withTenant } from "../../db/client.js";
+import { LiveMonitorService } from "../live-monitor.service.js";
+import type { PollDriver } from "./driver.js";
+import { MockPollDriver } from "./mock-driver.js";
+// eslint-disable-next-line no-restricted-syntax
+import { EgressPeerTubeProbeClient, PeerTubePollDriver } from "./peertube-driver.js";
+import { monitorEgress } from "./egress.js";
+import { HlsProbeDriver } from "./hls-driver.js";
+import { BackoffPollDriver } from "./backoff-driver.js";
+
+export interface PollSource {
+  provider: string;
+  sourceRef: string;
+  workspaceId: string;
+  connectionId: string;
+  scenario?: string;
+  scenarioSource?: "A" | "B" | "C";
+  playbackUrl?: string;
+}
+
+export interface PollerDependencies {
+  sources: PollSource[];
+  intervalMs: number;
+  enabled: boolean;
+  random: () => number;
+  schedule: (callback: () => void, delayMs: number) => ReturnType<typeof setTimeout>;
+  cancel: (timer: ReturnType<typeof setTimeout>) => void;
+  resolveSourceId: (source: PollSource) => Promise<string>;
+  makeDriver: (source: PollSource, intervalMs: number) => Promise<PollDriver>;
+}
+
+export const MEDIA_POLLER_DEPENDENCIES = Symbol("MEDIA_POLLER_DEPENDENCIES");
+
+export function jitteredInterval(intervalMs: number, random: number): number {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) throw new Error("poll interval must be positive");
+  if (!Number.isFinite(random) || random < 0 || random > 1) throw new Error("random must be between 0 and 1");
+  return Math.round(intervalMs * (0.8 + random * 0.4));
+}
+
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} must be a non-empty string`);
+  return value;
+}
+
+export function parsePollSources(raw: string | undefined): PollSource[] {
+  if (raw === undefined || raw.trim() === "") return [];
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed)) throw new Error("MEDIA_POLLER_SOURCES must be a JSON array");
+  return parsed.map((entry: unknown, index): PollSource => {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      throw new Error(`MEDIA_POLLER_SOURCES[${index}] must be an object`);
+    }
+    const row = entry as Record<string, unknown>;
+    const source: PollSource = {
+      provider: requiredString(row.provider, "provider"),
+      sourceRef: requiredString(row.sourceRef, "sourceRef"),
+      workspaceId: requiredString(row.workspaceId, "workspaceId"),
+      connectionId: requiredString(row.connectionId, "connectionId"),
+    };
+    if (row.scenario !== undefined) source.scenario = requiredString(row.scenario, "scenario");
+    if (row.playbackUrl !== undefined) source.playbackUrl = requiredString(row.playbackUrl, "playbackUrl");
+    if (row.scenarioSource !== undefined) {
+      if (row.scenarioSource !== "A" && row.scenarioSource !== "B" && row.scenarioSource !== "C") {
+        throw new Error("scenarioSource must be A, B, or C");
+      }
+      source.scenarioSource = row.scenarioSource;
+    }
+    return source;
+  });
+}
+
+async function resolveSourceId(source: PollSource): Promise<string> {
+  return withTenant(source.workspaceId, async (client) => {
+    const result = await client.query(
+      "SELECT id FROM source_monitor_states WHERE connection_id = $1 AND remote_ref = $2",
+      [source.connectionId, source.sourceRef],
+    );
+    if (result.rowCount !== 1) throw new NotFoundException(`monitored source ${source.sourceRef} not found`);
+    return String(result.rows[0]?.id);
+  });
+}
+
+async function makeDriver(source: PollSource, intervalMs: number): Promise<PollDriver> {
+  // Provider routing lives here until the connector registry exposes monitor probes.
+  if (source.provider === "mock-livestream") {
+    return MockPollDriver.create({
+      scenario: source.scenario ?? "single-live", source: source.scenarioSource ?? "A",
+      sourceRef: source.sourceRef, workspaceId: source.workspaceId, connectionId: source.connectionId,
+      tickMs: intervalMs,
+    });
+  }
+  // eslint-disable-next-line no-restricted-syntax
+  if (source.provider === "peertube" || source.provider === "hls") {
+    const egress = await monitorEgress();
+    const drivers: PollDriver[] = [];
+    // eslint-disable-next-line no-restricted-syntax
+    if (source.provider === "peertube") {
+      const fields = await withTenant(source.workspaceId, async (client) => {
+        const result = await client.query<{ fields: Record<string, unknown> }>(
+          "SELECT fields FROM connections WHERE id = $1 AND workspace_id = $2 AND disconnected_at IS NULL",
+          [source.connectionId, source.workspaceId]);
+        if (result.rowCount !== 1) throw new NotFoundException("monitor connection not found");
+        return result.rows[0]!.fields;
+      });
+      const instanceUrl = requiredString(fields.instanceUrl, "connection instanceUrl");
+      const videoId = source.sourceRef.startsWith("video:")
+        ? source.sourceRef.slice(6).split("@")[0]! : source.sourceRef;
+      drivers.push(new BackoffPollDriver(new PeerTubePollDriver(videoId,
+        new EgressPeerTubeProbeClient(instanceUrl, egress)), "api-poll"));
+    }
+    if (source.playbackUrl) drivers.push(new BackoffPollDriver(new HlsProbeDriver(source.playbackUrl, egress), "hls-probe"));
+    if (!drivers.length) throw new Error("HLS monitor source requires playbackUrl");
+    return { poll: async () => {
+      const observations = [];
+      for (const driver of drivers) observations.push(...await driver.poll());
+      return observations;
+    } };
+  }
+  throw new Error(`no live poll driver for provider ${source.provider}`);
+}
+
+function defaults(): PollerDependencies {
+  const interval = Number(process.env.MEDIA_POLLER_INTERVAL_MS ?? 10_000);
+  if (!Number.isFinite(interval) || interval <= 0) throw new Error("MEDIA_POLLER_INTERVAL_MS must be positive");
+  const enabled = process.env.MEDIA_POLLER_ENABLED === undefined
+    ? process.env.NODE_ENV !== "production" : process.env.MEDIA_POLLER_ENABLED === "true";
+  return {
+    sources: parsePollSources(process.env.MEDIA_POLLER_SOURCES), intervalMs: interval, enabled,
+    random: Math.random, schedule: setTimeout, cancel: clearTimeout, resolveSourceId, makeDriver,
+  };
+}
+
+@Injectable()
+export class LiveMonitorPoller implements OnApplicationBootstrap, OnApplicationShutdown {
+  private readonly logger = new Logger(LiveMonitorPoller.name);
+  private readonly config: PollerDependencies;
+  private readonly drivers = new Map<string, PollDriver>();
+  private readonly sourceIds = new Map<string, string>();
+  private timer: ReturnType<typeof setTimeout> | undefined;
+  private active: Promise<void> | undefined;
+  private running = false;
+
+  constructor(
+    @Inject(LiveMonitorService) private readonly monitor: LiveMonitorService,
+    @Optional() @Inject(MEDIA_POLLER_DEPENDENCIES) dependencies?: Partial<PollerDependencies>,
+  ) {
+    this.config = { ...defaults(), ...dependencies };
+  }
+
+  onApplicationBootstrap(): void {
+    if (this.config.enabled) this.start();
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await this.stop();
+  }
+
+  get isRunning(): boolean { return this.running; }
+
+  start(): { running: boolean } {
+    if (this.running) return { running: true };
+    this.running = true;
+    this.schedule(0);
+    return { running: true };
+  }
+
+  async stop(): Promise<{ running: boolean }> {
+    this.running = false;
+    if (this.timer !== undefined) this.config.cancel(this.timer);
+    this.timer = undefined;
+    await this.active;
+    return { running: false };
+  }
+
+  private schedule(delayMs: number): void {
+    if (!this.running) return;
+    this.timer = this.config.schedule(() => {
+      this.timer = undefined;
+      this.active = this.pollOnce().catch((error: unknown) => {
+        this.logger.error(`poll tick failed: ${String(error)}`);
+      }).finally(() => {
+        this.active = undefined;
+        this.schedule(jitteredInterval(this.config.intervalMs, this.config.random()));
+      });
+    }, delayMs);
+  }
+
+  /** One serialized tick; each source fails independently. */
+  async pollOnce(): Promise<void> {
+    for (const source of this.config.sources) {
+      if (!this.running) return;
+      const key = `${source.workspaceId}:${source.connectionId}:${source.sourceRef}`;
+      try {
+        let driver = this.drivers.get(key);
+        if (driver === undefined) {
+          driver = await this.config.makeDriver(source, this.config.intervalMs);
+          this.drivers.set(key, driver);
+        }
+        let sourceId = this.sourceIds.get(key);
+        if (sourceId === undefined) {
+          sourceId = await this.config.resolveSourceId(source);
+          this.sourceIds.set(key, sourceId);
+        }
+        const observations = await driver.poll();
+        for (const observation of observations) {
+          if (!this.running) return;
+          await this.monitor.recordObservation(source.workspaceId, sourceId, observation);
+        }
+      } catch (error) {
+        this.logger.error(`poll failed for ${key}: ${String(error)}`);
+      }
+    }
+  }
+}
diff --git a/apps/api/src/live-monitor/poller/signals.test.ts b/apps/api/src/live-monitor/poller/signals.test.ts
new file mode 100644
index 0000000..375f14a
--- /dev/null
+++ b/apps/api/src/live-monitor/poller/signals.test.ts
@@ -0,0 +1,172 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { EgressError, EgressPolicy, rewriteSegmentUris, validateMasterPlaylist } from "../../../../../packages/egress/src/index.js";
+import { BackoffPollDriver } from "./backoff-driver.js";
+import { MONITOR_MAX_BYTES, MONITOR_TIMEOUT_MS, type MonitorEgress } from "./egress.js";
+import { HlsProbeDriver, parseMediaPlaylist } from "./hls-driver.js";
+import { EgressPeerTubeProbeClient, PeerTubePollDriver } from "./peertube-driver.js";
+
+const epoch = Date.parse("2026-01-01T00:00:12.000Z");
+const origin = "https://stream.example";
+const masterUrl = `${origin}/hls/master.m3u8`;
+const liveUrl = `${origin}/hls/live.m3u8`;
+const fixture = (name: string) => readFileSync(resolve(__dirname, "fixtures", name), "utf8");
+const live = fixture("live.m3u8");
+
+/** A fake transport tracks each egress fetch/debit; real WP7 URI policy/helpers still run. */
+function fakeEgress(routes: Record<string, string | Response | (() => Response | Promise<Response>)>) {
+  const draws: Array<{ host: string; hostClass: string; url: string }> = [];
+  const policy = new EgressPolicy({ resolver: async () => [{ address: "8.8.8.8", family: 4 }] });
+  const egress: MonitorEgress = {
+    policy, validateMasterPlaylist: vi.fn(validateMasterPlaylist), rewriteSegmentUris: vi.fn(rewriteSegmentUris),
+    egressFetch: vi.fn(async (raw, _init, context) => {
+      const endpoint = await policy.validate(raw);
+      draws.push({ host: endpoint.hostKey, hostClass: context.hostClass, url: endpoint.url.href });
+      const route = routes[endpoint.url.href];
+      if (route === undefined) throw new Error("unexpected outbound URL");
+      const response = typeof route === "function" ? await route() : typeof route === "string" ? new Response(route) : route.clone();
+      if (!response.url) Object.defineProperty(response, "url", { value: endpoint.url.href });
+      return response;
+    }),
+  };
+  return { egress, draws };
+}
+
+afterEach(() => { vi.useRealTimers(); });
+
+describe("HLS media ground truth", () => {
+  it("fetches a master and exactly one variant through monitor-probe egress, validates all URIs", async () => {
+    const f = fakeEgress({ [masterUrl]: fixture("master.m3u8"), [liveUrl]: live });
+    const observation = (await new HlsProbeDriver(masterUrl, f.egress, () => epoch).poll())[0];
+    expect(observation).toMatchObject({ tier: "hls-probe", payload: { outcome: "ok", mediaPresent: true } });
+    expect(f.draws).toEqual([
+      { url: masterUrl, host: "stream.example:443", hostClass: "monitor-probe" },
+      { url: liveUrl, host: "stream.example:443", hostClass: "monitor-probe" },
+    ]);
+    expect(f.egress.validateMasterPlaylist).toHaveBeenCalledOnce();
+    expect(f.egress.rewriteSegmentUris).toHaveBeenCalledOnce();
+    expect(f.egress.rewriteSegmentUris).toHaveBeenCalledWith(live, liveUrl, f.egress.policy);
+  });
+
+  it.each(["offline.m3u8", "empty", "404"])("reports %s as offline", async (name) => {
+    const body = name === "empty" ? "#EXTM3U\n#EXT-X-TARGETDURATION:6\n"
+      : name === "404" ? new Response(null, { status: 404 }) : fixture(name);
+    const f = fakeEgress({ [liveUrl]: body });
+    expect((await new HlsProbeDriver(liveUrl, f.egress, () => epoch).poll())[0]?.payload)
+      .toMatchObject({ outcome: "fail", mediaPresent: false });
+  });
+
+  it("reports stale program dates and unreasonable future dates as offline", async () => {
+    const f = fakeEgress({ [liveUrl]: live });
+    expect((await new HlsProbeDriver(liveUrl, f.egress, () => epoch + 19_000).poll())[0]?.payload.outcome).toBe("fail");
+    expect((await new HlsProbeDriver(liveUrl, f.egress, () => epoch - 19_000).poll())[0]?.payload.outcome).toBe("fail");
+  });
+
+  it("uses media-sequence/last-segment progression and three target durations when PDT is absent", async () => {
+    let now = epoch; let body = live.replace(/#EXT-X-PROGRAM-DATE-TIME:.*\n/, "");
+    const f = fakeEgress({ [liveUrl]: () => new Response(body) });
+    const driver = new HlsProbeDriver(liveUrl, f.egress, () => now);
+    expect((await driver.poll())[0]?.payload.outcome).toBe("ok");
+    now += 18_001;
+    expect((await driver.poll())[0]?.payload.outcome).toBe("fail");
+    body = body.replace("SEQUENCE:20", "SEQUENCE:21").replace("segment21.ts", "segment22.ts");
+    expect((await driver.poll())[0]?.payload.outcome).toBe("ok");
+  });
+
+  it.each(["malformed.m3u8", "header", "missing-duration", "missing-uri"])("rejects malformed playlist %s", async (name) => {
+    const body = name === "header" ? "not a playlist" : name === "missing-duration" ? "#EXTM3U\n#EXT-X-TARGETDURATION:6\nseg.ts\n"
+      : name === "missing-uri" ? "#EXTM3U\n#EXT-X-TARGETDURATION:6\n#EXTINF:6,\n" : fixture(name);
+    const f = fakeEgress({ [liveUrl]: body });
+    await expect(new HlsProbeDriver(liveUrl, f.egress, () => epoch).poll()).rejects.toThrow();
+  });
+
+  it("accepts EVENT playlists and rejects invalid target-duration math", () => {
+    expect(parseMediaPlaylist(live.replace("#EXT-X-TARGETDURATION", "#EXT-X-PLAYLIST-TYPE:EVENT\n#EXT-X-TARGETDURATION")).vod).toBe(false);
+    expect(() => parseMediaPlaylist(live.replace("EXTINF:6", "EXTINF:7"))).toThrow();
+  });
+
+  it.each(["variant", "unused-variant", "segment", "key"])("denies private %s references before any child request", async (kind) => {
+    const master = kind === "variant" ? "#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=800000\nhttp://169.254.169.254/private.m3u8\n"
+      : fixture("master.m3u8").replace("unused.m3u8", "http://127.0.0.1/unused.m3u8");
+    const media = kind === "segment" ? live.replace("segment20.ts", "http://10.0.0.1/seg.ts")
+      : live.replace("#EXTINF:6,", '#EXT-X-KEY:METHOD=AES-128,URI="http://169.254.169.254/key"\n#EXTINF:6,');
+    const isMaster = kind === "variant" || kind === "unused-variant";
+    const f = fakeEgress({ [isMaster ? masterUrl : liveUrl]: isMaster ? master : media });
+    await expect(new HlsProbeDriver(isMaster ? masterUrl : liveUrl, f.egress, () => epoch).poll())
+      .rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+    expect(f.draws).toHaveLength(1);
+  });
+
+  it("resolves variant and segment URIs against the final redirected playlist URL", async () => {
+    const response = new Response(fixture("master.m3u8"));
+    Object.defineProperty(response, "url", { value: `${origin}/redirected/master.m3u8` });
+    const f = fakeEgress({ [masterUrl]: () => response, [`${origin}/redirected/live.m3u8`]: live });
+    await new HlsProbeDriver(masterUrl, f.egress, () => epoch).poll();
+    expect(f.draws[1]?.url).toBe(`${origin}/redirected/live.m3u8`);
+  });
+
+  it("enforces body size, URI count and whole-probe deadlines", async () => {
+    const oversized = fakeEgress({ [liveUrl]: "x".repeat(MONITOR_MAX_BYTES + 1) });
+    await expect(new HlsProbeDriver(liveUrl, oversized.egress).poll()).rejects.toThrow("size cap");
+    const references = fakeEgress({ [liveUrl]: `#EXTM3U\n${"#EXTINF:6,\nsegment.ts\n".repeat(129)}` });
+    await expect(new HlsProbeDriver(liveUrl, references.egress).poll()).rejects.toThrow("too many HLS references");
+    expect(references.egress.rewriteSegmentUris).not.toHaveBeenCalled();
+    vi.useFakeTimers();
+    const hanging = fakeEgress({ [liveUrl]: () => new Promise<Response>(() => undefined) });
+    const pending = new HlsProbeDriver(liveUrl, hanging.egress).poll();
+    const rejected = expect(pending).rejects.toThrow("deadline");
+    await vi.advanceTimersByTimeAsync(MONITOR_TIMEOUT_MS);
+    await rejected;
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});
+
+describe("monitor API budgets and adaptive source backoff", () => {
+  it("counts API + master + variant draws on the same host, with the required host classes", async () => {
+    const f = fakeEgress({ [`${origin}/api/v1/videos/video-1`]: JSON.stringify({ isLive: true, state: { id: 1 } }),
+      [masterUrl]: fixture("master.m3u8"), [liveUrl]: live });
+    const api = new PeerTubePollDriver("video-1", new EgressPeerTubeProbeClient(origin, f.egress, () => epoch));
+    expect((await api.poll())[0]?.payload.outcome).toBe("ok");
+    await new HlsProbeDriver(masterUrl, f.egress, () => epoch).poll();
+    expect(f.draws.map((draw) => draw.hostClass)).toEqual(["monitor-api", "monitor-probe", "monitor-probe"]);
+    expect(new Set(f.draws.map((draw) => draw.host))).toEqual(new Set(["stream.example:443"]));
+    expect(f.egress.egressFetch).toHaveBeenNthCalledWith(1, expect.any(URL), expect.anything(), { hostClass: "monitor-api", pinnedOrigin: true });
+  });
+
+  it.each([4, 5])("does not consider PeerTube state %s live even when isLive=true", async (state) => {
+    const f = fakeEgress({ [`${origin}/api/v1/videos/video-1`]: JSON.stringify({ isLive: true, state: { id: state } }) });
+    expect((await new EgressPeerTubeProbeClient(origin, f.egress).probe("video-1"))[0]?.payload.outcome).toBe("fail");
+  });
+
+  it.each([429, 503])("backs off source after HTTP %s, honors Retry-After and resets on recovery", async (status) => {
+    let now = epoch; let attempt = 0;
+    const f = fakeEgress({ [liveUrl]: () => ++attempt === 1 ? new Response(null, { status, headers: { "retry-after": "30" } }) : new Response(live) });
+    const driver = new BackoffPollDriver(new HlsProbeDriver(liveUrl, f.egress, () => now), "hls-probe", () => now, () => 0.5);
+    expect((await driver.poll())[0]?.payload.outcome).toBe("unavailable");
+    expect(driver.nextAttemptAt).toBe(epoch + 30_000);
+    now += 29_999; expect(await driver.poll()).toEqual([]); expect(f.draws).toHaveLength(1);
+    now += 1; await driver.poll(); expect(f.draws).toHaveLength(2); expect(driver.nextAttemptAt).toBe(0);
+  });
+
+  it("honors an HTTP-date Retry-After for API polls and grows source-local delays on repeated 5xx", async () => {
+    let now = epoch; let attempt = 0;
+    const f = fakeEgress({ [`${origin}/api/v1/videos/v`]: () => new Response(null, { status: 503,
+      headers: ++attempt === 1 ? { "retry-after": new Date(epoch + 60_000).toUTCString() } : {} }) });
+    const driver = new BackoffPollDriver(new PeerTubePollDriver("v", new EgressPeerTubeProbeClient(origin, f.egress)), "api-poll", () => now, () => 0.5);
+    await driver.poll(); expect(driver.nextAttemptAt).toBe(epoch + 60_000);
+    now += 60_000; await driver.poll(); expect(driver.nextAttemptAt).toBe(now + 2000);
+    now += 2000; await driver.poll(); expect(driver.nextAttemptAt).toBe(now + 4000);
+  });
+
+  it("respects WP7 budget exhaustion and allows a different source to proceed", async () => {
+    let now = epoch;
+    const egress = fakeEgress({ [liveUrl]: live });
+    const blocked = { ...egress.egress, egressFetch: vi.fn(async () => { throw new EgressError("BUDGET_EXHAUSTED", "budget", 10_000); }) };
+    const one = new BackoffPollDriver(new HlsProbeDriver(liveUrl, blocked, () => now), "hls-probe", () => now, () => 0.5);
+    const two = new BackoffPollDriver(new HlsProbeDriver(liveUrl, egress.egress, () => now), "hls-probe", () => now, () => 0.5);
+    await one.poll(); now += 1000; expect(await one.poll()).toEqual([]);
+    expect((await two.poll())[0]?.payload.outcome).toBe("ok");
+    expect(blocked.egressFetch).toHaveBeenCalledOnce(); expect(egress.draws).toHaveLength(1);
+  });
+});
diff --git a/apps/api/src/live-monitor/reducer.test.ts b/apps/api/src/live-monitor/reducer.test.ts
new file mode 100644
index 0000000..b42cdc8
--- /dev/null
+++ b/apps/api/src/live-monitor/reducer.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, it } from "vitest";
+import { applyObservation, type MonitorObservation, type MonitorRowState, type SignalTier } from "./reducer.js";
+
+const start = Date.parse("2026-01-01T00:00:00.000Z");
+const at = (seconds: number): string => new Date(start + seconds * 1000).toISOString();
+
+function initial(): MonitorRowState {
+  return {
+    id: "source", workspaceId: "workspace", connectionId: "connection", remoteRef: "live:1",
+    state: "OFFLINE", version: 0, authoritativeTier: null,
+    lastMediaHealthAt: null, lastHlsProbeAt: null, lastWebhookAt: null, lastApiPollAt: null,
+    tierStatus: {}, okStreak: 0, failStreak: 0, stateEnteredAt: at(0),
+    holdUntil: null, cooldownUntil: null, previousState: null,
+    lastTransitionAt: null, lastTransitionReason: null, createdAt: at(0), updatedAt: at(0),
+  };
+}
+
+function obs(tier: SignalTier, outcome: MonitorObservation["payload"]["outcome"], seconds: number,
+  extra: Partial<MonitorObservation> = {}): MonitorObservation {
+  return { tier, observedAt: at(seconds), receivedAt: at(seconds), payload: { outcome }, ...extra };
+}
+
+function fold(state: MonitorRowState, ...observations: MonitorObservation[]): MonitorRowState {
+  return observations.reduce((current, observation) => applyObservation(current, observation).state, state);
+}
+
+describe("live source reducer", () => {
+  it("confirms LIVE after two ok signals from a poll-only source", () => {
+    const first = applyObservation(initial(), obs("api-poll", "ok", 1));
+    expect(first.state.state).toBe("PROBING");
+    const second = applyObservation(first.state, obs("api-poll", "ok", 2));
+    expect(second.state.state).toBe("LIVE");
+    expect(second.state.authoritativeTier).toBe("api-poll");
+    expect(second.transition?.version).toBe(2);
+  });
+
+  it("confirms OFFLINE after three failures and waits out hysteresis", () => {
+    const live = fold(initial(), obs("api-poll", "ok", 1), obs("api-poll", "ok", 2));
+    const one = applyObservation(live, obs("api-poll", "fail", 3));
+    expect(one.state.state).toBe("LIVE");
+    const two = applyObservation(one.state, obs("api-poll", "fail", 4));
+    expect(two.state.state).toBe("UNSTABLE");
+    const three = applyObservation(two.state, obs("api-poll", "fail", 5));
+    expect(three.state.state).toBe("UNSTABLE");
+    expect(applyObservation(three.state, obs("api-poll", "fail", 12)).state.state).toBe("OFFLINE");
+  });
+
+  it("holds a flapping source without rapid LIVE/OFFLINE cuts", () => {
+    let state = fold(initial(), obs("api-poll", "ok", 1), obs("api-poll", "ok", 2));
+    const terminal: string[] = [state.state];
+    for (let second = 3; second <= 9; second += 1) {
+      const outcome = second % 2 === 0 ? "ok" : "fail";
+      const result = applyObservation(state, obs("api-poll", outcome, second));
+      state = result.state;
+      if (result.transition?.to === "LIVE" || result.transition?.to === "OFFLINE") terminal.push(result.transition.to);
+    }
+    expect(terminal).toEqual(["LIVE"]);
+  });
+
+  it("discards stale observations within a tier and repeated provider IDs", () => {
+    const first = fold(initial(), obs("webhook", "ok", 3, { providerEventId: "event-1" }));
+    expect(applyObservation(first, obs("webhook", "fail", 2)).state).toBe(first);
+    const second = fold(first, obs("webhook", "ok", 4, { providerEventId: "event-2" }));
+    expect(applyObservation(second, obs("webhook", "ok", 5, { providerEventId: "event-1" })).state).toBe(second);
+    expect(first.version).toBe(1);
+  });
+
+  it("keeps a newer HLS probe authoritative against a late API poll and clock-skewed webhook", () => {
+    const futureWebhook = obs("webhook", "fail", 1000, { receivedAt: at(1) });
+    const state = fold(initial(), futureWebhook,
+      obs("hls-probe", "ok", 2), obs("hls-probe", "ok", 3),
+      obs("api-poll", "fail", 1, { receivedAt: at(6) }));
+    expect(state.authoritativeTier).toBe("hls-probe");
+    expect(state.state).toBe("UNSTABLE");
+    expect(state.tierStatus["hls-probe"]?.okStreak).toBe(2);
+    const confirmed = applyObservation(state, obs("hls-probe", "ok", 13)).state;
+    expect(confirmed.state).toBe("LIVE");
+  });
+
+  it("raises and lowers authority when HLS becomes available then denied", () => {
+    const poll = fold(initial(), obs("api-poll", "ok", 1), obs("api-poll", "ok", 2));
+    const raised = applyObservation(poll, obs("hls-probe", "ok", 3)).state;
+    expect(raised.authoritativeTier).toBe("hls-probe");
+    const lowered = applyObservation(raised, obs("hls-probe", "unavailable", 4)).state;
+    expect(lowered.authoritativeTier).toBe("api-poll");
+    expect(lowered.state).toBe("LIVE");
+  });
+
+  it("uses ten seconds without media as a failure confirmation", () => {
+    const live = fold(initial(),
+      { ...obs("media-health", "ok", 1), payload: { outcome: "ok", mediaPresent: true } },
+      { ...obs("media-health", "ok", 2), payload: { outcome: "ok", mediaPresent: true } });
+    const failed = applyObservation(live, obs("media-health", "fail", 13));
+    expect(failed.state.state).toBe("OFFLINE");
+    expect(failed.transition?.reason).toBe("media-health:no-media-timeout");
+  });
+});
diff --git a/apps/api/src/live-monitor/reducer.ts b/apps/api/src/live-monitor/reducer.ts
new file mode 100644
index 0000000..5e04ea6
--- /dev/null
+++ b/apps/api/src/live-monitor/reducer.ts
@@ -0,0 +1,182 @@
+/** Pure per-source fold. Provider time is used only to order one tier's events. */
+export type MonitorState = "OFFLINE" | "PROBING" | "LIVE" | "UNSTABLE" | "ERROR";
+export type SignalTier = "media-health" | "hls-probe" | "webhook" | "api-poll";
+export type ObservationOutcome = "ok" | "fail" | "error" | "unavailable";
+
+export interface MonitorObservation {
+  tier: SignalTier;
+  observedAt: string;
+  /** Ingest clock, never a provider clock. */
+  receivedAt: string;
+  providerEventId?: string;
+  payload: { outcome: ObservationOutcome; reason?: string; mediaPresent?: boolean };
+}
+
+export interface TierStatus {
+  available: boolean;
+  lastOutcome?: ObservationOutcome;
+  lastReceivedAt?: string;
+  lastProviderEventId?: string;
+  /** Recent replay guard; the database journal provides durable full-history dedupe. */
+  seenProviderEventIds?: string[];
+  okStreak: number;
+  failStreak: number;
+  lastMediaAt?: string;
+}
+
+export interface MonitorRowState {
+  id: string;
+  workspaceId: string;
+  connectionId: string;
+  remoteRef: string;
+  state: MonitorState;
+  version: number;
+  authoritativeTier: SignalTier | null;
+  lastMediaHealthAt: string | null;
+  lastHlsProbeAt: string | null;
+  lastWebhookAt: string | null;
+  lastApiPollAt: string | null;
+  tierStatus: Partial<Record<SignalTier, TierStatus>>;
+  okStreak: number;
+  failStreak: number;
+  stateEnteredAt: string;
+  holdUntil: string | null;
+  cooldownUntil: string | null;
+  previousState: MonitorState | null;
+  lastTransitionAt: string | null;
+  lastTransitionReason: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface MonitorPolicy {
+  liveConfirmations: number;
+  offlineConfirmations: number;
+  noMediaMs: number;
+  minHoldMs: number;
+  cooldownMs: number;
+}
+
+export const DEFAULT_MONITOR_POLICY: MonitorPolicy = {
+  liveConfirmations: 2,
+  offlineConfirmations: 3,
+  noMediaMs: 10_000,
+  minHoldMs: 2_000,
+  cooldownMs: 10_000,
+};
+
+export interface MonitorTransition {
+  from: MonitorState;
+  to: MonitorState;
+  version: number;
+  reason: string;
+  at: string;
+}
+
+export interface Reduction {
+  state: MonitorRowState;
+  transition?: MonitorTransition;
+}
+
+const PRECEDENCE: readonly SignalTier[] = ["media-health", "hls-probe", "webhook", "api-poll"];
+const OBSERVED_FIELD: Record<SignalTier, keyof Pick<MonitorRowState,
+  "lastMediaHealthAt" | "lastHlsProbeAt" | "lastWebhookAt" | "lastApiPollAt">> = {
+  "media-health": "lastMediaHealthAt",
+  "hls-probe": "lastHlsProbeAt",
+  webhook: "lastWebhookAt",
+  "api-poll": "lastApiPollAt",
+};
+
+export function applyObservation(
+  state: MonitorRowState,
+  observation: MonitorObservation,
+  policy: MonitorPolicy = DEFAULT_MONITOR_POLICY,
+): Reduction {
+  const now = Date.parse(observation.receivedAt);
+  const observed = Date.parse(observation.observedAt);
+  if (!Number.isFinite(now) || !Number.isFinite(observed)) throw new Error("observation timestamps must be valid");
+  const field = OBSERVED_FIELD[observation.tier];
+  const last = state[field];
+  if (last !== null && observed <= Date.parse(last)) return { state };
+  const oldTier = state.tierStatus[observation.tier];
+  if (observation.providerEventId !== undefined && (oldTier?.lastProviderEventId === observation.providerEventId
+    || oldTier?.seenProviderEventIds?.includes(observation.providerEventId) === true)) {
+    return { state };
+  }
+
+  const outcome = observation.payload.outcome;
+  const available = outcome !== "unavailable";
+  const okStreak = outcome === "ok" ? (oldTier?.okStreak ?? 0) + 1 : 0;
+  const failStreak = outcome === "fail" ? (oldTier?.failStreak ?? 0) + 1 : 0;
+  const tierStatus: MonitorRowState["tierStatus"] = {
+    ...state.tierStatus,
+    [observation.tier]: {
+      available,
+      lastOutcome: outcome,
+      lastReceivedAt: observation.receivedAt,
+      ...(observation.providerEventId === undefined
+        ? oldTier?.lastProviderEventId === undefined ? {} : { lastProviderEventId: oldTier.lastProviderEventId }
+        : { lastProviderEventId: observation.providerEventId }),
+      ...(observation.providerEventId === undefined && oldTier?.seenProviderEventIds === undefined
+        ? {} : { seenProviderEventIds: observation.providerEventId === undefined
+          ? oldTier?.seenProviderEventIds
+          : [...(oldTier?.seenProviderEventIds ?? []), observation.providerEventId].slice(-64) }),
+      okStreak,
+      failStreak,
+      ...(observation.payload.mediaPresent === true
+        ? { lastMediaAt: observation.receivedAt }
+        : oldTier?.lastMediaAt === undefined ? {} : { lastMediaAt: oldTier.lastMediaAt }),
+    },
+  };
+  const authoritativeTier = PRECEDENCE.find((tier) => tierStatus[tier]?.available === true) ?? null;
+  const authority = authoritativeTier === null ? undefined : tierStatus[authoritativeTier];
+  let next: MonitorRowState = {
+    ...state,
+    [field]: observation.observedAt,
+    tierStatus,
+    authoritativeTier,
+    version: state.version + 1,
+    okStreak: authority?.okStreak ?? 0,
+    failStreak: authority?.failStreak ?? 0,
+    updatedAt: observation.receivedAt,
+  };
+
+  let target: MonitorState | undefined;
+  let reason = `${observation.tier}:${outcome}`;
+  if (outcome === "error" && observation.tier === authoritativeTier) {
+    target = "ERROR";
+  } else if (authoritativeTier !== null) {
+    const lowerSignal = observation.tier !== authoritativeTier;
+    if (lowerSignal && outcome !== "unavailable") {
+      if (outcome === "fail" || outcome === "error") target = state.state === "LIVE" ? "UNSTABLE" : "PROBING";
+    } else if (authority?.lastOutcome === "ok") {
+      if (authority.okStreak >= policy.liveConfirmations) target = "LIVE";
+      else if (state.state !== "LIVE") target = "PROBING";
+    } else if (authority?.lastOutcome === "fail") {
+      const noMedia = authoritativeTier === "media-health" && authority.lastMediaAt !== undefined
+        && now - Date.parse(authority.lastMediaAt) >= policy.noMediaMs;
+      if (authority.failStreak >= policy.offlineConfirmations || noMedia) target = "OFFLINE";
+      else if (state.state === "LIVE") target = "UNSTABLE";
+      else if (state.state !== "OFFLINE" && state.state !== "UNSTABLE") target = "PROBING";
+      if (noMedia) reason = "media-health:no-media-timeout";
+    }
+  }
+
+  if (target === undefined || target === state.state) return { state: next };
+  const terminal = target === "LIVE" || target === "OFFLINE";
+  const held = target !== "ERROR" && state.state !== "PROBING" && state.state !== "UNSTABLE"
+    && state.holdUntil !== null && now < Date.parse(state.holdUntil);
+  const cooling = terminal && state.cooldownUntil !== null && now < Date.parse(state.cooldownUntil);
+  if (held || cooling) return { state: next };
+  next = {
+    ...next,
+    state: target,
+    previousState: state.state,
+    stateEnteredAt: observation.receivedAt,
+    holdUntil: terminal ? new Date(now + policy.minHoldMs).toISOString() : state.holdUntil,
+    cooldownUntil: terminal ? new Date(now + policy.cooldownMs).toISOString() : state.cooldownUntil,
+    lastTransitionAt: observation.receivedAt,
+    lastTransitionReason: reason,
+  };
+  return { state: next, transition: { from: state.state, to: target, version: next.version, reason, at: observation.receivedAt } };
+}
diff --git a/apps/api/src/live-monitor/webhook.controller.ts b/apps/api/src/live-monitor/webhook.controller.ts
new file mode 100644
index 0000000..d096d2c
--- /dev/null
+++ b/apps/api/src/live-monitor/webhook.controller.ts
@@ -0,0 +1,19 @@
+import { Controller, HttpCode, Inject, Param, Post, Req } from "@nestjs/common";
+import type { Request } from "express";
+import { MonitorWebhookService } from "./webhook.service.js";
+
+/** Provider authentication is performed over raw bytes; browser session guards do not apply. */
+@Controller("live-monitor/webhooks")
+export class MonitorWebhookController {
+  constructor(@Inject(MonitorWebhookService) private readonly webhook: MonitorWebhookService) {}
+
+  @Post(":endpointId")
+  @HttpCode(200)
+  async ingest(@Param("endpointId") endpointId: string, @Req() request: Request): Promise<{ accepted: true }> {
+    await this.webhook.ingest(endpointId, request.body as Buffer, {
+      signature: request.get("x-monitor-signature"), timestamp: request.get("x-monitor-timestamp"),
+      eventId: request.get("x-monitor-event-id"),
+    });
+    return { accepted: true };
+  }
+}
diff --git a/apps/api/src/live-monitor/webhook.integration.test.ts b/apps/api/src/live-monitor/webhook.integration.test.ts
new file mode 100644
index 0000000..ebe3bfa
--- /dev/null
+++ b/apps/api/src/live-monitor/webhook.integration.test.ts
@@ -0,0 +1,91 @@
+import { createHmac, randomBytes, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+import { vault } from "../vault/vault.js";
+import { LiveMonitorService } from "./live-monitor.service.js";
+import { MonitorWebhookService, type MonitorWebhookEndpoint } from "./webhook.service.js";
+
+const available = process.env.DATABASE_URL !== undefined && process.env.SUPER_DATABASE_URL !== undefined;
+const owner = new Pool({ connectionString: process.env.SUPER_DATABASE_URL });
+const app = new Pool({ connectionString: process.env.DATABASE_URL });
+async function asTenant<T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await app.connect();
+  try {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (error) { await client.query("ROLLBACK"); throw error; }
+  finally { client.release(); }
+}
+
+describe.skipIf(!available)("monitor webhook durable journal and RLS (PostgreSQL)", () => {
+  const secret = randomBytes(32);
+  const workspaces: string[] = [];
+  let endpoint: MonitorWebhookEndpoint;
+  let sourceId: string;
+  let foreignSourceId: string;
+  let monitor: LiveMonitorService;
+  const service = () => new MonitorWebhookService(monitor, { endpoints: [endpoint], tenantTransaction: asTenant });
+
+  beforeAll(async () => {
+    await runMigrations(process.env.MIGRATIONS_DIR ?? join(process.cwd(), "migrations"));
+    for (let index = 0; index < 2; index++) {
+      const workspace = await owner.query<{ id: string }>(
+        "INSERT INTO workspaces (name, slug) VALUES ('Webhook integration', $1) RETURNING id", [`monitor-webhook-${randomUUID()}`]);
+      const workspaceId = workspace.rows[0]!.id;
+      workspaces.push(workspaceId);
+      await asTenant(workspaceId, async (client) => {
+        const connection = await client.query<{ id: string }>(
+          "INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-livestream', 'webhook') RETURNING id", [workspaceId]);
+        const connectionId = connection.rows[0]!.id;
+        const source = await client.query<{ id: string }>(
+          "INSERT INTO source_monitor_states (workspace_id, connection_id, remote_ref) VALUES ($1, $2, 'live:webhook') RETURNING id", [workspaceId, connectionId]);
+        if (index === 0) {
+          sourceId = source.rows[0]!.id;
+          const sealed = await vault.seal(workspaceId, connectionId, secret);
+          const credential = await client.query<{ id: string }>(
+            `INSERT INTO credentials (workspace_id, connection_id, kind, ciphertext, key_version)
+             VALUES ($1, $2, 'monitor-webhook', $3, $4) RETURNING id`, [workspaceId, connectionId, sealed.ciphertext, sealed.keyVersion]);
+          endpoint = { endpointId: randomBytes(32).toString("hex"), workspaceId, connectionId,
+            credentialId: credential.rows[0]!.id, subscriptionId: "db-subscription" };
+        } else foreignSourceId = source.rows[0]!.id;
+      });
+    }
+    monitor = new LiveMonitorService({ tenantTransaction: asTenant });
+  });
+
+  afterAll(async () => {
+    for (const workspace of workspaces) await owner.query("DELETE FROM workspaces WHERE id = $1", [workspace]);
+    await app.end(); await owner.end(); secret.fill(0);
+  });
+
+  function request(source = sourceId, eventId = randomUUID()) {
+    const raw = Buffer.from(JSON.stringify({ sourceId: source, subscriptionId: endpoint.subscriptionId, outcome: "ok" }));
+    const timestamp = new Date().toISOString();
+    const signature = `sha256=${createHmac("sha256", secret).update(eventId).update(timestamp).update(raw).digest("hex")}`;
+    return { raw, headers: { eventId, timestamp, signature } };
+  }
+
+  it("accepts one concurrent delivery, rejects its replay after service restart, persists exactly one journal row", async () => {
+    const { raw, headers } = request();
+    const results = await Promise.allSettled([service().ingest(endpoint.endpointId, raw, headers), service().ingest(endpoint.endpointId, raw, headers)]);
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    expect(results.find((result) => result.status === "rejected")).toMatchObject({ reason: { status: 409 } });
+    await expect(service().ingest(endpoint.endpointId, raw, headers)).rejects.toMatchObject({ status: 409 });
+    expect((await monitor.getState(endpoint.workspaceId, sourceId)).version).toBe(1);
+    const journal = await asTenant(endpoint.workspaceId, (client) => client.query<{ count: number }>(
+      "SELECT count(*)::int AS count FROM monitor_seen_events WHERE source_monitor_state_id = $1", [sourceId]));
+    expect(journal.rows[0]!.count).toBe(1);
+  });
+
+  it("rejects an authenticated event targeting another workspace without touching either source", async () => {
+    const { raw, headers } = request(foreignSourceId);
+    await expect(service().ingest(endpoint.endpointId, raw, headers)).rejects.toMatchObject({ status: 404 });
+    expect((await monitor.getState(workspaces[1]!, foreignSourceId)).version).toBe(0);
+    expect((await monitor.getState(endpoint.workspaceId, sourceId)).version).toBe(1);
+  });
+});
diff --git a/apps/api/src/live-monitor/webhook.service.ts b/apps/api/src/live-monitor/webhook.service.ts
new file mode 100644
index 0000000..72dc00f
--- /dev/null
+++ b/apps/api/src/live-monitor/webhook.service.ts
@@ -0,0 +1,136 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { BadRequestException, Inject, Injectable, NotFoundException, Optional, PayloadTooLargeException, UnauthorizedException } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import { isUuid, requireObject, requireString } from "../http/validation.js";
+import { vault } from "../vault/vault.js";
+import { LiveMonitorService } from "./live-monitor.service.js";
+import type { MonitorRowState, ObservationOutcome } from "./reducer.js";
+
+export const WEBHOOK_MAX_BYTES = 64 * 1024;
+export const WEBHOOK_WINDOW_MS = 5 * 60 * 1000;
+export interface MonitorWebhookEndpoint {
+  endpointId: string;
+  workspaceId: string;
+  connectionId: string;
+  credentialId: string;
+  subscriptionId: string;
+}
+export interface MonitorWebhookHeaders { signature?: string; timestamp?: string; eventId?: string }
+export interface MonitorWebhookDependencies {
+  endpoints: readonly MonitorWebhookEndpoint[];
+  tenantTransaction: typeof withTenant;
+  openSecret: typeof vault.open;
+  now: () => number;
+}
+export const MONITOR_WEBHOOK_DEPENDENCIES = Symbol("MONITOR_WEBHOOK_DEPENDENCIES");
+
+/** Server-controlled mapping, never a workspace/connection supplied by the sender. */
+export function parseWebhookEndpoints(raw: string | undefined): MonitorWebhookEndpoint[] {
+  if (!raw) return [];
+  const value: unknown = JSON.parse(raw);
+  if (!Array.isArray(value)) throw new Error("MONITOR_WEBHOOK_ENDPOINTS must be an array");
+  const endpoints = value.map((entry) => {
+    const row = requireObject(entry, "endpoint");
+    const endpoint: MonitorWebhookEndpoint = {
+      endpointId: requireString(row.endpointId, "endpointId"),
+      workspaceId: requireString(row.workspaceId, "workspaceId"),
+      connectionId: requireString(row.connectionId, "connectionId"),
+      credentialId: requireString(row.credentialId, "credentialId"),
+      subscriptionId: requireString(row.subscriptionId, "subscriptionId"),
+    };
+    if (!/^[a-f0-9]{64}$/.test(endpoint.endpointId)
+      || ![endpoint.workspaceId, endpoint.connectionId, endpoint.credentialId].every(isUuid)) {
+      throw new Error("invalid monitor webhook endpoint mapping (endpointId must be 32 random bytes in hex)");
+    }
+    return endpoint;
+  });
+  if (new Set(endpoints.map((entry) => entry.endpointId)).size !== endpoints.length) {
+    throw new Error("duplicate monitor webhook endpoint");
+  }
+  return endpoints;
+}
+
+/** Signature covers event id + ISO timestamp + exact bytes, including whitespace. */
+export function verifyMonitorSignature(raw: Buffer, headers: MonitorWebhookHeaders, secret: Buffer, now: number): void {
+  const { signature, timestamp, eventId } = headers;
+  if (!signature || !/^sha256=[a-f0-9]{64}$/.test(signature) || !timestamp
+    || !/^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,3})?Z$/.test(timestamp)
+    || !eventId || eventId.length > 256 || /[\s\p{Cc}]/u.test(eventId)
+    || !Number.isFinite(Date.parse(timestamp)) || Math.abs(now - Date.parse(timestamp)) > WEBHOOK_WINDOW_MS) {
+    throw new UnauthorizedException("invalid webhook authentication");
+  }
+  const expected = createHmac("sha256", secret).update(eventId).update(timestamp).update(raw).digest();
+  if (!timingSafeEqual(expected, Buffer.from(signature.slice(7), "hex"))) {
+    throw new UnauthorizedException("invalid webhook authentication");
+  }
+}
+
+@Injectable()
+export class MonitorWebhookService {
+  private readonly config: MonitorWebhookDependencies;
+  constructor(
+    @Inject(LiveMonitorService) private readonly monitor: LiveMonitorService,
+    @Optional() @Inject(MONITOR_WEBHOOK_DEPENDENCIES) dependencies?: Partial<MonitorWebhookDependencies>,
+  ) {
+    this.config = {
+      endpoints: parseWebhookEndpoints(process.env.MONITOR_WEBHOOK_ENDPOINTS),
+      tenantTransaction: withTenant, openSecret: vault.open.bind(vault), now: Date.now,
+      ...dependencies,
+    };
+  }
+
+  async ingest(endpointId: string, raw: Buffer, headers: MonitorWebhookHeaders): Promise<MonitorRowState> {
+    const endpoint = this.config.endpoints.find((entry) => entry.endpointId === endpointId);
+    if (!endpoint) throw new NotFoundException("webhook endpoint not found");
+    if (!Buffer.isBuffer(raw)) throw new BadRequestException("raw webhook body required");
+    if (raw.length > WEBHOOK_MAX_BYTES) throw new PayloadTooLargeException();
+    return this.config.tenantTransaction(endpoint.workspaceId, async (client) => {
+      // A removed connection/revoked credential disables even a configured endpoint.
+      const credential = await client.query<{ ciphertext: Buffer; key_version: number }>(
+        `SELECT cr.ciphertext, cr.key_version FROM credentials cr
+         JOIN connections c ON c.id = cr.connection_id AND c.workspace_id = cr.workspace_id
+         WHERE cr.id = $1 AND cr.connection_id = $2 AND cr.workspace_id = $3
+           AND cr.kind = 'monitor-webhook' AND cr.revoked_at IS NULL AND c.disconnected_at IS NULL
+         FOR SHARE OF cr, c`, [endpoint.credentialId, endpoint.connectionId, endpoint.workspaceId],
+      );
+      const sealed = credential.rows[0];
+      if (!sealed) throw new UnauthorizedException("invalid webhook authentication");
+      let secret: Buffer;
+      try {
+        secret = await this.config.openSecret(endpoint.workspaceId, endpoint.connectionId,
+          { ciphertext: sealed.ciphertext, keyVersion: sealed.key_version });
+      } catch { throw new UnauthorizedException("invalid webhook authentication"); }
+      const now = this.config.now();
+      try {
+        if (secret.length < 32) throw new UnauthorizedException("invalid webhook authentication");
+        verifyMonitorSignature(raw, headers, secret, now);
+      } finally { secret.fill(0); }
+      let parsed: unknown;
+      try { parsed = JSON.parse(raw.toString("utf8")); }
+      catch { throw new BadRequestException("invalid webhook JSON"); }
+      const body = requireObject(parsed, "event");
+      if (body.subscriptionId !== endpoint.subscriptionId
+        || body.workspaceId !== undefined && body.workspaceId !== endpoint.workspaceId
+        || body.connectionId !== undefined && body.connectionId !== endpoint.connectionId) {
+        throw new UnauthorizedException("webhook binding mismatch");
+      }
+      const sourceId = requireString(body.sourceId, "sourceId");
+      if (!isUuid(sourceId)) throw new BadRequestException("sourceId must be a UUID");
+      const outcome = body.outcome;
+      if (outcome !== "ok" && outcome !== "fail" && outcome !== "error" && outcome !== "unavailable") {
+        throw new BadRequestException("invalid webhook outcome");
+      }
+      const source = await client.query(
+        `SELECT id FROM source_monitor_states WHERE id = $1 AND workspace_id = $2 AND connection_id = $3 FOR UPDATE`,
+        [sourceId, endpoint.workspaceId, endpoint.connectionId],
+      );
+      if (source.rowCount !== 1) throw new NotFoundException("webhook source not found");
+      // Journal retention exceeds the acceptance window. The tuple scopes ids per endpoint without ambiguity.
+      const providerEventId = `webhook:${createHash("sha256").update(JSON.stringify([endpointId, headers.eventId])).digest("hex")}`;
+      return this.monitor.recordObservationInTransaction(client, endpoint.workspaceId, sourceId, {
+        tier: "webhook", observedAt: headers.timestamp!, receivedAt: new Date(now).toISOString(), providerEventId,
+        payload: { outcome: outcome as ObservationOutcome, reason: "signed-webhook" },
+      }, { userId: null, role: "monitor-webhook" }, true);
+    });
+  }
+}
diff --git a/apps/api/src/live-monitor/webhook.test.ts b/apps/api/src/live-monitor/webhook.test.ts
new file mode 100644
index 0000000..532c5fb
--- /dev/null
+++ b/apps/api/src/live-monitor/webhook.test.ts
@@ -0,0 +1,199 @@
+import "reflect-metadata";
+import { createHmac } from "node:crypto";
+import { BadRequestException, ConflictException, NotFoundException, UnauthorizedException, type INestApplication } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+import type { PoolClient } from "pg";
+import { afterEach, describe, expect, it } from "vitest";
+import { injectHttp } from "../connections/http-test-transport.js";
+import { vault } from "../vault/vault.js";
+import { LiveMonitorModule } from "./live-monitor.module.js";
+import { LIVE_MONITOR_DEPENDENCIES, LiveMonitorService } from "./live-monitor.service.js";
+import { MEDIA_POLLER_DEPENDENCIES } from "./poller/poller.js";
+import { MONITOR_WEBHOOK_DEPENDENCIES, MonitorWebhookService, parseWebhookEndpoints, verifyMonitorSignature,
+  WEBHOOK_MAX_BYTES, WEBHOOK_WINDOW_MS, type MonitorWebhookDependencies, type MonitorWebhookHeaders } from "./webhook.service.js";
+
+const workspaceId = "11111111-1111-4111-8111-111111111111";
+const connectionId = "22222222-2222-4222-8222-222222222222";
+const credentialId = "33333333-3333-4333-8333-333333333333";
+const sourceId = "44444444-4444-4444-8444-444444444444";
+const endpointId = "ab".repeat(32);
+const endpoint = { endpointId, workspaceId, connectionId, credentialId, subscriptionId: "subscription-1" };
+const secret = Buffer.alloc(32, 42);
+const epoch = Date.parse("2026-01-01T00:00:00.000Z");
+const event = { sourceId, subscriptionId: endpoint.subscriptionId, outcome: "ok" };
+
+function signed(raw: Buffer, eventId = "event-1", time = epoch): MonitorWebhookHeaders {
+  const timestamp = new Date(time).toISOString();
+  return { eventId, timestamp, signature: `sha256=${createHmac("sha256", secret).update(eventId).update(timestamp).update(raw).digest("hex")}` };
+}
+
+async function fixture() {
+  const row: Record<string, unknown> = {
+    id: sourceId, workspace_id: workspaceId, connection_id: connectionId, remote_ref: "live:1",
+    state: "OFFLINE", version: 0, authoritative_tier: null, last_media_health_at: null, last_hls_probe_at: null,
+    last_webhook_at: null, last_api_poll_at: null, tier_status: {}, ok_streak: 0, fail_streak: 0,
+    state_entered_at: new Date(epoch).toISOString(), hold_until: null, cooldown_until: null, previous_state: null,
+    last_transition_at: null, last_transition_reason: null, created_at: new Date(epoch).toISOString(), updated_at: new Date(epoch).toISOString(),
+  };
+  const sealed = await vault.seal(workspaceId, connectionId, secret);
+  const journal = new Set<string>();
+  let now = epoch;
+  let failUpdate = false;
+  let revoked = false;
+  let audits = 0;
+  const client = { async query(sql: string, params: unknown[] = []) {
+    if (sql.startsWith("SELECT cr.ciphertext")) {
+      expect(params).toEqual([credentialId, connectionId, workspaceId]);
+      return { rowCount: revoked ? 0 : 1, rows: revoked ? [] : [{ ciphertext: sealed.ciphertext, key_version: sealed.keyVersion }] };
+    }
+    if (sql.startsWith("SELECT id FROM source_monitor_states")) {
+      const owns = params[0] === row.id && params[1] === row.workspace_id && params[2] === row.connection_id;
+      return { rowCount: owns ? 1 : 0, rows: owns ? [{ id: sourceId }] : [] };
+    }
+    if (sql.startsWith("SELECT * FROM source_monitor_states")) return { rowCount: 1, rows: [{ ...row }] };
+    if (sql.startsWith("INSERT INTO monitor_seen_events")) {
+      const key = JSON.stringify([params[0], params[1]]);
+      if (journal.has(key)) return { rowCount: 0, rows: [] };
+      journal.add(key);
+      return { rowCount: 1, rows: [{}] };
+    }
+    if (sql.startsWith("UPDATE source_monitor_states")) {
+      if (failUpdate) throw new Error("database update failed");
+      const columns = ["state", "version", "authoritative_tier", "last_media_health_at", "last_hls_probe_at",
+        "last_webhook_at", "last_api_poll_at", "tier_status", "ok_streak", "fail_streak", "state_entered_at", "hold_until",
+        "cooldown_until", "previous_state", "last_transition_at", "last_transition_reason", "updated_at"];
+      columns.forEach((column, index) => { row[column] = params[index + 1]; });
+      return { rowCount: 1, rows: [{ ...row }] };
+    }
+    if (sql.startsWith("SELECT audit_append")) { audits++; return { rowCount: 1, rows: [{}] }; }
+    throw new Error(`unexpected query ${sql}`);
+  } } as unknown as PoolClient;
+  let pending = Promise.resolve();
+  const tenantTransaction: MonitorWebhookDependencies["tenantTransaction"] = async (workspace, fn) => {
+    expect(workspace).toBe(workspaceId);
+    const previous = pending;
+    let release!: () => void;
+    pending = new Promise<void>((resolve) => { release = resolve; });
+    await previous;
+    const snapshot = { row: structuredClone(row), journal: [...journal], audits };
+    try { return await fn(client); }
+    catch (error) {
+      Object.assign(row, snapshot.row); journal.clear(); snapshot.journal.forEach((key) => journal.add(key));
+      audits = snapshot.audits;
+      throw error;
+    } finally { release(); }
+  };
+  const dependencies: MonitorWebhookDependencies = {
+    endpoints: [endpoint, { ...endpoint, endpointId: "cd".repeat(32) }],
+    tenantTransaction, now: () => now, openSecret: vault.open.bind(vault),
+  };
+  const monitor = new LiveMonitorService({ tenantTransaction });
+  const service = () => new MonitorWebhookService(monitor, dependencies);
+  return { service, dependencies, monitor, row, journal, audits: () => audits,
+    clock: (time: number) => { now = time; }, fail: (value: boolean) => { failUpdate = value; }, revoke: () => { revoked = true; } };
+}
+
+describe("monitor webhook authentication and ingest", () => {
+  it("verifies exact raw bytes, event id and timestamp in constant-time HMAC", () => {
+    const raw = Buffer.from(JSON.stringify(event));
+    expect(() => verifyMonitorSignature(raw, signed(raw), secret, epoch)).not.toThrow();
+    expect(() => verifyMonitorSignature(raw, signed(raw), Buffer.alloc(32, 43), epoch)).toThrow(UnauthorizedException);
+    expect(() => verifyMonitorSignature(Buffer.concat([raw, Buffer.from(" ")]), signed(raw), secret, epoch)).toThrow(UnauthorizedException);
+    expect(() => verifyMonitorSignature(raw, { ...signed(raw), eventId: "event-2" }, secret, epoch)).toThrow(UnauthorizedException);
+    expect(() => verifyMonitorSignature(raw, { ...signed(raw), timestamp: new Date(epoch + 1000).toISOString() }, secret, epoch)).toThrow(UnauthorizedException);
+    expect(() => verifyMonitorSignature(raw, { ...signed(raw), signature: "sha256=bad" }, secret, epoch)).toThrow(UnauthorizedException);
+  });
+
+  it.each([-1, 1])("rejects signed timestamps outside the window in direction %s", (direction) => {
+    const raw = Buffer.from(JSON.stringify(event));
+    expect(() => verifyMonitorSignature(raw, signed(raw, "event-1", epoch + direction * (WEBHOOK_WINDOW_MS + 1)), secret, epoch)).toThrow(UnauthorizedException);
+    expect(() => verifyMonitorSignature(raw, signed(raw, "event-1", epoch + direction * WEBHOOK_WINDOW_MS), secret, epoch)).not.toThrow();
+  });
+
+  it("folds authenticated events through the existing service and reducer; replay survives service recreation", async () => {
+    const f = await fixture(); const raw = Buffer.from(JSON.stringify(event));
+    expect((await f.service().ingest(endpointId, raw, signed(raw))).state).toBe("PROBING");
+    await expect(f.service().ingest(endpointId, raw, signed(raw))).rejects.toBeInstanceOf(ConflictException);
+    expect(f.row.version).toBe(1); expect(f.audits()).toBe(1); expect(f.journal.size).toBe(1);
+  });
+
+  it("retains dedupe across the full early-to-late timestamp acceptance span", async () => {
+    const f = await fixture(); const raw = Buffer.from(JSON.stringify(event));
+    f.clock(epoch - WEBHOOK_WINDOW_MS);
+    await f.service().ingest(endpointId, raw, signed(raw));
+    f.clock(epoch + 4 * 60 * 1000);
+    await expect(f.service().ingest(endpointId, raw, signed(raw))).rejects.toBeInstanceOf(ConflictException);
+    expect(f.row.version).toBe(1);
+  });
+
+  it("scopes event ids per endpoint, including under concurrent delivery", async () => {
+    const f = await fixture(); const raw = Buffer.from(JSON.stringify(event));
+    const results = await Promise.allSettled([f.service().ingest(endpointId, raw, signed(raw)), f.service().ingest(endpointId, raw, signed(raw))]);
+    expect(results.filter((result) => result.status === "fulfilled")).toHaveLength(1);
+    await f.service().ingest("cd".repeat(32), raw, signed(raw));
+    expect(f.journal.size).toBe(2); expect(f.row.version).toBe(1); // same-tier stale timestamp is still folded only once
+  });
+
+  it.each(["workspace_id", "connection_id"])("rejects a source owned by a different %s before journaling", async (column) => {
+    const f = await fixture(); f.row[column] = "55555555-5555-4555-8555-555555555555";
+    const raw = Buffer.from(JSON.stringify(event));
+    await expect(f.service().ingest(endpointId, raw, signed(raw))).rejects.toBeInstanceOf(NotFoundException);
+    expect(f.journal.size).toBe(0); expect(f.row.version).toBe(0);
+  });
+
+  it.each([{ subscriptionId: "other" }, { workspaceId: "other" }, { connectionId: "other" }])("rejects provider binding mismatch %j", async (binding) => {
+    const f = await fixture(); const raw = Buffer.from(JSON.stringify({ ...event, ...binding }));
+    await expect(f.service().ingest(endpointId, raw, signed(raw))).rejects.toBeInstanceOf(UnauthorizedException);
+    expect(f.journal.size).toBe(0); expect(f.row.version).toBe(0);
+  });
+
+  it("rolls back the replay claim when state persistence fails", async () => {
+    const f = await fixture(); const raw = Buffer.from(JSON.stringify(event)); f.fail(true);
+    await expect(f.service().ingest(endpointId, raw, signed(raw))).rejects.toThrow("database update failed");
+    expect(f.journal.size).toBe(0); f.fail(false);
+    expect((await f.service().ingest(endpointId, raw, signed(raw))).version).toBe(1);
+  });
+
+  it("rejects unknown endpoints, revoked credentials, malformed JSON and bad authentication without writes", async () => {
+    const f = await fixture(); const raw = Buffer.from(JSON.stringify(event));
+    await expect(f.service().ingest("unknown", raw, signed(raw))).rejects.toBeInstanceOf(NotFoundException);
+    await expect(f.service().ingest(endpointId, raw, {})).rejects.toBeInstanceOf(UnauthorizedException);
+    const malformed = Buffer.from("{");
+    await expect(f.service().ingest(endpointId, malformed, signed(malformed))).rejects.toBeInstanceOf(BadRequestException);
+    f.revoke();
+    await expect(f.service().ingest(endpointId, raw, signed(raw))).rejects.toBeInstanceOf(UnauthorizedException);
+    expect(f.journal.size).toBe(0); expect(f.row.version).toBe(0);
+  });
+
+  it("requires valid and unique server-controlled endpoint mappings", () => {
+    expect(parseWebhookEndpoints(JSON.stringify([endpoint]))).toEqual([endpoint]);
+    expect(() => parseWebhookEndpoints(JSON.stringify([endpoint, endpoint]))).toThrow("duplicate");
+    expect(() => parseWebhookEndpoints(JSON.stringify([{ ...endpoint, endpointId: "guessable" }]))).toThrow("invalid");
+  });
+});
+
+describe("monitor webhook raw HTTP route", () => {
+  let app: INestApplication | undefined;
+  afterEach(async () => { await app?.close(); app = undefined; });
+
+  it("captures whitespace before Nest JSON parsing, needs no browser session, rejects replay/tampering/oversize", async () => {
+    const f = await fixture();
+    app = await NestFactory.create({ module: LiveMonitorModule, providers: [
+      { provide: LIVE_MONITOR_DEPENDENCIES, useValue: { tenantTransaction: f.dependencies.tenantTransaction } },
+      { provide: MONITOR_WEBHOOK_DEPENDENCIES, useValue: f.dependencies },
+      { provide: MEDIA_POLLER_DEPENDENCIES, useValue: { enabled: false } },
+    ] }, { logger: false, abortOnError: false });
+    await app.init();
+    const body = `  ${JSON.stringify(event, null, 2)}\n`;
+    const auth = signed(Buffer.from(body));
+    const headers = { "content-type": "application/json", "x-monitor-signature": auth.signature!,
+      "x-monitor-timestamp": auth.timestamp!, "x-monitor-event-id": auth.eventId! };
+    const post = (value: string) => injectHttp(app!.getHttpAdapter().getInstance(), `http://api.test/live-monitor/webhooks/${endpointId}`,
+      { method: "POST", body: value, headers });
+    expect((await post(body)).status).toBe(200);
+    expect((await post(body)).status).toBe(409);
+    expect((await post(`${body} `)).status).toBe(401);
+    expect((await post(" ".repeat(WEBHOOK_MAX_BYTES + 1))).status).toBe(413);
+    expect(f.row.version).toBe(1);
+  });
+});
diff --git a/apps/api/src/live/go-live.service.ts b/apps/api/src/live/go-live.service.ts
new file mode 100644
index 0000000..5c999d5
--- /dev/null
+++ b/apps/api/src/live/go-live.service.ts
@@ -0,0 +1,171 @@
+import { BadRequestException, ConflictException, Inject, Injectable, NotFoundException, Optional } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+import { LiveDestinationRepository, type OutputSummary } from "./live-destination.repository.js";
+import { createGenericHlsResolver, GENERIC_HLS_PROVIDER, type LiveSourceResolver } from "./live-source-resolver.js";
+
+export type TenantTransaction = <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+
+/**
+ * The media-plane target a go-live spawns: everything the relay needs, with
+ * raw secret material held only inside this service's resolution path.
+ */
+export interface ResolvedOutputTarget {
+  output: OutputSummary;
+  /** Ingest endpoint for the push (destination's, or null for a disabled/generic-missing output). */
+  endpointUrl: string;
+  /** True when the credential came through a destination (vs the output's own handle). */
+  throughDestination: boolean;
+  /** Vault handle the worker's VaultHandleBroker redeems at relay start. */
+  credentialHandleId: string | null;
+}
+
+/** Resolved program input for the take/start path. */
+export interface ResolvedProgramSource {
+  playbackHlsUrl: string;
+  live: boolean;
+  provider: string;
+}
+
+export interface GoLiveDependencies {
+  transaction: TenantTransaction;
+  /** Provider-keyed resolvers; connectors register their own, generic-hls is built in. */
+  sourceResolvers: Map<string, LiveSourceResolver>;
+}
+
+export const GO_LIVE_DEPENDENCIES = Symbol("GO_LIVE_DEPENDENCIES");
+
+/**
+ * Go-live wiring (WP6/WP9): take/start resolves StreamOutput ->
+ * LiveStreamDestination -> credential via the vault (same pattern as the
+ * publish credential accessor), and resolves the program source through
+ * connector-level resolvers. Nothing here mutates Redis or signs commands;
+ * callers feed the result into MediaControlService.setDesired/director.
+ */
+@Injectable()
+export class GoLiveService {
+  private readonly resolvers: Map<string, LiveSourceResolver>;
+  private readonly transaction: TenantTransaction;
+
+  constructor(
+    @Inject(LiveDestinationRepository) private readonly destinations: LiveDestinationRepository,
+    @Optional() @Inject(GO_LIVE_DEPENDENCIES) dependencies?: Partial<GoLiveDependencies>,
+  ) {
+    const defaults: GoLiveDependencies = {
+      transaction: withTenant,
+      sourceResolvers: new Map([[GENERIC_HLS_PROVIDER, createGenericHlsResolver()]]),
+    };
+    const merged = { ...defaults, ...dependencies };
+    this.resolvers = merged.sourceResolvers;
+    this.transaction = merged.transaction;
+  }
+
+  registerSourceResolver(provider: string, resolver: LiveSourceResolver): void {
+    this.resolvers.set(provider, resolver);
+  }
+
+  /**
+   * Resolve every enabled output of a channel into media-plane targets.
+   * Destination-referenced outputs resolve their credential handle through the
+   * destination (aggregate boundary); handle outputs pass theirs through
+   * untouched. The raw stream key never enters this surface — the worker
+   * redeems the handle at relay start.
+   */
+  async resolveOutputs(workspaceId: string, virtualChannelId: string): Promise<ResolvedOutputTarget[]> {
+    const outputs = await this.listChannelOutputs(workspaceId, virtualChannelId);
+    const targets: ResolvedOutputTarget[] = [];
+    for (const output of outputs) {
+      if (!output.enabled) continue;
+      if (output.destinationId !== null) {
+        const destination = await this.destinations.get(workspaceId, output.destinationId);
+        if (destination.credentialId === null) {
+          throw new ConflictException(`destination ${destination.label} has no ingest credential`);
+        }
+        if (destination.credentialRevokedAt !== null) {
+          throw new ConflictException(`destination ${destination.label} ingest credential is revoked`);
+        }
+        targets.push({
+          output,
+          endpointUrl: destination.endpointUrl,
+          throughDestination: true,
+          credentialHandleId: destination.credentialId,
+        });
+        continue;
+      }
+      const handle = output.credentialHandleId;
+      if (handle === null) throw new ConflictException(`stream output ${output.id} has neither destination nor credential handle`);
+      targets.push({ output, endpointUrl: "", throughDestination: false, credentialHandleId: handle });
+    }
+    return targets;
+  }
+
+  /**
+   * Take/start resolution of the program source for a virtual channel source
+   * row: provider-keyed resolvers (twitch via Helix, generic-hls direct) map
+   * {channelId | externalUrl} to {playbackHlsUrl, live}.
+   */
+  async resolveProgramSource(workspaceId: string, request: { provider: string; channelId?: string; externalUrl?: string }): Promise<ResolvedProgramSource> {
+    if (request.provider === "") throw new BadRequestException("provider is required");
+    const resolver = this.resolvers.get(request.provider);
+    if (resolver === undefined) throw new NotFoundException(`no live source resolver for provider ${request.provider}`);
+    const resolution = await resolver({ channelId: request.channelId, externalUrl: request.externalUrl });
+    if (resolution.playbackHlsUrl === null) {
+      throw new ConflictException(`live source for ${request.provider} is not live`);
+    }
+    return { playbackHlsUrl: resolution.playbackHlsUrl, live: resolution.live, provider: request.provider };
+  }
+
+  /**
+   * Redeem the destination ingest credential (vault.open with tenant + handle
+   * AAD) for a destination-referenced output. Called only by the relay spawn
+   * path; the returned secret never reaches logs, audit, or HTTP responses.
+   */
+  async redeemDestinationCredential(workspaceId: string, destinationId: string): Promise<{ endpointUrl: string; streamKey: string; provider: string }> {
+    return this.destinations.resolveIngestCredential(workspaceId, destinationId);
+  }
+
+  /**
+   * Take/start: build a DesiredSpec for the go-live flow from the channel's
+   * enabled StreamOutputs and a resolved program source. Destination-referenced
+   * outputs contribute the destination's endpoint + credential handle (resolved
+   * through the vault at relay start); a single-output channel maps onto the
+   * v1 spec shape MediaControlService.setDesired expects. Channels with
+   * multiple enabled outputs are a multi-fan-out concern of the worker relay
+   * (WP9) and resolve per-output there.
+   */
+  async desiredSpecForGoLive(workspaceId: string, virtualChannelId: string, source: { provider: string; channelId?: string; externalUrl?: string },
+    options?: { profile?: "720p30" | "1080p30" | "1080p60"; mode?: "passthrough" | "normalize" }): Promise<{
+      desiredStatus: "RUNNING";
+      source: { kind: "hls"; url: string };
+      output: { endpointUrl: string; credentialHandleId: string };
+      profile: "720p30" | "1080p30" | "1080p60";
+      mode: "passthrough" | "normalize";
+    }> {
+    const [program, outputs] = await Promise.all([
+      this.resolveProgramSource(workspaceId, source),
+      this.resolveOutputs(workspaceId, virtualChannelId),
+    ]);
+    if (outputs.length === 0) throw new ConflictException("no enabled stream outputs for this channel");
+    const target = outputs[0]!;
+    return {
+      desiredStatus: "RUNNING",
+      source: { kind: "hls", url: program.playbackHlsUrl },
+      output: { endpointUrl: target.endpointUrl, credentialHandleId: target.credentialHandleId ?? "" },
+      profile: options?.profile ?? (target.output.profile as "720p30" | "1080p30" | "1080p60"),
+      mode: options?.mode ?? (target.output.mode as "passthrough" | "normalize"),
+    };
+  }
+
+  private async listChannelOutputs(workspaceId: string, virtualChannelId: string): Promise<OutputSummary[]> {
+    return this.transaction(workspaceId, async (client) => {
+      const result = await client.query("SELECT * FROM stream_outputs WHERE workspace_id = $1 AND virtual_channel_id = $2 ORDER BY created_at", [workspaceId, virtualChannelId]);
+      return result.rows.map((row) => ({
+        id: String(row.id), workspaceId: String(row.workspace_id), virtualChannelId: String(row.virtual_channel_id),
+        label: String(row.label), profile: String(row.profile), mode: String(row.mode), enabled: Boolean(row.enabled),
+        destinationId: row.destination_id === null ? null : String(row.destination_id),
+        credentialHandleId: row.credential_handle_id === null ? null : String(row.credential_handle_id),
+        createdAt: new Date(row.created_at), updatedAt: new Date(row.updated_at),
+      }));
+    });
+  }
+}
diff --git a/apps/api/src/live/live-destination.controller.ts b/apps/api/src/live/live-destination.controller.ts
new file mode 100644
index 0000000..4852f39
--- /dev/null
+++ b/apps/api/src/live/live-destination.controller.ts
@@ -0,0 +1,62 @@
+import { Body, Controller, Delete, Get, Inject, Param, Patch, Post, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { parseId, requireSession } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { LiveDestinationRepository, parseCreateDestination, parseUpdateDestination, type DestinationRecord, type OutputSummary } from "./live-destination.repository.js";
+
+@Controller("live/destinations")
+@UseGuards(RbacGuard)
+export class LiveDestinationController {
+  constructor(@Inject(LiveDestinationRepository) private readonly destinations: LiveDestinationRepository) {}
+
+  @Post()
+  @RequirePermission("streamoutput.manage")
+  async create(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<DestinationRecord> {
+    const session = requireSession(request);
+    return this.destinations.create(session.workspaceId, parseCreateDestination(body),
+      { userId: session.userId, role: session.role });
+  }
+
+  @Get()
+  @RequirePermission("streamoutput.manage")
+  async list(@Req() request: Request & AuthenticatedRequest): Promise<DestinationRecord[]> {
+    return this.destinations.list(requireSession(request).workspaceId);
+  }
+
+  @Get(":id")
+  @RequirePermission("streamoutput.manage")
+  async get(@Req() request: Request & AuthenticatedRequest, @Param("id") id: string): Promise<DestinationRecord> {
+    return this.destinations.get(requireSession(request).workspaceId, parseId(id));
+  }
+
+  @Patch(":id")
+  @RequirePermission("streamoutput.manage")
+  async update(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+    @Body() body: unknown,
+  ): Promise<DestinationRecord> {
+    const session = requireSession(request);
+    return this.destinations.update(session.workspaceId, parseId(id), parseUpdateDestination(body),
+      { userId: session.userId, role: session.role });
+  }
+
+  @Delete(":id")
+  @RequirePermission("streamoutput.manage")
+  async remove(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+  ): Promise<{ id: string; disabledOutputs: number; revokedCredential: boolean }> {
+    const session = requireSession(request);
+    const parsed = parseId(id);
+    const result = await this.destinations.remove(session.workspaceId, parsed,
+      { userId: session.userId, role: session.role });
+    return { id: parsed, ...result };
+  }
+
+  @Get(":id/outputs")
+  @RequirePermission("streamoutput.manage")
+  async outputs(@Req() request: Request & AuthenticatedRequest, @Param("id") id: string): Promise<OutputSummary[]> {
+    return this.destinations.outputsForDestination(requireSession(request).workspaceId, parseId(id));
+  }
+}
diff --git a/apps/api/src/live/live-destination.integration.test.ts b/apps/api/src/live/live-destination.integration.test.ts
new file mode 100644
index 0000000..c4f0a7f
--- /dev/null
+++ b/apps/api/src/live/live-destination.integration.test.ts
@@ -0,0 +1,171 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+
+/**
+ * Migration 022 (WP6 live destinations + stream outputs) against a live
+ * PostgreSQL: the exclusive-target CHECK, the FK-lifecycle rule, and FORCE
+ * RLS tenant isolation on both new tables. Assertions run as sp_app
+ * (DATABASE_URL); setup/cleanup as owner. Skipped without DATABASE_URL.
+ */
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+const appPool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const FK_VIOLATION = "23503";
+const CHECK_VIOLATION = "23514";
+const RLS_VIOLATION = "42501";
+
+async function asTenant<T>(workspaceId: string | null, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await appPool.connect();
+  try {
+    await client.query("BEGIN");
+    if (workspaceId !== null) await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+
+/** Each expected failure runs in its own savepoint so the surrounding tx survives. */
+async function expectQueryError(client: PoolClient, codes: string | string[], sql: string, params: unknown[]): Promise<void> {
+  const accepted = Array.isArray(codes) ? codes : [codes];
+  await client.query("SAVEPOINT probe");
+  try {
+    await client.query(sql, params);
+    expect.fail(`expected ${sql} to fail with ${accepted.join("|")}`);
+  } catch (error) {
+    expect(accepted).toContain((error as { code?: string }).code);
+  } finally {
+    await client.query("ROLLBACK TO SAVEPOINT probe");
+  }
+}
+
+describe.skipIf(!dbAvailable)("live destinations + stream outputs (live DB)", () => {
+  let wsA: string;
+  let wsB: string;
+  let channelA: string;
+
+  beforeAll(async () => {
+    await runMigrations(join(process.cwd(), "migrations"));
+    await ownerPool.query("BEGIN");
+    const a = await ownerPool.query("INSERT INTO workspaces(name,slug) VALUES('Live A',$1) RETURNING id", [`la-${randomUUID().slice(0, 8)}`]);
+    const b = await ownerPool.query("INSERT INTO workspaces(name,slug) VALUES('Live B',$1) RETURNING id", [`lb-${randomUUID().slice(0, 8)}`]);
+    wsA = a.rows[0].id as string;
+    wsB = b.rows[0].id as string;
+    await ownerPool.query("SELECT set_config('app.workspace_id', $1, false)", [wsA]);
+    const ch = await ownerPool.query("INSERT INTO virtual_channels(workspace_id,slug,name) VALUES($1,'live','Live') RETURNING id", [wsA]);
+    channelA = ch.rows[0].id as string;
+    await ownerPool.query("COMMIT");
+  });
+
+  afterAll(async () => {
+    await ownerPool.query("DELETE FROM workspaces WHERE id IN ($1,$2)", [wsA, wsB]);
+    await appPool.end();
+    await ownerPool.end();
+  });
+
+  async function destination(client: PoolClient, workspaceId: string, credentialId: string | null = null): Promise<string> {
+    const result = await client.query(
+      "INSERT INTO live_stream_destinations(workspace_id,label,provider,endpoint_url,credential_id) VALUES($1,$2,'peertube','rtmps://live.example.net/app',$3) RETURNING id",
+      [workspaceId, `dest-${randomUUID().slice(0, 8)}`, credentialId],
+    );
+    return result.rows[0].id as string;
+  }
+
+  async function credential(client: PoolClient, workspaceId: string): Promise<string> {
+    const result = await client.query(
+      "INSERT INTO credentials(workspace_id,kind,ciphertext,key_version) VALUES($1,'ingest-stream-key',gen_random_bytes(48),1) RETURNING id",
+      [workspaceId],
+    );
+    return result.rows[0].id as string;
+  }
+
+  it("holds the exclusive-target CHECK: neither or both targets rejected", async () => {
+    await asTenant(wsA, async (client) => {
+      const dest = await destination(client, wsA);
+      await expectQueryError(client, CHECK_VIOLATION,
+        "INSERT INTO stream_outputs(workspace_id,virtual_channel_id,label,destination_id,credential_handle_id) VALUES($1,$2,'none',NULL,NULL)",
+        [wsA, channelA]);
+      await expectQueryError(client, CHECK_VIOLATION,
+        "INSERT INTO stream_outputs(workspace_id,virtual_channel_id,label,destination_id,credential_handle_id) VALUES($1,$2,'both',$3,'vh_0123456789abcdef')",
+        [wsA, channelA, dest]);
+      await client.query(
+        "INSERT INTO stream_outputs(workspace_id,virtual_channel_id,label,destination_id,credential_handle_id) VALUES($1,$2,'dest',$3,NULL)",
+        [wsA, channelA, dest],
+      );
+    });
+  });
+
+  it("FK-lifecycle: deleting the destination while outputs reference it fails", async () => {
+    await asTenant(wsA, async (client) => {
+      const dest = await destination(client, wsA);
+      await client.query(
+        "INSERT INTO stream_outputs(workspace_id,virtual_channel_id,label,destination_id,credential_handle_id,enabled) VALUES($1,$2,'x',$3,NULL,false)",
+        [wsA, channelA, dest],
+      );
+      await expect(client.query("DELETE FROM live_stream_destinations WHERE workspace_id=$1 AND id=$2", [wsA, dest]))
+        .rejects.toMatchObject({ code: FK_VIOLATION });
+    });
+  });
+
+  it("FK-lifecycle: the credential cannot be deleted before its destination", async () => {
+    await asTenant(wsA, async (client) => {
+      const cred = await credential(client, wsA);
+      const dest = await destination(client, wsA, cred);
+      await expectQueryError(client, FK_VIOLATION,
+        "DELETE FROM credentials WHERE workspace_id=$1 AND id=$2", [wsA, cred]);
+      // Orderly lifecycle: delete destination first, then the credential row.
+      await client.query("DELETE FROM live_stream_destinations WHERE workspace_id=$1 AND id=$2", [wsA, dest]);
+      await client.query("DELETE FROM credentials WHERE workspace_id=$1 AND id=$2", [wsA, cred]);
+    });
+  });
+
+  it("FORCE RLS isolates both new tables across tenants", async () => {
+    const destA = await asTenant(wsA, async (client) => destination(client, wsA));
+    await asTenant(wsB, async (client) => {
+      const rows = await client.query("SELECT count(*)::int AS n FROM live_stream_destinations");
+      expect(rows.rows[0].n).toBe(0);
+      await expectQueryError(client, RLS_VIOLATION,
+        "INSERT INTO live_stream_destinations(workspace_id,label,provider,endpoint_url) VALUES($1,'cross','peertube','rtmps://live.example.net/app')",
+        [wsA]);
+      // A stream output of B referencing A's destination is denied — by the
+      // tenant policy and/or the tenant-composite FK, whichever fires first.
+      const channelB = await client.query(
+        "INSERT INTO virtual_channels(workspace_id,slug,name) VALUES($1,'live','Live') RETURNING id", [wsB]);
+      await expectQueryError(client, [RLS_VIOLATION, FK_VIOLATION],
+        "INSERT INTO stream_outputs(workspace_id,virtual_channel_id,label,destination_id,credential_handle_id) VALUES($1,$2,'cross',$3,NULL)",
+        [wsB, channelB.rows[0].id, destA]);
+      // And the denial is durable: B still has no outputs at all.
+      const bOutputs = await client.query("SELECT count(*)::int AS n FROM stream_outputs");
+      expect(bOutputs.rows[0].n).toBe(0);
+    });
+    const seen = await asTenant(wsA, async (client) => client.query("SELECT count(*)::int AS n FROM live_stream_destinations"));
+    expect(seen.rows[0].n).toBeGreaterThanOrEqual(1);
+    // No tenant context at all: zero rows, fail closed (FORCE binds sp_app).
+    const none = await asTenant(null, async (client) => client.query("SELECT count(*)::int AS n FROM live_stream_destinations"));
+    expect(none.rows[0].n).toBe(0);
+  });
+
+  it("rejects workspace_id changes on both tables (lifecycle immutability)", async () => {
+    await asTenant(wsA, async (client) => {
+      const dest = await destination(client, wsA);
+      await expectQueryError(client, CHECK_VIOLATION,
+        "UPDATE live_stream_destinations SET workspace_id=$2 WHERE id=$1", [dest, wsB]);
+      const out = (await client.query(
+        "INSERT INTO stream_outputs(workspace_id,virtual_channel_id,label,credential_handle_id) VALUES($1,$2,'g','vh_0123456789abcdef') RETURNING id",
+        [wsA, channelA],
+      )).rows[0].id as string;
+      await expectQueryError(client, CHECK_VIOLATION,
+        "UPDATE stream_outputs SET workspace_id=$2 WHERE id=$1", [out, wsB]);
+    });
+  });
+});
diff --git a/apps/api/src/live/live-destination.repository.ts b/apps/api/src/live/live-destination.repository.ts
new file mode 100644
index 0000000..4f3db7d
--- /dev/null
+++ b/apps/api/src/live/live-destination.repository.ts
@@ -0,0 +1,348 @@
+import { BadRequestException, ConflictException, Inject, Injectable, NotFoundException, Optional } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { Vault } from "@tactical-media-broadcast-hub/connector-runtime";
+import { vault } from "../vault/vault.js";
+import { withTenant } from "../db/client.js";
+import type { LiveStreamDestination } from "@tactical-media-broadcast-hub/core";
+import { validateEndpointShape } from "../media-control/endpoints.js";
+import { scrub } from "../audit/audit.service.js";
+
+export type DestinationPlatformState = LiveStreamDestination["lastPlatformState"];
+
+export interface DestinationRecord {
+  id: string;
+  workspaceId: string;
+  label: string;
+  provider: string;
+  endpointUrl: string;
+  credentialId: string | null;
+  credentialRevokedAt: Date | null;
+  lastPlatformState: DestinationPlatformState;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateDestination {
+  label: string;
+  provider: string;
+  endpointUrl: string;
+  credentialId?: string | null;
+}
+
+export interface UpdateDestination extends Partial<CreateDestination> {
+  lastPlatformState?: DestinationPlatformState;
+}
+
+export interface OutputSummary {
+  id: string;
+  workspaceId: string;
+  virtualChannelId: string;
+  label: string;
+  profile: string;
+  mode: string;
+  enabled: boolean;
+  destinationId: string | null;
+  credentialHandleId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Credential material the go-live path resolves for a destination-referenced output. */
+export interface ResolvedIngestCredential {
+  endpointUrl: string;
+  /** Raw secret, only ever returned to the vault-backed relay path — never logged or audited. */
+  streamKey: string;
+  provider: string;
+}
+
+export type TenantTransaction = <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+
+export interface LiveDestinationDependencies {
+  transaction: TenantTransaction;
+  encryption: Vault;
+}
+
+export const LIVE_DESTINATION_DEPENDENCIES = Symbol("LIVE_DESTINATION_DEPENDENCIES");
+
+const DEFAULT_DEPENDENCIES: LiveDestinationDependencies = { transaction: withTenant, encryption: vault };
+
+const LABEL = /^.{1,120}$/s;
+const PROVIDER = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const STATE_VALUES: readonly DestinationPlatformState[] = ["unknown", "created", "waiting", "live", "ended"];
+
+function destinationFromRow(row: Record<string, unknown>): DestinationRecord {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    label: String(row.label),
+    provider: String(row.provider),
+    endpointUrl: String(row.endpoint_url),
+    credentialId: row.credential_id === null ? null : String(row.credential_id),
+    credentialRevokedAt: row.credential_revoked_at === null || row.credential_revoked_at === undefined ? null : new Date(row.credential_revoked_at as string),
+    lastPlatformState: (row.last_platform_state ?? "unknown") as DestinationPlatformState,
+    createdAt: new Date(row.created_at as Date),
+    updatedAt: new Date(row.updated_at as Date),
+  };
+}
+
+function outputFromRow(row: Record<string, unknown>): OutputSummary {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    virtualChannelId: String(row.virtual_channel_id),
+    label: String(row.label),
+    profile: String(row.profile),
+    mode: String(row.mode),
+    enabled: Boolean(row.enabled),
+    destinationId: row.destination_id === null ? null : String(row.destination_id),
+    credentialHandleId: row.credential_handle_id === null ? null : String(row.credential_handle_id),
+    createdAt: new Date(row.created_at as Date),
+    updatedAt: new Date(row.updated_at as Date),
+  };
+}
+
+export function parseCreateDestination(value: unknown): CreateDestination {
+  if (typeof value !== "object" || value === null) throw new BadRequestException("body must be an object");
+  const body = value as Record<string, unknown>;
+  const label = typeof body.label === "string" ? body.label.trim() : "";
+  if (!LABEL.test(label)) throw new BadRequestException("label must be 1-120 characters");
+  const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
+  if (!PROVIDER.test(provider)) throw new BadRequestException("provider must be 1-64 lowercase identifier characters");
+  const endpointUrl = typeof body.endpointUrl === "string" ? body.endpointUrl : "";
+  if (endpointUrl === "") throw new BadRequestException("endpointUrl is required");
+  try { validateEndpointShape(endpointUrl, "output"); } catch (error: unknown) {
+    throw new BadRequestException(`endpointUrl: ${error instanceof Error ? error.message : "invalid endpoint"}`);
+  }
+  const credentialId = body.credentialId === undefined || body.credentialId === null ? null : String(body.credentialId);
+  return { label, provider, endpointUrl, credentialId };
+}
+
+export function parseUpdateDestination(value: unknown): UpdateDestination {
+  if (typeof value !== "object" || value === null) throw new BadRequestException("body must be an object");
+  const body = value as Record<string, unknown>;
+  const update: UpdateDestination = {};
+  if (body.label !== undefined) {
+    const label = typeof body.label === "string" ? body.label.trim() : "";
+    if (!LABEL.test(label)) throw new BadRequestException("label must be 1-120 characters");
+    update.label = label;
+  }
+  if (body.provider !== undefined) {
+    const provider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
+    if (!PROVIDER.test(provider)) throw new BadRequestException("provider must be 1-64 lowercase identifier characters");
+    update.provider = provider;
+  }
+  if (body.endpointUrl !== undefined) {
+    const endpointUrl = typeof body.endpointUrl === "string" ? body.endpointUrl : "";
+    if (endpointUrl === "") throw new BadRequestException("endpointUrl cannot be empty");
+    try { validateEndpointShape(endpointUrl, "output"); } catch (error: unknown) {
+      throw new BadRequestException(`endpointUrl: ${error instanceof Error ? error.message : "invalid endpoint"}`);
+    }
+    update.endpointUrl = endpointUrl;
+  }
+  if (body.credentialId !== undefined) update.credentialId = body.credentialId === null ? null : String(body.credentialId);
+  if (body.lastPlatformState !== undefined) {
+    if (!STATE_VALUES.includes(body.lastPlatformState as DestinationPlatformState)) throw new BadRequestException("lastPlatformState is invalid");
+    update.lastPlatformState = body.lastPlatformState as DestinationPlatformState;
+  }
+  if (Object.keys(update).length === 0) throw new BadRequestException("no recognized fields to update");
+  return update;
+}
+
+@Injectable()
+export class LiveDestinationRepository {
+  private readonly deps: LiveDestinationDependencies;
+
+  constructor(@Optional() @Inject(LIVE_DESTINATION_DEPENDENCIES) dependencies?: Partial<LiveDestinationDependencies>) {
+    this.deps = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+  }
+
+  async list(workspaceId: string): Promise<DestinationRecord[]> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT d.*, c.revoked_at AS credential_revoked_at
+           FROM live_stream_destinations d
+           LEFT JOIN credentials c ON c.id = d.credential_id AND c.workspace_id = d.workspace_id
+          WHERE d.workspace_id = $1 ORDER BY d.label, d.id`,
+        [workspaceId],
+      );
+      return result.rows.map(destinationFromRow);
+    });
+  }
+
+  async get(workspaceId: string, id: string): Promise<DestinationRecord> {
+    return this.deps.transaction(workspaceId, async (client) => this.read(client, workspaceId, id));
+  }
+
+  private async read(client: PoolClient, workspaceId: string, id: string): Promise<DestinationRecord> {
+    const result = await client.query(
+      `SELECT d.*, c.revoked_at AS credential_revoked_at
+         FROM live_stream_destinations d
+         LEFT JOIN credentials c ON c.id = d.credential_id AND c.workspace_id = d.workspace_id
+        WHERE d.workspace_id = $1 AND d.id = $2`,
+      [workspaceId, id],
+    );
+    const row = result.rows[0];
+    if (row === undefined) throw new NotFoundException("live stream destination not found");
+    return destinationFromRow(row);
+  }
+
+  async create(workspaceId: string, input: CreateDestination, actor: { userId: string | null; role: string }): Promise<DestinationRecord> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      if (input.credentialId !== null) await this.assertLiveCredential(client, workspaceId, input.credentialId ?? "");
+      const result = await client.query(
+        `INSERT INTO live_stream_destinations (workspace_id, label, provider, endpoint_url, credential_id)
+         VALUES ($1, $2, $3, $4, $5) RETURNING *`,
+        [workspaceId, input.label, input.provider, input.endpointUrl, input.credentialId],
+      );
+      const record = destinationFromRow(result.rows[0] ?? {});
+      await this.audit(client, workspaceId, actor, "live.destination.created", record.id, {
+        provider: record.provider, labeled: record.label,
+      });
+      return record;
+    });
+  }
+
+  async update(workspaceId: string, id: string, input: UpdateDestination, actor: { userId: string | null; role: string }): Promise<DestinationRecord> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM live_stream_destinations WHERE workspace_id = $1 AND id = $2 FOR UPDATE", [workspaceId, id]);
+      const before = await this.read(client, workspaceId, id);
+      if (input.credentialId !== undefined && input.credentialId !== null) {
+        await this.assertLiveCredential(client, workspaceId, input.credentialId);
+      }
+      const result = await client.query(
+        `UPDATE live_stream_destinations SET
+           label = COALESCE($3, label), provider = COALESCE($4, provider),
+           endpoint_url = COALESCE($5, endpoint_url),
+           credential_id = CASE WHEN $6 THEN $7 ELSE credential_id END,
+           last_platform_state = COALESCE($8, last_platform_state),
+           updated_at = now()
+         WHERE workspace_id = $1 AND id = $2 RETURNING *`,
+        [workspaceId, id, input.label ?? null, input.provider ?? null, input.endpointUrl ?? null,
+          input.credentialId !== undefined, input.credentialId ?? null, input.lastPlatformState ?? null],
+      );
+      if (result.rows[0] === undefined) throw new NotFoundException("live stream destination not found");
+      const record = destinationFromRow(result.rows[0]);
+      await this.audit(client, workspaceId, actor, "live.destination.updated", id, {
+        providerChanged: input.provider !== undefined && input.provider !== before.provider,
+        endpointChanged: input.endpointUrl !== undefined && input.endpointUrl !== before.endpointUrl,
+        credentialChanged: input.credentialId !== undefined,
+      });
+      return record;
+    });
+  }
+
+  /**
+   * WP6 lifecycle rule: 409 while a referencing output is enabled; otherwise
+   * disable dependents, revoke the ingest credential, delete the row.
+   */
+  async remove(workspaceId: string, id: string, actor: { userId: string | null; role: string }): Promise<{ disabledOutputs: number; revokedCredential: boolean }> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM live_stream_destinations WHERE workspace_id = $1 AND id = $2 FOR UPDATE", [workspaceId, id]);
+      const record = await this.read(client, workspaceId, id);
+      const referencing = await client.query<{ id: string; enabled: boolean }>(
+        "SELECT id, enabled FROM stream_outputs WHERE workspace_id = $1 AND destination_id = $2",
+        [workspaceId, id],
+      );
+      const enabled = referencing.rows.filter((row) => row.enabled);
+      if (enabled.length > 0) {
+        throw new ConflictException(
+          `live stream destination is referenced by ${enabled.length} enabled stream output(s); disable them first`,
+        );
+      }
+      const disabled = await client.query(
+        "UPDATE stream_outputs SET enabled = false, updated_at = now() WHERE workspace_id = $1 AND destination_id = $2 AND enabled RETURNING id",
+        [workspaceId, id],
+      );
+      const deleted = await client.query("DELETE FROM live_stream_destinations WHERE workspace_id = $1 AND id = $2 RETURNING id", [workspaceId, id]);
+      if (deleted.rows[0] === undefined) throw new NotFoundException("live stream destination not found");
+      let revoked = false;
+      if (record.credentialId !== null) {
+        await client.query("UPDATE credentials SET revoked_at = now() WHERE id = $1 AND workspace_id = $2 AND revoked_at IS NULL", [record.credentialId, workspaceId]);
+        revoked = true;
+      }
+      await this.audit(client, workspaceId, actor, "live.destination.deleted", id, {
+        disabledOutputs: disabled.rows.length, revokedCredential: revoked,
+      });
+      return { disabledOutputs: disabled.rows.length, revokedCredential: revoked };
+    });
+  }
+
+  async outputsForDestination(workspaceId: string, destinationId: string): Promise<OutputSummary[]> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      const result = await client.query(
+        "SELECT * FROM stream_outputs WHERE workspace_id = $1 AND destination_id = $2 ORDER BY created_at",
+        [workspaceId, destinationId],
+      );
+      return result.rows.map(outputFromRow);
+    });
+  }
+
+  /**
+   * Credential revoke disables dependents (WP9 lifecycle): a revoked ingest
+   * credential turns every destination-referencing output disabled so no new
+   * go-live can redeem it. Returns how many outputs were disabled.
+   */
+  async disableDependentsOfCredential(workspaceId: string, credentialId: string): Promise<number> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      const result = await client.query(
+        `UPDATE stream_outputs o SET enabled = false, updated_at = now()
+           FROM live_stream_destinations d
+          WHERE o.workspace_id = $1 AND o.destination_id = d.id AND d.workspace_id = $1
+            AND d.credential_id = $2 AND o.enabled
+          RETURNING o.id`,
+        [workspaceId, credentialId],
+      );
+      return result.rows.length;
+    });
+  }
+
+  /**
+   * Go-live credential resolution (vault pattern of the publish credential
+   * accessor): destination -> credential row -> vault.open with tenant + handle
+   * AAD. Fails closed on a revoked credential, a cross-tenant handle, or a
+   * shape violation. Raw material never leaves this path.
+   */
+  async resolveIngestCredential(workspaceId: string, destinationId: string): Promise<ResolvedIngestCredential> {
+    return this.deps.transaction(workspaceId, async (client) => {
+      const result = await client.query<{ id: string; provider: string; endpoint_url: string; credential_id: string | null }>(
+        "SELECT id, provider, endpoint_url, credential_id FROM live_stream_destinations WHERE workspace_id = $1 AND id = $2",
+        [workspaceId, destinationId],
+      );
+      const row = result.rows[0];
+      if (row === undefined) throw new NotFoundException("live stream destination not found");
+      if (row.credential_id === null) return { endpointUrl: row.endpoint_url, streamKey: "", provider: row.provider };
+      const credential = await client.query<{ ciphertext: Buffer; key_version: number; revoked_at: Date | null; kind: string }>(
+        "SELECT ciphertext, key_version, revoked_at, kind FROM credentials WHERE id = $1 AND workspace_id = $2",
+        [row.credential_id, workspaceId],
+      );
+      const cred = credential.rows[0];
+      if (cred === undefined) throw new NotFoundException("destination credential not found");
+      if (cred.revoked_at !== null) throw new ConflictException("destination credential is revoked");
+      const plaintext = await this.deps.encryption.open(workspaceId, row.id, { ciphertext: cred.ciphertext, keyVersion: cred.key_version });
+      const secrets: unknown = JSON.parse(plaintext.toString());
+      if (typeof secrets !== "object" || secrets === null || Array.isArray(secrets)) {
+        throw new ConflictException("destination credential payload is malformed");
+      }
+      const key = (secrets as Record<string, unknown>).stream_key;
+      if (key !== undefined && typeof key !== "string") throw new ConflictException("destination credential payload is malformed");
+      return { endpointUrl: row.endpoint_url, streamKey: typeof key === "string" ? key : "", provider: row.provider };
+    });
+  }
+
+  private async assertLiveCredential(client: PoolClient, workspaceId: string, credentialId: string): Promise<void> {
+    const result = await client.query<{ revoked_at: Date | null }>(
+      "SELECT revoked_at FROM credentials WHERE id = $1 AND workspace_id = $2",
+      [credentialId, workspaceId],
+    );
+    const row = result.rows[0];
+    if (row === undefined) throw new BadRequestException("credentialId does not reference a credential in this workspace");
+    if (row.revoked_at !== null) throw new BadRequestException("credentialId references a revoked credential");
+  }
+
+  private async audit(client: PoolClient, workspaceId: string, actor: { userId: string | null; role: string },
+    action: string, targetId: string, diff: Record<string, unknown>): Promise<void> {
+    await client.query("SELECT audit_append($1,$2,$3,$4,$5,$6,$7)",
+      [workspaceId, actor.userId, actor.role, action, "live_destination", targetId, scrub(diff)]);
+  }
+}
diff --git a/apps/api/src/live/live-destination.test.ts b/apps/api/src/live/live-destination.test.ts
new file mode 100644
index 0000000..81a97d8
--- /dev/null
+++ b/apps/api/src/live/live-destination.test.ts
@@ -0,0 +1,331 @@
+import { randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { ConflictException, NotFoundException } from "@nestjs/common";
+import { describe, expect, it } from "vitest";
+import { Vault } from "@tactical-media-broadcast-hub/connector-runtime";
+import {
+  LiveDestinationRepository, parseCreateDestination, parseUpdateDestination, type TenantTransaction,
+} from "./live-destination.repository.js";
+import { GoLiveService } from "./go-live.service.js";
+import { createGenericHlsResolver, type LiveSourceResolver } from "./live-source-resolver.js";
+
+/**
+ * Live-destination lifecycle (WP6/WP9 aggregate boundary) against an
+ * in-memory tenant-transaction double: delete-blocked-while-referenced,
+ * credential revoke disables dependents, and go-live resolution of
+ * StreamOutput -> LiveStreamDestination -> credential via the vault.
+ */
+
+interface DestinationRow {
+  id: string; workspace_id: string; label: string; provider: string; endpoint_url: string;
+  credential_id: string | null; last_platform_state: string; created_at: Date; updated_at: Date;
+}
+interface OutputRow {
+  id: string; workspace_id: string; virtual_channel_id: string; label: string; profile: string;
+  mode: string; enabled: boolean; destination_id: string | null; credential_handle_id: string | null;
+  created_at: Date; updated_at: Date;
+}
+interface CredentialRow { id: string; workspace_id: string; ciphertext: Buffer; key_version: number; revoked_at: Date | null }
+
+const WS = randomUUID();
+const ACTOR = { userId: randomUUID(), role: "Owner" };
+
+function store(): {
+  destinations: DestinationRow[]; outputs: OutputRow[]; credentials: CredentialRow[];
+  transaction: TenantTransaction; client: PoolClient;
+} {
+  const destinations: DestinationRow[] = [];
+  const outputs: OutputRow[] = [];
+  const credentials: CredentialRow[] = [];
+  const audit: unknown[][] = [];
+  const transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> => {
+    const query = async (sql: string, args: unknown[]): Promise<{ rows: Record<string, unknown>[]; rowCount: number }> => {
+      const table = sql.includes("FROM live_stream_destinations") || sql.includes("INTO live_stream_destinations") || sql.includes("UPDATE live_stream_destinations") || sql.includes("DELETE FROM live_stream_destinations") ? "destinations"
+        : sql.includes("stream_outputs") ? "outputs"
+        : sql.includes("FROM credentials") || sql.includes("UPDATE credentials") ? "credentials" : "other";
+      if (sql.startsWith("SELECT")) {
+        if (table === "destinations" && sql.includes("LEFT JOIN credentials")) {
+          const rows = destinations.filter(d => sql.includes("$2") ? d.id === args[1] : d.workspace_id === args[0])
+            .map(d => ({ ...d, credential_revoked_at: credentials.find(c => c.id === d.credential_id)?.revoked_at ?? null }));
+          return { rows: rows as unknown as Record<string, unknown>[], rowCount: rows.length };
+        }
+        if (table === "destinations") {
+          const rows = destinations.filter(d => d.id === args[1] && d.workspace_id === args[0]);
+          return { rows: rows as unknown as Record<string, unknown>[], rowCount: rows.length };
+        }
+        if (table === "outputs") {
+          const rows = outputs.filter(o => o.workspace_id === args[0] && (sql.includes("destination_id") ? o.destination_id === args[1] : o.virtual_channel_id === args[1]));
+          return { rows: rows as unknown as Record<string, unknown>[], rowCount: rows.length };
+        }
+        if (table === "credentials") {
+          const rows = credentials.filter(c => c.id === args[0] && c.workspace_id === args[1]);
+          return { rows: rows as unknown as Record<string, unknown>[], rowCount: rows.length };
+        }
+        if (sql.includes("workspaces") || sql.includes("virtual_channels") || sql.includes("audit_log")) {
+          return { rows: [{ id: args[0] ?? randomUUID() }], rowCount: 1 };
+        }
+        return { rows: [], rowCount: 0 };
+      }
+      if (sql.startsWith("INSERT INTO live_stream_destinations")) {
+        const row: DestinationRow = { id: randomUUID(), workspace_id: String(args[0]), label: String(args[1]),
+          provider: String(args[2]), endpoint_url: String(args[3]), credential_id: args[4] === null ? null : String(args[4]),
+          last_platform_state: "unknown", created_at: new Date(), updated_at: new Date() };
+        destinations.push(row);
+        return { rows: [row as unknown as Record<string, unknown>], rowCount: 1 };
+      }
+      if (sql.startsWith("INSERT INTO stream_outputs")) {
+        const row: OutputRow = { id: randomUUID(), workspace_id: String(args[0]), virtual_channel_id: String(args[1]),
+          label: String(args[2]), profile: String(args[3]), mode: String(args[4]), enabled: Boolean(args[5]),
+          destination_id: args[6] === null ? null : String(args[6]), credential_handle_id: args[7] === null ? null : String(args[7]),
+          created_at: new Date(), updated_at: new Date() };
+        outputs.push(row);
+        return { rows: [row as unknown as Record<string, unknown>], rowCount: 1 };
+      }
+      if (sql.startsWith("UPDATE stream_outputs SET enabled = false")) {
+        const ids = outputs.filter(o => o.destination_id === args[1] && o.enabled).map(o => { o.enabled = false; o.updated_at = new Date(); return { id: o.id }; });
+        return { rows: ids, rowCount: ids.length };
+      }
+      if (sql.startsWith("UPDATE stream_outputs o SET enabled = false")) {
+        const ids = outputs.filter(o => { const d = destinations.find(x => x.id === o.destination_id); return d !== undefined && d.credential_id === args[1] && o.enabled; })
+          .map(o => { o.enabled = false; o.updated_at = new Date(); return { id: o.id }; });
+        return { rows: ids, rowCount: ids.length };
+      }
+      if (sql.startsWith("UPDATE stream_outputs")) {
+        const target = outputs.find(o => o.id === args[10] && o.workspace_id === args[0]);
+        if (target === undefined) return { rows: [], rowCount: 0 };
+        if (args[2] !== null) target.label = String(args[2]);
+        if (args[3] !== null) target.enabled = Boolean(args[3]);
+        return { rows: [target as unknown as Record<string, unknown>], rowCount: 1 };
+      }
+      if (sql.startsWith("UPDATE live_stream_destinations")) {
+        const target = destinations.find(d => d.id === args[1] && d.workspace_id === args[0]);
+        if (target === undefined) return { rows: [], rowCount: 0 };
+        if (args[2] !== null) target.label = String(args[2]);
+        if (args[3] !== null) target.provider = String(args[3]);
+        if (args[4] !== null) target.endpoint_url = String(args[4]);
+        if (args[6]) target.credential_id = args[7] === null ? null : String(args[7]);
+        if (args[7] !== null) target.last_platform_state = String(args[7]);
+        target.updated_at = new Date();
+        return { rows: [target as unknown as Record<string, unknown>], rowCount: 1 };
+      }
+      if (sql.startsWith("UPDATE credentials SET revoked_at")) {
+        const target = credentials.find(c => c.id === args[0] && c.workspace_id === args[1] && c.revoked_at === null);
+        if (target !== undefined) target.revoked_at = new Date();
+        return { rows: [], rowCount: 1 };
+      }
+      if (sql.startsWith("DELETE FROM live_stream_destinations")) {
+        const index = destinations.findIndex(d => d.id === args[1] && d.workspace_id === args[0]);
+        if (index === -1) return { rows: [], rowCount: 0 };
+        const [row] = destinations.splice(index, 1);
+        return { rows: [row as unknown as Record<string, unknown>], rowCount: 1 };
+      }
+      if (sql.startsWith("DELETE FROM stream_outputs")) {
+        const index = outputs.findIndex(o => o.id === args[2] && o.workspace_id === args[0]);
+        if (index === -1) return { rows: [], rowCount: 0 };
+        outputs.splice(index, 1);
+        return { rows: [], rowCount: 1 };
+      }
+      if (sql.startsWith("SELECT audit_append")) { audit.push(args); return { rows: [{ id: randomUUID() }], rowCount: 1 }; }
+      return { rows: [], rowCount: 0 };
+    };
+    return fn({ query } as unknown as PoolClient);
+  };
+  return { destinations, outputs, credentials, transaction, client: {} as PoolClient };
+}
+
+function repository(over: Partial<ConstructorParameters<typeof LiveDestinationRepository>[0]> = {}): LiveDestinationRepository {
+  return new LiveDestinationRepository(over);
+}
+
+describe("live stream destination CRUD + lifecycle", () => {
+  it("creates, lists, updates and reads destinations", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const created = await repo.create(WS, parseCreateDestination({ label: "Twitch main", provider: "twitch", endpointUrl: "rtmps://live.example.net/app", credentialId: null }), ACTOR);
+    expect(created.label).toBe("Twitch main");
+    expect(created.provider).toBe("twitch");
+    const listed = await repo.list(WS);
+    expect(listed).toHaveLength(1);
+    const updated = await repo.update(WS, created.id, parseUpdateDestination({ label: "Twitch backup", lastPlatformState: "live" }), ACTOR);
+    expect(updated.label).toBe("Twitch backup");
+    expect(updated.lastPlatformState).toBe("live");
+    await expect(repo.get(WS, created.id)).resolves.toMatchObject({ label: "Twitch backup" });
+  });
+
+  it("rejects bad bodies at parse time (label, provider, endpoint shape)", () => {
+    expect(() => parseCreateDestination({ label: "", provider: "twitch", endpointUrl: "rtmps://live.example.net/app" })).toThrow("label");
+    expect(() => parseCreateDestination({ label: "x", provider: "Twitch!", endpointUrl: "rtmps://live.example.net/app" })).toThrow("provider");
+    expect(() => parseCreateDestination({ label: "x", provider: "twitch", endpointUrl: "https://live.example.net/app" })).toThrow("endpointUrl");
+    expect(() => parseCreateDestination({ label: "x", provider: "twitch", endpointUrl: "rtmp://user:pw@live.example.net/app" })).toThrow("endpointUrl");
+    expect(() => parseUpdateDestination({})).toThrow("no recognized fields");
+    expect(() => parseUpdateDestination({ lastPlatformState: "exploded" })).toThrow("lastPlatformState");
+  });
+
+  it("delete is blocked (409) while an enabled output references the destination", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const destination = await repo.create(WS, parseCreateDestination({ label: "D", provider: "twitch", endpointUrl: "rtmps://live.example.net/app" }), ACTOR);
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: randomUUID(), label: "O", profile: "720p30",
+      mode: "passthrough", enabled: true, destination_id: destination.id, credential_handle_id: null,
+      created_at: new Date(), updated_at: new Date() });
+    await expect(repo.remove(WS, destination.id, ACTOR)).rejects.toThrow(ConflictException);
+    await expect(repo.remove(WS, destination.id, ACTOR)).rejects.toThrow(/referenced by 1 enabled/);
+    expect(s.destinations).toHaveLength(1);
+  });
+
+  it("delete proceeds once the referencing output is disabled: dependents disabled, credential revoked, row removed", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const credential = randomUUID();
+    s.credentials.push({ id: credential, workspace_id: WS, ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: null });
+    const destination = await repo.create(WS, parseCreateDestination({ label: "D", provider: "twitch", endpointUrl: "rtmps://live.example.net/app", credentialId: credential }), ACTOR);
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: randomUUID(), label: "O", profile: "720p30",
+      mode: "passthrough", enabled: false, destination_id: destination.id, credential_handle_id: null,
+      created_at: new Date(), updated_at: new Date() });
+    const result = await repo.remove(WS, destination.id, ACTOR);
+    expect(result).toEqual({ disabledOutputs: 0, revokedCredential: true });
+    expect(s.destinations).toHaveLength(0);
+    expect(s.credentials[0]?.revoked_at).not.toBeNull();
+    await expect(repo.get(WS, destination.id)).rejects.toThrow(NotFoundException);
+  });
+
+  it("credential revoke disables dependents (outputs referencing a destination on that credential)", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const credential = randomUUID();
+    s.credentials.push({ id: credential, workspace_id: WS, ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: null });
+    const destination = await repo.create(WS, parseCreateDestination({ label: "D", provider: "peertube", endpointUrl: "rtmp://live.example.net/app", credentialId: credential }), ACTOR);
+    const channel = randomUUID();
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: channel, label: "A", profile: "720p30",
+      mode: "passthrough", enabled: true, destination_id: destination.id, credential_handle_id: null, created_at: new Date(), updated_at: new Date() });
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: channel, label: "B", profile: "720p30",
+      mode: "passthrough", enabled: true, destination_id: destination.id, credential_handle_id: null, created_at: new Date(), updated_at: new Date() });
+    const disabled = await repo.disableDependentsOfCredential(WS, credential);
+    expect(disabled).toBe(2);
+    expect(s.outputs.every(o => !o.enabled)).toBe(true);
+  });
+
+  it("refuses a credential from another workspace or a revoked one on create", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const foreign = randomUUID();
+    s.credentials.push({ id: foreign, workspace_id: randomUUID(), ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: null });
+    await expect(repo.create(WS, parseCreateDestination({ label: "D", provider: "twitch", endpointUrl: "rtmps://live.example.net/app", credentialId: foreign }), ACTOR))
+      .rejects.toThrow(/credential in this workspace/);
+    const revoked = randomUUID();
+    s.credentials.push({ id: revoked, workspace_id: WS, ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: new Date() });
+    await expect(repo.create(WS, parseCreateDestination({ label: "D", provider: "twitch", endpointUrl: "rtmps://live.example.net/app", credentialId: revoked }), ACTOR))
+      .rejects.toThrow(/revoked/);
+  });
+});
+
+describe("go-live wiring (StreamOutput -> destination -> vault credential)", () => {
+  const CHANNEL = randomUUID();
+
+  function vaultFixture(): { vault: Vault; secrets: Map<string, string> } {
+    const real = new Vault();
+    const secrets = new Map<string, string>();
+    const vault = {
+      async seal(workspaceId: string, id: string, plaintext: Buffer) { return real.seal(workspaceId, id, plaintext); },
+      async open(workspaceId: string, id: string, _sealed: { ciphertext: Buffer; keyVersion: number }) {
+        return Buffer.from(secrets.get(`${workspaceId}:${id}`) ?? "");
+      },
+    } as unknown as Vault;
+    return { vault, secrets };
+  }
+
+  it("resolves enabled destination-referenced outputs through the destination and its credential", async () => {
+    const s = store();
+    const { vault, secrets } = vaultFixture();
+    const repo = repository({ transaction: s.transaction, encryption: vault });
+    const credential = randomUUID();
+    s.credentials.push({ id: credential, workspace_id: WS, ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: null });
+    const destination = await repo.create(WS, parseCreateDestination({ label: "D", provider: "twitch", endpointUrl: "rtmps://live.example.net/app", credentialId: credential }), ACTOR);
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: CHANNEL, label: "A", profile: "1080p30",
+      mode: "normalize", enabled: true, destination_id: destination.id, credential_handle_id: null, created_at: new Date(), updated_at: new Date() });
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: CHANNEL, label: "B", profile: "720p30",
+      mode: "passthrough", enabled: false, destination_id: destination.id, credential_handle_id: null, created_at: new Date(), updated_at: new Date() });
+    const goLive = new GoLiveService(repo, { transaction: s.transaction });
+    const targets = await goLive.resolveOutputs(WS, CHANNEL);
+    expect(targets).toHaveLength(1);
+    expect(targets[0]).toMatchObject({ endpointUrl: "rtmps://live.example.net/app", throughDestination: true, credentialHandleId: credential });
+    expect(targets[0]?.output.label).toBe("A");
+    // Redeem path: vault.open with tenant+handle AAD, raw key surfaced only here.
+    secrets.set(`${WS}:${destination.id}`, JSON.stringify({ stream_key: "live_123" }));
+    const redeemed = await goLive.redeemDestinationCredential(WS, destination.id);
+    expect(redeemed).toEqual({ endpointUrl: "rtmps://live.example.net/app", streamKey: "live_123", provider: "twitch" });
+  });
+
+  it("fails closed when the destination credential is revoked or the destination has none", async () => {
+    const s = store();
+    const { vault } = vaultFixture();
+    const repo = repository({ transaction: s.transaction, encryption: vault });
+    const credential = randomUUID();
+    s.credentials.push({ id: credential, workspace_id: WS, ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: new Date() });
+    // The repository (correctly) refuses to create a destination on a revoked
+    // credential, so this destination was revoked after creation.
+    const revokedDestination = { id: randomUUID(), workspace_id: WS, label: "R", provider: "twitch",
+      endpoint_url: "rtmps://live.example.net/app", credential_id: credential, last_platform_state: "unknown",
+      created_at: new Date(), updated_at: new Date() };
+    s.destinations.push(revokedDestination);
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: CHANNEL, label: "A", profile: "720p30",
+      mode: "passthrough", enabled: true, destination_id: revokedDestination.id, credential_handle_id: null, created_at: new Date(), updated_at: new Date() });
+    const goLive = new GoLiveService(repo, { transaction: s.transaction });
+    await expect(goLive.resolveOutputs(WS, CHANNEL)).rejects.toThrow(/revoked/);
+    await expect(goLive.redeemDestinationCredential(WS, revokedDestination.id)).rejects.toThrow(/revoked/);
+  });
+
+  it("resolves the program source through provider resolvers and refuses non-live sources", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const seen: string[] = [];
+    const goLive = new GoLiveService(repo, {
+      transaction: s.transaction,
+      sourceResolvers: new Map<string, LiveSourceResolver>([
+        ["twitch", async (request) => { seen.push(request.channelId ?? ""); return { playbackHlsUrl: "https://usher.example.com/a.m3u8", live: true }; }],
+        ["offline-provider", async () => ({ playbackHlsUrl: null, live: false })],
+      ]),
+    });
+    const resolved = await goLive.resolveProgramSource(WS, { provider: "twitch", channelId: "someone" });
+    expect(resolved).toEqual({ playbackHlsUrl: "https://usher.example.com/a.m3u8", live: true, provider: "twitch" });
+    expect(seen).toEqual(["someone"]);
+    await expect(goLive.resolveProgramSource(WS, { provider: "offline-provider", channelId: "x" })).rejects.toThrow(/not live/);
+    await expect(goLive.resolveProgramSource(WS, { provider: "nope", channelId: "x" })).rejects.toThrow(NotFoundException);
+  });
+
+  it("builds a RUNNING DesiredSpec for the take/start path from outputs + resolved source", async () => {
+    const s = store();
+    const repo = repository({ transaction: s.transaction });
+    const destination = await repo.create(WS, parseCreateDestination({ label: "D", provider: "twitch", endpointUrl: "rtmps://live.example.net/app" }), ACTOR);
+    s.credentials.push({ id: "cred-go-live", workspace_id: WS, ciphertext: Buffer.alloc(8), key_version: 1, revoked_at: null });
+    s.destinations.forEach(d => { if (d.id === destination.id) d.credential_id = "cred-go-live"; });
+    s.outputs.push({ id: randomUUID(), workspace_id: WS, virtual_channel_id: CHANNEL, label: "A", profile: "1080p60",
+      mode: "normalize", enabled: true, destination_id: destination.id, credential_handle_id: null, created_at: new Date(), updated_at: new Date() });
+    const goLive = new GoLiveService(repo, {
+      transaction: s.transaction,
+      sourceResolvers: new Map([["twitch", async () => ({ playbackHlsUrl: "https://usher.example.com/a.m3u8", live: true })]]),
+    });
+    const spec = await goLive.desiredSpecForGoLive(WS, CHANNEL, { provider: "twitch", channelId: "someone" });
+    expect(spec).toEqual({
+      desiredStatus: "RUNNING",
+      source: { kind: "hls", url: "https://usher.example.com/a.m3u8" },
+      output: { endpointUrl: "rtmps://live.example.net/app", credentialHandleId: "cred-go-live" },
+      profile: "1080p60",
+      mode: "normalize",
+    });
+    // The spec is exactly MediaControlService.setDesired's DesiredSpec shape.
+    await expect(goLive.desiredSpecForGoLive(WS, randomUUID(), { provider: "twitch" })).rejects.toThrow(/no enabled stream outputs/);
+  });
+
+  it("generic-hls resolver uses the external URL directly and probes liveness", async () => {
+    const requests: string[] = [];
+    const resolver = createGenericHlsResolver(async (input) => { requests.push(String(input)); return new Response("", { status: 200 }); }, 250);
+    await expect(resolver({ externalUrl: "https://cdn.example.com/live/index.m3u8" }))
+      .resolves.toEqual({ playbackHlsUrl: "https://cdn.example.com/live/index.m3u8", live: true });
+    expect(requests).toEqual(["https://cdn.example.com/live/index.m3u8"]);
+    const failing = createGenericHlsResolver(async () => new Response("gone", { status: 404 }), 250);
+    await expect(failing({ externalUrl: "https://cdn.example.com/live/index.m3u8" }))
+      .resolves.toEqual({ playbackHlsUrl: "https://cdn.example.com/live/index.m3u8", live: false });
+    await expect(resolver({})).rejects.toThrow("externalUrl");
+  });
+});
diff --git a/apps/api/src/live/live-source-resolver.ts b/apps/api/src/live/live-source-resolver.ts
new file mode 100644
index 0000000..c2f481d
--- /dev/null
+++ b/apps/api/src/live/live-source-resolver.ts
@@ -0,0 +1,72 @@
+import type { LiveSourceResolution } from "@tactical-media-broadcast-hub/core";
+import type { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+
+/**
+ * Source resolvers (WP6 go-live slice). Connector-level: each connector owns
+ * its provider behaviour; the app resolves by provider id through the
+ * connector registry and never switches on provider names.
+ */
+export interface LiveSourceRequest {
+  /** Provider channel identity (e.g. a Twitch login). */
+  channelId?: string;
+  /** External URL naming the same channel (provider-specific shape). */
+  externalUrl?: string;
+}
+
+export type LiveSourceResolver = (request: LiveSourceRequest) => Promise<LiveSourceResolution>;
+
+export class LiveSourceNotFoundError extends Error {
+  constructor(readonly provider: string) { super(`no live source resolver for provider "${provider}"`); }
+}
+
+/**
+ * Registry-shaped resolver: resolves by provider id through the connector
+ * registry. `connection` supplies the credential context a connector needs
+ * (some connectors call Helix with a bound token; callers pass the connection
+ * associated with the destination/source being resolved).
+ */
+export function createLiveSourceResolver(registry: ConnectorRegistry): (provider: string, request: LiveSourceRequest, connectionId?: string) => Promise<LiveSourceResolution> {
+  return async (provider, request, connectionId) => {
+    if (!registry.has(provider)) throw new LiveSourceNotFoundError(provider);
+    const connector = registry.get(provider);
+    if (connector.resolveLiveSource === undefined) throw new LiveSourceNotFoundError(provider);
+    // A minimal connection carries the credential ref; connectors that need no
+    // token (generic-hls) ignore it.
+    const connection = {
+      id: connectionId ?? `${provider}:live-source`,
+      workspaceId: "live-source",
+      provider,
+      channelId: request.channelId ?? request.externalUrl ?? "",
+      credentialId: { kind: "credential-ref" as const, id: connectionId ?? `${provider}:live-source` },
+      fields: {},
+      createdAt: new Date(),
+    };
+    return connector.resolveLiveSource(connection, request);
+  };
+}
+
+/**
+ * generic-hls: the external URL is the playback URL. Liveness is probed with a
+ * bounded HEAD/GET of the playlist; 2xx/3xx and a 4xx/5xx without transport
+ * error are both definitive, only a transport failure reports unknown (live
+ * kept false and playbackUrl still returned so callers can poll).
+ */
+export function createGenericHlsResolver(fetchImpl: typeof fetch = fetch, timeoutMs = 5_000): LiveSourceResolver {
+  return async (request) => {
+    const url = request.externalUrl;
+    if (url === undefined || url.length === 0) throw new Error("generic-hls resolver requires externalUrl");
+    let live = false;
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const response = await fetchImpl(url, { method: "GET", signal: controller.signal, redirect: "follow" });
+        live = response.ok;
+      } finally { clearTimeout(timer); }
+    } catch { live = false; }
+    return { playbackHlsUrl: url, live };
+  };
+}
+
+/** Registers the generic-hls pseudo connector id used by destinations/sources with no dedicated connector. */
+export const GENERIC_HLS_PROVIDER = "generic-hls";
diff --git a/apps/api/src/live/live.module.test.ts b/apps/api/src/live/live.module.test.ts
new file mode 100644
index 0000000..041fef6
--- /dev/null
+++ b/apps/api/src/live/live.module.test.ts
@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { LiveModule } from "./live.module.js";
+import { LiveDestinationRepository } from "./live-destination.repository.js";
+import { GoLiveService } from "./go-live.service.js";
+import { StreamOutputController } from "./stream-output.controller.js";
+import { LiveDestinationController } from "./live-destination.controller.js";
+import type { INestApplicationContext } from "@nestjs/common";
+import { NestFactory } from "@nestjs/core";
+
+/**
+ * Module wiring smoke test: LiveModule is importable without a database (the
+ * registry registration is env-gated) and provides its services/controllers
+ * with the DI graph intact.
+ */
+describe("LiveModule wiring", () => {
+  it("provides the repository, go-live service and controllers", async () => {
+    const hadDatabaseUrl = process.env.DATABASE_URL; // registry registration is DB-gated; module must still construct
+    delete process.env.DATABASE_URL;
+    const app: INestApplicationContext = await NestFactory.createApplicationContext(LiveModule, { logger: false });
+    try {
+      expect(app.get(LiveDestinationRepository)).toBeInstanceOf(LiveDestinationRepository);
+      const goLive = app.get(GoLiveService, { strict: false });
+      expect(goLive).toBeInstanceOf(GoLiveService);
+      expect(app.get(LiveDestinationController)).toBeInstanceOf(LiveDestinationController);
+      expect(app.get(StreamOutputController)).toBeInstanceOf(StreamOutputController);
+    } finally {
+      await app.close();
+      if (hadDatabaseUrl !== undefined) process.env.DATABASE_URL = hadDatabaseUrl;
+    }
+  });
+});
diff --git a/apps/api/src/live/live.module.ts b/apps/api/src/live/live.module.ts
new file mode 100644
index 0000000..df724ca
--- /dev/null
+++ b/apps/api/src/live/live.module.ts
@@ -0,0 +1,58 @@
+import { Module } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import { LiveDestinationController } from "./live-destination.controller.js";
+import { LiveDestinationRepository, LIVE_DESTINATION_DEPENDENCIES, type TenantTransaction } from "./live-destination.repository.js";
+import { GoLiveService, GO_LIVE_DEPENDENCIES } from "./go-live.service.js";
+import { StreamOutputController } from "./stream-output.controller.js";
+import { createPublishingRegistry } from "@tactical-media-broadcast-hub/connector-runtime";
+import { pool } from "../db/client.js";
+
+/** Registers connector-level live source resolvers from the connector registry. */
+function registerSourceResolvers(goLive: GoLiveService): void {
+  // Registry pattern: the provider set comes from the publishing registry —
+  // connector packages (twitch et al.) own provider behaviour, so every
+  // connector implementing resolveLiveSource registers under its own manifest
+  // id; generic-hls resolves through the built-in prober. No provider names
+  // branch here.
+  if (process.env.DATABASE_URL === undefined) return;
+  try {
+    const registry = createPublishingRegistry(pool);
+    for (const connector of registry.list()) {
+      const { id } = connector.manifest();
+      if (connector.resolveLiveSource === undefined) continue;
+      const resolveLiveSource = connector.resolveLiveSource.bind(connector);
+      goLive.registerSourceResolver(id, async (request) => resolveLiveSource(
+        {
+          id: `${id}:live-source`, workspaceId: "live-source", provider: id,
+          channelId: request.channelId ?? request.externalUrl ?? "",
+          credentialId: { kind: "credential-ref", id: `${id}:live-source` },
+          fields: {}, createdAt: new Date(),
+        },
+        request,
+      ));
+    }
+  } catch { /* No connectors configured in this process: only generic-hls stays registered. */ }
+}
+
+@Module({
+  controllers: [LiveDestinationController, StreamOutputController],
+  providers: [
+    { provide: "STREAM_OUTPUT_TRANSACTION", useValue: withTenant satisfies TenantTransaction },
+    {
+      provide: LiveDestinationRepository,
+      useFactory: (dependencies?: unknown) => new LiveDestinationRepository(dependencies as never),
+      inject: [{ token: LIVE_DESTINATION_DEPENDENCIES, optional: true }],
+    },
+    {
+      provide: GoLiveService,
+      useFactory: (destinations: LiveDestinationRepository, dependencies?: unknown) => {
+        const service = new GoLiveService(destinations, dependencies as never);
+        registerSourceResolvers(service);
+        return service;
+      },
+      inject: [LiveDestinationRepository, { token: GO_LIVE_DEPENDENCIES, optional: true }],
+    },
+  ],
+  exports: [LiveDestinationRepository, GoLiveService],
+})
+export class LiveModule {}
diff --git a/apps/api/src/live/stream-output.controller.ts b/apps/api/src/live/stream-output.controller.ts
new file mode 100644
index 0000000..7cebb65
--- /dev/null
+++ b/apps/api/src/live/stream-output.controller.ts
@@ -0,0 +1,162 @@
+import { BadRequestException, Body, Controller, Delete, Get, Inject, Param, Patch, Post, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import type { PoolClient } from "pg";
+import { parseId, requireSession } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { streamOutputTarget } from "@tactical-media-broadcast-hub/core";
+import { LiveDestinationRepository } from "./live-destination.repository.js";
+import type { OutputSummary, TenantTransaction } from "./live-destination.repository.js";
+
+/** Creates/edits stream outputs (the StreamOutput half of the WP9 boundary). */
+@Controller("channels/:channelId/outputs")
+@UseGuards(RbacGuard)
+export class StreamOutputController {
+  constructor(
+    @Inject(LiveDestinationRepository) private readonly destinations: LiveDestinationRepository,
+    @Inject("STREAM_OUTPUT_TRANSACTION") private readonly transaction: TenantTransaction,
+  ) {}
+
+  @Post()
+  @RequirePermission("streamoutput.manage")
+  async create(@Req() request: Request & AuthenticatedRequest, @Param("channelId") channelId: string, @Body() body: unknown): Promise<OutputSummary> {
+    const session = requireSession(request);
+    const parsed = parseId(channelId, "channelId");
+    const dto = parseCreateOutput(body);
+    return this.transaction(session.workspaceId, async (client) => {
+      await this.assertChannel(client, session.workspaceId, parsed);
+      // Type + API validation of the aggregate boundary: exactly one target.
+      const target = streamOutputTarget({ destinationId: dto.destinationId, credentialHandleId: dto.credentialHandleId });
+      if (target === null) throw new BadRequestException("output must reference a destination or its own credential handle");
+      if (target.kind === "destination") await this.destinations.get(session.workspaceId, target.destinationId);
+      if (target.kind === "handle" && !/^vh_[A-Za-z0-9_-]{16,128}$/.test(target.credentialHandleId)) {
+        throw new BadRequestException("credentialHandleId must be a vault handle reference");
+      }
+      const result = await client.query(
+        `INSERT INTO stream_outputs (workspace_id, virtual_channel_id, label, profile, mode, enabled, destination_id, credential_handle_id)
+         VALUES ($1,$2,$3,$4,$5,$6,$7,$8) RETURNING *`,
+        [session.workspaceId, parsed, dto.label, dto.profile, dto.mode, dto.enabled, dto.destinationId ?? null, dto.credentialHandleId ?? null],
+      );
+      return mapOutput(result.rows[0] ?? {});
+    });
+  }
+
+  @Get()
+  @RequirePermission("streamoutput.manage")
+  async list(@Req() request: Request & AuthenticatedRequest, @Param("channelId") channelId: string): Promise<OutputSummary[]> {
+    const session = requireSession(request);
+    return this.transaction(session.workspaceId, async (client) => {
+      await this.assertChannel(client, session.workspaceId, parseId(channelId, "channelId"));
+      const result = await client.query(
+        "SELECT * FROM stream_outputs WHERE workspace_id = $1 AND virtual_channel_id = $2 ORDER BY created_at",
+        [session.workspaceId, channelId],
+      );
+      return result.rows.map(mapOutput);
+    });
+  }
+
+  @Patch(":id")
+  @RequirePermission("streamoutput.manage")
+  async update(@Req() request: Request & AuthenticatedRequest, @Param("channelId") channelId: string, @Param("id") id: string, @Body() body: unknown): Promise<OutputSummary> {
+    const session = requireSession(request);
+    const parsedChannel = parseId(channelId, "channelId");
+    const parsedId = parseId(id);
+    const dto = parseUpdateOutput(body);
+    return this.transaction(session.workspaceId, async (client) => {
+      await this.assertChannel(client, session.workspaceId, parsedChannel);
+      // Re-check the exclusivity invariant whenever a target field changes.
+      if (dto.destinationId !== undefined || dto.credentialHandleId !== undefined) {
+        const current = await client.query<{ destination_id: string | null; credential_handle_id: string | null }>(
+          "SELECT destination_id, credential_handle_id FROM stream_outputs WHERE workspace_id=$1 AND virtual_channel_id=$2 AND id=$3",
+          [session.workspaceId, parsedChannel, parsedId],
+        );
+        const row = current.rows[0];
+        if (row === undefined) throw new BadRequestException("stream output not found");
+        const nextDestination = dto.destinationId === undefined ? row.destination_id ?? undefined : dto.destinationId ?? undefined;
+        const nextHandle = dto.credentialHandleId === undefined ? row.credential_handle_id ?? undefined : dto.credentialHandleId ?? undefined;
+        try { streamOutputTarget({ destinationId: nextDestination, credentialHandleId: nextHandle }); } catch {
+          throw new BadRequestException("output cannot reference both a destination and its own credential handle");
+        }
+        if (nextDestination !== undefined) await this.destinations.get(session.workspaceId, nextDestination);
+      }
+      const result = await client.query(
+        `UPDATE stream_outputs SET
+           label = COALESCE($3, label), enabled = COALESCE($4, enabled),
+           profile = COALESCE($5, profile), mode = COALESCE($6, mode),
+           destination_id = CASE WHEN $7 THEN $8 ELSE destination_id END,
+           credential_handle_id = CASE WHEN $9 THEN $10 ELSE credential_handle_id END,
+           updated_at = now()
+         WHERE workspace_id = $1 AND virtual_channel_id = $2 AND id = $11 RETURNING *`,
+        [session.workspaceId, parsedChannel, dto.label ?? null, dto.enabled ?? null, dto.profile ?? null, dto.mode ?? null,
+          dto.destinationId !== undefined, dto.destinationId ?? null,
+          dto.credentialHandleId !== undefined, dto.credentialHandleId ?? null, parsedId],
+      );
+      if (result.rows[0] === undefined) throw new BadRequestException("stream output not found");
+      return mapOutput(result.rows[0]);
+    });
+  }
+
+  @Delete(":id")
+  @RequirePermission("streamoutput.manage")
+  async remove(@Req() request: Request & AuthenticatedRequest, @Param("channelId") channelId: string, @Param("id") id: string): Promise<{ id: string }> {
+    const session = requireSession(request);
+    const parsedId = parseId(id);
+    await this.transaction(session.workspaceId, async (client) => {
+      await this.assertChannel(client, session.workspaceId, parseId(channelId, "channelId"));
+      await client.query("DELETE FROM stream_outputs WHERE workspace_id=$1 AND virtual_channel_id=$2 AND id=$3",
+        [session.workspaceId, channelId, parsedId]);
+    });
+    return { id: parsedId };
+  }
+
+  private async assertChannel(client: PoolClient, workspaceId: string, channelId: string): Promise<void> {
+    const found = await client.query("SELECT id FROM virtual_channels WHERE workspace_id=$1 AND id=$2", [workspaceId, channelId]);
+    if (found.rowCount === 0) throw new BadRequestException("channelId must reference a virtual channel in this workspace");
+  }
+}
+
+export function mapOutput(row: Record<string, unknown>): OutputSummary {
+  return {
+    id: String(row.id), workspaceId: String(row.workspace_id), virtualChannelId: String(row.virtual_channel_id),
+    label: String(row.label), profile: String(row.profile), mode: String(row.mode), enabled: Boolean(row.enabled),
+    destinationId: row.destination_id === null ? null : String(row.destination_id),
+    credentialHandleId: row.credential_handle_id === null ? null : String(row.credential_handle_id),
+    createdAt: new Date(row.created_at as Date), updatedAt: new Date(row.updated_at as Date),
+  };
+}
+
+const LABEL = /^.{1,120}$/s;
+
+export function parseCreateOutput(value: unknown): { label: string; profile: string; mode: string; enabled: boolean; destinationId?: string; credentialHandleId?: string } {
+  if (typeof value !== "object" || value === null) throw new BadRequestException("body must be an object");
+  const body = value as Record<string, unknown>;
+  const label = typeof body.label === "string" ? body.label.trim() : "";
+  if (!LABEL.test(label)) throw new BadRequestException("label must be 1-120 characters");
+  const profile = body.profile === undefined ? "720p30" : String(body.profile);
+  if (!["720p30", "1080p30", "1080p60"].includes(profile)) throw new BadRequestException("profile must be 720p30, 1080p30 or 1080p60");
+  const mode = body.mode === undefined ? "passthrough" : String(body.mode);
+  if (!["passthrough", "normalize"].includes(mode)) throw new BadRequestException("mode must be passthrough or normalize");
+  const enabled = body.enabled === undefined ? true : Boolean(body.enabled);
+  const dto: { label: string; profile: string; mode: string; enabled: boolean; destinationId?: string; credentialHandleId?: string } = { label, profile, mode, enabled };
+  if (body.destinationId !== undefined && body.destinationId !== null) dto.destinationId = String(body.destinationId);
+  if (body.credentialHandleId !== undefined && body.credentialHandleId !== null) dto.credentialHandleId = String(body.credentialHandleId);
+  return dto;
+}
+
+export function parseUpdateOutput(value: unknown): { label?: string; profile?: string; mode?: string; enabled?: boolean; destinationId?: string | null; credentialHandleId?: string | null } {
+  if (typeof value !== "object" || value === null) throw new BadRequestException("body must be an object");
+  const body = value as Record<string, unknown>;
+  const dto: { label?: string; profile?: string; mode?: string; enabled?: boolean; destinationId?: string | null; credentialHandleId?: string | null } = {};
+  if (body.label !== undefined) {
+    const label = typeof body.label === "string" ? body.label.trim() : "";
+    if (!LABEL.test(label)) throw new BadRequestException("label must be 1-120 characters");
+    dto.label = label;
+  }
+  if (body.profile !== undefined && !["720p30", "1080p30", "1080p60"].includes(String(body.profile))) throw new BadRequestException("profile must be 720p30, 1080p30 or 1080p60");
+  if (body.profile !== undefined) dto.profile = String(body.profile);
+  if (body.mode !== undefined && !["passthrough", "normalize"].includes(String(body.mode))) throw new BadRequestException("mode must be passthrough or normalize");
+  if (body.mode !== undefined) dto.mode = String(body.mode);
+  if (body.enabled !== undefined) dto.enabled = Boolean(body.enabled);
+  if (body.destinationId !== undefined) dto.destinationId = body.destinationId === null ? null : String(body.destinationId);
+  if (body.credentialHandleId !== undefined) dto.credentialHandleId = body.credentialHandleId === null ? null : String(body.credentialHandleId);
+  return dto;
+}
diff --git a/apps/api/src/main.ts b/apps/api/src/main.ts
new file mode 100644
index 0000000..cb07e8e
--- /dev/null
+++ b/apps/api/src/main.ts
@@ -0,0 +1,40 @@
+import "./telemetry/otel";
+import { NestFactory } from "@nestjs/core";
+import { Module } from "@nestjs/common";
+import { AppModule } from "./app.module";
+import { FeedsModule } from "./feeds/feeds.module";
+import { ArchiveModule } from "./archive/archive.module";
+import { logger } from "./telemetry/logger";
+
+@Module({ imports: [AppModule, ArchiveModule, FeedsModule] })
+class RootModule {}
+
+/** Browser origins allowed to call the API (comma-separated). Defaults cover the dev web server on :3001. */
+function corsOrigins(): string[] {
+  const configured = process.env.CORS_ORIGINS;
+  if (configured !== undefined && configured.trim() !== "") return configured.split(",").map((o) => o.trim());
+  return ["http://localhost:3001", "http://127.0.0.1:3001", "http://localhost:3000", "http://127.0.0.1:3000"];
+}
+
+async function bootstrap(): Promise<void> {
+  const app = await NestFactory.create(RootModule, {
+    logger: ["error", "warn"],
+    abortOnError: false,
+  });
+  // Sessions use bearer tokens; OAuth callbacks also bind the initiating browser with an HttpOnly cookie.
+  app.enableCors({
+    origin: corsOrigins(),
+    credentials: true,
+    methods: ["GET", "POST", "PATCH", "DELETE"],
+    allowedHeaders: ["Authorization", "Content-Type"],
+  });
+  const port = Number(process.env.PORT ?? 3000);
+  app.enableShutdownHooks();
+  await app.listen(port);
+  logger.info({ port }, "api listening");
+}
+
+void bootstrap().catch((error: unknown) => {
+  console.error("api bootstrap failed", error);
+  process.exitCode = 1;
+});
diff --git a/apps/api/src/media-control/capacity.test.ts b/apps/api/src/media-control/capacity.test.ts
new file mode 100644
index 0000000..d784724
--- /dev/null
+++ b/apps/api/src/media-control/capacity.test.ts
@@ -0,0 +1,551 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { HttpException } from "@nestjs/common";
+import { beforeEach, describe, expect, it } from "vitest";
+import {
+  CapacityGate, CapacityQueueFullError, ChannelPendingCapacityError, DEFAULT_CHANNEL_QUOTA, FAILOVER_RESERVE,
+  capacityUnits, effectiveUnits, fairShareOrder, jobResourceCaps, pendingBoundFor,
+} from "./capacity.js";
+import { MemoryRedis } from "../production/testing/memory-redis.js";
+import { MediaControlService, MEDIA_CONTROL_KEYS as K } from "./media-control.service.js";
+import { StubCredentialHandleProvider } from "./credential-handles.js";
+import { Ed25519ControlSigner } from "./wire.js";
+import type { RedisReply } from "./redis.js";
+import type { DesiredSpec } from "./spec.js";
+import type { DirectorReceipt, TenantTransaction } from "../production/journal.js";
+
+/**
+ * Capacity acceptance: per-worker
+ * unit accounting, the PENDING_CAPACITY queue with fair share across
+ * workspaces, admission on the take/start path (over-quota write rejected with
+ * nothing persisted), the bounded pending queue (8 = 2 × the default quota 4 →
+ * 429 CAPACITY_QUEUE_FULL), concurrency at quota − 1, tenant isolation, and
+ * per-job resource-cap isolation at the accounting level.
+ *
+ * `MemoryRedis` does not implement the capacity Lua scripts, so the gate runs
+ * its read-modify-write fallback under the in-process per-worker lock — the
+ * same path a Redis fake without `eval` support takes.
+ */
+
+const WORKER = "media-worker-a";
+const HANDLE = "vh_0123456789abcdefXYZ";
+const ACTOR = { userId: null, role: "system" } as const;
+
+function running(profile: DesiredSpec["profile"] = "720p30"): DesiredSpec {
+  return {
+    desiredStatus: "RUNNING",
+    source: { kind: "hls", url: "https://cdn.example.com/live/index.m3u8" },
+    output: { endpointUrl: "rtmps://live.example.net/app", credentialHandleId: HANDLE },
+    profile, mode: "passthrough",
+  };
+}
+const stopped: DesiredSpec = { desiredStatus: "STOPPED", source: null, output: null, profile: "720p30", mode: "passthrough" };
+
+/** Drives the gate's read-modify-write fallback: the capacity scripts are unsupported here. */
+class FakeRedis extends MemoryRedis {
+  override async eval(script: string, keys: string[], args: string[]): Promise<RedisReply> {
+    if (script.includes("tostring(cur)") || script.includes("tostring(v)")) throw new Error("no script support");
+    return super.eval(script, keys, args);
+  }
+}
+
+/** Aggregate DB fake: the director path (production channels) starts/stops channels. */
+class ProductionDb {
+  state = { version: 0, receipts: [] as DirectorReceipt[] };
+  applied: Array<{ ch: string; status: string }> = [];
+  failAfter = 0;
+  readonly transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> => {
+    const before = structuredClone(this.state);
+    const query = async (sql: string, values: unknown[] = []): Promise<{ rows: unknown[]; rowCount: number }> => {
+      let rows: unknown[] = [];
+      if (sql.startsWith("SELECT id FROM virtual_channels")) rows = [{ id: values[1] }]; // this channel exists
+      else if (sql.startsWith("SELECT desired_version")) rows = [{ desired_version: String(this.state.version), desired_status: "STOPPED" }];
+      else if (sql.includes("FROM audit_log")) {
+        const found = sql.includes("requestId")
+          ? this.state.receipts.find(r => r.requestId === values[2])
+          : this.state.receipts.at(-1);
+        rows = found ? [{ diff: found }] : [];
+      } else if (sql.startsWith("UPDATE virtual_channels")) {
+        this.state.version = Number(values[2]);
+        this.applied.push({ ch: String(values[1]), status: String(values[3]) });
+      } else if (sql.startsWith("SELECT audit_append")) {
+        this.state.receipts.push(values[6] as DirectorReceipt);
+        if (this.failAfter > 0) { this.failAfter -= 1; throw new Error("commit refused"); }
+      }
+      return { rows, rowCount: rows.length };
+    };
+    try { return await fn({ query } as unknown as PoolClient); }
+    catch (error) { this.state = before; throw error; } // PostgreSQL rolls back with the transaction
+  };
+}
+
+const WS = randomUUID();
+const CH = randomUUID();
+
+async function catchError(promise: Promise<unknown>): Promise<HttpException> {
+  const error: unknown = await promise.then(() => null, (e: unknown) => e);
+  expect(error).toBeInstanceOf(HttpException);
+  return error as HttpException;
+}
+function codeOf(error: HttpException): unknown {
+  const response = error.getResponse();
+  return typeof response === "object" && response !== null ? (response as Record<string, unknown>).code : response;
+}
+
+describe("§4.4 unit accounting", () => {
+  it("charges each running channel its profile's units of its worker's capacity", () => {
+    expect(capacityUnits("720p30")).toBe(4);
+    expect(capacityUnits("1080p30")).toBe(6);
+    expect(capacityUnits("1080p60")).toBe(10);
+  });
+
+  it("reserves the 20 % failover reserve from advertised capacity", () => {
+    expect(effectiveUnits(100, FAILOVER_RESERVE)).toBe(80);
+    expect(effectiveUnits(25, FAILOVER_RESERVE)).toBe(20); // 4 × 720p30 channels
+    expect(effectiveUnits(7, FAILOVER_RESERVE)).toBe(5); // floor
+  });
+
+  it("scales per-job caps with reserved units so Σ caps fit the worker", () => {
+    expect(jobResourceCaps("1080p60")).toEqual({ capacityUnits: 10, cpuShares: 2560, memoryMiB: 5120, fdBudget: 256, egressMbps: 20 });
+    // Two 720p30 jobs fit a 10-unit worker (2×4 = 8 ≤ 10) with disjoint budgets:
+    // a job hitting its own cap cannot take a sibling's budget.
+    const a = jobResourceCaps("720p30"), b = jobResourceCaps("720p30");
+    expect(a.cpuShares + b.cpuShares).toBeLessThanOrEqual(10 * 256);
+    expect(a.memoryMiB + b.memoryMiB).toBeLessThanOrEqual(10 * 512);
+    expect(a.fdBudget).toBe(b.fdBudget); // per-job RLIMIT_NOFILE, not shared
+  });
+});
+
+describe("fair share across workspaces", () => {
+  const entry = (ws: string, seq: number, units = 4) => ({ workspaceId: ws, seq, units });
+
+  it("interleaves workspaces so one tenant's queue cannot delay another", () => {
+    const order = fairShareOrder([entry("A", 1), entry("A", 3), entry("A", 5), entry("B", 2)], () => 1).map(i => i.workspaceId);
+    expect(order).toEqual(["A", "B", "A", "A"]);
+  });
+
+  it("a heavier tenant earns proportionally more service without starving the light one", () => {
+    // A (weight 2) is served, then B's ratio is lower, so B runs second.
+    const order = fairShareOrder([entry("A", 1), entry("A", 2), entry("B", 3), entry("A", 4), entry("A", 5)], ws => (ws === "A" ? 2 : 1));
+    expect(order.map(i => i.workspaceId)).toEqual(["A", "B", "A", "A", "A"]);
+    expect(order.findIndex(i => i.workspaceId === "B")).toBe(1);
+  });
+
+  it("keeps FIFO order within a workspace (admission_requested_at)", () => {
+    expect(fairShareOrder([entry("A", 9), entry("A", 2), entry("A", 5)], () => 1).map(i => i.seq)).toEqual([2, 5, 9]);
+  });
+});
+
+describe("CapacityGate admission", () => {
+  let redis: MemoryRedis;
+  let gate: CapacityGate;
+
+  beforeEach(() => {
+    redis = new MemoryRedis();
+    gate = new CapacityGate({ redis, now: () => Date.parse("2026-10-07T12:00:00.000Z") });
+  });
+
+  const start = (channelId: string, spec: DesiredSpec = running(), key = channelId) =>
+    gate.admit(WS, channelId, WORKER, spec, ACTOR, key, "desired-v1", null);
+  const queued = (promise: Promise<unknown>) => catchError(promise).then(error => {
+    expect(error).toBeInstanceOf(ChannelPendingCapacityError);
+    expect(error.getStatus()).toBe(202);
+    expect(codeOf(error)).toBe("PENDING_CAPACITY");
+    return error as ChannelPendingCapacityError;
+  });
+
+  it("4 placed channels; the 5th queues as PENDING_CAPACITY while running channels are unaffected", async () => {
+    await gate.advertiseWorker(WORKER, 25); // effective 20 → four 4-unit channels
+    const placed = Array.from({ length: 4 }, () => randomUUID());
+    for (const channelId of placed) await expect(start(channelId)).resolves.toMatchObject({ placed: true, units: 4 });
+    for (const channelId of placed) expect(await gate.channelOf(WS, channelId)).toMatchObject({ state: "PLACED", units: 4 });
+
+    const fifth = randomUUID();
+    const error = await queued(start(fifth));
+    expect((error.getResponse() as Record<string, unknown>).position).toBe(1);
+    expect(await gate.channelOf(WS, fifth)).toMatchObject({ state: "PENDING_CAPACITY", units: 4 });
+    // The four running channels keep their placements and reservations.
+    const snapshot = await gate.snapshot(WS, [...placed, fifth]);
+    expect(snapshot.placedChannels).toBe(4);
+    expect(snapshot.pendingChannels).toBe(1);
+    expect(snapshot.workers[0]).toMatchObject({ usedUnits: 16, queued: 1 });
+  });
+
+  it("freeing capacity never places more than the quota", async () => {
+    await gate.advertiseWorker(WORKER, 25);
+    const placed = Array.from({ length: 4 }, () => randomUUID());
+    for (const channelId of placed) await start(channelId);
+    const waiting = Array.from({ length: 5 }, () => randomUUID());
+    for (const channelId of waiting) await queued(start(channelId));
+    const all = [...placed, ...waiting];
+
+    for (const channelId of placed) {
+      await gate.release(WS, channelId);
+      const admitted = await gate.drain(WORKER);
+      expect(admitted.length).toBeLessThanOrEqual(1);
+      const snapshot = await gate.snapshot(WS, all);
+      expect(snapshot.placedChannels).toBeLessThanOrEqual(DEFAULT_CHANNEL_QUOTA);
+      expect(snapshot.placedChannels + snapshot.pendingChannels).toBe(9 - placed.indexOf(channelId) - 1);
+      expect(snapshot.workers[0]?.usedUnits).toBeLessThanOrEqual(20);
+    }
+    const final = await gate.snapshot(WS, all);
+    expect(final.placedChannels).toBe(DEFAULT_CHANNEL_QUOTA); // exactly the quota, never more
+    expect(final.pendingChannels).toBe(1);
+  });
+
+  it("drives a workspace to the pending bound and rejects the 9th with 429 CAPACITY_QUEUE_FULL, nothing persisted", async () => {
+    await gate.advertiseWorker(WORKER, 25);
+    const placed = Array.from({ length: 4 }, () => randomUUID());
+    for (const channelId of placed) await start(channelId);
+    const waiting: string[] = [];
+    for (let i = 0; i < pendingBoundFor(DEFAULT_CHANNEL_QUOTA); i += 1) {
+      const channelId = randomUUID();
+      waiting.push(channelId);
+      await queued(start(channelId));
+    }
+    expect(pendingBoundFor(DEFAULT_CHANNEL_QUOTA)).toBe(8); // 2 × the default quota of 4
+
+    const ninth = randomUUID();
+    const error = await catchError(start(ninth));
+    expect(error).toBeInstanceOf(CapacityQueueFullError);
+    expect(error.getStatus()).toBe(429);
+    expect(codeOf(error)).toBe("CAPACITY_QUEUE_FULL");
+    // Nothing persisted for the rejected start.
+    expect(await gate.channelOf(WS, ninth)).toBeNull();
+    const snapshot = await gate.snapshot(WS, [ninth]);
+    expect(snapshot.placedChannels).toBe(0);
+    expect(snapshot.pendingChannels).toBe(0);
+    expect((await gate.snapshot(WS, [...placed, ...waiting])).pendingChannels).toBe(8);
+  });
+
+  it("two concurrent starts at quota − 1 admit exactly one", async () => {
+    await gate.advertiseWorker(WORKER, 25); // effective 20: 4 channels by capacity, quota 4
+    for (let i = 0; i < DEFAULT_CHANNEL_QUOTA - 1; i += 1) await start(randomUUID());
+    const a = randomUUID(), b = randomUUID();
+    const results = await Promise.allSettled([start(a), start(b)]);
+    expect(results.filter(r => r.status === "fulfilled")).toHaveLength(1);
+    const rejected = results.filter(r => r.status === "rejected").map(r => (r as PromiseRejectedResult).reason);
+    expect(rejected).toHaveLength(1);
+    expect(rejected[0]).toBeInstanceOf(ChannelPendingCapacityError);
+    // One placed, one queued — both accounted, never two placements.
+    expect((await gate.snapshot(WS, [a, b])).placedChannels).toBe(1);
+    const states = await Promise.all([gate.channelOf(WS, a), gate.channelOf(WS, b)]);
+    expect(states.filter(c => c?.state === "PLACED")).toHaveLength(1);
+    expect(states.filter(c => c?.state === "PENDING_CAPACITY")).toHaveLength(1);
+  });
+
+  it("a tenant saturating its quota cannot delay another tenant's placement", async () => {
+    await gate.advertiseWorker(WORKER, 100); // effective 80: room for both tenants
+    const other = randomUUID();
+    // Tenant A saturates its quota and fills its pending queue.
+    for (let i = 0; i < DEFAULT_CHANNEL_QUOTA; i += 1) await start(randomUUID());
+    for (let i = 0; i < pendingBoundFor(DEFAULT_CHANNEL_QUOTA); i += 1) await queued(start(randomUUID()));
+    // Tenant B places immediately, ahead of A's queued channels.
+    const b1 = randomUUID(), b2 = randomUUID();
+    await expect(gate.admit(other, b1, WORKER, running(), ACTOR, b1, "desired-v1", null)).resolves.toMatchObject({ placed: true });
+    await expect(gate.admit(other, b2, WORKER, running(), ACTOR, b2, "desired-v1", null)).resolves.toMatchObject({ placed: true });
+    expect((await gate.snapshot(other, [b1, b2])).placedChannels).toBe(2);
+  });
+
+  it("re-admitting under the same idempotency key is a replay counted once", async () => {
+    await gate.advertiseWorker(WORKER, 25);
+    const channelId = randomUUID();
+    await start(channelId, running(), "same-key");
+    await expect(start(channelId, running(), "same-key")).resolves.toMatchObject({ replay: true });
+    expect((await gate.snapshot(WS, [channelId])).placedChannels).toBe(1);
+  });
+
+  it("a profile change beyond free worker capacity queues instead of overcommitting", async () => {
+    await gate.advertiseWorker(WORKER, 10); // effective 8: one 6-unit channel fits
+    const channelId = randomUUID();
+    await start(channelId, running("1080p30"));
+    const second = randomUUID();
+    await queued(start(second, running("1080p60"))); // 10 units > 2 free
+    expect(await gate.channelOf(WS, second)).toMatchObject({ state: "PENDING_CAPACITY" });
+    expect(await gate.channelOf(WS, channelId)).toMatchObject({ state: "PLACED", units: 6 }); // unaffected
+  });
+
+  it("undo reverses reservations so a failed desired-state write leaks no capacity", async () => {
+    await gate.advertiseWorker(WORKER, 25);
+    const channelId = randomUUID();
+    const admitted = await start(channelId);
+    await admitted.undo();
+    expect(await gate.channelOf(WS, channelId)).toBeNull();
+    expect((await gate.snapshot(WS, [channelId])).placedChannels).toBe(0);
+    const refill = randomUUID();
+    await expect(start(refill)).resolves.toMatchObject({ placed: true }); // units are reusable
+    expect((await gate.snapshot(WS, [refill])).workers[0]).toMatchObject({ usedUnits: 4 });
+  });
+
+  it("records per-job throttle/kill events without touching sibling reservations", async () => {
+    await gate.advertiseWorker(WORKER, 25);
+    const a = randomUUID(), b = randomUUID();
+    await start(a);
+    await start(b);
+    await gate.recordResourceEvent(WS, a, "killed", "memory.max exceeded");
+    expect(await gate.channelOf(WS, a)).toMatchObject({ state: "PLACED", units: 4, lastEvent: { kind: "killed", reason: "memory.max exceeded" } });
+    // b's placement and budget are untouched: the kill is isolated to a's own job.
+    const sibling = await gate.channelOf(WS, b);
+    expect(sibling).toMatchObject({ state: "PLACED", units: 4 });
+    expect(sibling?.lastEvent).toBeUndefined();
+    const snapshot = await gate.snapshot(WS, [a, b]);
+    expect(snapshot.placedChannels).toBe(2);
+    expect(snapshot.workers[0]?.usedUnits).toBe(8);
+    expect(snapshot.channels.find(c => c.channelId === a)?.caps).toEqual(jobResourceCaps("720p30"));
+  });
+
+  it("without an advertised capacity nothing is accounted (opt-in per worker)", async () => {
+    const channelId = randomUUID();
+    const admitted = await start(channelId);
+    expect(admitted.channel).toBeNull();
+    expect(await gate.channelOf(WS, channelId)).toBeNull();
+  });
+});
+
+describe("admission wired into the start path (setDesired)", () => {
+  let redis: FakeRedis;
+  let db: ProductionDb;
+  let service: MediaControlService;
+
+  beforeEach(async () => {
+    redis = new FakeRedis();
+    db = new ProductionDb();
+    service = new MediaControlService({
+      redis, transaction: db.transaction, assignments: [],
+      signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey),
+      handles: new StubCredentialHandleProvider(),
+      now: () => Date.parse("2026-10-07T12:00:00.000Z"), commandTtlMs: 30_000,
+      capacity: { workerUnits: { [WORKER]: 100 } },
+    });
+    await service.advertiseWorkerCapacity(WORKER, 100); // effective 80: room for both tenants
+  });
+
+  const start = (channelId: string, spec: DesiredSpec = running(), key = channelId) =>
+    service.setDesired(WS, channelId, spec, { idempotencyKey: key, actor: ACTOR });
+  const assign = (channelId: string) => service.assign(WS, channelId, WORKER, 1);
+  const desiredKey = (channelId: string) => redis.data.get(K.desired(WS, channelId)) ?? null;
+  const versionKey = (channelId: string) => redis.data.get(K.version(WS, channelId)) ?? null;
+
+  it("4 placed channels; the 5th stays PENDING_CAPACITY while running channels are unaffected", async () => {
+    const placed = [CH, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await assign(channelId); await expect(start(channelId)).resolves.toBeTruthy(); }
+    for (const channelId of placed) expect(JSON.parse(desiredKey(channelId) ?? "null")).toMatchObject({ desiredStatus: "RUNNING" });
+
+    const fifth = randomUUID();
+    await assign(fifth);
+    const error = await catchError(start(fifth));
+    expect(codeOf(error)).toBe("PENDING_CAPACITY");
+    expect((await service.channelCapacity(WS, fifth))?.state).toBe("PENDING_CAPACITY");
+    // Nothing persisted for the queued start...
+    expect(versionKey(fifth)).toBeNull();
+    expect(desiredKey(fifth)).toBeNull();
+    // ...and the four running channels keep their committed desired state.
+    for (const channelId of placed) expect(JSON.parse(desiredKey(channelId) ?? "null")).toMatchObject({ desiredStatus: "RUNNING" });
+    const capacity = await service.capacityGate.snapshot(WS, [...placed, fifth]);
+    expect(capacity).toMatchObject({ placedChannels: 4, pendingChannels: 1 });
+    expect(capacity.workers[0]).toMatchObject({ usedUnits: 16 });
+  });
+
+  it("an over-quota desired-state write is rejected with nothing persisted", async () => {
+    const placed = [CH, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await assign(channelId); await start(channelId); }
+    const before = redis.published.length;
+    const fifth = randomUUID();
+    await assign(fifth);
+    await expect(start(fifth)).rejects.toThrow();
+    expect(versionKey(fifth)).toBeNull();
+    expect(desiredKey(fifth)).toBeNull();
+    expect(db.applied.filter(a => a.ch === fifth)).toEqual([]);
+    expect(redis.published.length).toBe(before); // no command issued
+  });
+
+  it("freeing worker capacity never places more than the quota", async () => {
+    const placed = [CH, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await assign(channelId); await start(channelId); }
+    const waiting = Array.from({ length: 4 }, () => randomUUID());
+    for (const channelId of waiting) { await assign(channelId); await expect(start(channelId)).rejects.toThrow(); }
+
+    await start(placed[0]!, stopped, `${placed[0]}:stop`); // stop → free 4 units → the queue drains one
+    const capacity = await service.capacityGate.snapshot(WS, [...placed, ...waiting]);
+    expect(capacity.placedChannels).toBe(DEFAULT_CHANNEL_QUOTA);
+    expect(capacity.pendingChannels).toBe(3);
+    expect(capacity.workers[0]?.usedUnits).toBe(16);
+    // The admitted channel's start was re-applied: a committed desired snapshot exists.
+    const waitingIds: readonly string[] = waiting;
+    const admitted = capacity.channels.find(c => c.state === "PLACED" && waitingIds.includes(c.channelId));
+    expect(admitted).toBeDefined();
+    const admittedId = admitted?.channelId;
+    expect(typeof admittedId).toBe("string");
+    expect(JSON.parse(desiredKey(admittedId ?? "") ?? "null")).toMatchObject({ desiredStatus: "RUNNING" });
+    // The stopped channel no longer holds capacity.
+    expect(await service.channelCapacity(WS, placed[0]!)).toBeNull();
+  });
+
+  it("drives a workspace to the pending bound (8) and 429s the 9th with nothing persisted", async () => {
+    const placed = [CH, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await assign(channelId); await start(channelId); }
+    const waiting: string[] = [];
+    for (let i = 0; i < pendingBoundFor(DEFAULT_CHANNEL_QUOTA); i += 1) {
+      const channelId = randomUUID();
+      waiting.push(channelId);
+      await assign(channelId);
+      await expect(start(channelId)).rejects.toThrow("PENDING_CAPACITY");
+    }
+    const before = redis.published.length;
+    const ninth = randomUUID();
+    await assign(ninth);
+    const error = await catchError(start(ninth));
+    expect(error).toBeInstanceOf(CapacityQueueFullError);
+    expect(error.getStatus()).toBe(429);
+    expect(codeOf(error)).toBe("CAPACITY_QUEUE_FULL");
+    // Nothing persisted: no Redis desired state, no capacity record, no DB write, no command.
+    expect(versionKey(ninth)).toBeNull();
+    expect(desiredKey(ninth)).toBeNull();
+    expect(await service.channelCapacity(WS, ninth)).toBeNull();
+    expect(db.applied.filter(a => a.ch === ninth)).toEqual([]);
+    expect(redis.published.length).toBe(before);
+    expect((await service.capacityGate.snapshot(WS, [...placed, ...waiting])).pendingChannels).toBe(8);
+  });
+
+  it("two concurrent starts at quota − 1 admit exactly one", async () => {
+    const placed = [CH, ...Array.from({ length: DEFAULT_CHANNEL_QUOTA - 2 }, () => randomUUID())];
+    for (const channelId of placed) { await assign(channelId); await start(channelId); }
+    const a = randomUUID(), b = randomUUID();
+    await assign(a); await assign(b);
+    const results = await Promise.allSettled([start(a), start(b)]);
+    expect(results.filter(r => r.status === "fulfilled")).toHaveLength(1);
+    expect(results.filter(r => r.status === "rejected")).toHaveLength(1);
+    const capacity = await service.capacityGate.snapshot(WS, [...placed, a, b]);
+    expect(capacity.placedChannels).toBe(DEFAULT_CHANNEL_QUOTA); // never one more
+    expect(capacity.pendingChannels).toBe(1);
+    expect(capacity.workers[0]?.usedUnits).toBe(16);
+  });
+
+  it("a tenant saturating its quota cannot delay another tenant's placement", async () => {
+    const tenantB = randomUUID();
+    const b1 = randomUUID(), b2 = randomUUID();
+    await service.assign(tenantB, b1, WORKER, 1);
+    await service.assign(tenantB, b2, WORKER, 1);
+    // Tenant A: quota saturated and its pending queue full.
+    const placed = [CH, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await assign(channelId); await start(channelId); }
+    for (let i = 0; i < pendingBoundFor(DEFAULT_CHANNEL_QUOTA); i += 1) {
+      const channelId = randomUUID();
+      await assign(channelId);
+      await expect(start(channelId)).rejects.toThrow("PENDING_CAPACITY");
+    }
+    // Tenant B still places immediately.
+    await expect(service.setDesired(tenantB, b1, running(), { idempotencyKey: b1, actor: ACTOR })).resolves.toBeTruthy();
+    await expect(service.setDesired(tenantB, b2, running(), { idempotencyKey: b2, actor: ACTOR })).resolves.toBeTruthy();
+    expect((await service.capacityGate.snapshot(tenantB, [b1, b2])).placedChannels).toBe(2);
+    expect(await service.channelCapacity(tenantB, b1)).toMatchObject({ state: "PLACED" });
+    expect(await service.channelCapacity(tenantB, b2)).toMatchObject({ state: "PLACED" });
+  });
+
+  it("per-job cap throttle/kill isolation is visible in the accounting", async () => {
+    await assign(CH);
+    await start(CH);
+    await service.recordResourceEvent(WS, CH, "throttled", "cpu.weight reached");
+    expect(await service.channelCapacity(WS, CH)).toMatchObject({
+      state: "PLACED", units: 4, lastEvent: { kind: "throttled", reason: "cpu.weight reached" },
+    });
+    const status = await service.getStatus(WS);
+    expect(status.capacity?.channels[0]?.caps).toEqual(jobResourceCaps("720p30"));
+  });
+
+  it("a mid-transaction failure after admission leaves no capacity leak", async () => {
+    const other = randomUUID();
+    await assign(other);
+    db.failAfter = 1; // audit_append throws → the whole transaction rolls back
+    await expect(start(other)).rejects.toThrow("commit refused");
+    expect(await service.channelCapacity(WS, other)).toBeNull();
+    const snapshot = await service.capacityGate.snapshot(WS, [other]);
+    expect(snapshot.placedChannels).toBe(0);
+    expect(versionKey(other)).toBeNull();
+    // The leaked-free units are reusable by a later start.
+    await expect(start(other)).resolves.toBeTruthy();
+  });
+});
+
+describe("admission on the director (take/start) path", () => {
+  let redis: FakeRedis;
+  let db: ProductionDb;
+  let service: MediaControlService;
+  let channel: string;
+
+  beforeEach(async () => {
+    redis = new FakeRedis();
+    db = new ProductionDb();
+    service = new MediaControlService({
+      redis, transaction: db.transaction, assignments: [],
+      signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey),
+      handles: new StubCredentialHandleProvider(),
+      now: () => Date.parse("2026-10-07T12:00:00.000Z"), commandTtlMs: 30_000,
+      capacity: { workerUnits: { [WORKER]: 25 } },
+    });
+    channel = randomUUID();
+    await service.advertiseWorkerCapacity(WORKER, 25);
+  });
+
+  const desired = (channelId: string, status: "RUNNING" | "STOPPED") =>
+    service.director(WS, channelId, { type: "desired", spec: status === "RUNNING" ? running() : stopped },
+      `${channelId}:${status}`, ACTOR);
+
+  it("a start over quota queues as PENDING_CAPACITY with nothing persisted", async () => {
+    const placed = [channel, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await service.assign(WS, channelId, WORKER, 1); await expect(desired(channelId, "RUNNING")).resolves.toBeTruthy(); }
+    const fifth = randomUUID();
+    await service.assign(WS, fifth, WORKER, 1);
+    const error = await catchError(desired(fifth, "RUNNING"));
+    expect(codeOf(error)).toBe("PENDING_CAPACITY");
+    expect(db.state.version).toBe(4); // four committed writes; the fifth rolled back
+    expect(db.state.receipts).toHaveLength(4);
+    expect(db.applied.filter(a => a.ch === fifth)).toEqual([]);
+    expect(await service.channelCapacity(WS, fifth)).toMatchObject({ state: "PENDING_CAPACITY" });
+  });
+
+  it("a stop frees capacity and the queue re-applies exactly one admitted start", async () => {
+    const placed = [channel, ...Array.from({ length: 3 }, () => randomUUID())];
+    for (const channelId of placed) { await service.assign(WS, channelId, WORKER, 1); await desired(channelId, "RUNNING"); }
+    const waiting: string[] = [];
+    for (let i = 0; i < 2; i += 1) {
+      const channelId = randomUUID();
+      waiting.push(channelId);
+      await service.assign(WS, channelId, WORKER, 1);
+      await expect(desired(channelId, "RUNNING")).rejects.toThrow("PENDING_CAPACITY");
+    }
+
+    await desired(placed[0]!, "STOPPED");
+    const capacity = await service.capacityGate.snapshot(WS, [...placed, ...waiting]);
+    expect(capacity.placedChannels).toBe(DEFAULT_CHANNEL_QUOTA); // never more than the quota
+    expect(capacity.pendingChannels).toBe(1);
+    const waitingIds: readonly string[] = waiting;
+    const admitted = capacity.channels.find(c => c.state === "PLACED" && waitingIds.includes(c.channelId));
+    expect(admitted).toBeDefined();
+    expect(JSON.parse(redis.data.get(K.desired(WS, admitted!.channelId)) ?? "null")).toMatchObject({ desiredStatus: "RUNNING" });
+  });
+
+  it("a mid-transaction failure after admission leaks nothing", async () => {
+    await service.assign(WS, channel, WORKER, 1);
+    db.failAfter = 1;
+    await expect(desired(channel, "RUNNING")).rejects.toThrow("commit refused");
+    expect(await service.channelCapacity(WS, channel)).toBeNull();
+    expect((await service.capacityGate.snapshot(WS, [channel])).placedChannels).toBe(0);
+    expect(db.state.receipts).toHaveLength(0);
+  });
+});
+
+describe("error shape", () => {
+  it("PENDING_CAPACITY is 202, CAPACITY_QUEUE_FULL is 429, both carry their code", () => {
+    const pending = new ChannelPendingCapacityError({ workspaceId: WS, channelId: CH, workerId: WORKER, units: 4,
+      profile: "720p30", requestedAt: "now", position: 1, pendingChannels: 1, pendingBound: 8 });
+    expect(pending).toBeInstanceOf(HttpException);
+    expect(pending.getStatus()).toBe(202);
+    expect((pending.getResponse() as Record<string, unknown>).code).toBe("PENDING_CAPACITY");
+
+    const full = new CapacityQueueFullError({ workspaceId: WS, channelId: CH, workerId: WORKER, pendingChannels: 8, pendingBound: 8 });
+    expect(full).toBeInstanceOf(HttpException);
+    expect(full.getStatus()).toBe(429);
+    expect((full.getResponse() as Record<string, unknown>).code).toBe("CAPACITY_QUEUE_FULL");
+  });
+});
diff --git a/apps/api/src/media-control/capacity.ts b/apps/api/src/media-control/capacity.ts
new file mode 100644
index 0000000..4c21ce0
--- /dev/null
+++ b/apps/api/src/media-control/capacity.ts
@@ -0,0 +1,720 @@
+import { HttpException } from "@nestjs/common";
+import type { DirectorActor, DirectorOperation } from "../production/journal.js";
+import type { ControlRedis } from "./redis.js";
+import type { DesiredSpec } from "./spec.js";
+import { OUTPUT_PRESETS, type OutputPreset } from "./wire.js";
+
+/**
+ * Capacity & admission for the media-control desired-state plane
+ * (WP9, proposal §4.4 capacity).
+ *
+ * Model
+ * - Every RUNNING channel consumes `PROFILE_UNITS[profile]` capacity units of
+ *   the worker it is placed on. A worker commits only
+ *   `effectiveUnits(totalUnits) = floor(totalUnits × (1 − failoverReserve))`
+ *   (the 20 % failover reserve of §4.4).
+ * - A workspace places at most `channelQuota` channels (default 4). Channels
+ *   waiting in `PENDING_CAPACITY` are exempt — the running-VC quota counts
+ *   placed channels only — and every placement re-checks the quota.
+ * - A start that does not fit is queued as `PENDING_CAPACITY` (ordered by
+ *   `admission_requested_at`) instead of overcommitting. The queue is bounded
+ *   at `pendingBound` = 2 × the channel quota; a start beyond the bound is
+ *   rejected `429 CAPACITY_QUEUE_FULL` and nothing is persisted.
+ * - The queue drains weighted-fair across workspaces, so a tenant saturating
+ *   its own quota cannot delay another tenant's placement.
+ *
+ * Safety
+ * - Reservations use atomic check-and-increment counters (worker units,
+ *   workspace placed count) so two concurrent starts at quota − 1 admit
+ *   exactly one, including across API processes. Redis fakes without `eval`
+ *   for the admission scripts fall back to read-modify-write, which is correct
+ *   within one process because every mutation runs under the gate's per-worker
+ *   in-process lock.
+ * - The per-worker queue index is mutated under that same lock; the counters
+ *   remain the authority on how much is placed, so a lost index update can
+ *   never over-place, only delay a drain.
+ * - All keys are control-plane owned (`mcp:cap:*`); workers never read them.
+ *   Queued admissions persist the parsed, secret-free `DesiredSpec`
+ *   (credential handles only, never stream keys).
+ *
+ * Out of scope for this slice (scheduler-owned): `virtual_channels` rows with
+ * `observed_status = 'PENDING_CAPACITY'`, queue rebuild on scheduler restart
+ * and best-fit worker selection. `advertiseWorker` is the hand-off point.
+ */
+
+/** Capacity units per output preset: roughly linear in pixels × frames. */
+export const PROFILE_UNITS: Readonly<Record<OutputPreset, number>> = {
+  "720p30": 4,
+  "1080p30": 6,
+  "1080p60": 10,
+};
+
+/** Default running-VC quota per workspace (§4.4). */
+export const DEFAULT_CHANNEL_QUOTA = 4;
+/** The pending queue holds at most 2 × the channel quota (§4.4). */
+export function pendingBoundFor(channelQuota: number): number { return 2 * channelQuota; }
+/** 20 % of advertised worker capacity is held back for failover (§4.4). */
+export const FAILOVER_RESERVE = 0.2;
+
+/** Per-job cgroup/RLIMIT budgets derived from a channel's capacity units. */
+export const PER_UNIT_CPU_SHARES = 256;
+export const PER_UNIT_MEMORY_MIB = 512;
+export const PER_UNIT_EGRESS_MBPS = 2;
+export const PER_JOB_FD_BUDGET = 256;
+
+export function capacityUnits(profile: OutputPreset): number {
+  const units = PROFILE_UNITS[profile];
+  if (!Number.isSafeInteger(units) || units <= 0) throw new Error(`no capacity units for profile ${profile}`);
+  return units;
+}
+
+/** Capacity a worker may actually commit to placements. */
+export function effectiveUnits(totalUnits: number, failoverReserve: number): number {
+  const reserve = Math.min(Math.max(failoverReserve, 0), 0.9);
+  return Math.max(0, Math.floor(totalUnits * (1 - reserve)));
+}
+
+export interface JobResourceCaps {
+  capacityUnits: number;
+  cpuShares: number;
+  memoryMiB: number;
+  fdBudget: number;
+  egressMbps: number;
+}
+
+/**
+ * Per-job resource caps for one channel's media process tree. Caps scale with
+ * the units the job reserves, so Σ caps of placed channels always fits the
+ * worker's effective capacity: a job throttled or killed at its own cap is
+ * isolated from sibling channels (§4.4 cgroup + RLIMIT_NOFILE limits).
+ */
+export function jobResourceCaps(profile: OutputPreset): JobResourceCaps {
+  const units = capacityUnits(profile);
+  return {
+    capacityUnits: units,
+    cpuShares: units * PER_UNIT_CPU_SHARES,
+    memoryMiB: units * PER_UNIT_MEMORY_MIB,
+    fdBudget: PER_JOB_FD_BUDGET,
+    egressMbps: units * PER_UNIT_EGRESS_MBPS,
+  };
+}
+
+export const CAPACITY_KEYS = {
+  /** Advertised worker capacity: `{ workerId, totalUnits }`. */
+  worker: (workerId: string) => `mcp:cap:worker:${workerId}`,
+  used: (workerId: string) => `mcp:cap:used:${workerId}`,
+  /** Bounded pending queue for a worker, a JSON array ordered by `seq`. */
+  queue: (workerId: string) => `mcp:cap:pq:${workerId}`,
+  placedCount: (workspaceId: string) => `mcp:cap:nplaced:${workspaceId}`,
+  pendingCount: (workspaceId: string) => `mcp:cap:npend:${workspaceId}`,
+  channel: (workspaceId: string, channelId: string) => `mcp:cap:ch:${workspaceId}:${channelId}`,
+  seq: () => "mcp:cap:seq",
+} as const;
+
+export type CapacityState = "PLACED" | "PENDING_CAPACITY";
+
+/** Public view of one channel's capacity accounting. */
+export interface ChannelCapacity {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  units: number;
+  profile: OutputPreset;
+  state: CapacityState;
+  /** Admission time (kept on re-queue so queue order follows first request). */
+  requestedAt: string;
+  seq: number;
+  /** 1-based position in the worker's fair-share drain order; null when placed. */
+  position: number | null;
+  caps: JobResourceCaps;
+  lastEvent?: { kind: "throttled" | "killed"; reason: string; at: string };
+}
+
+/** Everything a queued start needs to be re-applied when its placement is admitted. */
+export interface AdmissionPayload {
+  spec: DesiredSpec;
+  actor: DirectorActor;
+  idempotencyKey: string;
+  path: "desired-v1" | "director";
+  operation: DirectorOperation | null;
+}
+
+/** A stored admission record (the secret-free spec is persisted with it). */
+export interface StoredAdmission extends ChannelCapacity, AdmissionPayload {
+  recordKey: string;
+}
+
+export interface QueueEntry { workspaceId: string; channelId: string; workerId: string; seq: number; units: number; requestedAt: string }
+
+export interface AdmissionResult {
+  placed: true;
+  units: number;
+  /** Null when this worker has no advertised capacity, so nothing is accounted. */
+  channel: ChannelCapacity | null;
+  /** True when the idempotency key replayed an already-admitted start. */
+  replay: boolean;
+  /**
+   * Reverses exactly the reservations this admission made. Call it when the
+   * desired-state write fails after admission: nothing persisted, no capacity
+   * leaked. It never drains the queue (an explicit free does that).
+   */
+  undo(): Promise<void>;
+}
+
+export interface ReleaseResult {
+  state: "STOPPED" | CapacityState;
+  workerId: string | null;
+  units: number;
+  /** Channels the freed capacity admitted from the pending queue. */
+  placed: string[];
+}
+
+export interface CapacitySnapshot {
+  workspaceId: string;
+  channelQuota: number;
+  pendingBound: number;
+  placedChannels: number;
+  pendingChannels: number;
+  channels: ChannelCapacity[];
+  workers: Array<{ workerId: string; totalUnits: number | null; effectiveUnits: number | null; usedUnits: number; queued: number }>;
+}
+
+export class CapacityQueueFullError extends HttpException {
+  constructor(detail: { workspaceId: string; channelId: string; workerId: string; pendingChannels: number; pendingBound: number }) {
+    super({ code: "CAPACITY_QUEUE_FULL", message: "capacity queue is full", ...detail }, 429);
+  }
+}
+export class ChannelPendingCapacityError extends HttpException {
+  constructor(detail: {
+    workspaceId: string; channelId: string; workerId: string; units: number; profile: OutputPreset;
+    requestedAt: string; position: number; pendingChannels: number; pendingBound: number;
+  }) {
+    super({ code: "PENDING_CAPACITY", message: "channel queued as PENDING_CAPACITY", ...detail }, 202);
+  }
+}
+export class CapacityProfileDeltaError extends HttpException {
+  constructor(detail: { workspaceId: string; channelId: string; workerId: string; units: number }) {
+    super({ code: "CAPACITY_PROFILE_DELTA", message: "profile change exceeds free worker capacity", ...detail }, 409);
+  }
+}
+
+export interface CapacityConfig {
+  /** Max placed (running) channels per workspace. */
+  channelQuota: number;
+  /** Max channels waiting in PENDING_CAPACITY per workspace (≤ 2 × quota). */
+  pendingBound: number;
+  /** Fraction of advertised worker capacity held back for failover. */
+  failoverReserve: number;
+  /** Weighted fair share per workspace (default 1). */
+  weights: Record<string, number>;
+  /** Worker capacities seeded at bootstrap; the scheduler advertises these in production. */
+  workerUnits: Record<string, number>;
+}
+
+export const DEFAULT_CAPACITY_CONFIG: CapacityConfig = {
+  channelQuota: DEFAULT_CHANNEL_QUOTA,
+  pendingBound: pendingBoundFor(DEFAULT_CHANNEL_QUOTA),
+  failoverReserve: FAILOVER_RESERVE,
+  weights: {},
+  workerUnits: {},
+};
+
+export interface CapacityGateDependencies {
+  redis: ControlRedis;
+  now(): number;
+  config?: Partial<CapacityConfig>;
+  /** Re-apply a queued start once its placement is admitted (wired by MediaControlService). */
+  applyPending?(admission: StoredAdmission): Promise<void>;
+}
+
+/** Atomic check-and-increment: `GET + delta ≤ limit` then `SET`, else no write. */
+const INCR_IF_AT_MOST_SCRIPT = `
+local cur = tonumber(redis.call('GET', KEYS[1]) or '0') + tonumber(ARGV[1])
+if cur > tonumber(ARGV[2]) then return 0 end
+redis.call('SET', KEYS[1], tostring(cur))
+return 1`;
+
+/** Atomic adjust with a zero floor (counters never go negative). */
+const ADJUST_SCRIPT = `
+local v = tonumber(redis.call('GET', KEYS[1]) or '0') + tonumber(ARGV[1])
+if v < 0 then v = 0 end
+redis.call('SET', KEYS[1], tostring(v))
+return v`;
+
+/**
+ * Weighted fair drain order: the workspace with the lowest served-units/weight
+ * ratio goes next, FIFO (by `seq`) within a workspace. With equal weights this
+ * is round-robin over workspaces, so one tenant's long queue never runs ahead
+ * of another tenant's single waiting channel.
+ */
+export function fairShareOrder<T extends { workspaceId: string; seq: number; units: number }>(
+  items: readonly T[], weightOf: (workspaceId: string) => number,
+): T[] {
+  const heads = new Map<string, T[]>();
+  for (const item of [...items].sort((a, b) => a.seq - b.seq)) {
+    const list = heads.get(item.workspaceId) ?? [];
+    list.push(item);
+    heads.set(item.workspaceId, list);
+  }
+  const served = new Map<string, number>();
+  const ordered: T[] = [];
+  while (ordered.length < items.length) {
+    let pick: { workspaceId: string; ratio: number; head: T } | null = null;
+    for (const [workspaceId, list] of heads) {
+      const head = list[0];
+      if (head === undefined) continue;
+      const ratio = (served.get(workspaceId) ?? 0) / weightOf(workspaceId);
+      if (pick === null || ratio < pick.ratio - 1e-9 ||
+          (Math.abs(ratio - pick.ratio) <= 1e-9 && head.seq < pick.head.seq)) {
+        pick = { workspaceId, ratio, head };
+      }
+    }
+    if (pick === null) break;
+    const list = heads.get(pick.workspaceId);
+    const item = list?.shift();
+    if (item === undefined) break;
+    served.set(pick.workspaceId, (served.get(pick.workspaceId) ?? 0) + item.units);
+    ordered.push(item);
+  }
+  return ordered;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOutputPreset(value: unknown): value is OutputPreset {
+  return typeof value === "string" && (OUTPUT_PRESETS as readonly string[]).includes(value);
+}
+function parseStored(raw: string | null): StoredAdmission | null {
+  if (raw === null || raw === "") return null;
+  let value: unknown;
+  try { value = JSON.parse(raw); } catch { return null; }
+  if (!isRecord(value)) return null;
+  const spec = value.spec;
+  if (!isRecord(spec)) return null;
+  const profile: unknown = spec.profile;
+  if (!isOutputPreset(profile)) return null;
+  const actor = value.actor;
+  if (!isRecord(actor) || (typeof actor.userId !== "string" && actor.userId !== null)) return null;
+  const { workspaceId, channelId, workerId, units, seq, requestedAt, recordKey, idempotencyKey, path, state } = value;
+  if (typeof workspaceId !== "string" || typeof channelId !== "string" || typeof workerId !== "string" ||
+      typeof units !== "number" || !Number.isSafeInteger(units) || units <= 0 ||
+      typeof seq !== "number" || !Number.isSafeInteger(seq) ||
+      typeof requestedAt !== "string" || typeof recordKey !== "string" ||
+      typeof idempotencyKey !== "string" || (path !== "desired-v1" && path !== "director") ||
+      (state !== "PLACED" && state !== "PENDING_CAPACITY")) return null;
+  const lastEvent = value.lastEvent;
+  return {
+    workspaceId, channelId, workerId, units, profile, state,
+    requestedAt, seq, position: null, caps: jobResourceCaps(profile),
+    ...(isRecord(lastEvent) && (lastEvent.kind === "throttled" || lastEvent.kind === "killed") &&
+        typeof lastEvent.reason === "string" && typeof lastEvent.at === "string"
+      ? { lastEvent: { kind: lastEvent.kind, reason: lastEvent.reason, at: lastEvent.at } } : {}),
+    spec: spec as unknown as DesiredSpec,
+    actor: actor as unknown as DirectorActor,
+    idempotencyKey, path,
+    operation: (value.operation ?? null) as DirectorOperation | null,
+    recordKey,
+  };
+}
+function parseQueueEntry(raw: string): QueueEntry | null {
+  let value: unknown;
+  try { value = JSON.parse(raw); } catch { return null; }
+  if (!isRecord(value) || typeof value.workspaceId !== "string" || typeof value.channelId !== "string" ||
+      typeof value.workerId !== "string" || !Number.isSafeInteger(value.seq) || !Number.isSafeInteger(value.units) ||
+      typeof value.requestedAt !== "string") return null;
+  const { workspaceId, channelId, workerId, seq, units, requestedAt } = value;
+  return { workspaceId, channelId, workerId, seq: seq as number, units: units as number, requestedAt };
+}
+function project(stored: StoredAdmission, position: number | null): ChannelCapacity {
+  const { spec: _spec, actor: _actor, idempotencyKey: _key, operation: _op, recordKey: _rk, ...view } = stored;
+  void _spec; void _actor; void _key; void _op; void _rk;
+  return { ...view, position };
+}
+function admissionKey(path: StoredAdmission["path"], idempotencyKey: string): string {
+  return `${path}:${idempotencyKey}`;
+}
+
+export class CapacityGate {
+  private readonly deps: CapacityGateDependencies;
+  readonly config: CapacityConfig;
+  private readonly locks = new Map<string, Promise<void>>();
+  private scripts = true;
+
+  constructor(deps: CapacityGateDependencies) {
+    this.deps = deps;
+    const provided = deps.config ?? {};
+    const quota = provided.channelQuota ?? DEFAULT_CAPACITY_CONFIG.channelQuota;
+    this.config = {
+      channelQuota: quota,
+      pendingBound: Math.min(provided.pendingBound ?? pendingBoundFor(quota), pendingBoundFor(quota)),
+      failoverReserve: provided.failoverReserve ?? DEFAULT_CAPACITY_CONFIG.failoverReserve,
+      weights: provided.weights ?? {},
+      workerUnits: provided.workerUnits ?? {},
+    };
+  }
+
+  /** The scheduler advertises worker capacity; placement stays within it. */
+  async advertiseWorker(workerId: string, totalUnits: number): Promise<void> {
+    if (!/^[A-Za-z0-9._-]{1,64}$/.test(workerId)) throw new Error("workerId is invalid");
+    if (!Number.isSafeInteger(totalUnits) || totalUnits <= 0) throw new Error("totalUnits must be a positive integer");
+    await this.deps.redis.set(CAPACITY_KEYS.worker(workerId), JSON.stringify({ workerId, totalUnits }));
+  }
+
+  /** Seed configured worker capacities (idempotent; called at bootstrap). */
+  async seed(): Promise<void> {
+    for (const [workerId, units] of Object.entries(this.config.workerUnits)) await this.advertiseWorker(workerId, units);
+  }
+
+  private weightOf(workspaceId: string): number {
+    const weight = this.config.weights[workspaceId] ?? 1;
+    return weight > 0 ? weight : 1;
+  }
+
+  private async read(key: string): Promise<string | null> {
+    const raw = await this.deps.redis.get(key);
+    return raw === null || raw === "" ? null : raw;
+  }
+  private async counter(key: string): Promise<number> {
+    return Math.max(0, Number(await this.read(key) ?? 0));
+  }
+  private async recordOf(workspaceId: string, channelId: string): Promise<StoredAdmission | null> {
+    return parseStored(await this.read(CAPACITY_KEYS.channel(workspaceId, channelId)));
+  }
+  private async write(stored: StoredAdmission): Promise<void> {
+    await this.deps.redis.set(CAPACITY_KEYS.channel(stored.workspaceId, stored.channelId), JSON.stringify(stored));
+  }
+  private async forget(workspaceId: string, channelId: string): Promise<void> {
+    await this.deps.redis.set(CAPACITY_KEYS.channel(workspaceId, channelId), "");
+  }
+  private async nextSeq(): Promise<number> {
+    return this.deps.redis.incr(CAPACITY_KEYS.seq());
+  }
+
+  /** Atomic `counter += delta` if it would not exceed `limit`; false leaves it untouched. */
+  private async incrIfAtMost(key: string, delta: number, limit: number): Promise<boolean> {
+    const redis = this.deps.redis;
+    if (this.scripts) {
+      try {
+        const applied = await redis.eval(INCR_IF_AT_MOST_SCRIPT, [key], [String(delta), String(limit)]);
+        if (typeof applied === "number") return applied === 1;
+        if (Array.isArray(applied) && applied.length === 0) { /* fall through */ }
+        else throw new Error("unexpected INCR_IF_AT_MOST reply");
+      } catch {
+        this.scripts = false; // fake without the script: read-modify-write under the in-process lock
+      }
+    }
+    const current = await this.counter(key);
+    if (current + delta > limit) return false;
+    await redis.set(key, String(current + delta));
+    return true;
+  }
+
+  /** Atomic adjust with a zero floor. */
+  private async adjust(key: string, delta: number): Promise<void> {
+    const redis = this.deps.redis;
+    if (this.scripts) {
+      try {
+        const applied = await redis.eval(ADJUST_SCRIPT, [key], [String(delta)]);
+        if (typeof applied === "number") return;
+        throw new Error("unexpected ADJUST reply");
+      } catch {
+        this.scripts = false;
+      }
+    }
+    const current = await this.counter(key);
+    await redis.set(key, String(Math.max(0, current + delta)));
+  }
+
+  private async workerUnitsOf(workerId: string): Promise<number | null> {
+    const raw = await this.read(CAPACITY_KEYS.worker(workerId));
+    if (raw === null) return null;
+    try {
+      const value = JSON.parse(raw) as { totalUnits?: unknown };
+      return typeof value.totalUnits === "number" && Number.isSafeInteger(value.totalUnits) && value.totalUnits > 0
+        ? value.totalUnits : null;
+    } catch { return null; }
+  }
+
+  private async withLock<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    const previous = this.locks.get(key) ?? Promise.resolve();
+    let release!: () => void;
+    const gate = new Promise<void>(resolve => { release = resolve; });
+    this.locks.set(key, previous.then(() => gate));
+    await previous;
+    try { return await fn(); } finally { release(); }
+  }
+
+  // ---- queue index (per-worker sorted set of waiting channels) ----
+
+  /**
+   * The per-worker queue index: one JSON array of waiting channels under a
+   * single key, mutated only under the gate's lock for this worker. It is an
+   * ordering hint for the fair drain; the unit/quota counters — not this index
+   * — decide what may be placed, so a stale index can only delay a drain.
+   */
+  private async queueEntries(workerId: string): Promise<QueueEntry[]> {
+    const raw = await this.read(CAPACITY_KEYS.queue(workerId));
+    if (raw === null) return [];
+    let value: unknown;
+    try { value = JSON.parse(raw); } catch { return []; }
+    if (!Array.isArray(value)) return [];
+    return value.flatMap(item => {
+      const entry = parseQueueEntry(typeof item === "string" ? item : JSON.stringify(item));
+      return entry === null || entry.workerId !== workerId ? [] : [entry];
+    }).sort((a, b) => a.seq - b.seq);
+  }
+  private async writeQueue(workerId: string, entries: QueueEntry[]): Promise<void> {
+    await this.deps.redis.set(CAPACITY_KEYS.queue(workerId), JSON.stringify(entries));
+  }
+  private async indexAdd(entry: QueueEntry): Promise<void> {
+    const entries = await this.queueEntries(entry.workerId);
+    if (!entries.some(item => item.channelId === entry.channelId)) entries.push(entry);
+    await this.writeQueue(entry.workerId, entries);
+  }
+  private async indexRemove(entry: QueueEntry): Promise<void> {
+    const entries = await this.queueEntries(entry.workerId);
+    await this.writeQueue(entry.workerId, entries.filter(item => item.channelId !== entry.channelId));
+  }
+  private entryOf(stored: StoredAdmission): QueueEntry {
+    return { workspaceId: stored.workspaceId, channelId: stored.channelId, workerId: stored.workerId,
+      seq: stored.seq, units: stored.units, requestedAt: stored.requestedAt };
+  }
+
+  private async pendingPositions(workerId: string): Promise<Map<string, number>> {
+    const order = fairShareOrder(await this.queueEntries(workerId), ws => this.weightOf(ws));
+    return new Map(order.map((entry, index) => [entry.channelId, index + 1]));
+  }
+
+  // ---- admission ----
+
+  /**
+   * Admit a start (RUNNING desired state). Either reserves capacity and
+   * resolves `placed`, or throws: `ChannelPendingCapacityError` (queued, the
+   * desired-state write must not proceed) or `CapacityQueueFullError` (429,
+   * nothing persisted). No reservation survives a failed desired-state write:
+   * call `undo()`.
+   */
+  async admit(
+    workspaceId: string, channelId: string, workerId: string, spec: DesiredSpec,
+    actor: DirectorActor, idempotencyKey: string, path: StoredAdmission["path"],
+    operation: DirectorOperation | null,
+  ): Promise<AdmissionResult> {
+    const units = capacityUnits(spec.profile);
+    const key = admissionKey(path, idempotencyKey);
+    const nowIso = () => new Date(this.deps.now()).toISOString();
+    return this.withLock(CAPACITY_KEYS.queue(workerId), async () => {
+      const existing = await this.recordOf(workspaceId, channelId);
+      if (existing !== null && existing.recordKey === key) {
+        if (existing.state === "PLACED") {
+          return { placed: true, units: existing.units, channel: project(existing, null), replay: true,
+            undo: async () => undefined };
+        }
+        const positions = await this.pendingPositions(workerId);
+        throw new ChannelPendingCapacityError({ workspaceId, channelId, workerId, units: existing.units,
+          profile: existing.profile, requestedAt: existing.requestedAt,
+          position: positions.get(channelId) ?? 1,
+          pendingChannels: await this.counter(CAPACITY_KEYS.pendingCount(workspaceId)),
+          pendingBound: this.config.pendingBound });
+      }
+      // A re-request while queued re-queues in place (keeps its original order).
+      if (existing?.state === "PENDING_CAPACITY") await this.dequeue(existing);
+
+      const totalUnits = await this.workerUnitsOf(workerId);
+      if (totalUnits === null) {
+        // Capacity is not yet advertised for this worker (the scheduler owns
+        // advertisement). Admission is opt-in per worker: without an
+        // advertisement there is no unit budget to enforce, so the bootstrap
+        // placement path keeps working and nothing is accounted.
+        return { placed: true, units, channel: null, replay: false, undo: async () => undefined };
+      }
+      const limit = effectiveUnits(totalUnits, this.config.failoverReserve);
+      const base = { workspaceId, channelId, workerId, profile: spec.profile,
+        requestedAt: existing?.requestedAt ?? nowIso(), seq: existing?.seq ?? await this.nextSeq(),
+        spec, actor, idempotencyKey, path, operation, recordKey: key };
+
+      if (existing?.state === "PLACED") {
+        // In-place update of a running channel: only the unit delta is reserved,
+        // the channel is already counted against the workspace quota.
+        const delta = units - existing.units;
+        if (delta > 0 && await this.counter(CAPACITY_KEYS.used(workerId)) + delta > limit) {
+          throw new CapacityProfileDeltaError({ workspaceId, channelId, workerId, units });
+        }
+        if (delta !== 0) await this.adjust(CAPACITY_KEYS.used(workerId), delta);
+        const stored: StoredAdmission = { ...base, units, state: "PLACED", position: null, caps: jobResourceCaps(spec.profile) };
+        await this.write(stored);
+        return { placed: true, units, channel: project(stored, null), replay: false,
+          undo: delta === 0 ? async () => undefined : async () => {
+            await this.forget(workspaceId, channelId);
+            await this.adjust(CAPACITY_KEYS.used(workerId), -delta);
+          } };
+      }
+
+      // Fresh placement: worker capacity and the workspace running-VC quota are
+      // each reserved atomically; a lost second reservation undoes the first.
+      const workerOk = totalUnits !== null && await this.incrIfAtMost(CAPACITY_KEYS.used(workerId), units, limit);
+      if (workerOk) {
+        const quotaOk = await this.incrIfAtMost(CAPACITY_KEYS.placedCount(workspaceId), 1, this.config.channelQuota);
+        if (quotaOk) {
+          const stored: StoredAdmission = { ...base, units, state: "PLACED", position: null, caps: jobResourceCaps(spec.profile) };
+          await this.write(stored);
+          return { placed: true, units, channel: project(stored, null), replay: false,
+            undo: async () => {
+              await this.forget(workspaceId, channelId);
+              await this.adjust(CAPACITY_KEYS.placedCount(workspaceId), -1);
+              await this.adjust(CAPACITY_KEYS.used(workerId), -units);
+            } };
+        }
+        await this.adjust(CAPACITY_KEYS.used(workerId), -units); // quota full → queue instead of overcommit
+      }
+
+      const pending = await this.counter(CAPACITY_KEYS.pendingCount(workspaceId));
+      if (pending + 1 > this.config.pendingBound) {
+        throw new CapacityQueueFullError({ workspaceId, channelId, workerId, pendingChannels: pending,
+          pendingBound: this.config.pendingBound });
+      }
+      const stored: StoredAdmission = { ...base, units, state: "PENDING_CAPACITY", position: null, caps: jobResourceCaps(spec.profile) };
+      await this.write(stored);
+      await this.indexAdd(this.entryOf(stored));
+      await this.adjust(CAPACITY_KEYS.pendingCount(workspaceId), 1);
+      const positions = await this.pendingPositions(workerId);
+      throw new ChannelPendingCapacityError({ workspaceId, channelId, workerId, units, profile: spec.profile,
+        requestedAt: stored.requestedAt, position: positions.get(channelId) ?? 1,
+        pendingChannels: pending + 1, pendingBound: this.config.pendingBound });
+    });
+  }
+
+  /** Remove a queued admission (record, index, pending count). */
+  private async dequeue(stored: StoredAdmission): Promise<void> {
+    await this.forget(stored.workspaceId, stored.channelId);
+    await this.indexRemove(this.entryOf(stored));
+    await this.adjust(CAPACITY_KEYS.pendingCount(stored.workspaceId), -1);
+  }
+
+  /**
+   * A channel stopped (desired STOPPED) or was deleted: free its reservation
+   * only — no drain happens here, because the caller frees capacity while its
+   * own desired-state transaction is still open. Call `drain(workerId)` once
+   * that transaction commits; freeing capacity can then only place what fits
+   * the worker limit *and* each workspace's quota.
+   */
+  async release(workspaceId: string, channelId: string): Promise<ReleaseResult> {
+    const stored = await this.recordOf(workspaceId, channelId);
+    if (stored === null) return { state: "STOPPED", workerId: null, units: 0, placed: [] };
+    if (stored.state === "PENDING_CAPACITY") {
+      await this.withLock(CAPACITY_KEYS.queue(stored.workerId), () => this.dequeue(stored));
+      return { state: "PENDING_CAPACITY", workerId: stored.workerId, units: stored.units, placed: [] };
+    }
+    await this.withLock(CAPACITY_KEYS.queue(stored.workerId), async () => {
+      await this.forget(workspaceId, channelId);
+      await this.adjust(CAPACITY_KEYS.placedCount(workspaceId), -1);
+      await this.adjust(CAPACITY_KEYS.used(stored.workerId), -stored.units);
+    });
+    return { state: "PLACED", workerId: stored.workerId, units: stored.units, placed: [] };
+  }
+
+  /**
+   * Place queued channels into free worker capacity, weighted-fair across
+   * workspaces. Never places beyond the worker's effective units or beyond any
+   * workspace's channel quota (the placement re-check). Re-applies each
+   * admitted start through `applyPending`; a failed re-apply rolls back to
+   * queued at the original position, so capacity is never leaked.
+   */
+  async drain(workerId: string): Promise<string[]> {
+    const admitted = await this.withLock(CAPACITY_KEYS.queue(workerId), () => this.collectDrain(workerId));
+    for (const admission of admitted) await this.applyAdmission(admission);
+    return admitted.map(admission => admission.channelId);
+  }
+
+  private async collectDrain(workerId: string): Promise<StoredAdmission[]> {
+    const entries = await this.queueEntries(workerId);
+    if (entries.length === 0) return [];
+    const totalUnits = await this.workerUnitsOf(workerId);
+    if (totalUnits === null) return [];
+    const limit = effectiveUnits(totalUnits, this.config.failoverReserve);
+    let used = await this.counter(CAPACITY_KEYS.used(workerId));
+    const admitted: StoredAdmission[] = [];
+    for (const entry of fairShareOrder(entries, ws => this.weightOf(ws))) {
+      if (used + entry.units > limit) continue;                     // freeing capacity never over-places
+      const stored = await this.recordOf(entry.workspaceId, entry.channelId);
+      if (stored === null || stored.state !== "PENDING_CAPACITY" || stored.workerId !== workerId) {
+        await this.indexRemove(entry);                              // stale index entry
+        continue;
+      }
+      // Placement re-checks the running-VC quota; pending channels were exempt.
+      const quotaOk = await this.incrIfAtMost(CAPACITY_KEYS.placedCount(entry.workspaceId), 1, this.config.channelQuota);
+      if (!quotaOk) continue;
+      await this.adjust(CAPACITY_KEYS.used(workerId), entry.units);
+      used += entry.units;
+      await this.forget(stored.workspaceId, stored.channelId);
+      await this.indexRemove(entry);
+      await this.adjust(CAPACITY_KEYS.pendingCount(stored.workspaceId), -1);
+      const placed: StoredAdmission = { ...stored, state: "PLACED", position: null };
+      await this.write(placed);
+      admitted.push(placed);
+    }
+    return admitted;
+  }
+
+  private async applyAdmission(admission: StoredAdmission): Promise<void> {
+    const apply = this.deps.applyPending;
+    if (apply === undefined) return;
+    try { await apply(admission); } catch { await this.rollbackAdmission(admission); }
+  }
+
+  /** A failed re-apply puts the channel back in the queue at its original position. */
+  private async rollbackAdmission(admission: StoredAdmission): Promise<void> {
+    await this.withLock(CAPACITY_KEYS.queue(admission.workerId), async () => {
+      await this.adjust(CAPACITY_KEYS.used(admission.workerId), -admission.units);
+      await this.adjust(CAPACITY_KEYS.placedCount(admission.workspaceId), -1);
+      await this.write({ ...admission, state: "PENDING_CAPACITY", position: null });
+      await this.indexAdd(this.entryOf(admission));
+      await this.adjust(CAPACITY_KEYS.pendingCount(admission.workspaceId), 1);
+    });
+  }
+
+  /**
+   * Record a per-job resource event (a job throttled or killed at its own
+   * cgroup/fd/egress cap). Purely an accounting annotation: it never touches
+   * other channels' reservations, which is the isolation §4.4 requires.
+   */
+  async recordResourceEvent(workspaceId: string, channelId: string, kind: "throttled" | "killed", reason: string): Promise<void> {
+    const stored = await this.recordOf(workspaceId, channelId);
+    if (stored === null) return;
+    stored.lastEvent = { kind, reason, at: new Date(this.deps.now()).toISOString() };
+    await this.write(stored);
+  }
+
+  async channelOf(workspaceId: string, channelId: string): Promise<ChannelCapacity | null> {
+    const stored = await this.recordOf(workspaceId, channelId);
+    if (stored === null) return null;
+    const position = stored.state === "PENDING_CAPACITY" ? (await this.pendingPositions(stored.workerId)).get(channelId) ?? 1 : null;
+    return project(stored, position);
+  }
+
+  /** Accounting view for status/tests. `channelIds` are the workspace's channels. */
+  async snapshot(workspaceId: string, channelIds: readonly string[]): Promise<CapacitySnapshot> {
+    const records = await Promise.all(channelIds.map(channelId => this.recordOf(workspaceId, channelId)));
+    const waiting = records.filter((record): record is StoredAdmission => record !== null && record.state === "PENDING_CAPACITY");
+    const workers = new Map<string, { totalUnits: number | null; effectiveUnits: number | null; usedUnits: number; queued: number }>();
+    for (const record of records) {
+      if (record === null) continue;
+      const totalUnits = await this.workerUnitsOf(record.workerId);
+      const entry = workers.get(record.workerId) ?? { totalUnits, effectiveUnits: totalUnits === null ? null : effectiveUnits(totalUnits, this.config.failoverReserve),
+        usedUnits: await this.counter(CAPACITY_KEYS.used(record.workerId)), queued: (await this.queueEntries(record.workerId)).length };
+      workers.set(record.workerId, entry);
+    }
+    const positions = await (async () => {
+      const map = new Map<string, number>();
+      for (const workerId of workers.keys()) for (const [channelId, position] of await this.pendingPositions(workerId)) map.set(channelId, position);
+      return map;
+    })();
+    return {
+      workspaceId, channelQuota: this.config.channelQuota, pendingBound: this.config.pendingBound,
+      placedChannels: records.filter(record => record?.state === "PLACED").length,
+      pendingChannels: waiting.length,
+      channels: records.flatMap(record => record === null ? [] : [project(record, positions.get(record.channelId) ?? null)]),
+      workers: [...workers.entries()].map(([workerId, entry]) => ({ workerId, ...entry })),
+    };
+  }
+}
diff --git a/apps/api/src/media-control/control-s3.integration.test.ts b/apps/api/src/media-control/control-s3.integration.test.ts
new file mode 100644
index 0000000..11aa350
--- /dev/null
+++ b/apps/api/src/media-control/control-s3.integration.test.ts
@@ -0,0 +1,76 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+import { withTenant } from "../db/client.js";
+import { MemoryRedis } from "../production/testing/memory-redis.js";
+import type { TenantTransaction } from "../production/journal.js";
+import { Ed25519ControlSigner } from "./wire.js";
+import { MediaControlService } from "./media-control.service.js";
+import { RespControlRedis } from "./redis.js";
+const owner = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+const workspaces: string[] = [];
+
+describe.skipIf(!process.env.DATABASE_URL)("S3 bus journal on PostgreSQL with real row locking/rollback", () => {
+  beforeAll(async () => { await runMigrations(join(process.cwd(), "migrations")); });
+  afterAll(async () => { for (const ws of workspaces) await owner.query("DELETE FROM workspaces WHERE id=$1", [ws]); await owner.end(); });
+  async function fixture(transaction: TenantTransaction = withTenant): Promise<{ ws: string; ch: string; a: string; b: string; redis: MemoryRedis; service: MediaControlService }> {
+    const ws = randomUUID(), ch = randomUUID(), a = randomUUID(), b = randomUUID(); workspaces.push(ws);
+    await owner.query("INSERT INTO workspaces(id,name,slug) VALUES($1,'S3 tests',$2)", [ws, `s3-${ws}`]);
+    await withTenant(ws, async client => {
+      await client.query("INSERT INTO virtual_channels(id,workspace_id,slug,name) VALUES($1,$2,'test','S3')", [ch, ws]);
+      await client.query("INSERT INTO production_scenes(id,workspace_id,virtual_channel_id,label,layout) VALUES($1,$3,$4,'A','single'),($2,$3,$4,'B','single')", [a, b, ws, ch]);
+      await client.query("INSERT INTO production_buses(workspace_id,virtual_channel_id,bus,scene_id) VALUES($1,$2,'preview',$3),($1,$2,'program',$4)", [ws, ch, a, b]);
+    });
+    const redis = new MemoryRedis(), service = new MediaControlService({ redis, transaction, signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey), assignments: [] });
+    await service.assign(ws, ch, "worker", 1); return { ws, ch, a, b, redis, service };
+  }
+  async function state(ws: string, ch: string): Promise<{ version: string; program: string; receipts: string }> {
+    return withTenant(ws, async client => {
+      const result = await client.query<{ version: string; program: string; receipts: string }>(`SELECT c.desired_version::text AS version,b.scene_id AS program,
+        (SELECT count(*)::text FROM audit_log WHERE workspace_id=$1 AND target_type='production_command') AS receipts
+        FROM virtual_channels c JOIN production_buses b ON b.workspace_id=c.workspace_id AND b.virtual_channel_id=c.id AND b.bus='program'
+        WHERE c.workspace_id=$1 AND c.id=$2`, [ws, ch]);
+      const row = result.rows[0]; if (!row) throw new Error("missing channel"); return row;
+    });
+  }
+  const actor = { userId: null, role: "system" };
+  it("duplicate and concurrent duplicates commit one bus effect/version/audit row", async () => {
+    const f = await fixture(); const first = await f.service.director(f.ws, f.ch, { type: "cut" }, "same", actor);
+    const commands = await Promise.all(Array.from({ length: 16 }, () => f.service.director(f.ws, f.ch, { type: "cut" }, "same", actor)));
+    expect(commands.every(command => command.commandId === first.commandId)).toBe(true);
+    expect(await state(f.ws, f.ch)).toEqual({ version: "1", program: f.a, receipts: "1" });
+    expect(f.redis.published.filter(p => p.channel.startsWith("cmd:"))).toHaveLength(1);
+  });
+  it("crash before commit rolls back buses/version/journal; retry applies once", async () => {
+    let crash = true;
+    const transaction: TenantTransaction = (ws, fn) => withTenant(ws, async client => { const result = await fn(client); if (crash) { crash = false; throw new Error("crash before commit"); } return result; });
+    const f = await fixture(transaction);
+    await expect(f.service.director(f.ws, f.ch, { type: "cut" }, "crash", actor)).rejects.toThrow("crash before commit");
+    expect(await state(f.ws, f.ch)).toEqual({ version: "0", program: f.b, receipts: "0" }); expect(f.redis.published).toHaveLength(0);
+    await f.service.director(f.ws, f.ch, { type: "cut" }, "crash", actor);
+    expect(await state(f.ws, f.ch)).toEqual({ version: "1", program: f.a, receipts: "1" });
+  });
+});
+
+describe.skipIf(!process.env.REDIS_URL)("S3 atomic delivery Lua on live Redis", () => {
+  it("concurrent receipt redelivery returns one commandId and preserves desiredVersion", async () => {
+    const redis = new RespControlRedis(process.env.REDIS_URL ?? "");
+    const ws = randomUUID(), ch = randomUUID(), scene = randomUUID(), requestId = randomUUID();
+    const service = new MediaControlService({ redis, signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey), assignments: [] });
+    await service.assign(ws, ch, "lua-worker", 1);
+    const receipt = { operation: { type: "cut" as const }, requestId, fingerprint: "test", state: { locked: false, override: null },
+      snapshot: { workspaceId: ws, channelId: ch, workerId: "lua-worker", assignmentEpoch: 1, desiredVersion: 1, desiredStatus: "STOPPED" as const,
+        profile: "720p30" as const, mode: "normalize" as const, source: null, output: null,
+        production: { scenes: [{ id: scene, label: "Scene", layout: "single" as const, slots: [] }], sources: [], overlays: [], buses: { preview: scene, program: scene }, transition: { type: "cut" as const }, audio: { masterGainDb: 0 } } } };
+    try {
+      const results = await Promise.all(Array.from({ length: 20 }, () => service.deliverReceipt(receipt)));
+      expect(new Set(results.map(result => result.commandId)).size).toBe(1);
+      expect(await redis.get(`mcp:ver:${ws}:${ch}`)).toBe("1"); expect(await redis.get(`mcp:director:${ws}:${ch}`)).not.toBeNull();
+    } finally {
+      await redis.eval("return redis.call('DEL',unpack(KEYS))", [`mcp:asg:${ws}:${ch}`, `mcp:channels:${ws}`, `mcp:des:${ws}:${ch}`, `mcp:ver:${ws}:${ch}`, `mcp:director:${ws}:${ch}`, `mcp:delivery:${requestId}`], []);
+      service.onModuleDestroy();
+    }
+  });
+});
diff --git a/apps/api/src/media-control/control-s3.test.ts b/apps/api/src/media-control/control-s3.test.ts
new file mode 100644
index 0000000..861333c
--- /dev/null
+++ b/apps/api/src/media-control/control-s3.test.ts
@@ -0,0 +1,141 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { describe, expect, it } from "vitest";
+import { DELIVER_RECEIPT_SCRIPT, MediaControlService, MEDIA_CONTROL_KEYS as K } from "./media-control.service.js";
+import { MemoryRedis } from "../production/testing/memory-redis.js";
+import { Ed25519ControlSigner } from "./wire.js";
+import type { DirectorReceipt, TenantTransaction } from "../production/journal.js";
+import { RealtimeService, type RealtimePeer } from "../realtime/realtime.service.js";
+
+const WS: string = randomUUID(), CH: string = randomUUID(), A: string = randomUUID(), B: string = randomUUID();
+class AggregateDatabase {
+  state = { version: 0, preview: A, program: B, receipts: [] as DirectorReceipt[] };
+  crash = false;
+  private tail: Promise<void> = Promise.resolve();
+  readonly transaction: TenantTransaction = async <T>(_ws: string, fn: (c: PoolClient) => Promise<T>): Promise<T> => {
+    const previous = this.tail;
+    let release = (): void => undefined;
+    this.tail = new Promise<void>(r => { release = r; });
+    await previous;
+    const before = structuredClone(this.state);
+    const query = async (sql: string, values: unknown[] = []): Promise<{ rows: unknown[]; rowCount: number }> => {
+      let rows: unknown[] = [];
+      if (sql.startsWith("SELECT id FROM virtual_channels")) rows = [{ id: CH }];
+      else if (sql.startsWith("SELECT desired_version")) rows = [{ desired_version: String(this.state.version), desired_status: "STOPPED" }];
+      else if (sql.includes("FROM audit_log")) {
+        const found = sql.includes("requestId") ? this.state.receipts.find(r => r.requestId === values[2]) : this.state.receipts.at(-1);
+        rows = found ? [{ diff: found }] : [];
+      } else if (sql.startsWith("SELECT scene_id")) rows = [{ scene_id: this.state.preview }];
+      else if (sql.startsWith("INSERT INTO production_buses")) { if (sql.includes("'program'")) this.state.program = String(values[2]); else this.state.preview = String(values[2]); }
+      else if (sql.startsWith("UPDATE virtual_channels")) this.state.version = Number(values[2]);
+      else if (sql.startsWith("SELECT audit_append")) { if (this.crash) { this.crash = false; throw new Error("crash mid-transaction"); } this.state.receipts.push(values[6] as DirectorReceipt); }
+      else if (sql.startsWith("SELECT id,label,layout")) rows = [A, B].map(id => ({ id, label: id === A ? "A" : "B", layout: "single" }));
+      else if (sql.startsWith("SELECT bus,scene_id")) rows = [{ bus: "preview", scene_id: this.state.preview }, { bus: "program", scene_id: this.state.program }];
+      else if (sql.startsWith("SELECT id FROM production_scenes")) rows = [A, B].includes(String(values[2])) ? [{ id: values[2] }] : [];
+      return { rows, rowCount: sql.startsWith("UPDATE") ? 1 : rows.length };
+    };
+    try { return await fn({ query } as unknown as PoolClient); }
+    catch (error) { this.state = before; throw error; }
+    finally { release(); }
+  };
+}
+async function fixture(): Promise<{ db: AggregateDatabase; redis: MemoryRedis; service: MediaControlService }> {
+  const db = new AggregateDatabase(), redis = new MemoryRedis();
+  const service = new MediaControlService({ transaction: db.transaction, redis, signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey), assignments: [] });
+  await service.assign(WS, CH, "fake-worker", 1);
+  return { db, redis, service };
+}
+const ACTOR = { userId: randomUUID(), role: "Owner" };
+
+describe("S3 bus idempotency and transactional crash matrix", () => {
+  it("duplicate CUT reuses the receipt, one version and one bus effect", async () => {
+    const { db, redis, service } = await fixture();
+    const first = await service.director(WS, CH, { type: "cut" }, "same", ACTOR);
+    expect(await service.director(WS, CH, { type: "cut" }, "same", ACTOR)).toEqual(first);
+    expect(db.state).toMatchObject({ version: 1, program: A }); expect(db.state.receipts).toHaveLength(1);
+    expect(redis.published.filter(p => p.channel.startsWith("cmd:"))).toHaveLength(1);
+    expect(db.state.receipts[0]?.state.override?.mode).toBe("until_released");
+  });
+  it("concurrent duplicate requests on separate service instances commit once", async () => {
+    const { db, redis, service } = await fixture();
+    const second = new MediaControlService({ transaction: db.transaction, redis, signer: new Ed25519ControlSigner("test", generateKeyPairSync("ed25519").privateKey), assignments: [] });
+    const results = await Promise.all(Array.from({ length: 20 }, (_, i) => (i % 2 ? service : second).director(WS, CH, { type: "take" }, "parallel", ACTOR)));
+    expect(new Set(results.map(r => r.commandId)).size).toBe(1);
+    expect(db.state.version).toBe(1); expect(db.state.receipts).toHaveLength(1);
+    expect(redis.published.filter(p => p.channel.startsWith("cmd:"))).toHaveLength(1);
+  });
+  it("crash mid-tx rolls back bus, version and outbox; retry applies once", async () => {
+    const { db, redis, service } = await fixture(); db.crash = true;
+    await expect(service.director(WS, CH, { type: "cut" }, "crash", ACTOR)).rejects.toThrow("mid-transaction");
+    expect(db.state).toMatchObject({ version: 0, program: B, receipts: [] }); expect(redis.published).toHaveLength(0);
+    await service.director(WS, CH, { type: "cut" }, "crash", ACTOR);
+    expect(db.state.version).toBe(1); expect(db.state.receipts).toHaveLength(1);
+  });
+  it("crash after commit before publish is recovered from durable receipt", async () => {
+    const { db, redis, service } = await fixture(); redis.failDelivery = true;
+    await expect(service.director(WS, CH, { type: "cut" }, "after", ACTOR)).rejects.toThrow("before delivery");
+    expect(db.state.version).toBe(1); expect(redis.published).toHaveLength(0);
+    await service.director(WS, CH, { type: "cut" }, "after", ACTOR);
+    expect(db.state.version).toBe(1); expect(redis.published.filter(p => p.channel.startsWith("cmd:"))).toHaveLength(1);
+  });
+  it("lost reply after publish is recovered without a second publish", async () => {
+    const { db, redis, service } = await fixture(); const evaluate = redis.eval.bind(redis);
+    let lose = true;
+    redis.eval = async (script, keys, args) => { const result = await evaluate(script, keys, args); if (script === DELIVER_RECEIPT_SCRIPT && lose) { lose = false; throw new Error("reply lost"); } return result; };
+    await expect(service.director(WS, CH, { type: "cut" }, "lost", ACTOR)).rejects.toThrow("reply lost");
+    await service.director(WS, CH, { type: "cut" }, "lost", ACTOR);
+    expect(db.state.version).toBe(1); expect(redis.published.filter(p => p.channel.startsWith("cmd:"))).toHaveLength(1);
+  });
+  it("rejects key reuse for another operation and cross-channel scene selection", async () => {
+    const { db, service } = await fixture(); await service.director(WS, CH, { type: "lock", enabled: true }, "reuse", ACTOR);
+    await expect(service.director(WS, CH, { type: "lock", enabled: false }, "reuse", ACTOR)).rejects.toThrow("another operation");
+    await expect(service.director(WS, CH, { type: "pst-select", sceneId: randomUUID() }, "foreign", ACTOR)).rejects.toThrow("this channel");
+    expect(db.state.version).toBe(1);
+  });
+  it("PST-select, CUT, lock and override each share the version fence", async () => {
+    const { db, service } = await fixture();
+    for (const [key, operation] of [
+      ["select", { type: "pst-select", sceneId: B }], ["cut", { type: "cut" }],
+      ["lock", { type: "lock", enabled: true }], ["override", { type: "override", mode: "five_minutes" }],
+      ["auto", { type: "override", mode: null }],
+    ] as const) await service.director(WS, CH, operation, key, ACTOR);
+    expect(db.state.version).toBe(5); expect(db.state.program).toBe(B); expect(db.state.receipts.at(-1)?.state).toEqual({ locked: true, override: null });
+  });
+  it("full desired writes on production channels share the bus transaction version fence", async () => {
+    const { db, service } = await fixture();
+    await service.director(WS, CH, { type: "cut" }, "seed-production", ACTOR);
+    const initial = db.state.receipts[0]?.snapshot;
+    if (!initial?.production) throw new Error("missing production snapshot");
+    const spec = { desiredStatus: "STOPPED" as const, source: null, output: null, profile: "720p30" as const,
+      mode: "normalize" as const, production: initial.production };
+    const results = await Promise.all([
+      service.setDesired(WS, CH, spec, { actor: ACTOR, idempotencyKey: "full-desired" }),
+      service.director(WS, CH, { type: "lock", enabled: true }, "lock-concurrent", ACTOR),
+    ]);
+    expect(results.map(result => result.desiredVersion).sort()).toEqual([2, 3]); expect(db.state.version).toBe(3);
+    const repeated = await service.setDesired(WS, CH, spec, { actor: ACTOR, idempotencyKey: "full-desired" });
+    expect(repeated).toEqual(results[0]); expect(db.state.version).toBe(3);
+  });
+  it("legacy full snapshots on a stored channel cannot race the first production bus command", async () => {
+    const { db, service } = await fixture();
+    const results = await Promise.all([
+      service.setDesired(WS, CH, { desiredStatus: "STOPPED", source: null, output: null, profile: "720p30", mode: "normalize" }),
+      service.director(WS, CH, { type: "cut" }, "first-cut", ACTOR),
+    ]);
+    expect(results.map(result => result.desiredVersion).sort()).toEqual([1, 2]); expect(db.state.version).toBe(2);
+  });
+  it("signed command reaches observed version and a realtime viewer within 300 ms", async () => {
+    const { redis, service } = await fixture();
+    redis.echo = command => { setTimeout(() => { void redis.set(K.observed(WS, CH), JSON.stringify({ workspaceId: WS, channelId: CH, workerId: "fake-worker", assignmentEpoch: 1, state: "STOPPED", realizedVersion: command.body.desiredVersion, updatedAt: new Date().toISOString(), reason: "fake worker echo" })); }, 10); };
+    const gateway = new RealtimeService(service, { subscriptions: { subscribe: async () => () => undefined, close: () => undefined }, authorize: async () => true, channelExists: async () => true });
+    const frames: unknown[] = []; const peer: RealtimePeer = { send: value => { frames.push(value); return true; }, close: () => undefined };
+    const connection = gateway.attach(peer); connection.message({ type: "auth", workspaceId: WS, token: "operator" });
+    connection.message({ type: "subscribe", channelId: CH });
+    await new Promise(r => setTimeout(r, 5));
+    const start = performance.now(); const issued = await service.director(WS, CH, { type: "cut" }, "latency", ACTOR);
+    while (!frames.some(value => typeof value === "object" && value && "kind" in value && value.kind === "observed" && "data" in value && value.data && typeof value.data === "object" && "realizedVersion" in value.data && value.data.realizedVersion === issued.desiredVersion) && performance.now() - start < 300) await new Promise(r => setTimeout(r, 5));
+    expect(performance.now() - start).toBeLessThan(300);
+    expect((await service.getStatus(WS)).channels[0]?.observed?.realizedVersion).toBe(issued.desiredVersion);
+    gateway.onModuleDestroy();
+  });
+});
diff --git a/apps/api/src/media-control/credential-handles.ts b/apps/api/src/media-control/credential-handles.ts
new file mode 100644
index 0000000..f4380a8
--- /dev/null
+++ b/apps/api/src/media-control/credential-handles.ts
@@ -0,0 +1,18 @@
+/**
+ * Stream keys never transit the control API. Outputs reference an opaque vault
+ * handle; the worker's VaultHandleBroker redeems it at relay start. This slice
+ * ships a format-only stub; the real provider must prove the handle belongs to
+ * the workspace (and channel) before a command is signed.
+ */
+export interface CredentialHandleProvider {
+  assertUsable(workspaceId: string, channelId: string, credentialHandleId: string): Promise<void>;
+}
+export const MEDIA_CREDENTIAL_HANDLES = Symbol("MEDIA_CREDENTIAL_HANDLES");
+
+const HANDLE = /^vh_[A-Za-z0-9_-]{16,128}$/;
+
+export class StubCredentialHandleProvider implements CredentialHandleProvider {
+  async assertUsable(_workspaceId: string, _channelId: string, credentialHandleId: string): Promise<void> {
+    if (!HANDLE.test(credentialHandleId)) throw new Error("credential handle is not a vault handle reference");
+  }
+}
diff --git a/apps/api/src/media-control/endpoints.ts b/apps/api/src/media-control/endpoints.ts
new file mode 100644
index 0000000..fc9d621
--- /dev/null
+++ b/apps/api/src/media-control/endpoints.ts
@@ -0,0 +1,40 @@
+import { BlockList, isIP } from "node:net";
+
+/**
+ * Mirror of apps/media-worker/src/relay/endpoints.ts shape rules. The API
+ * rejects early what the worker would reject at verify time; the worker's
+ * DNS-pinning validator remains the final authority on resolved hosts.
+ */
+export type EndpointUse = "hls" | "output";
+
+const blocked = new BlockList();
+for (const [subnet, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+  ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
+  ["192.0.2.0", 24], ["198.18.0.0", 15], ["198.51.100.0", 24],
+  ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+] as const) blocked.addSubnet(subnet, prefix, "ipv4");
+for (const [subnet, prefix] of [
+  ["::", 128], ["::1", 128], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8],
+  ["2001::", 32], ["2001:db8::", 32], ["2002::", 16], ["64:ff9b::", 96],
+] as const) blocked.addSubnet(subnet, prefix, "ipv6");
+
+export function assertPublicAddress(address: string): void {
+  const normalized = address.replace(/^\[|\]$/g, "").toLowerCase();
+  const family = isIP(normalized);
+  if (family === 0) throw new Error("unresolved endpoint address");
+  if (normalized.startsWith("::ffff:")) throw new Error("mapped endpoint rejected");
+  if (blocked.check(normalized, family === 4 ? "ipv4" : "ipv6")) throw new Error("private endpoint rejected");
+}
+
+export function validateEndpointShape(raw: string, use: EndpointUse): URL {
+  let url: URL;
+  try { url = new URL(raw); } catch { throw new Error("invalid endpoint URL"); }
+  const schemes = use === "hls" ? ["https:"] : ["rtmp:", "rtmps:"];
+  if (!schemes.includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash) throw new Error("endpoint scheme or credentials rejected");
+  if (isIP(url.hostname.replace(/^\[|\]$/g, ""))) assertPublicAddress(url.hostname);
+  // Stricter than the worker: loopback names never resolve to a public relay target.
+  const host = url.hostname.toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost")) throw new Error("private endpoint rejected");
+  return url;
+}
diff --git a/apps/api/src/media-control/media-control.controller.ts b/apps/api/src/media-control/media-control.controller.ts
new file mode 100644
index 0000000..b21765f
--- /dev/null
+++ b/apps/api/src/media-control/media-control.controller.ts
@@ -0,0 +1,77 @@
+import { Body, Controller, Get, Headers, Inject, Param, Post, Put, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { parseId, requireSession } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { MediaControlService, type IssuedCommand, type MediaControlStatus } from "./media-control.service.js";
+import { PreviewService } from "../production/preview.js";
+import type { DirectorOperation } from "../production/journal.js";
+import { parseDesiredSpec } from "./spec.js";
+
+@Controller("media-control")
+@UseGuards(RbacGuard)
+export class MediaControlController {
+  constructor(@Inject(MediaControlService) private readonly control: MediaControlService,
+    @Inject(PreviewService) private readonly preview: PreviewService) {}
+
+  @Put("channels/:channelId/desired")
+  @RequirePermission("media.manage")
+  async setDesired(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("channelId") channelId: string,
+    @Body() body: unknown,
+    @Headers("idempotency-key") idempotencyKey?: string,
+  ): Promise<IssuedCommand> {
+    const session = requireSession(request);
+    return this.control.setDesired(session.workspaceId, parseId(channelId, "channelId"), parseDesiredSpec(body), {
+      actor: { userId: session.userId, role: session.role }, ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    });
+  }
+
+  private command(request: Request & AuthenticatedRequest, channelId: string, key: string | undefined, operation: DirectorOperation): Promise<IssuedCommand> {
+    const session = requireSession(request);
+    return this.control.director(session.workspaceId, parseId(channelId, "channelId"), operation, key ?? "",
+      { userId: session.userId, role: session.role });
+  }
+
+  @Post("channels/:channelId/take")
+  @RequirePermission("director.take")
+  take(@Req() req: Request & AuthenticatedRequest, @Param("channelId") ch: string, @Headers("idempotency-key") key?: string): Promise<IssuedCommand> {
+    return this.command(req, ch, key, { type: "take" });
+  }
+
+  @Post("channels/:channelId/cut")
+  @RequirePermission("director.take")
+  cut(@Req() req: Request & AuthenticatedRequest, @Param("channelId") ch: string, @Headers("idempotency-key") key?: string): Promise<IssuedCommand> {
+    return this.command(req, ch, key, { type: "cut" });
+  }
+
+  @Post("channels/:channelId/pst-select")
+  @RequirePermission("director.take")
+  select(@Req() req: Request & AuthenticatedRequest, @Param("channelId") ch: string, @Body() body: { sceneId: string }, @Headers("idempotency-key") key?: string): Promise<IssuedCommand> {
+    return this.command(req, ch, key, { type: "pst-select", sceneId: body?.sceneId });
+  }
+
+  @Post("channels/:channelId/lock")
+  @RequirePermission("director.lock_program")
+  lock(@Req() req: Request & AuthenticatedRequest, @Param("channelId") ch: string, @Body() body: { enabled: boolean }, @Headers("idempotency-key") key?: string): Promise<IssuedCommand> {
+    return this.command(req, ch, key, { type: "lock", enabled: body?.enabled });
+  }
+
+  @Post("channels/:channelId/override")
+  @RequirePermission("director.override_auto")
+  override(@Req() req: Request & AuthenticatedRequest, @Param("channelId") ch: string, @Body() body: { mode: import("../production/journal.js").OverrideMode | null }, @Headers("idempotency-key") key?: string): Promise<IssuedCommand> {
+    return this.command(req, ch, key, { type: "override", mode: body?.mode });
+  }
+
+  @Get("channels/:channelId/preview/:tap")
+  @RequirePermission("director.view")
+  previewUrls(@Req() req: Request & AuthenticatedRequest, @Param("channelId") ch: string, @Param("tap") tap: string): Promise<Record<string, string>> {
+    return this.preview.urls(requireSession(req).workspaceId, parseId(ch, "channelId"), tap === "program" ? tap : parseId(tap, "tap"));
+  }
+
+  @Get("status")
+  @RequirePermission("media.view")
+  async status(@Req() request: Request & AuthenticatedRequest): Promise<MediaControlStatus> {
+    return this.control.getStatus(requireSession(request).workspaceId);
+  }
+}
diff --git a/apps/api/src/media-control/media-control.integration.test.ts b/apps/api/src/media-control/media-control.integration.test.ts
new file mode 100644
index 0000000..4dd923a
--- /dev/null
+++ b/apps/api/src/media-control/media-control.integration.test.ts
@@ -0,0 +1,76 @@
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { verifyCommand } from "../../../media-worker/src/bus/envelope.js";
+import { RedisBus } from "../../../media-worker/src/bus/redis.js";
+import { StubCredentialHandleProvider } from "./credential-handles.js";
+import { MEDIA_CONTROL_KEYS as K, MediaControlService } from "./media-control.service.js";
+import { RespControlRedis } from "./redis.js";
+import { Ed25519ControlSigner } from "./wire.js";
+
+const redisUrl = process.env.REDIS_URL;
+
+/** Real wire: the worker's own RedisBus subscribes and reports; the API publishes and reads back. */
+describe.skipIf(redisUrl === undefined)("media control plane (live Redis)", () => {
+  const workspaceId = randomUUID();
+  const channelId = randomUUID();
+  const workerId = `it-worker-${randomUUID().slice(0, 8)}`;
+  const { privateKey, publicKey } = generateKeyPairSync("ed25519");
+  let redis: RespControlRedis;
+  let bus: RedisBus;
+  let service: MediaControlService;
+  const received: string[] = [];
+
+  beforeAll(async () => {
+    redis = new RespControlRedis(redisUrl ?? "");
+    service = new MediaControlService({ redis, signer: new Ed25519ControlSigner("control-v1", privateKey),
+      handles: new StubCredentialHandleProvider(), assignments: [] });
+    bus = await RedisBus.connect(redisUrl ?? "");
+    await bus.subscribe(workerId, [workspaceId], (message) => { received.push(message); });
+  });
+  afterAll(async () => {
+    await redis.eval("return redis.call('DEL', unpack(KEYS))", [K.assignment(workspaceId, channelId), K.channels(workspaceId),
+      K.version(workspaceId, channelId), K.desired(workspaceId, channelId), K.observed(workspaceId, channelId), K.heartbeat(workerId)], []);
+    bus.close();
+    redis.close();
+  });
+
+  it("Lua assignment CAS enforces forward-only epochs", async () => {
+    await service.assign(workspaceId, channelId, workerId, 1);
+    await expect(service.assign(workspaceId, channelId, workerId, 0)).rejects.toThrow("stale");
+    await expect(service.assign(workspaceId, channelId, "other-worker", 1)).rejects.toThrow("stale");
+    expect(await service.getAssignment(workspaceId, channelId)).toEqual({ workerId, assignmentEpoch: 1 });
+  });
+
+  it("delivers a signed command the worker verifies, with a SETNX audit record", async () => {
+    const issued = await service.setDesired(workspaceId, channelId, {
+      desiredStatus: "RUNNING", source: { kind: "hls", url: "https://cdn.example.com/live.m3u8" },
+      output: { endpointUrl: "rtmps://live.example.net/app", credentialHandleId: "vh_integration_handle_01" },
+      profile: "720p30", mode: "passthrough",
+    });
+    expect(issued.receivers).toBe(1);
+    for (let i = 0; i < 50 && received.length === 0; i += 1) await new Promise((r) => setTimeout(r, 20));
+    const command = verifyCommand(JSON.parse(received[0] ?? "null"), new Map([["control-v1", publicKey]]), workerId);
+    expect(command.body).toMatchObject({ commandId: issued.commandId, desiredVersion: issued.desiredVersion, assignmentEpoch: 1 });
+    expect(await redis.set(K.issued(issued.commandId), "x", { nx: true, pxMs: 1000 })).toBe(false);
+    const ttl = await redis.eval("return redis.call('PTTL', KEYS[1])", [K.issued(issued.commandId)], []);
+    expect(typeof ttl === "number" && ttl > 0 && ttl <= 30_000).toBe(true);
+  });
+
+  it("Lua commit CAS rejects an older version", async () => {
+    await redis.set(K.desired(workspaceId, channelId), JSON.stringify({ desiredVersion: 1_000 }));
+    await expect(service.setDesired(workspaceId, channelId, { desiredStatus: "STOPPED", source: null, output: null,
+      profile: "720p30", mode: "passthrough" })).rejects.toThrow("newer desired version");
+    await redis.eval("return redis.call('DEL', KEYS[1])", [K.desired(workspaceId, channelId)], []);
+  });
+
+  it("reads observed state and liveness written by the worker's RedisBus", async () => {
+    const issued = await service.setDesired(workspaceId, channelId, { desiredStatus: "STOPPED", source: null, output: null,
+      profile: "720p30", mode: "passthrough" });
+    await bus.heartbeat(workerId, [{ workspaceId, channelId, workerId, assignmentEpoch: 1, state: "STOPPED",
+      realizedVersion: issued.desiredVersion, updatedAt: new Date().toISOString(), reason: "signed desired state stopped" }]);
+    const status = await service.getStatus(workspaceId);
+    expect(status.workers).toEqual([expect.objectContaining({ workerId, alive: true })]);
+    expect(status.channels).toEqual([expect.objectContaining({ channelId, converged: true, workerAlive: true,
+      desired: { desiredVersion: issued.desiredVersion, desiredStatus: "STOPPED" } })]);
+  });
+});
diff --git a/apps/api/src/media-control/media-control.module.ts b/apps/api/src/media-control/media-control.module.ts
new file mode 100644
index 0000000..8f23c43
--- /dev/null
+++ b/apps/api/src/media-control/media-control.module.ts
@@ -0,0 +1,8 @@
+import { Module } from "@nestjs/common";
+import { MediaControlController } from "./media-control.controller.js";
+import { MediaControlService } from "./media-control.service.js";
+import { PreviewService } from "../production/preview.js";
+import { PreviewController } from "../production/preview.controller.js";
+
+@Module({ controllers: [MediaControlController, PreviewController], providers: [MediaControlService, PreviewService], exports: [MediaControlService] })
+export class MediaControlModule {}
diff --git a/apps/api/src/media-control/media-control.service.ts b/apps/api/src/media-control/media-control.service.ts
new file mode 100644
index 0000000..655565e
--- /dev/null
+++ b/apps/api/src/media-control/media-control.service.ts
@@ -0,0 +1,640 @@
+import { randomUUID, createPrivateKey } from "node:crypto";
+import { withTenant, pool } from "../db/client.js";
+import { productionSnapshot } from "../production/snapshot.js";
+import { findReceipt, fingerprint, requestIdentity, type DirectorOperation, type DirectorActor, type DirectorState, type DirectorReceipt, type TenantTransaction } from "../production/journal.js";
+import { readFileSync } from "node:fs";
+import {
+  BadRequestException, ConflictException, Inject, Injectable, OnModuleDestroy, OnModuleInit, Optional, ServiceUnavailableException,
+} from "@nestjs/common";
+import { isUuid } from "../http/validation.js";
+import { MEDIA_CREDENTIAL_HANDLES, StubCredentialHandleProvider, type CredentialHandleProvider } from "./credential-handles.js";
+import { RespControlRedis, type ControlRedis } from "./redis.js";
+import { parseDesiredSpec, type DesiredSpec } from "./spec.js";
+import { Ed25519ControlSigner, type CommandBody, type ControlCommandSigner, type DesiredChannel, type ObservedChannel, type OutputPreset } from "./wire.js";
+import { CapacityGate, DEFAULT_CAPACITY_CONFIG, type CapacityConfig, type CapacitySnapshot, type ChannelCapacity, type StoredAdmission } from "./capacity.js";
+
+/**
+ * Key layout. Worker-owned (read-only here): `cmd:{ws}:{worker}` pub/sub,
+ * `obs:{ws}:{ch}` (EX 60), `hb:{worker}` (EX 15). The worker never reads a
+ * desired-state key — it learns desired state only from signed commands — so
+ * desired snapshots live under control-plane-owned `mcp:*` keys.
+ */
+export const MEDIA_CONTROL_KEYS = {
+  assignment: (ws: string, ch: string) => `mcp:asg:${ws}:${ch}`,
+  channels: (ws: string) => `mcp:channels:${ws}`,
+  version: (ws: string, ch: string) => `mcp:ver:${ws}:${ch}`,
+  desired: (ws: string, ch: string) => `mcp:des:${ws}:${ch}`,
+  issued: (commandId: string) => `mcp:cmdlog:${commandId}`,
+  command: (ws: string, workerId: string) => `cmd:${ws}:${workerId}`,
+  observed: (ws: string, ch: string) => `obs:${ws}:${ch}`,
+  heartbeat: (workerId: string) => `hb:${workerId}`,
+} as const;
+
+/** Worker heartbeat TTL (apps/media-worker/src/bus/redis.ts). */
+export const HEARTBEAT_TTL_MS = 15_000;
+const DEFAULT_COMMAND_TTL_MS = 30_000;
+const WORKER_ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+/** Assignment CAS: epochs only move forward; one epoch names exactly one worker. */
+export const ASSIGN_SCRIPT = `
+local cur = redis.call('GET', KEYS[1])
+if cur then
+  local obj = cjson.decode(cur)
+  local epoch = tonumber(ARGV[2])
+  if obj.assignmentEpoch > epoch then return 0 end
+  if obj.assignmentEpoch == epoch and obj.workerId ~= ARGV[3] then return 0 end
+end
+redis.call('SET', KEYS[1], ARGV[1])
+redis.call('SADD', KEYS[2], ARGV[4])
+return 1`;
+
+/** Desired CAS: commit only if the assignment is unchanged and no newer version is stored. */
+export const COMMIT_DESIRED_SCRIPT = `
+if redis.call('GET', KEYS[2]) ~= ARGV[3] then return -1 end
+local cur = redis.call('GET', KEYS[1])
+if cur then
+  local obj = cjson.decode(cur)
+  if tonumber(obj.desiredVersion) >= tonumber(ARGV[2]) then return 0 end
+end
+redis.call('SET', KEYS[1], ARGV[1])
+return 1`;
+
+export interface Assignment { workerId: string; assignmentEpoch: number }
+export interface IssuedCommand {
+  commandId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  desiredVersion: number;
+  issuedAt: string;
+  expiresAt: string;
+  /** Subscribers that received the publish; 0 means no worker is listening right now. */
+  receivers: number;
+}
+export interface ChannelStatus {
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  desired: { desiredVersion: number; desiredStatus: DesiredChannel["desiredStatus"]; production?: DesiredChannel["production"]; director?: DirectorState } | null;
+  observed: ObservedChannel | null;
+  /** True when the worker realized the current desired version under the current assignment. */
+  converged: boolean;
+  workerAlive: boolean;
+}
+export interface WorkerStatus { workerId: string; alive: boolean; lastHeartbeatAt: string | null }
+export interface MediaControlStatus { channels: ChannelStatus[]; workers: WorkerStatus[]; capacity?: CapacitySnapshot }
+
+/** An admission decision paired with one desired-state write. */
+export interface CapacityDecision {
+  /** Reverses the reservations when the desired-state write fails: nothing persisted, no capacity leaked. */
+  undo(): Promise<void>;
+  /** Queued starts admitted because this write freed capacity. */
+  placedFromQueue: string[];
+}
+
+export interface MediaControlDependencies {
+  redis: ControlRedis;
+  signer: ControlCommandSigner | null;
+  handles: CredentialHandleProvider;
+  now: () => number;
+  commandTtlMs: number;
+  /** Bootstrap assignments (mirrors the worker's MEDIA_DESIRED_CONFIG until a scheduler owns placement). */
+  assignments: Array<Assignment & { workspaceId: string; channelId: string }>;
+  transaction: TenantTransaction;
+  /** Capacity & admission (§4.4). Defaults: quota 4, pending bound 8, 20 % failover reserve. */
+  capacity?: Partial<CapacityConfig>;
+}
+export const MEDIA_CONTROL_DEPENDENCIES = Symbol("MEDIA_CONTROL_DEPENDENCIES");
+
+/** Advertised worker capacity (units) until the scheduler owns placement: `{ "media-worker-a": 40 }`. */
+function envWorkerUnits(): Record<string, number> {
+  const raw = process.env.MEDIA_WORKER_UNITS;
+  if (!raw) return {};
+  const value: unknown = JSON.parse(raw);
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new Error("MEDIA_WORKER_UNITS must be a JSON object");
+  const units: Record<string, number> = {};
+  for (const [workerId, item] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof item !== "number" || !Number.isSafeInteger(item) || item <= 0) throw new Error("invalid worker capacity");
+    units[workerId] = item;
+  }
+  return units;
+}
+
+function envSigner(): ControlCommandSigner | null {
+  const path = process.env.MEDIA_CONTROL_PRIVATE_KEY;
+  if (!path) return null;
+  return new Ed25519ControlSigner(process.env.MEDIA_CONTROL_KID ?? "control-v1", createPrivateKey(readFileSync(path)));
+}
+
+function envAssignments(): MediaControlDependencies["assignments"] {
+  const raw = process.env.MEDIA_CONTROL_ASSIGNMENTS;
+  if (!raw) return [];
+  const value: unknown = JSON.parse(raw);
+  if (!Array.isArray(value)) throw new Error("MEDIA_CONTROL_ASSIGNMENTS must be a JSON array");
+  return value.map((item: unknown) => {
+    if (typeof item !== "object" || item === null) throw new Error("invalid assignment");
+    const { workspaceId, channelId, workerId, assignmentEpoch } = item as Record<string, unknown>;
+    if (typeof workspaceId !== "string" || typeof channelId !== "string" || typeof workerId !== "string" ||
+        typeof assignmentEpoch !== "number") throw new Error("invalid assignment");
+    return { workspaceId, channelId, workerId, assignmentEpoch };
+  });
+}
+
+function parseJson<T>(raw: string | null, guard: (value: unknown) => value is T): T | null {
+  if (raw === null) return null;
+  try {
+    const value: unknown = JSON.parse(raw);
+    return guard(value) ? value : null;
+  } catch { return null; }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isAssignment(value: unknown): value is Assignment {
+  return isRecord(value) && typeof value.workerId === "string" && Number.isSafeInteger(value.assignmentEpoch);
+}
+function isSnapshot(value: unknown): value is DesiredChannel {
+  return isRecord(value) && typeof value.workspaceId === "string" && typeof value.channelId === "string" &&
+    typeof value.workerId === "string" && Number.isSafeInteger(value.assignmentEpoch) &&
+    Number.isSafeInteger(value.desiredVersion) && (value.desiredStatus === "RUNNING" || value.desiredStatus === "STOPPED") &&
+    "source" in value && "output" in value && typeof value.profile === "string" && typeof value.mode === "string";
+}
+function isObserved(value: unknown): value is ObservedChannel {
+  return isRecord(value) && typeof value.workerId === "string" && typeof value.state === "string" &&
+    Number.isSafeInteger(value.assignmentEpoch) && (value.realizedVersion === null || Number.isSafeInteger(value.realizedVersion));
+}
+function isHeartbeat(value: unknown): value is { workerId: string; sentAt: string } {
+  return isRecord(value) && typeof value.workerId === "string" && typeof value.sentAt === "string";
+}
+
+/** Canonical assignment JSON — the commit script compares it byte-for-byte. */
+function assignmentJson(a: Assignment): string {
+  return JSON.stringify({ workerId: a.workerId, assignmentEpoch: a.assignmentEpoch });
+}
+
+@Injectable()
+export class MediaControlService implements OnModuleDestroy, OnModuleInit {
+  private readonly deps: MediaControlDependencies;
+  private bootstrapped: Promise<void> | null = null;
+  private recoveryTimer: ReturnType<typeof setInterval> | null = null;
+  private recovering = false;
+  private readonly databaseConfigured: boolean;
+
+  constructor(
+    @Optional() @Inject(MEDIA_CONTROL_DEPENDENCIES) dependencies?: Partial<MediaControlDependencies>,
+    @Optional() @Inject(MEDIA_CREDENTIAL_HANDLES) handles?: CredentialHandleProvider,
+  ) {
+    this.databaseConfigured = dependencies?.transaction !== undefined || process.env.DATABASE_URL !== undefined;
+    this.deps = {
+      redis: dependencies?.redis ?? new RespControlRedis(process.env.REDIS_URL ??
+        `redis://${process.env.REDIS_HOST ?? "localhost"}:${process.env.REDIS_PORT ?? "6379"}`),
+      signer: dependencies?.signer !== undefined ? dependencies.signer : envSigner(),
+      handles: dependencies?.handles ?? handles ?? new StubCredentialHandleProvider(),
+      now: dependencies?.now ?? Date.now,
+      commandTtlMs: dependencies?.commandTtlMs ?? DEFAULT_COMMAND_TTL_MS,
+      assignments: dependencies?.assignments ?? envAssignments(),
+      transaction: dependencies?.transaction ?? withTenant,
+    };
+    this.capacityGate = new CapacityGate({
+      redis: this.deps.redis, now: this.deps.now,
+      config: { ...DEFAULT_CAPACITY_CONFIG, workerUnits: envWorkerUnits(), ...dependencies?.capacity },
+      applyPending: admission => this.reapplyAdmission(admission),
+    });
+  }
+
+  /** §4.4 capacity & admission gate; the scheduler advertises worker capacity here. */
+  readonly capacityGate: CapacityGate;
+  async advertiseWorkerCapacity(workerId: string, totalUnits: number): Promise<void> {
+    await this.capacityGate.advertiseWorker(workerId, totalUnits);
+  }
+
+  onModuleInit(): void {
+    const recover = async (): Promise<void> => {
+      if (this.recovering || !this.deps.signer) return;
+      this.recovering = true;
+      try { await this.flushOutbox(); } catch { /* DB/Redis outage: retry on the next tick. */ }
+      finally { this.recovering = false; }
+    };
+    void recover();
+    this.recoveryTimer = setInterval(() => { void recover(); }, 1000);
+    this.recoveryTimer.unref();
+  }
+  onModuleDestroy(): void {
+    if (this.recoveryTimer) clearInterval(this.recoveryTimer);
+    this.deps.redis.close();
+  }
+
+  private bootstrap(): Promise<void> {
+    this.bootstrapped ??= (async () => {
+      await this.capacityGate.seed();
+      for (const a of this.deps.assignments) await this.assign(a.workspaceId, a.channelId, a.workerId, a.assignmentEpoch);
+    })().catch((error: unknown) => { this.bootstrapped = null; throw error; });
+    return this.bootstrapped;
+  }
+
+  /** Place a channel on a worker. Epochs are monotonic; the worker must be configured with the same epoch. */
+  async assign(workspaceId: string, channelId: string, workerId: string, assignmentEpoch: number): Promise<void> {
+    assertIds(workspaceId, channelId);
+    if (!WORKER_ID.test(workerId)) throw new BadRequestException("workerId is invalid");
+    if (!Number.isSafeInteger(assignmentEpoch) || assignmentEpoch < 0) throw new BadRequestException("assignmentEpoch is invalid");
+    const k = MEDIA_CONTROL_KEYS;
+    const applied = await this.deps.redis.eval(ASSIGN_SCRIPT, [k.assignment(workspaceId, channelId), k.channels(workspaceId)],
+      [assignmentJson({ workerId, assignmentEpoch }), String(assignmentEpoch), workerId, channelId]);
+    if (applied !== 1) throw new ConflictException("assignment epoch is stale or already bound to another worker");
+  }
+
+  async getAssignment(workspaceId: string, channelId: string): Promise<Assignment | null> {
+    return parseJson(await this.deps.redis.get(MEDIA_CONTROL_KEYS.assignment(workspaceId, channelId)), isAssignment);
+  }
+
+  /**
+   * Commit a desired snapshot, then sign and publish it. Order matters: the
+   * snapshot is durably committed (CAS on assignment + version) before signing,
+   * and the commandId is recorded (SET NX, TTL = envelope lifetime) before publish.
+   */
+  async setDesired(workspaceId: string, channelId: string, spec: DesiredSpec,
+    options?: { idempotencyKey?: string; actor: DirectorActor }): Promise<IssuedCommand> {
+    assertIds(workspaceId, channelId);
+    const checked = parseDesiredSpec(spec);
+    const signer = this.deps.signer;
+    if (signer === null) throw new ServiceUnavailableException("media control signing key is not configured");
+    await this.bootstrap();
+    const existing = parseJson(await this.deps.redis.get(MEDIA_CONTROL_KEYS.desired(workspaceId, channelId)), isSnapshot);
+    // Once a channel uses production, full snapshot writes must join the same
+    // PostgreSQL fence as bus/overlay writes; a Redis-only INCR could collide.
+    const productionChannel = this.databaseConfigured && await this.deps.transaction(workspaceId, async client => {
+      const channel = await client.query("SELECT id FROM virtual_channels WHERE workspace_id=$1 AND id=$2", [workspaceId, channelId]);
+      return Boolean(channel.rowCount);
+    });
+    if (checked.production || existing?.production || productionChannel) {
+      return this.director(workspaceId, channelId, { type: "desired", spec: checked }, options?.idempotencyKey ?? randomUUID(),
+        options?.actor ?? { userId: null, role: "system" });
+    }
+    const assignment = await this.getAssignment(workspaceId, channelId);
+    if (assignment === null) throw new ConflictException("channel is not assigned to a media worker");
+    if (checked.output !== null) {
+      try { await this.deps.handles.assertUsable(workspaceId, channelId, checked.output.credentialHandleId); } catch (error: unknown) {
+        throw new BadRequestException(`output.credentialHandleId: ${error instanceof Error ? error.message : "unusable"}`);
+      }
+    }
+    // The queued admission replays under this key when capacity frees up.
+    const idempotencyKey = options?.idempotencyKey ?? randomUUID();
+    const admission = await this.admitForCapacity(workspaceId, channelId, assignment.workerId, checked,
+      idempotencyKey, "desired-v1", null, options?.actor);
+    const stopWorker = checked.desiredStatus === "STOPPED" ? assignment.workerId : null;
+
+    const k = MEDIA_CONTROL_KEYS;
+    const desiredVersion = await this.deps.redis.incr(k.version(workspaceId, channelId));
+    const snapshot: DesiredChannel = {
+      workspaceId, channelId, workerId: assignment.workerId, assignmentEpoch: assignment.assignmentEpoch,
+      desiredVersion, desiredStatus: checked.desiredStatus, source: checked.source, output: checked.output,
+      profile: checked.profile, mode: checked.mode,
+      ...(checked.production === undefined ? {} : { production: checked.production }),
+    };
+    const committed = await this.deps.redis.eval(COMMIT_DESIRED_SCRIPT,
+      [k.desired(workspaceId, channelId), k.assignment(workspaceId, channelId)],
+      [JSON.stringify(snapshot), String(desiredVersion), assignmentJson(assignment)]);
+    if (committed !== 1) {
+      await admission.undo(); // nothing persisted: no desired state, no capacity reservation
+      throw new ConflictException(committed === -1
+        ? "channel assignment changed; retry"
+        : "a newer desired version was committed concurrently");
+    }
+
+    const issued = await this.issue(signer, snapshot);
+    // The commit is durable, so the capacity reservation is kept even if the
+    // publish fails: the outbox recovery loop re-delivers the snapshot and the
+    // reservation is never taken twice for one desired version.
+    if (stopWorker !== null) await this.drainQueued(stopWorker);
+    return issued;
+  }
+
+  /**
+   * §4.4 admission on the take/start path. A RUNNING start either reserves
+   * capacity or throws (PENDING_CAPACITY / 429 CAPACITY_QUEUE_FULL) before any
+   * desired state is written; STOPPED frees the reservation and offers the
+   * freed capacity to the pending queue. Idempotent by idempotency key.
+   */
+  private async admitForCapacity(
+    workspaceId: string, channelId: string, workerId: string, spec: DesiredSpec,
+    idempotencyKey: string, path: "desired-v1" | "director", operation: DirectorOperation | null,
+    actor: DirectorActor = { userId: null, role: "system" },
+  ): Promise<CapacityDecision> {
+    if (spec.desiredStatus === "STOPPED") {
+      const released = await this.capacityGate.release(workspaceId, channelId);
+      return { undo: async () => undefined, placedFromQueue: released.placed };
+    }
+    const admitted = await this.capacityGate.admit(workspaceId, channelId, workerId, spec,
+      actor, idempotencyKey, path, operation);
+    return { undo: admitted.undo, placedFromQueue: [] };
+  }
+
+  /**
+   * Re-deliver the committed snapshot under a fresh commandId (same version):
+   * the worker fence accepts an equal version with an unseen commandId. Used
+   * when a publish reached no subscriber or a worker restarted.
+   */
+  async republish(workspaceId: string, channelId: string): Promise<IssuedCommand> {
+    assertIds(workspaceId, channelId);
+    const signer = this.deps.signer;
+    if (signer === null) throw new ServiceUnavailableException("media control signing key is not configured");
+    const [assignment, snapshot] = await Promise.all([
+      this.getAssignment(workspaceId, channelId),
+      this.deps.redis.get(MEDIA_CONTROL_KEYS.desired(workspaceId, channelId)).then((raw) => parseJson(raw, isSnapshot)),
+    ]);
+    if (assignment === null || snapshot === null) throw new ConflictException("no committed desired state for channel");
+    if (snapshot.workspaceId !== workspaceId || snapshot.channelId !== channelId) throw new ConflictException("committed snapshot is corrupt");
+    if (snapshot.workerId !== assignment.workerId || snapshot.assignmentEpoch !== assignment.assignmentEpoch) {
+      throw new ConflictException("channel was reassigned since the last commit; set desired state again");
+    }
+    return this.issue(signer, snapshot);
+  }
+
+  private async issue(signer: ControlCommandSigner, snapshot: DesiredChannel): Promise<IssuedCommand> {
+    const now = this.deps.now();
+    const body: CommandBody = {
+      workspaceId: snapshot.workspaceId, channelId: snapshot.channelId, workerId: snapshot.workerId,
+      assignmentEpoch: snapshot.assignmentEpoch, commandId: randomUUID(), desiredVersion: snapshot.desiredVersion,
+      issuedAt: new Date(now).toISOString(), expiresAt: new Date(now + this.deps.commandTtlMs).toISOString(), snapshot,
+    };
+    const signed = await signer.signCommittedSnapshot(body);
+    await this.recordIssued(body, signed.kid);
+    const receivers = await this.deps.redis.publish(MEDIA_CONTROL_KEYS.command(body.workspaceId, body.workerId), JSON.stringify(signed));
+    return {
+      commandId: body.commandId, workerId: body.workerId, assignmentEpoch: body.assignmentEpoch,
+      desiredVersion: body.desiredVersion, issuedAt: body.issuedAt, expiresAt: body.expiresAt, receivers,
+    };
+  }
+
+  /** Durable anti-replay audit: a commandId is issued at most once, retained until its envelope expires. */
+  async recordIssued(body: CommandBody, kid: string): Promise<void> {
+    const ttl = Date.parse(body.expiresAt) - this.deps.now();
+    if (!(ttl > 0)) throw new Error("command already expired");
+    const fresh = await this.deps.redis.set(MEDIA_CONTROL_KEYS.issued(body.commandId), JSON.stringify({
+      workspaceId: body.workspaceId, channelId: body.channelId, workerId: body.workerId,
+      assignmentEpoch: body.assignmentEpoch, desiredVersion: body.desiredVersion, kid,
+      issuedAt: body.issuedAt, expiresAt: body.expiresAt,
+    }), { nx: true, pxMs: ttl });
+    if (!fresh) throw new ConflictException("commandId already issued (replay refused)");
+  }
+
+  /** The channel row serializes writers; the receipt is the transactional outbox.
+   * No external effects occur inside this PostgreSQL transaction. */
+  async director(workspaceId: string, channelId: string, operation: DirectorOperation, idempotencyKey: string,
+    actor: DirectorActor): Promise<IssuedCommand> {
+    assertIds(workspaceId, channelId);
+    validateOperation(operation);
+    if (!this.deps.signer) throw new ServiceUnavailableException("media control signing key is not configured");
+    await this.bootstrap();
+    const requestId = requestIdentity(workspaceId, channelId, idempotencyKey);
+    const expected = fingerprint(operation);
+    // Holder object: TS cannot track assignments made inside the closure below.
+    const capacityUndo: { undo: (() => Promise<void>) | null; releasedFromStop: boolean; workerId: string } =
+      { undo: null, releasedFromStop: false, workerId: "" };
+    let receipt: DirectorReceipt;
+    const transaction = this.deps.transaction(workspaceId, async client => {
+      const channel = await client.query<{ desired_version: string; desired_status: "RUNNING" | "STOPPED" }>(
+        "SELECT desired_version,desired_status FROM virtual_channels WHERE workspace_id=$1 AND id=$2 FOR UPDATE", [workspaceId, channelId]);
+      const row = channel.rows[0];
+      if (!row) throw new ConflictException("unknown production channel");
+      const duplicate = await findReceipt(client, workspaceId, channelId, requestId, expected);
+      if (duplicate) return duplicate;
+      const latest = await client.query<{ diff: DirectorReceipt }>(
+        "SELECT diff FROM audit_log WHERE workspace_id=$1 AND target_type='production_command' AND target_id=$2 ORDER BY seq DESC LIMIT 1", [workspaceId, channelId]);
+      const state: DirectorState = structuredClone(latest.rows[0]?.diff.state ?? { locked: false, override: null });
+      if (operation.type === "lock") state.locked = operation.enabled;
+      if (operation.type === "override") state.override = operation.mode === null ? null : {
+        mode: operation.mode, expiresAt: operation.mode === "five_minutes" ? new Date(this.deps.now() + 300_000).toISOString() : null,
+      };
+      if (operation.type === "take" || operation.type === "cut") {
+        const preview = await client.query<{ scene_id: string | null }>(
+          "SELECT scene_id FROM production_buses WHERE workspace_id=$1 AND virtual_channel_id=$2 AND bus='preview'", [workspaceId, channelId]);
+        const sceneId = preview.rows[0]?.scene_id;
+        if (!sceneId) throw new ConflictException("preview bus is empty");
+        await client.query(`INSERT INTO production_buses(workspace_id,virtual_channel_id,bus,scene_id) VALUES($1,$2,'program',$3)
+          ON CONFLICT(workspace_id,virtual_channel_id,bus) DO UPDATE SET scene_id=EXCLUDED.scene_id,updated_at=now()`, [workspaceId, channelId, sceneId]);
+        state.override = { mode: "until_released", expiresAt: null };
+      }
+      if (operation.type === "pst-select") {
+        const scene = await client.query("SELECT id FROM production_scenes WHERE workspace_id=$1 AND virtual_channel_id=$2 AND id=$3", [workspaceId, channelId, operation.sceneId]);
+        if (!scene.rowCount) throw new BadRequestException("scene must belong to this channel");
+        await client.query(`INSERT INTO production_buses(workspace_id,virtual_channel_id,bus,scene_id) VALUES($1,$2,'preview',$3)
+          ON CONFLICT(workspace_id,virtual_channel_id,bus) DO UPDATE SET scene_id=EXCLUDED.scene_id,updated_at=now()`, [workspaceId, channelId, operation.sceneId]);
+      }
+      if (operation.type === "overlay") {
+        const updated = await client.query(`UPDATE overlay_slots s SET current_revision_id=r.id,updated_at=now()
+          FROM overlay_revisions r WHERE s.workspace_id=$1 AND s.virtual_channel_id=$2 AND s.id=$3
+          AND r.workspace_id=s.workspace_id AND r.virtual_channel_id=s.virtual_channel_id AND r.overlay_slot_id=s.id
+          AND r.id=$4 AND r.render_state='rendered' AND (s.current_revision_id IS NULL OR r.created_at >=
+            (SELECT active_revision.created_at FROM overlay_revisions active_revision WHERE active_revision.workspace_id=s.workspace_id AND active_revision.id=s.current_revision_id))`, [workspaceId, channelId, operation.slotId, operation.revisionId]);
+        if (!updated.rowCount) throw new BadRequestException("rendered revision must belong to this overlay slot");
+      }
+      const assignment = await this.getAssignment(workspaceId, channelId);
+      if (!assignment) throw new ConflictException("channel is not assigned to a media worker");
+      const cached = parseJson(await this.deps.redis.get(MEDIA_CONTROL_KEYS.desired(workspaceId, channelId)), isSnapshot);
+      const previous = latest.rows[0]?.diff.snapshot ?? cached;
+      const spec = operation.type === "desired" ? parseDesiredSpec(operation.spec) : parseDesiredSpec({
+        desiredStatus: row.desired_status, source: null, output: previous?.output ?? null,
+        profile: previous?.profile ?? "720p30", mode: previous?.mode ?? "normalize",
+        production: await productionSnapshot(client, workspaceId, channelId),
+      });
+      if (spec.output) await this.deps.handles.assertUsable(workspaceId, channelId, spec.output.credentialHandleId);
+      // §4.4 admission is part of the transaction: an over-quota write rolls
+      // the whole thing back — no bus effect, no version bump, no audit row.
+      // A start queued as PENDING_CAPACITY throws here too, so nothing is
+      // persisted for a channel whose placement is not admitted.
+      if (this.databaseConfigured) {
+        const decision = await this.admitForCapacity(workspaceId, channelId, assignment.workerId, spec,
+          idempotencyKey, "director", operation, actor);
+        capacityUndo.undo = () => decision.undo();
+        if (spec.desiredStatus === "STOPPED") { capacityUndo.releasedFromStop = true; capacityUndo.workerId = assignment.workerId; }
+      }
+      const floor = Math.max(Number(row.desired_version), previous?.desiredVersion ?? 0,
+        Number(await this.deps.redis.get(MEDIA_CONTROL_KEYS.version(workspaceId, channelId)) ?? 0));
+      if (!Number.isSafeInteger(floor) || floor >= Number.MAX_SAFE_INTEGER) throw new ConflictException("desired version exhausted");
+      const desiredVersion = floor + 1;
+      await client.query("UPDATE virtual_channels SET desired_version=$3,desired_status=$4,updated_at=now() WHERE workspace_id=$1 AND id=$2", [workspaceId, channelId, desiredVersion, spec.desiredStatus]);
+      const snapshot: DesiredChannel = { workspaceId, channelId, ...assignment, desiredVersion, ...spec };
+      const committed: DirectorReceipt = { operation, requestId, fingerprint: expected, snapshot, state };
+      // Serialize our appends with one another, preserving the tenant audit chain.
+      await client.query("SELECT pg_advisory_xact_lock(hashtextextended($1,0))", [`production-audit:${workspaceId}`]);
+      await client.query("SELECT audit_append($1,$2,$3,$4,$5,$6,$7)",
+        [workspaceId, actor.userId, actor.role, `director.${operation.type}`, "production_command", channelId, committed]);
+      return committed;
+    });
+    try {
+      receipt = await transaction;
+    } catch (error: unknown) {
+      const undo = capacityUndo.undo;
+      if (undo !== null) await undo(); // rolled back: nothing persisted, no capacity leaked
+      throw error;
+    }
+    // The transaction committed, so the reservation stands; a stop offers its
+    // freed capacity to the pending queue (each re-apply is idempotent under
+    // the stored idempotency key).
+    if (capacityUndo.releasedFromStop) await this.drainQueued(capacityUndo.workerId);
+    return this.deliverReceipt(receipt);
+  }
+
+  /** Offer freed capacity to the pending queue (each re-apply is idempotent). */
+  private async drainQueued(workerId: string): Promise<void> {
+    await this.capacityGate.drain(workerId).catch(() => undefined);
+  }
+
+  /**
+   * Re-apply a queued start once its placement is admitted by a drain. Runs
+   * under the original idempotency key, so a retry of the original request
+   * replays the same receipt instead of double-starting.
+   */
+  private async reapplyAdmission(admission: StoredAdmission): Promise<void> {
+    if (admission.path === "desired-v1") {
+      await this.setDesired(admission.workspaceId, admission.channelId, admission.spec, {
+        idempotencyKey: admission.idempotencyKey, actor: admission.actor,
+      });
+      return;
+    }
+    const operation = admission.operation;
+    if (operation === null) throw new Error("queued admission is missing its director operation");
+    await this.director(admission.workspaceId, admission.channelId, operation,
+      admission.idempotencyKey, admission.actor);
+  }
+
+  async deliverReceipt(receipt: DirectorReceipt): Promise<IssuedCommand> {
+    const signer = this.deps.signer;
+    if (!signer) throw new ServiceUnavailableException("media control signing key is not configured");
+    const snapshot = receipt.snapshot;
+    const key = `mcp:delivery:${receipt.requestId}`;
+    const prior = await this.deps.redis.get(key);
+    if (prior) return JSON.parse(prior) as IssuedCommand;
+    const assignment = await this.getAssignment(snapshot.workspaceId, snapshot.channelId);
+    if (!assignment || assignmentJson(assignment) !== assignmentJson(snapshot)) throw new ConflictException("outbox assignment changed");
+    const now = this.deps.now();
+    const body: CommandBody = { workspaceId: snapshot.workspaceId, channelId: snapshot.channelId, workerId: snapshot.workerId,
+      assignmentEpoch: snapshot.assignmentEpoch, desiredVersion: snapshot.desiredVersion, commandId: randomUUID(),
+      issuedAt: new Date(now).toISOString(), expiresAt: new Date(now + this.deps.commandTtlMs).toISOString(), snapshot };
+    const signed = await signer.signCommittedSnapshot(body);
+    const result: IssuedCommand = { commandId: body.commandId, workerId: body.workerId, assignmentEpoch: body.assignmentEpoch,
+      desiredVersion: body.desiredVersion, issuedAt: body.issuedAt, expiresAt: body.expiresAt, receivers: 0 };
+    const k = MEDIA_CONTROL_KEYS;
+    const response = await this.deps.redis.eval(DELIVER_RECEIPT_SCRIPT,
+      [key, k.desired(body.workspaceId, body.channelId), k.version(body.workspaceId, body.channelId),
+        k.assignment(body.workspaceId, body.channelId), k.command(body.workspaceId, body.workerId), k.issued(body.commandId),
+        `state:${body.workspaceId}:${body.channelId}:desired`, `mcp:director:${body.workspaceId}:${body.channelId}`],
+      [JSON.stringify(result), JSON.stringify(snapshot), String(snapshot.desiredVersion), assignmentJson(assignment),
+        JSON.stringify(signed), String(this.deps.commandTtlMs), JSON.stringify({ desiredVersion: snapshot.desiredVersion, state: receipt.state })]);
+    if (response === -1) throw new ConflictException("outbox assignment changed");
+    if (typeof response !== "string") throw new Error("invalid delivery receipt");
+    return JSON.parse(response) as IssuedCommand;
+  }
+
+  /** Recovery also runs after process restart, independent of an HTTP retry. */
+  async flushOutbox(): Promise<void> {
+    const workspaces = await pool.query<{ id: string }>("SELECT id FROM workspaces");
+    for (const workspace of workspaces.rows) {
+      const receipts = await this.deps.transaction(workspace.id, async client => {
+        const result = await client.query<{ diff: DirectorReceipt }>(
+          "SELECT diff FROM audit_log WHERE workspace_id=$1 AND target_type='production_command' ORDER BY seq", [workspace.id]);
+        return result.rows.map(row => row.diff);
+      });
+      for (const receipt of receipts) await this.deliverReceipt(receipt).catch(() => undefined);
+    }
+  }
+
+  async getStatus(workspaceId: string): Promise<MediaControlStatus> {
+    if (!isUuid(workspaceId)) throw new BadRequestException("workspaceId must be a UUID");
+    await this.bootstrap();
+    const k = MEDIA_CONTROL_KEYS;
+    const channelIds = (await this.deps.redis.smembers(k.channels(workspaceId))).filter(isUuid).sort();
+    if (channelIds.length === 0) return { channels: [], workers: [] };
+    const [assignments, desired, observed, director] = await Promise.all([
+      this.deps.redis.mget(channelIds.map((ch) => k.assignment(workspaceId, ch))),
+      this.deps.redis.mget(channelIds.map((ch) => k.desired(workspaceId, ch))),
+      this.deps.redis.mget(channelIds.map((ch) => k.observed(workspaceId, ch))),
+      this.deps.redis.mget(channelIds.map((ch) => `mcp:director:${workspaceId}:${ch}`)),
+    ]);
+    const parsedAssignments = assignments.map((raw) => parseJson(raw, isAssignment));
+    const workerIds = [...new Set(parsedAssignments.flatMap((a) => (a === null ? [] : [a.workerId])))].sort();
+    const beats = await this.deps.redis.mget(workerIds.map((id) => k.heartbeat(id)));
+    const now = this.deps.now();
+    // Heartbeats carry every workspace's channels for that worker; only liveness is surfaced here.
+    const workers: WorkerStatus[] = workerIds.map((workerId, i) => {
+      const hb = parseJson(beats[i] ?? null, isHeartbeat);
+      const sentAt = hb === null || hb.workerId !== workerId ? NaN : Date.parse(hb.sentAt);
+      const alive = Number.isFinite(sentAt) && now - sentAt <= HEARTBEAT_TTL_MS;
+      return { workerId, alive, lastHeartbeatAt: Number.isFinite(sentAt) ? new Date(sentAt).toISOString() : null };
+    });
+    const alive = new Map(workers.map((w) => [w.workerId, w.alive]));
+
+    const channels: ChannelStatus[] = [];
+    channelIds.forEach((channelId, i) => {
+      const assignment = parsedAssignments[i];
+      if (!assignment) return;
+      const want = parseJson(desired[i] ?? null, isSnapshot);
+      const seen = parseJson(observed[i] ?? null, isObserved);
+      // An observation from a previous placement says nothing about the current one.
+      const current = seen !== null && seen.workerId === assignment.workerId && seen.assignmentEpoch === assignment.assignmentEpoch ? seen : null;
+      channels.push({
+        channelId, workerId: assignment.workerId, assignmentEpoch: assignment.assignmentEpoch,
+        desired: want === null ? null : { desiredVersion: want.desiredVersion, desiredStatus: want.desiredStatus,
+          ...(want.production ? { production: want.production } : {}),
+          ...(director[i] ? { director: JSON.parse(director[i] ?? "null") as DirectorState } : {}) },
+        observed: current,
+        converged: want !== null && current !== null && current.realizedVersion === want.desiredVersion,
+        workerAlive: alive.get(assignment.workerId) ?? false,
+      });
+    });
+    // §4.4 capacity accounting: only channels of this workspace are reported.
+    const capacity = await this.capacityGate.snapshot(workspaceId, channelIds).catch(() => null);
+    return capacity === null ? { channels, workers } : { channels, workers, capacity };
+  }
+
+  /** Per-job resource event: a channel throttled/killed at its own cgroup/fd/egress cap (§4.4). */
+  async recordResourceEvent(workspaceId: string, channelId: string, kind: "throttled" | "killed", reason: string): Promise<void> {
+    assertIds(workspaceId, channelId);
+    await this.capacityGate.recordResourceEvent(workspaceId, channelId, kind, reason);
+  }
+
+  /** Capacity accounting for one channel (null when the channel holds no reservation). */
+  async channelCapacity(workspaceId: string, channelId: string): Promise<ChannelCapacity | null> {
+    assertIds(workspaceId, channelId);
+    return this.capacityGate.channelOf(workspaceId, channelId);
+  }
+}
+
+function assertIds(workspaceId: string, channelId: string): void {
+  if (!isUuid(workspaceId)) throw new BadRequestException("workspaceId must be a UUID");
+  if (!isUuid(channelId)) throw new BadRequestException("channelId must be a UUID");
+}
+
+/** Atomic Redis delivery: one publish for a durable receipt even if the client
+ * loses the response. Old receipts may be delivered but never replace newer state. */
+export const DELIVER_RECEIPT_SCRIPT = `
+local prior = redis.call('GET', KEYS[1])
+if prior then return prior end
+if redis.call('GET', KEYS[4]) ~= ARGV[4] then return -1 end
+local cur = redis.call('GET', KEYS[2])
+if not cur or tonumber(cjson.decode(cur).desiredVersion) < tonumber(ARGV[3]) then
+  redis.call('SET', KEYS[2], ARGV[2])
+  redis.call('SET', KEYS[3], ARGV[3])
+  redis.call('SET', KEYS[8], cjson.encode(cjson.decode(ARGV[7]).state))
+end
+redis.call('SET', KEYS[6], ARGV[5], 'PX', ARGV[6])
+local result = cjson.decode(ARGV[1])
+result.receivers = redis.call('PUBLISH', KEYS[5], ARGV[5])
+local receipt = cjson.encode(result)
+redis.call('SET', KEYS[1], receipt)
+redis.call('PUBLISH', KEYS[7], ARGV[7])
+return receipt`;
+
+function validateOperation(operation: DirectorOperation): void {
+  if (!operation || typeof operation !== "object") throw new BadRequestException("invalid director operation");
+  const fields: Record<string, string[]> = { desired: ["type", "spec"], take: ["type"], cut: ["type"], "pst-select": ["type", "sceneId"],
+    lock: ["type", "enabled"], override: ["type", "mode"], overlay: ["type", "slotId", "revisionId"] };
+  const allowed = fields[operation.type];
+  if (!allowed || Object.keys(operation).some(k => !allowed.includes(k))) throw new BadRequestException("invalid director operation");
+  if (operation.type === "desired") parseDesiredSpec(operation.spec);
+  if (operation.type === "pst-select" && !isUuid(operation.sceneId)) throw new BadRequestException("sceneId must be a UUID");
+  if (operation.type === "lock" && typeof operation.enabled !== "boolean") throw new BadRequestException("enabled must be boolean");
+  if (operation.type === "override" && operation.mode !== null && !["until_released", "five_minutes", "until_source_offline", "until_next_event"].includes(operation.mode)) throw new BadRequestException("invalid override mode");
+  if (operation.type === "overlay" && (!isUuid(operation.slotId) || !isUuid(operation.revisionId))) throw new BadRequestException("invalid overlay identity");
+}
diff --git a/apps/api/src/media-control/media-control.test.ts b/apps/api/src/media-control/media-control.test.ts
new file mode 100644
index 0000000..95345fd
--- /dev/null
+++ b/apps/api/src/media-control/media-control.test.ts
@@ -0,0 +1,417 @@
+import { createPublicKey, generateKeyPairSync, randomUUID, type KeyObject } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { HttpException } from "@nestjs/common";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+// The worker is the contract: verify with its own code, not a copy.
+import { signCommand as workerSign, verifyCommand as workerVerify } from "../../../media-worker/src/bus/envelope.js";
+import { Ed25519ControlSigner as WorkerSigner } from "../../../media-worker/src/bus/control-signer.js";
+import { DurableFence } from "../../../media-worker/src/bus/fence.js";
+import { validateEndpointShape as workerValidate } from "../../../media-worker/src/relay/endpoints.js";
+import { StubCredentialHandleProvider } from "./credential-handles.js";
+import { validateEndpointShape } from "./endpoints.js";
+import {
+  ASSIGN_SCRIPT, COMMIT_DESIRED_SCRIPT, HEARTBEAT_TTL_MS, MEDIA_CONTROL_KEYS as K, MediaControlService,
+} from "./media-control.service.js";
+import type { ControlRedis, RedisReply } from "./redis.js";
+import { parseDesiredSpec, type DesiredSpec } from "./spec.js";
+import { parseProductionSpec } from "./production.js";
+import { Ed25519ControlSigner, type CommandBody, type SignedCommand } from "./wire.js";
+
+/** In-memory Redis with the two control-plane scripts emulated by identity. */
+class FakeRedis implements ControlRedis {
+  readonly kv = new Map<string, { value: string; expiresAt: number | null }>();
+  readonly sets = new Map<string, Set<string>>();
+  readonly published: Array<{ channel: string; message: string }> = [];
+  subscribers = 1;
+  constructor(private readonly now: () => number) {}
+  async get(key: string): Promise<string | null> {
+    const entry = this.kv.get(key);
+    if (!entry) return null;
+    if (entry.expiresAt !== null && entry.expiresAt <= this.now()) { this.kv.delete(key); return null; }
+    return entry.value;
+  }
+  async mget(keys: string[]): Promise<Array<string | null>> { return Promise.all(keys.map((key) => this.get(key))); }
+  async set(key: string, value: string, options: { nx?: boolean; pxMs?: number } = {}): Promise<boolean> {
+    if (options.nx && (await this.get(key)) !== null) return false;
+    this.kv.set(key, { value, expiresAt: options.pxMs === undefined ? null : this.now() + options.pxMs });
+    return true;
+  }
+  async incr(key: string): Promise<number> {
+    const next = Number((await this.get(key)) ?? "0") + 1;
+    this.kv.set(key, { value: String(next), expiresAt: null });
+    return next;
+  }
+  async sadd(key: string, member: string): Promise<void> {
+    const set = this.sets.get(key) ?? new Set<string>();
+    set.add(member);
+    this.sets.set(key, set);
+  }
+  async smembers(key: string): Promise<string[]> { return [...(this.sets.get(key) ?? [])]; }
+  async publish(channel: string, message: string): Promise<number> {
+    this.published.push({ channel, message });
+    return this.subscribers;
+  }
+  async eval(script: string, keys: string[], args: string[]): Promise<RedisReply> {
+    const [k1 = "", k2 = ""] = keys;
+    const [a1 = "", a2 = "", a3 = "", a4 = ""] = args;
+    if (script === ASSIGN_SCRIPT) {
+      const cur = await this.get(k1);
+      if (cur !== null) {
+        const obj = JSON.parse(cur) as { workerId: string; assignmentEpoch: number };
+        if (obj.assignmentEpoch > Number(a2)) return 0;
+        if (obj.assignmentEpoch === Number(a2) && obj.workerId !== a3) return 0;
+      }
+      await this.set(k1, a1);
+      await this.sadd(k2, a4);
+      return 1;
+    }
+    if (script === COMMIT_DESIRED_SCRIPT) {
+      if ((await this.get(k2)) !== a3) return -1;
+      const cur = await this.get(k1);
+      if (cur !== null && (JSON.parse(cur) as { desiredVersion: number }).desiredVersion >= Number(a2)) return 0;
+      await this.set(k1, a1);
+      return 1;
+    }
+    throw new Error("unknown script");
+  }
+  close(): void {}
+}
+
+const WS = randomUUID();
+const CH = randomUUID();
+const WORKER = "media-worker-a";
+const KID = "control-v1";
+const HANDLE = "vh_0123456789abcdefXYZ";
+const RUNNING: DesiredSpec = {
+  desiredStatus: "RUNNING",
+  source: { kind: "hls", url: "https://cdn.example.com/live/index.m3u8" },
+  output: { endpointUrl: "rtmps://live.example.net/app", credentialHandleId: HANDLE },
+  profile: "1080p30",
+  mode: "normalize",
+};
+
+describe("desired-state v1/v2 parser", () => {
+  it("round-trips a v1 single HLS source without adding production fields", () => {
+    expect(parseDesiredSpec(structuredClone(RUNNING))).toEqual(RUNNING);
+    expect(JSON.stringify(parseDesiredSpec(structuredClone(RUNNING)))).toBe(JSON.stringify(RUNNING));
+  });
+
+  const sourceId = randomUUID();
+  const sceneId = randomUUID();
+  const playlist = {
+    sources: [{ id: sourceId, label: "Reel", kind: "playlist", assetIds: [randomUUID()], loop: true }],
+    scenes: [{ id: sceneId, label: "Main", layout: "single", slots: [
+      { index: 0, sourceId, rect: null, fit: "contain", audioMode: "primary", gainDb: -6 },
+    ] }],
+    buses: { preview: sceneId, program: sceneId }, overlays: [],
+    transition: { type: "cut" }, audio: { masterGainDb: 0 },
+  };
+
+  it("accepts playlist sources and a single primary audio slot", () => {
+    expect(parseProductionSpec(playlist).sources[0]?.kind).toBe("playlist");
+  });
+
+  it("rejects filtergraph payloads in scene and source labels", () => {
+    for (const bad of ["a;b", "x[0]", "a,b", "it's", "movie=/etc/passwd"]) {
+      expect(() => parseProductionSpec({ ...playlist, scenes: [{ ...playlist.scenes[0], label: bad }] })).toThrow();
+      expect(() => parseProductionSpec({ ...playlist, sources: [{ ...playlist.sources[0], label: bad }] })).toThrow();
+    }
+  });
+
+  it("rejects two primary slots and gains outside -24..0 in 3 dB steps", () => {
+    const scene = playlist.scenes[0];
+    const slot = scene?.slots[0];
+    if (!scene || !slot) throw new Error("fixture missing slot");
+    expect(() => parseProductionSpec({ ...playlist, scenes: [{ ...scene, layout: "2x1", slots: [slot, { ...slot, index: 1 }] }] })).toThrow(/primary/);
+    for (const gainDb of [-25, -4, 1]) {
+      expect(() => parseProductionSpec({ ...playlist, scenes: [{ ...scene, slots: [{ ...slot, gainDb }] }] })).toThrow();
+    }
+  });
+});
+
+function keys(): { privateKey: KeyObject; publicKey: KeyObject } { return generateKeyPairSync("ed25519"); }
+
+function statusOf(error: unknown): number {
+  return error instanceof HttpException ? error.getStatus() : -1;
+}
+async function rejectsWith(promise: Promise<unknown>, status: number): Promise<void> {
+  const error: unknown = await promise.then(() => null, (e: unknown) => e);
+  expect(statusOf(error)).toBe(status);
+}
+
+describe("media control plane", () => {
+  let now: number;
+  let redis: FakeRedis;
+  let pair: { privateKey: KeyObject; publicKey: KeyObject };
+  let workerKeys: Map<string, KeyObject>;
+  let service: MediaControlService;
+  let fenceDir: string;
+
+  beforeEach(async () => {
+    now = Date.parse("2026-10-07T12:00:00.000Z");
+    redis = new FakeRedis(() => now);
+    pair = keys();
+    workerKeys = new Map([[KID, pair.publicKey]]);
+    service = new MediaControlService({
+      redis, signer: new Ed25519ControlSigner(KID, pair.privateKey), handles: new StubCredentialHandleProvider(),
+      now: () => now, commandTtlMs: 30_000, assignments: [],
+    });
+    await service.assign(WS, CH, WORKER, 3);
+    fenceDir = mkdtempSync(join(tmpdir(), "mcp-fence-"));
+  });
+  afterEach(() => rmSync(fenceDir, { recursive: true, force: true }));
+
+  function lastPublished(): unknown { return JSON.parse(redis.published.at(-1)?.message ?? "null"); }
+
+  describe("envelope interop with the worker", () => {
+    it("published command verifies under the worker's verifyCommand", async () => {
+      const issued = await service.setDesired(WS, CH, RUNNING);
+      expect(redis.published.at(-1)?.channel).toBe(`cmd:${WS}:${WORKER}`);
+      const verified = workerVerify(lastPublished(), workerKeys, WORKER, now);
+      expect(verified.body).toMatchObject({ workspaceId: WS, channelId: CH, workerId: WORKER, assignmentEpoch: 3,
+        commandId: issued.commandId, desiredVersion: 1 });
+      expect(verified.body.snapshot.output).toEqual({ endpointUrl: RUNNING.output?.endpointUrl, credentialHandleId: HANDLE });
+    });
+
+    it("produces byte-identical signatures to the worker's own Ed25519ControlSigner", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      const ours = lastPublished() as SignedCommand;
+      const theirs = await new WorkerSigner(KID, pair.privateKey).signCommittedSnapshot(ours.body);
+      expect(theirs.signature).toBe(ours.signature);
+      expect(workerSign(ours.body, KID, pair.privateKey).signature).toBe(ours.signature);
+    });
+
+    it("signs canonically even when snapshot keys arrive in a different order", async () => {
+      const signer = new Ed25519ControlSigner(KID, pair.privateKey);
+      const snapshot = { mode: "passthrough" as const, profile: "720p30" as const, output: null, source: null,
+        desiredStatus: "STOPPED" as const, desiredVersion: 9, assignmentEpoch: 3, workerId: WORKER, channelId: CH, workspaceId: WS };
+      const body: CommandBody = { workspaceId: WS, channelId: CH, workerId: WORKER, assignmentEpoch: 3, commandId: randomUUID(),
+        desiredVersion: 9, issuedAt: new Date(now).toISOString(), expiresAt: new Date(now + 10_000).toISOString(), snapshot };
+      const signed = await signer.signCommittedSnapshot(body);
+      expect(() => workerVerify(JSON.parse(JSON.stringify(signed)), workerKeys, WORKER, now)).not.toThrow();
+    });
+
+    it("worker rejects tampering, unknown kid, wrong worker, and expiry", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      const signed = lastPublished() as SignedCommand;
+      const tampered = structuredClone(signed);
+      if (tampered.body.snapshot.source) tampered.body.snapshot.source.url = "https://evil.example.com/x.m3u8";
+      expect(() => workerVerify(tampered, workerKeys, WORKER, now)).toThrow("invalid signature");
+      expect(() => workerVerify({ ...signed, kid: "control-v2" }, workerKeys, WORKER, now)).toThrow("invalid signature");
+      expect(() => workerVerify(signed, new Map([[KID, keys().publicKey]]), WORKER, now)).toThrow("invalid signature");
+      expect(() => workerVerify(signed, workerKeys, "media-worker-b", now)).toThrow("invalid command fields");
+      expect(() => workerVerify(signed, workerKeys, WORKER, now + 30_000)).toThrow("expired command");
+    });
+
+    it("refuses non-Ed25519 keys", () => {
+      const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+      expect(() => new Ed25519ControlSigner(KID, privateKey)).toThrow("Ed25519");
+      expect(() => new Ed25519ControlSigner(KID, createPublicKey(pair.privateKey))).toThrow("Ed25519");
+    });
+  });
+
+  describe("replay", () => {
+    it("worker fence accepts a command once and reports replay on redelivery", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      const fence = new DurableFence(join(fenceDir, "fence.json"));
+      const command = workerVerify(lastPublished(), workerKeys, WORKER, now);
+      expect(fence.accept(command.body, now)).toBe("accepted");
+      expect(fence.accept(command.body, now)).toBe("replay");
+      // Durable: a restarted worker still refuses it.
+      expect(new DurableFence(join(fenceDir, "fence.json")).accept(command.body, now)).toBe("replay");
+    });
+
+    it("control plane records each commandId once (SETNX) with TTL = envelope lifetime", async () => {
+      const issued = await service.setDesired(WS, CH, RUNNING);
+      const record = redis.kv.get(K.issued(issued.commandId));
+      expect(record?.expiresAt).toBe(Date.parse(issued.expiresAt));
+      expect(JSON.parse(record?.value ?? "{}")).toMatchObject({ workerId: WORKER, desiredVersion: 1, kid: KID });
+      const body = (lastPublished() as SignedCommand).body;
+      await rejectsWith(service.recordIssued(body, KID), 409);
+      now = Date.parse(issued.expiresAt);
+      await expect(service.recordIssued(body, KID)).rejects.toThrow("already expired");
+    });
+
+    it("every issued command gets a distinct commandId", async () => {
+      const a = await service.setDesired(WS, CH, RUNNING);
+      const b = await service.republish(WS, CH);
+      expect(a.commandId).not.toBe(b.commandId);
+      expect(b.desiredVersion).toBe(a.desiredVersion);
+    });
+  });
+
+  describe("desiredVersion monotonicity", () => {
+    it("allocates strictly increasing versions and the worker fence accepts them in order", async () => {
+      const fence = new DurableFence(join(fenceDir, "fence.json"));
+      const versions: number[] = [];
+      for (const spec of [RUNNING, { ...RUNNING, desiredStatus: "STOPPED" as const }, RUNNING]) {
+        const issued = await service.setDesired(WS, CH, spec);
+        versions.push(issued.desiredVersion);
+        expect(fence.accept(workerVerify(lastPublished(), workerKeys, WORKER, now).body, now)).toBe("accepted");
+      }
+      expect(versions).toEqual([1, 2, 3]);
+    });
+
+    it("an older command delivered late is stale at the worker", async () => {
+      const fence = new DurableFence(join(fenceDir, "fence.json"));
+      await service.setDesired(WS, CH, RUNNING);
+      const older = workerVerify(lastPublished(), workerKeys, WORKER, now).body;
+      await service.setDesired(WS, CH, RUNNING);
+      const newer = workerVerify(lastPublished(), workerKeys, WORKER, now).body;
+      expect(fence.accept(newer, now)).toBe("accepted");
+      expect(fence.accept(older, now)).toBe("stale");
+    });
+
+    it("republish re-delivers the committed version under a fresh commandId the fence accepts", async () => {
+      const fence = new DurableFence(join(fenceDir, "fence.json"));
+      await service.setDesired(WS, CH, RUNNING);
+      expect(fence.accept(workerVerify(lastPublished(), workerKeys, WORKER, now).body, now)).toBe("accepted");
+      await service.republish(WS, CH);
+      expect(fence.accept(workerVerify(lastPublished(), workerKeys, WORKER, now).body, now)).toBe("accepted");
+    });
+
+    it("commit CAS refuses to overwrite a newer committed version", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      // Simulate a concurrent writer that committed version 5 after we allocated version 2.
+      redis.kv.set(K.desired(WS, CH), { value: JSON.stringify({ desiredVersion: 5 }), expiresAt: null });
+      const before = redis.published.length;
+      await rejectsWith(service.setDesired(WS, CH, RUNNING), 409);
+      expect(redis.published.length).toBe(before);
+    });
+
+    it("commit CAS refuses when the assignment changed underneath", async () => {
+      const incr = redis.incr.bind(redis);
+      // Reassign between the assignment read and the commit (version allocation sits in between).
+      redis.incr = async (key: string) => { await service.assign(WS, CH, "media-worker-b", 4); return incr(key); };
+      await rejectsWith(service.setDesired(WS, CH, RUNNING), 409);
+      expect(redis.published).toHaveLength(0);
+      redis.incr = incr;
+      const issued = await service.setDesired(WS, CH, RUNNING);
+      expect(issued).toMatchObject({ workerId: "media-worker-b", assignmentEpoch: 4 });
+      expect(redis.published.at(-1)?.channel).toBe(`cmd:${WS}:media-worker-b`);
+    });
+
+    it("assignment epochs only move forward and one epoch binds one worker", async () => {
+      await rejectsWith(service.assign(WS, CH, WORKER, 2), 409);
+      await rejectsWith(service.assign(WS, CH, "media-worker-b", 3), 409);
+      await expect(service.assign(WS, CH, WORKER, 3)).resolves.toBeUndefined();
+    });
+
+    it("republish refuses after reassignment", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      await service.assign(WS, CH, "media-worker-b", 4);
+      await rejectsWith(service.republish(WS, CH), 409);
+    });
+  });
+
+  describe("fail-closed preconditions", () => {
+    it("503 without a signing key, 409 for unassigned channels, 400 for bad handles", async () => {
+      const unsigned = new MediaControlService({ redis, signer: null, handles: new StubCredentialHandleProvider(), now: () => now, assignments: [] });
+      await rejectsWith(unsigned.setDesired(WS, CH, RUNNING), 503);
+      await rejectsWith(service.setDesired(WS, randomUUID(), RUNNING), 409);
+      await rejectsWith(service.setDesired(WS, CH, { ...RUNNING, output: { endpointUrl: "rtmps://live.example.net/app", credentialHandleId: "sk_live_abc" } }), 400);
+      expect(redis.published).toHaveLength(0);
+    });
+
+    it("bootstraps assignments from configuration", async () => {
+      const ch = randomUUID();
+      const boot = new MediaControlService({ redis, signer: new Ed25519ControlSigner(KID, pair.privateKey),
+        handles: new StubCredentialHandleProvider(), now: () => now, assignments: [{ workspaceId: WS, channelId: ch, workerId: WORKER, assignmentEpoch: 1 }] });
+      await expect(boot.setDesired(WS, ch, RUNNING)).resolves.toMatchObject({ assignmentEpoch: 1, desiredVersion: 1 });
+    });
+  });
+
+  describe("endpoint and body validation", () => {
+    const cases: Array<[string, "hls" | "output"]> = [
+      ["https://cdn.example.com/a.m3u8", "hls"], ["http://cdn.example.com/a.m3u8", "hls"],
+      ["rtmp://live.example.net/app", "output"], ["rtmps://live.example.net/app", "output"], ["srt://live.example.net", "output"],
+      ["rtmp://user:pw@live.example.net/app", "output"], ["rtmp://live.example.net/app?key=abc", "output"],
+      ["https://cdn.example.com/a.m3u8#frag", "hls"], ["https://10.1.2.3/a.m3u8", "hls"], ["https://127.0.0.1/a.m3u8", "hls"],
+      ["https://169.254.169.254/latest", "hls"], ["rtmp://192.168.1.10/app", "output"], ["rtmp://100.64.0.1/app", "output"],
+      ["https://[::1]/a.m3u8", "hls"], ["https://[fe80::1]/a.m3u8", "hls"], ["https://[fd00::1]/a.m3u8", "hls"],
+      ["https://[::ffff:8.8.8.8]/a.m3u8", "hls"], ["https://8.8.8.8/a.m3u8", "hls"], ["rtmp://[2606:4700::1]/app", "output"],
+      ["not a url", "hls"],
+    ];
+    it.each(cases)("agrees with the worker on %s (%s)", (url, use) => {
+      const ours = (() => { try { validateEndpointShape(url, use); return "ok"; } catch (e) { return String(e); } })();
+      const theirs = (() => { try { workerValidate(url, use); return "ok"; } catch (e) { return String(e); } })();
+      expect(ours).toBe(theirs);
+    });
+
+    it("is stricter than the worker for loopback hostnames", () => {
+      expect(() => validateEndpointShape("https://localhost/a.m3u8", "hls")).toThrow("private");
+      expect(() => validateEndpointShape("rtmp://relay.localhost/app", "output")).toThrow("private");
+    });
+
+    it("never accepts secrets in the body", () => {
+      for (const body of [
+        { ...RUNNING, streamKey: "live_123" },
+        { ...RUNNING, output: { ...RUNNING.output, streamKey: "live_123" } },
+        { ...RUNNING, output: { ...RUNNING.output, password: "pw" } },
+        { ...RUNNING, source: { ...RUNNING.source, token: "t" } },
+      ]) expect(() => parseDesiredSpec(body)).toThrow("secrets are never accepted");
+      expect(() => parseDesiredSpec({ ...RUNNING, output: { endpointUrl: "rtmp://live.example.net/app?key=abc", credentialHandleId: HANDLE } }))
+        .toThrow("credentials rejected");
+    });
+
+    it("rejects malformed bodies", () => {
+      expect(() => parseDesiredSpec({ ...RUNNING, workerId: "x" })).toThrow("not allowed");
+      expect(() => parseDesiredSpec({ ...RUNNING, desiredVersion: 99 })).toThrow("not allowed");
+      expect(() => parseDesiredSpec({ ...RUNNING, output: null })).toThrow("RUNNING requires");
+      expect(() => parseDesiredSpec({ ...RUNNING, profile: "4k" })).toThrow("profile");
+      expect(() => parseDesiredSpec({ ...RUNNING, source: { kind: "rtmp", url: "https://cdn.example.com/a" } })).toThrow("source.kind");
+      expect(() => parseDesiredSpec({ ...RUNNING, source: { kind: "hls", url: "https://10.0.0.1/a.m3u8" } })).toThrow("private");
+      expect(() => parseDesiredSpec([])).toThrow("object");
+    });
+
+    it("accepts STOPPED with no endpoints and applies defaults", () => {
+      expect(parseDesiredSpec({ desiredStatus: "STOPPED" })).toEqual({ desiredStatus: "STOPPED", source: null, output: null, profile: "720p30", mode: "passthrough" });
+    });
+  });
+
+  describe("status", () => {
+    function observe(overrides: Record<string, unknown>): void {
+      redis.kv.set(K.observed(WS, CH), { value: JSON.stringify({ workspaceId: WS, channelId: CH, workerId: WORKER, assignmentEpoch: 3,
+        state: "RUNNING", realizedVersion: 1, updatedAt: new Date(now).toISOString(), reason: "ok", ...overrides }), expiresAt: now + 60_000 });
+    }
+    function beat(sentAt: number): void {
+      redis.kv.set(K.heartbeat(WORKER), { value: JSON.stringify({ workerId: WORKER, sentAt: new Date(sentAt).toISOString(), channels: [] }), expiresAt: now + 15_000 });
+    }
+
+    it("reports desired vs observed, convergence, and worker liveness", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      observe({});
+      beat(now - 1_000);
+      const status = await service.getStatus(WS);
+      expect(status.workers).toEqual([{ workerId: WORKER, alive: true, lastHeartbeatAt: new Date(now - 1_000).toISOString() }]);
+      expect(status.channels).toEqual([expect.objectContaining({ channelId: CH, workerId: WORKER, assignmentEpoch: 3,
+        desired: { desiredVersion: 1, desiredStatus: "RUNNING" }, converged: true, workerAlive: true })]);
+    });
+
+    it("is not converged until the realized version catches up", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      await service.setDesired(WS, CH, RUNNING);
+      observe({ realizedVersion: 1 });
+      expect((await service.getStatus(WS)).channels[0]?.converged).toBe(false);
+    });
+
+    it("ignores observations from a previous placement and stale heartbeats", async () => {
+      await service.setDesired(WS, CH, RUNNING);
+      observe({ assignmentEpoch: 2 });
+      beat(now - HEARTBEAT_TTL_MS - 1);
+      const status = await service.getStatus(WS);
+      expect(status.channels[0]).toMatchObject({ observed: null, converged: false, workerAlive: false });
+      expect(status.workers[0]?.alive).toBe(false);
+    });
+
+    it("is scoped to the caller's workspace", async () => {
+      const other = randomUUID();
+      await service.assign(other, randomUUID(), "media-worker-z", 0);
+      const status = await service.getStatus(WS);
+      expect(status.channels.map((c) => c.channelId)).toEqual([CH]);
+      expect(status.workers.map((w) => w.workerId)).toEqual([WORKER]);
+    });
+  });
+});
diff --git a/apps/api/src/media-control/production.ts b/apps/api/src/media-control/production.ts
new file mode 100644
index 0000000..e8206e7
--- /dev/null
+++ b/apps/api/src/media-control/production.ts
@@ -0,0 +1,358 @@
+/**
+ * Desired-state v2: the production part of a channel snapshot
+ * (docs/design/streaming-architecture.md §2, §4, §6 S1).
+ *
+ * This file is mirrored byte-for-byte at apps/media-worker/src/production.ts
+ * (a test asserts it). It has no imports so both builds compile it as-is.
+ *
+ * Everything that can reach a filtergraph or argv is typed: ids are UUIDs,
+ * assets are sha256 content ids, geometry is integer basis points, gains are
+ * 3 dB steps, enums are closed. Labels are display text for operators and logs
+ * only; they are still held to a strict allowlist so a filtergraph payload
+ * (`;`, `[`, `,`, `'`, `movie=`) can never ride along in a snapshot.
+ */
+
+export type SceneLayout = "single" | "pip" | "2x1" | "2x2" | "3x3" | "4x4" | "custom";
+export type SlotFit = "contain" | "cover" | "crop";
+export type AudioMode = "off" | "on" | "primary";
+export type OverlayKind = "lower_third" | "chyron" | "logo" | "clock";
+export type ClockFormat = "HH:MM" | "HH:MM:SS";
+export type FadeMs = 300 | 500 | 1000 | 2000;
+
+export const SCENE_LAYOUTS: readonly SceneLayout[] = ["single", "pip", "2x1", "2x2", "3x3", "4x4", "custom"];
+export const SLOT_FITS: readonly SlotFit[] = ["contain", "cover", "crop"];
+export const AUDIO_MODES: readonly AudioMode[] = ["off", "on", "primary"];
+export const OVERLAY_KINDS: readonly OverlayKind[] = ["lower_third", "chyron", "logo", "clock"];
+export const CLOCK_FORMATS: readonly ClockFormat[] = ["HH:MM", "HH:MM:SS"];
+export const FADE_MS: readonly FadeMs[] = [300, 500, 1000, 2000];
+
+/** Slot capacity per layout. `custom` places up to 16 explicit rectangles. */
+export const LAYOUT_CAPACITY: Readonly<Record<SceneLayout, number>> = {
+  single: 1, pip: 2, "2x1": 2, "2x2": 4, "3x3": 9, "4x4": 16, custom: 16,
+};
+
+/** Geometry is integer basis points of the output frame (0..10000), resolution independent. */
+export const GEOMETRY_SCALE = 10_000;
+export const GAIN_DB_MIN = -24;
+export const GAIN_DB_MAX = 0;
+export const GAIN_DB_STEP = 3;
+export const CHYRON_SPEED_MIN = 40;
+export const CHYRON_SPEED_MAX = 400;
+export const CHYRON_STRIP_MAX_PX = 16_384;
+export const MAX_SOURCES = 32;
+export const MAX_SCENES = 32;
+export const MAX_OVERLAYS = 64;
+export const MAX_PLAYLIST_ITEMS = 500;
+export const MAX_OVERLAY_LAYER = 7;
+
+export interface Rect { x: number; y: number; w: number; h: number }
+export interface Point { x: number; y: number }
+
+export interface HlsProductionSource { id: string; label: string; kind: "hls"; url: string }
+/** Ordered, pre-normalized video asset ids (video_assets.id), fed by the worker's asset feeder. */
+export interface PlaylistProductionSource { id: string; label: string; kind: "playlist"; assetIds: string[]; loop: boolean }
+export type ProductionSource = HlsProductionSource | PlaylistProductionSource;
+
+export interface SceneSlot {
+  index: number;
+  /** null = empty slot (renders the fallback). */
+  sourceId: string | null;
+  /** Required for `custom` and `pip` layouts; null means the layout's own grid cell. */
+  rect: Rect | null;
+  fit: SlotFit;
+  audioMode: AudioMode;
+  gainDb: number;
+}
+
+export interface ProductionScene { id: string; label: string; layout: SceneLayout; slots: SceneSlot[] }
+
+export interface ProductionBuses { preview: string | null; program: string | null }
+
+export interface ProductionOverlay {
+  /** overlay_slots.id */
+  id: string;
+  sceneId: string;
+  kind: OverlayKind;
+  enabled: boolean;
+  layer: number;
+  position: Point;
+  /** overlay_revisions.id; null only for the server-generated clock. */
+  revisionId: string | null;
+  /** sha256 content id of the rendered PNG; null only for the clock. */
+  assetId: string | null;
+  chyron: { speedPxPerSec: number; stripWidthPx: number } | null;
+  clock: { format: ClockFormat } | null;
+}
+
+export type Transition = { type: "cut" } | { type: "fade"; ms: FadeMs };
+
+export interface ProgramAudio { masterGainDb: number }
+
+export interface ProductionSpec {
+  scenes: ProductionScene[];
+  buses: ProductionBuses;
+  sources: ProductionSource[];
+  overlays: ProductionOverlay[];
+  transition: Transition;
+  audio: ProgramAudio;
+}
+
+export class ProductionSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProductionSpecError";
+  }
+}
+
+const SECRETISH = /key|secret|token|password|passwd|credential(?!HandleId)|auth/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+/** Letters, digits, space and `_ . -` only: no filtergraph or shell metacharacters, no `=`. */
+const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} _.-]{0,63}$/u;
+
+function fail(message: string): never { throw new ProductionSpecError(message); }
+
+function record(value: unknown, field: string, allowed: readonly string[]): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${field} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (allowed.includes(key)) continue;
+    if (SECRETISH.test(key)) fail(`${field}.${key}: secrets are never accepted; reference a vault credentialHandleId`);
+    fail(`${field}.${key} is not allowed`);
+  }
+  for (const key of allowed) if (!(key in value)) fail(`${field}.${key} is required`);
+  return value as Record<string, unknown>;
+}
+
+function list(value: unknown, field: string, max: number): unknown[] {
+  if (!Array.isArray(value)) fail(`${field} must be an array`);
+  if (value.length > max) fail(`${field} allows at most ${max} entries`);
+  return value;
+}
+
+function uuid(value: unknown, field: string): string {
+  if (typeof value !== "string" || !UUID.test(value)) fail(`${field} must be a lowercase UUID`);
+  return value;
+}
+
+function nullableUuid(value: unknown, field: string): string | null {
+  return value === null ? null : uuid(value, field);
+}
+
+function label(value: unknown, field: string): string {
+  if (typeof value !== "string" || !LABEL.test(value)) {
+    fail(`${field} must be 1-64 letters, digits, spaces, '_', '.', '-'`);
+  }
+  return value;
+}
+
+function int(value: unknown, field: string, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+    fail(`${field} must be an integer in ${min}..${max}`);
+  }
+  return value;
+}
+
+function bool(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") fail(`${field} must be a boolean`);
+  return value;
+}
+
+function oneOf<T extends string | number>(value: unknown, field: string, options: readonly T[]): T {
+  const found = options.find((option) => option === value);
+  if (found === undefined) fail(`${field} must be one of ${options.join(", ")}`);
+  return found;
+}
+
+export function gainDb(value: unknown, field: string): number {
+  const gain = int(value, field, GAIN_DB_MIN, GAIN_DB_MAX);
+  if (gain % GAIN_DB_STEP !== 0) fail(`${field} must be a multiple of ${GAIN_DB_STEP} dB`);
+  return gain === 0 ? 0 : gain;
+}
+
+function rect(value: unknown, field: string): Rect {
+  const r = record(value, field, ["x", "y", "w", "h"]);
+  const x = int(r.x, `${field}.x`, 0, GEOMETRY_SCALE - 1);
+  const y = int(r.y, `${field}.y`, 0, GEOMETRY_SCALE - 1);
+  const w = int(r.w, `${field}.w`, 1, GEOMETRY_SCALE);
+  const h = int(r.h, `${field}.h`, 1, GEOMETRY_SCALE);
+  if (x + w > GEOMETRY_SCALE || y + h > GEOMETRY_SCALE) fail(`${field} must lie inside the frame`);
+  return { x, y, w, h };
+}
+
+function point(value: unknown, field: string): Point {
+  const p = record(value, field, ["x", "y"]);
+  return { x: int(p.x, `${field}.x`, 0, GEOMETRY_SCALE), y: int(p.y, `${field}.y`, 0, GEOMETRY_SCALE) };
+}
+
+function unique(ids: string[], field: string): void {
+  if (new Set(ids).size !== ids.length) fail(`${field} ids must be unique`);
+}
+
+/**
+ * HLS URLs are shape-checked by the caller with its own endpoint validator
+ * (API and worker differ on loopback strictness); here only bounds are checked.
+ */
+function source(value: unknown, field: string): ProductionSource {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${field} must be an object`);
+  const kind = (value as Record<string, unknown>).kind;
+  if (kind === "hls") {
+    const s = record(value, field, ["id", "label", "kind", "url"]);
+    if (typeof s.url !== "string" || s.url.trim() === "" || s.url.length > 2048) fail(`${field}.url must be a non-empty string`);
+    return { id: uuid(s.id, `${field}.id`), label: label(s.label, `${field}.label`), kind: "hls", url: s.url };
+  }
+  if (kind === "playlist") {
+    const s = record(value, field, ["id", "label", "kind", "assetIds", "loop"]);
+    const assetIds = list(s.assetIds, `${field}.assetIds`, MAX_PLAYLIST_ITEMS).map((item, i) => uuid(item, `${field}.assetIds[${i}]`));
+    if (assetIds.length === 0) fail(`${field}.assetIds must not be empty`);
+    return { id: uuid(s.id, `${field}.id`), label: label(s.label, `${field}.label`), kind: "playlist", assetIds, loop: bool(s.loop, `${field}.loop`) };
+  }
+  return fail(`${field}.kind must be hls or playlist`);
+}
+
+function slot(value: unknown, field: string, layout: SceneLayout, sources: ReadonlySet<string>): SceneSlot {
+  const s = record(value, field, ["index", "sourceId", "rect", "fit", "audioMode", "gainDb"]);
+  const index = int(s.index, `${field}.index`, 0, LAYOUT_CAPACITY[layout] - 1);
+  const sourceId = nullableUuid(s.sourceId, `${field}.sourceId`);
+  if (sourceId !== null && !sources.has(sourceId)) fail(`${field}.sourceId must name a source of this channel`);
+  const needsRect = layout === "custom" || (layout === "pip" && index > 0);
+  const slotRect = s.rect === null ? null : rect(s.rect, `${field}.rect`);
+  if (needsRect && slotRect === null) fail(`${field}.rect is required for the ${layout} layout`);
+  if (!needsRect && slotRect !== null) fail(`${field}.rect is only allowed for custom layouts and PIP insets`);
+  return {
+    index, sourceId, rect: slotRect,
+    fit: oneOf(s.fit, `${field}.fit`, SLOT_FITS),
+    audioMode: oneOf(s.audioMode, `${field}.audioMode`, AUDIO_MODES),
+    gainDb: gainDb(s.gainDb, `${field}.gainDb`),
+  };
+}
+
+function scene(value: unknown, field: string, sources: ReadonlySet<string>): ProductionScene {
+  const s = record(value, field, ["id", "label", "layout", "slots"]);
+  const layout = oneOf(s.layout, `${field}.layout`, SCENE_LAYOUTS);
+  const slots = list(s.slots, `${field}.slots`, LAYOUT_CAPACITY[layout]).map((item, i) => slot(item, `${field}.slots[${i}]`, layout, sources));
+  if (new Set(slots.map((x) => x.index)).size !== slots.length) fail(`${field}.slots indexes must be unique`);
+  if (slots.filter((x) => x.audioMode === "primary").length > 1) fail(`${field}.slots: at most one primary audio slot per scene`);
+  return { id: uuid(s.id, `${field}.id`), label: label(s.label, `${field}.label`), layout, slots };
+}
+
+function overlay(value: unknown, field: string, scenes: ReadonlySet<string>): ProductionOverlay {
+  const o = record(value, field, ["id", "sceneId", "kind", "enabled", "layer", "position", "revisionId", "assetId", "chyron", "clock"]);
+  const sceneId = uuid(o.sceneId, `${field}.sceneId`);
+  if (!scenes.has(sceneId)) fail(`${field}.sceneId must name a scene of this channel`);
+  const kind = oneOf(o.kind, `${field}.kind`, OVERLAY_KINDS);
+  const rendered = kind !== "clock";
+  let revisionId: string | null = null;
+  let assetId: string | null = null;
+  if (rendered) {
+    revisionId = uuid(o.revisionId, `${field}.revisionId`);
+    if (typeof o.assetId !== "string" || !SHA256.test(o.assetId)) fail(`${field}.assetId must be a sha256 content id`);
+    assetId = o.assetId;
+  } else if (o.revisionId !== null || o.assetId !== null) fail(`${field}: a clock overlay has no rendered asset`);
+
+  let chyron: ProductionOverlay["chyron"] = null;
+  if (kind === "chyron") {
+    const c = record(o.chyron, `${field}.chyron`, ["speedPxPerSec", "stripWidthPx"]);
+    chyron = {
+      speedPxPerSec: int(c.speedPxPerSec, `${field}.chyron.speedPxPerSec`, CHYRON_SPEED_MIN, CHYRON_SPEED_MAX),
+      stripWidthPx: int(c.stripWidthPx, `${field}.chyron.stripWidthPx`, 1, CHYRON_STRIP_MAX_PX),
+    };
+  } else if (o.chyron !== null) fail(`${field}.chyron is only allowed for chyron overlays`);
+
+  let clock: ProductionOverlay["clock"] = null;
+  if (kind === "clock") {
+    const c = record(o.clock, `${field}.clock`, ["format"]);
+    clock = { format: oneOf(c.format, `${field}.clock.format`, CLOCK_FORMATS) };
+  } else if (o.clock !== null) fail(`${field}.clock is only allowed for clock overlays`);
+
+  return {
+    id: uuid(o.id, `${field}.id`), sceneId, kind,
+    enabled: bool(o.enabled, `${field}.enabled`),
+    layer: int(o.layer, `${field}.layer`, 0, MAX_OVERLAY_LAYER),
+    position: point(o.position, `${field}.position`),
+    revisionId, assetId, chyron, clock,
+  };
+}
+
+function transition(value: unknown, field: string): Transition {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${field} must be an object`);
+  const type = (value as Record<string, unknown>).type;
+  if (type === "cut") {
+    record(value, field, ["type"]);
+    return { type: "cut" };
+  }
+  if (type === "fade") {
+    const t = record(value, field, ["type", "ms"]);
+    return { type: "fade", ms: oneOf(t.ms, `${field}.ms`, FADE_MS) };
+  }
+  return fail(`${field}.type must be cut or fade`);
+}
+
+/** Parse and normalize; throws ProductionSpecError with a field path on the first problem. */
+export function parseProductionSpec(value: unknown, field = "production"): ProductionSpec {
+  const p = record(value, field, ["scenes", "buses", "sources", "overlays", "transition", "audio"]);
+  const sources = list(p.sources, `${field}.sources`, MAX_SOURCES).map((item, i) => source(item, `${field}.sources[${i}]`));
+  unique(sources.map((s) => s.id), `${field}.sources`);
+  const sourceIds = new Set(sources.map((s) => s.id));
+  const scenes = list(p.scenes, `${field}.scenes`, MAX_SCENES).map((item, i) => scene(item, `${field}.scenes[${i}]`, sourceIds));
+  unique(scenes.map((s) => s.id), `${field}.scenes`);
+  const sceneIds = new Set(scenes.map((s) => s.id));
+  const overlays = list(p.overlays, `${field}.overlays`, MAX_OVERLAYS).map((item, i) => overlay(item, `${field}.overlays[${i}]`, sceneIds));
+  unique(overlays.map((o) => o.id), `${field}.overlays`);
+
+  const b = record(p.buses, `${field}.buses`, ["preview", "program"]);
+  const buses: ProductionBuses = {
+    preview: nullableUuid(b.preview, `${field}.buses.preview`),
+    program: nullableUuid(b.program, `${field}.buses.program`),
+  };
+  for (const bus of ["preview", "program"] as const) {
+    const id = buses[bus];
+    if (id !== null && !sceneIds.has(id)) fail(`${field}.buses.${bus} must name a scene of this channel`);
+  }
+  const a = record(p.audio, `${field}.audio`, ["masterGainDb"]);
+  return {
+    scenes, buses, sources, overlays,
+    transition: transition(p.transition, `${field}.transition`),
+    audio: { masterGainDb: gainDb(a.masterGainDb, `${field}.audio.masterGainDb`) },
+  };
+}
+
+export function isProductionSpec(value: unknown): value is ProductionSpec {
+  try {
+    parseProductionSpec(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every remote URL a production snapshot can make the worker fetch. */
+export function productionHlsUrls(spec: ProductionSpec): string[] {
+  return spec.sources.flatMap((s) => (s.kind === "hls" ? [s.url] : []));
+}
+
+/** Declared key order for signing: insertion order of the input can never drift the signed bytes. */
+export function canonicalProduction(spec: ProductionSpec): ProductionSpec {
+  return {
+    scenes: spec.scenes.map((s) => ({
+      id: s.id, label: s.label, layout: s.layout,
+      slots: s.slots.map((x) => ({
+        index: x.index, sourceId: x.sourceId,
+        rect: x.rect === null ? null : { x: x.rect.x, y: x.rect.y, w: x.rect.w, h: x.rect.h },
+        fit: x.fit, audioMode: x.audioMode, gainDb: x.gainDb,
+      })),
+    })),
+    buses: { preview: spec.buses.preview, program: spec.buses.program },
+    sources: spec.sources.map((s): ProductionSource => (s.kind === "hls"
+      ? { id: s.id, label: s.label, kind: "hls", url: s.url }
+      : { id: s.id, label: s.label, kind: "playlist", assetIds: [...s.assetIds], loop: s.loop })),
+    overlays: spec.overlays.map((o) => ({
+      id: o.id, sceneId: o.sceneId, kind: o.kind, enabled: o.enabled, layer: o.layer,
+      position: { x: o.position.x, y: o.position.y },
+      revisionId: o.revisionId, assetId: o.assetId,
+      chyron: o.chyron === null ? null : { speedPxPerSec: o.chyron.speedPxPerSec, stripWidthPx: o.chyron.stripWidthPx },
+      clock: o.clock === null ? null : { format: o.clock.format },
+    })),
+    transition: spec.transition.type === "cut" ? { type: "cut" } : { type: "fade", ms: spec.transition.ms },
+    audio: { masterGainDb: spec.audio.masterGainDb },
+  };
+}
diff --git a/apps/api/src/media-control/redis.ts b/apps/api/src/media-control/redis.ts
new file mode 100644
index 0000000..76ad959
--- /dev/null
+++ b/apps/api/src/media-control/redis.ts
@@ -0,0 +1,177 @@
+import net, { type Socket } from "node:net";
+import tls from "node:tls";
+
+/** Minimal Redis surface the control plane needs; faked in unit tests. */
+export interface ControlRedis {
+  get(key: string): Promise<string | null>;
+  mget(keys: string[]): Promise<Array<string | null>>;
+  /** SET key value PX ttl [NX]; resolves false when NX lost. */
+  set(key: string, value: string, options?: { nx?: boolean; pxMs?: number }): Promise<boolean>;
+  incr(key: string): Promise<number>;
+  sadd(key: string, member: string): Promise<void>;
+  smembers(key: string): Promise<string[]>;
+  publish(channel: string, message: string): Promise<number>;
+  eval(script: string, keys: string[], args: string[]): Promise<RedisReply>;
+  close(): void;
+}
+
+export type RedisReply = string | number | null | RedisReply[] | RedisError;
+export class RedisError extends Error {}
+
+const MAX_BULK = 4_000_000;
+const MAX_ARRAY = 100_000;
+
+export function encode(parts: string[]): Buffer {
+  return Buffer.from(`*${parts.length}\r\n${parts.map((part) => `$${Buffer.byteLength(part)}\r\n${part}\r\n`).join("")}`);
+}
+
+export function parse(buffer: Buffer, offset = 0): { reply: RedisReply; end: number } | null {
+  if (offset >= buffer.length) return null;
+  const endLine = buffer.indexOf("\r\n", offset);
+  if (endLine < 0) return null;
+  const type = String.fromCharCode(buffer[offset] ?? 0);
+  const line = buffer.subarray(offset + 1, endLine).toString();
+  let pos = endLine + 2;
+  if (type === "+") return { reply: line, end: pos };
+  if (type === "-") return { reply: new RedisError(line), end: pos };
+  if (type === ":") return { reply: Number(line), end: pos };
+  const length = Number(line);
+  if (type === "$") {
+    if (length === -1) return { reply: null, end: pos };
+    if (!Number.isInteger(length) || length < 0 || length > MAX_BULK) throw new Error("invalid Redis bulk length");
+    if (buffer.length < pos + length + 2) return null;
+    return { reply: buffer.subarray(pos, pos + length).toString(), end: pos + length + 2 };
+  }
+  if (type === "*") {
+    if (length === -1) return { reply: null, end: pos };
+    if (!Number.isInteger(length) || length < 0 || length > MAX_ARRAY) throw new Error("invalid Redis array length");
+    const replies: RedisReply[] = [];
+    for (let i = 0; i < length; i += 1) {
+      const item = parse(buffer, pos);
+      if (!item) return null;
+      replies.push(item.reply);
+      pos = item.end;
+    }
+    return { reply: replies, end: pos };
+  }
+  throw new Error("invalid Redis reply");
+}
+
+class RedisConnection {
+  private buffer = Buffer.alloc(0);
+  private readonly pending: Array<{ resolve: (reply: RedisReply) => void; reject: (error: Error) => void }> = [];
+  closed = false;
+
+  private constructor(private readonly socket: Socket) {
+    socket.on("data", (chunk: Buffer) => {
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+      if (this.buffer.length > MAX_BULK * 2) { socket.destroy(new Error("Redis reply too large")); return; }
+      try {
+        for (let parsed = parse(this.buffer); parsed; parsed = parse(this.buffer)) {
+          this.buffer = this.buffer.subarray(parsed.end);
+          const waiter = this.pending.shift();
+          if (parsed.reply instanceof RedisError) waiter?.reject(parsed.reply);
+          else waiter?.resolve(parsed.reply);
+        }
+      } catch (error: unknown) {
+        socket.destroy(error instanceof Error ? error : new Error("Redis protocol error"));
+      }
+    });
+    const fail = (error: Error): void => {
+      this.closed = true;
+      for (const item of this.pending.splice(0)) item.reject(error);
+    };
+    socket.on("error", fail);
+    socket.on("close", () => fail(new Error("Redis disconnected")));
+  }
+
+  static async connect(url: URL): Promise<RedisConnection> {
+    const port = Number(url.port || 6379);
+    const socket = url.protocol === "rediss:"
+      ? tls.connect({ host: url.hostname, port, servername: url.hostname, rejectUnauthorized: true })
+      : net.connect({ host: url.hostname, port });
+    await new Promise<void>((resolve, reject) => {
+      socket.once(url.protocol === "rediss:" ? "secureConnect" : "connect", () => resolve());
+      socket.once("error", reject);
+    });
+    const connection = new RedisConnection(socket);
+    if (url.password) await connection.send(["AUTH", decodeURIComponent(url.username || "default"), decodeURIComponent(url.password)]);
+    const db = url.pathname.replace(/^\//, "");
+    if (db !== "") await connection.send(["SELECT", db]);
+    return connection;
+  }
+
+  send(parts: string[]): Promise<RedisReply> {
+    if (this.closed) return Promise.reject(new Error("Redis disconnected"));
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve, reject });
+      this.socket.write(encode(parts));
+    });
+  }
+
+  close(): void { this.closed = true; this.socket.destroy(); }
+}
+
+function asString(reply: RedisReply): string | null {
+  return typeof reply === "string" ? reply : null;
+}
+
+/** Lazily (re)connecting client: a dropped socket is replaced on the next call. */
+export class RespControlRedis implements ControlRedis {
+  private connection: Promise<RedisConnection> | null = null;
+  private readonly url: URL;
+
+  constructor(rawUrl: string) {
+    this.url = new URL(rawUrl);
+    if (this.url.protocol !== "redis:" && this.url.protocol !== "rediss:") throw new Error("invalid Redis URL");
+  }
+
+  private async send(parts: string[]): Promise<RedisReply> {
+    let current = this.connection;
+    if (current) {
+      const conn = await current.catch(() => null);
+      if (!conn || conn.closed) current = null;
+    }
+    if (!current) {
+      current = RedisConnection.connect(this.url);
+      this.connection = current;
+      current.catch(() => { if (this.connection === current) this.connection = null; });
+    }
+    return (await current).send(parts);
+  }
+
+  async get(key: string): Promise<string | null> { return asString(await this.send(["GET", key])); }
+  async mget(keys: string[]): Promise<Array<string | null>> {
+    if (keys.length === 0) return [];
+    const reply = await this.send(["MGET", ...keys]);
+    return Array.isArray(reply) ? reply.map(asString) : keys.map(() => null);
+  }
+  async set(key: string, value: string, options: { nx?: boolean; pxMs?: number } = {}): Promise<boolean> {
+    const parts = ["SET", key, value];
+    if (options.pxMs !== undefined) parts.push("PX", String(Math.max(1, Math.ceil(options.pxMs))));
+    if (options.nx) parts.push("NX");
+    return (await this.send(parts)) === "OK";
+  }
+  async incr(key: string): Promise<number> {
+    const reply = await this.send(["INCR", key]);
+    if (typeof reply !== "number") throw new Error("unexpected INCR reply");
+    return reply;
+  }
+  async sadd(key: string, member: string): Promise<void> { await this.send(["SADD", key, member]); }
+  async smembers(key: string): Promise<string[]> {
+    const reply = await this.send(["SMEMBERS", key]);
+    return Array.isArray(reply) ? reply.filter((item): item is string => typeof item === "string") : [];
+  }
+  async publish(channel: string, message: string): Promise<number> {
+    const reply = await this.send(["PUBLISH", channel, message]);
+    return typeof reply === "number" ? reply : 0;
+  }
+  async eval(script: string, keys: string[], args: string[]): Promise<RedisReply> {
+    return this.send(["EVAL", script, String(keys.length), ...keys, ...args]);
+  }
+  close(): void {
+    const current = this.connection;
+    this.connection = null;
+    void current?.then((conn) => conn.close(), () => undefined);
+  }
+}
diff --git a/apps/api/src/media-control/spec.ts b/apps/api/src/media-control/spec.ts
new file mode 100644
index 0000000..a3e14b2
--- /dev/null
+++ b/apps/api/src/media-control/spec.ts
@@ -0,0 +1,88 @@
+import { BadRequestException } from "@nestjs/common";
+import { validateEndpointShape } from "./endpoints.js";
+import { parseProductionSpec, ProductionSpecError, type ProductionSpec } from "./production.js";
+import { hasRunnableProgram, OUTPUT_MODES, OUTPUT_PRESETS, type DesiredState, type OutputMode, type OutputPreset } from "./wire.js";
+
+/** Operator-controlled part of a desired snapshot; identity/assignment/version are control-plane owned. */
+export interface DesiredSpec {
+  desiredStatus: DesiredState;
+  source: { kind: "hls"; url: string } | null;
+  output: { endpointUrl: string; credentialHandleId: string } | null;
+  profile: OutputPreset;
+  mode: OutputMode;
+  /** v2 production; omitted for v1 specs so they round-trip unchanged. Excludes `source`. */
+  production?: ProductionSpec;
+}
+
+const SPEC_KEYS = ["desiredStatus", "source", "output", "profile", "mode", "production"];
+const SECRETISH = /key|secret|token|password|passwd|credential(?!HandleId)|auth/i;
+
+function object(value: unknown, field: string, allowed: string[]): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) throw new BadRequestException(`${field} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (allowed.includes(key)) continue;
+    if (SECRETISH.test(key)) throw new BadRequestException(`${field}.${key}: secrets are never accepted; reference a vault credentialHandleId`);
+    throw new BadRequestException(`${field}.${key} is not allowed`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function nonEmpty(value: unknown, field: string, max = 2048): string {
+  if (typeof value !== "string" || value.trim() === "" || value.length > max) throw new BadRequestException(`${field} must be a non-empty string`);
+  return value;
+}
+
+function endpoint(raw: string, use: "hls" | "output", field: string): string {
+  try { validateEndpointShape(raw, use); } catch (error: unknown) {
+    throw new BadRequestException(`${field}: ${error instanceof Error ? error.message : "invalid endpoint"}`);
+  }
+  return raw;
+}
+
+function isPreset(value: unknown): value is OutputPreset { return OUTPUT_PRESETS.some((preset) => preset === value); }
+function isMode(value: unknown): value is OutputMode { return OUTPUT_MODES.some((mode) => mode === value); }
+
+export function parseDesiredSpec(value: unknown): DesiredSpec {
+  const body = object(value, "body", SPEC_KEYS);
+  const desiredStatus = body.desiredStatus;
+  if (desiredStatus !== "RUNNING" && desiredStatus !== "STOPPED") throw new BadRequestException("desiredStatus must be RUNNING or STOPPED");
+  const profile = body.profile ?? "720p30";
+  if (!isPreset(profile)) throw new BadRequestException(`profile must be one of ${OUTPUT_PRESETS.join(", ")}`);
+  const mode = body.mode ?? "passthrough";
+  if (!isMode(mode)) throw new BadRequestException(`mode must be one of ${OUTPUT_MODES.join(", ")}`);
+
+  let source: DesiredSpec["source"] = null;
+  if (body.source !== undefined && body.source !== null) {
+    const s = object(body.source, "source", ["kind", "url"]);
+    if (s.kind !== "hls") throw new BadRequestException("source.kind must be hls");
+    source = { kind: "hls", url: endpoint(nonEmpty(s.url, "source.url"), "hls", "source.url") };
+  }
+  let output: DesiredSpec["output"] = null;
+  if (body.output !== undefined && body.output !== null) {
+    const o = object(body.output, "output", ["endpointUrl", "credentialHandleId"]);
+    output = {
+      endpointUrl: endpoint(nonEmpty(o.endpointUrl, "output.endpointUrl"), "output", "output.endpointUrl"),
+      credentialHandleId: nonEmpty(o.credentialHandleId, "output.credentialHandleId", 160),
+    };
+  }
+  if (body.production === undefined || body.production === null) {
+    if (desiredStatus === "RUNNING" && !hasRunnableProgram({ source, output })) {
+      throw new BadRequestException("RUNNING requires both source and output");
+    }
+    return { desiredStatus, source, output, profile, mode };
+  }
+
+  if (source !== null) throw new BadRequestException("source must be null with production; list sources in production.sources");
+  let production: ProductionSpec;
+  try { production = parseProductionSpec(body.production); } catch (error: unknown) {
+    if (error instanceof ProductionSpecError) throw new BadRequestException(error.message);
+    throw error;
+  }
+  production.sources.forEach((s, i) => {
+    if (s.kind === "hls") endpoint(s.url, "hls", `production.sources[${i}].url`);
+  });
+  if (desiredStatus === "RUNNING" && !hasRunnableProgram({ source, output, production })) {
+    throw new BadRequestException("RUNNING requires output and a program scene (production.buses.program)");
+  }
+  return { desiredStatus, source, output, profile, mode, production };
+}
diff --git a/apps/api/src/media-control/wire.ts b/apps/api/src/media-control/wire.ts
new file mode 100644
index 0000000..577be15
--- /dev/null
+++ b/apps/api/src/media-control/wire.ts
@@ -0,0 +1,125 @@
+import { sign, type KeyObject } from "node:crypto";
+import { validateEndpointShape } from "./endpoints.js";
+import { canonicalProduction, parseProductionSpec, productionHlsUrls, type ProductionSpec } from "./production.js";
+
+/**
+ * Local mirror of the media worker's control contract
+ * (apps/media-worker/src/types.ts + bus/envelope.ts + bus/control-signer.ts).
+ * Kept in this module so the API build never compiles worker sources; the
+ * interop tests sign here and verify with the worker's own verifier.
+ */
+export type DesiredState = "STOPPED" | "RUNNING";
+export type OutputPreset = "720p30" | "1080p30" | "1080p60";
+export type OutputMode = "passthrough" | "normalize";
+export type ChannelState = "STOPPED" | "STARTING" | "RUNNING" | "DEGRADED" | "RESTARTING" | "FAILED";
+
+export const OUTPUT_PRESETS: readonly OutputPreset[] = ["720p30", "1080p30", "1080p60"];
+export const OUTPUT_MODES: readonly OutputMode[] = ["passthrough", "normalize"];
+
+/** A complete, secret-free channel snapshot. The control plane owns this record. */
+export interface DesiredChannel {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  desiredVersion: number;
+  desiredStatus: DesiredState;
+  source: { kind: "hls"; url: string } | null;
+  output: { endpointUrl: string; credentialHandleId: string } | null;
+  profile: OutputPreset;
+  mode: OutputMode;
+  /**
+   * Desired-state v2 (production: scenes, buses, sources, overlays,
+   * transition, audio). Absent on v1 snapshots, which keep their exact
+   * signed bytes; when present, `source` is null.
+   */
+  production?: ProductionSpec;
+}
+
+export interface ObservedChannel {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  state: ChannelState;
+  realizedVersion: number | null;
+  updatedAt: string;
+  reason: string;
+}
+
+export interface CommandBody {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  commandId: string;
+  desiredVersion: number;
+  issuedAt: string;
+  expiresAt: string;
+  snapshot: DesiredChannel;
+}
+export interface SignedCommand { kid: string; body: CommandBody; signature: string }
+
+/** Fixed field order is the wire-format contract for both signing and verifying. */
+export function commandBytes(body: CommandBody): Buffer {
+  return Buffer.from(JSON.stringify({
+    workspaceId: body.workspaceId, channelId: body.channelId, workerId: body.workerId,
+    assignmentEpoch: body.assignmentEpoch, commandId: body.commandId,
+    desiredVersion: body.desiredVersion, issuedAt: body.issuedAt,
+    expiresAt: body.expiresAt, snapshot: canonicalSnapshot(body.snapshot),
+  }));
+}
+
+/** Snapshot keys in the worker's declared order, so key insertion order can't drift the bytes. */
+export function canonicalSnapshot(s: DesiredChannel): DesiredChannel {
+  const canonical: DesiredChannel = {
+    workspaceId: s.workspaceId, channelId: s.channelId, workerId: s.workerId,
+    assignmentEpoch: s.assignmentEpoch, desiredVersion: s.desiredVersion, desiredStatus: s.desiredStatus,
+    source: s.source === null ? null : { kind: s.source.kind, url: s.source.url },
+    output: s.output === null ? null : { endpointUrl: s.output.endpointUrl, credentialHandleId: s.output.credentialHandleId },
+    profile: s.profile, mode: s.mode,
+  };
+  // v1 snapshots carry no production key at all, so their signed bytes are unchanged.
+  if (s.production !== undefined) canonical.production = canonicalProduction(s.production);
+  return canonical;
+}
+
+/** Every remote HLS URL a snapshot can make the worker fetch (v1 source or v2 production sources). */
+export function snapshotHlsUrls(s: DesiredChannel): string[] {
+  return [...(s.source === null ? [] : [s.source.url]), ...(s.production === undefined ? [] : productionHlsUrls(s.production))];
+}
+
+/** RUNNING needs an output plus something to put on program: the v1 source, or a v2 program scene. */
+export function hasRunnableProgram(s: Pick<DesiredChannel, "source" | "output" | "production">): boolean {
+  if (s.output === null) return false;
+  return s.production === undefined ? s.source !== null : s.production.buses.program !== null;
+}
+
+/** Caller must commit desired state and re-authorize before signing. */
+export interface ControlCommandSigner {
+  signCommittedSnapshot(body: CommandBody): Promise<SignedCommand>;
+}
+
+export class Ed25519ControlSigner implements ControlCommandSigner {
+  constructor(private readonly kid: string, private readonly privateKey: KeyObject) {
+    if (privateKey.type !== "private" || privateKey.asymmetricKeyType !== "ed25519") throw new Error("control signer requires an Ed25519 private key");
+  }
+  async signCommittedSnapshot(body: CommandBody): Promise<SignedCommand> {
+    assertBodyMatchesSnapshot(body);
+    for (const url of snapshotHlsUrls(body.snapshot)) validateEndpointShape(url, "hls");
+    if (body.snapshot.output) validateEndpointShape(body.snapshot.output.endpointUrl, "output");
+    const canonical: CommandBody = { ...body, snapshot: canonicalSnapshot(body.snapshot) };
+    return { kid: this.kid, body: canonical, signature: sign(null, commandBytes(canonical), this.privateKey).toString("base64") };
+  }
+}
+
+function assertBodyMatchesSnapshot(body: CommandBody): void {
+  const s = body.snapshot;
+  if (s.workspaceId !== body.workspaceId || s.channelId !== body.channelId || s.workerId !== body.workerId ||
+      s.assignmentEpoch !== body.assignmentEpoch || s.desiredVersion !== body.desiredVersion) throw new Error("snapshot mismatch");
+  if (s.production !== undefined) {
+    if (s.source !== null) throw new Error("production snapshots carry sources in production.sources");
+    parseProductionSpec(s.production);
+  }
+  if (s.desiredStatus === "RUNNING" && !hasRunnableProgram(s)) throw new Error("running snapshot requires a program source and output");
+}
diff --git a/apps/api/src/production/journal.ts b/apps/api/src/production/journal.ts
new file mode 100644
index 0000000..021062d
--- /dev/null
+++ b/apps/api/src/production/journal.ts
@@ -0,0 +1,46 @@
+import type { PoolClient } from "pg";
+import { BadRequestException, ConflictException } from "@nestjs/common";
+import { createHash } from "node:crypto";
+import type { DesiredChannel } from "../media-control/wire.js";
+import type { DesiredSpec } from "../media-control/spec.js";
+
+export type OverrideMode = "until_released" | "five_minutes" | "until_source_offline" | "until_next_event";
+export type DirectorOperation =
+  | { type: "desired"; spec: DesiredSpec }
+  | { type: "take" | "cut" }
+  | { type: "pst-select"; sceneId: string }
+  | { type: "lock"; enabled: boolean }
+  | { type: "override"; mode: OverrideMode | null }
+  | { type: "overlay"; slotId: string; revisionId: string };
+export interface DirectorState { locked: boolean; override: { mode: OverrideMode; expiresAt: string | null } | null }
+export interface DirectorReceipt {
+  operation: DirectorOperation;
+  requestId: string;
+  fingerprint: string;
+  snapshot: DesiredChannel;
+  state: DirectorState;
+}
+export interface DirectorActor { userId: string | null; role: string }
+export type TenantTransaction = <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+
+export function requestIdentity(workspaceId: string, channelId: string, idempotencyKey: string): string {
+  if (!/^[\x21-\x7e]{1,128}$/.test(idempotencyKey)) throw new BadRequestException("Idempotency-Key must contain 1–128 printable characters");
+  return createHash("sha256").update(JSON.stringify([workspaceId, channelId, idempotencyKey])).digest("hex");
+}
+export function fingerprint(operation: DirectorOperation): string {
+  // Rebuild a closed shape: field insertion order cannot change request identity.
+  const value = operation.type === "pst-select" ? [operation.type, operation.sceneId]
+    : operation.type === "lock" ? [operation.type, operation.enabled]
+    : operation.type === "override" ? [operation.type, operation.mode]
+    : operation.type === "overlay" ? [operation.type, operation.slotId, operation.revisionId]
+    : operation.type === "desired" ? [operation.type, operation.spec] : [operation.type];
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex");
+}
+export async function findReceipt(client: PoolClient, workspaceId: string, channelId: string, requestId: string, expected: string): Promise<DirectorReceipt | null> {
+  const result = await client.query<{ diff: DirectorReceipt }>(
+    `SELECT diff FROM audit_log WHERE workspace_id=$1 AND target_type='production_command'
+       AND target_id=$2 AND diff->>'requestId'=$3 ORDER BY seq DESC LIMIT 1`, [workspaceId, channelId, requestId]);
+  const receipt = result.rows[0]?.diff;
+  if (receipt && receipt.fingerprint !== expected) throw new ConflictException("Idempotency-Key was used with another operation");
+  return receipt ?? null;
+}
diff --git a/apps/api/src/production/preview.controller.ts b/apps/api/src/production/preview.controller.ts
new file mode 100644
index 0000000..48e934e
--- /dev/null
+++ b/apps/api/src/production/preview.controller.ts
@@ -0,0 +1,33 @@
+import { Controller, ForbiddenException, Get, Inject, Param, Query, Req, Res } from "@nestjs/common";
+import type { Request, Response } from "express";
+import { parseId } from "../http/validation.js";
+import { PreviewService } from "./preview.js";
+
+/** Capability URLs are minted by the authenticated media-control endpoint.
+ * Proxy plaintext through this origin; encrypted S3 objects are never redirected. */
+@Controller("media-control/preview")
+export class PreviewController {
+  constructor(@Inject(PreviewService) private readonly preview: PreviewService) {}
+  @Get(":workspaceId/:channelId/:tap/:file")
+  async read(@Req() request: Request, @Res() response: Response,
+    @Param("workspaceId") ws: string, @Param("channelId") ch: string, @Param("tap") tap: string, @Param("file") file: string,
+    @Query("expires") expires: string, @Query("signature") signature: string): Promise<void> {
+    const origin = request.headers.origin;
+    const ownOrigin = process.env.PUBLIC_ORIGIN ?? `${request.protocol}://${request.get("host")}`;
+    if (origin && origin !== ownOrigin) throw new ForbiddenException("cross-origin preview denied");
+    parseId(ws, "workspaceId"); parseId(ch, "channelId");
+    if (tap !== "program") parseId(tap, "tap");
+    this.preview.verify(ws, ch, tap, file, expires, signature);
+    const object = await this.preview.read(ws, ch, tap, file);
+    response.setHeader("ETag", object.etag);
+    response.setHeader("Cache-Control", "private, max-age=1");
+    response.setHeader("Cross-Origin-Resource-Policy", "same-origin");
+    response.setHeader("X-Content-Type-Options", "nosniff");
+    response.setHeader("Vary", "Origin");
+    response.removeHeader("Access-Control-Allow-Origin");
+    if (request.headers["if-none-match"]?.split(/,\s*/).some(tag => tag === object.etag || tag === `W/${object.etag}` || tag === "*")) {
+      response.status(304).end(); return;
+    }
+    response.type(object.contentType).send(object.body);
+  }
+}
diff --git a/apps/api/src/production/preview.test.ts b/apps/api/src/production/preview.test.ts
new file mode 100644
index 0000000..04f5556
--- /dev/null
+++ b/apps/api/src/production/preview.test.ts
@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import { MemoryRedis } from "./testing/memory-redis.js";
+import { PreviewService } from "./preview.js";
+import { keyForHash, sha256, type StorageService } from "../storage/storage.js";
+const WS = randomUUID(), CH = randomUUID(), TAP = randomUUID();
+function fixture(): { preview: PreviewService; storage: StorageService; redis: MemoryRedis; seed: (file: string, body: string, type?: string) => void; advance: (ms: number) => void } {
+  const redis = new MemoryRedis(), objects = new Map<string, Buffer>(); let now = Date.now();
+  const storage: StorageService = { putContent: async () => { throw new Error("unused"); }, getObject: vi.fn(async key => { await new Promise(r => setTimeout(r, 1)); return objects.get(key) ?? Buffer.alloc(0); }), hasContent: async () => false, presign: async () => { throw new Error("must not redirect to encrypted S3"); } };
+  const preview = new PreviewService({ redis, storage, secret: "test", now: () => now, assertTap: async () => undefined });
+  const seed = (file: string, body: string, type = "video/mp2t"): void => {
+    const buffer = Buffer.from(body), key = keyForHash(sha256(buffer), type); objects.set(key, buffer);
+    redis.data.set(`preview:${WS}:${CH}:${TAP}:${file}`, JSON.stringify({ key, contentType: type }));
+  };
+  return { preview, storage, redis, seed, advance: ms => { now += ms; } };
+}
+describe("same-origin short-lived preview capabilities and shared cache", () => {
+  it("single-flight concurrent requests fill once and reuse an ETag", async () => {
+    const f = fixture(); f.seed("thumbnail.jpg", "jpeg", "image/jpeg");
+    const objects = await Promise.all(Array.from({ length: 20 }, () => f.preview.read(WS, CH, TAP, "thumbnail.jpg")));
+    expect(f.storage.getObject).toHaveBeenCalledTimes(1); expect(new Set(objects.map(o => o.etag)).size).toBe(1);
+    expect(objects[0]?.body.toString()).toBe("jpeg");
+    f.advance(1001); await f.preview.read(WS, CH, TAP, "thumbnail.jpg"); expect(f.storage.getObject).toHaveBeenCalledTimes(2);
+  });
+  it("keeps at most six segments per tap and fills evicted segments", async () => {
+    const f = fixture(); for (let i = 0; i < 7; i++) { f.seed(`s${i}.ts`, `segment-${i}`); await f.preview.read(WS, CH, TAP, `s${i}.ts`); }
+    await f.preview.read(WS, CH, TAP, "s0.ts"); expect(f.storage.getObject).toHaveBeenCalledTimes(8);
+  });
+  it("signs path-bound URLs that expire after 60 seconds", async () => {
+    const f = fixture(); const urls = await f.preview.urls(WS, CH, TAP);
+    const url = new URL(urls.thumbnail ?? "", "https://same-origin.example");
+    const expiry = url.searchParams.get("expires") ?? "", signature = url.searchParams.get("signature") ?? "";
+    expect(url.pathname.startsWith("/media-control/preview/")).toBe(true);
+    expect(() => f.preview.verify(WS, CH, TAP, "thumbnail.jpg", expiry, signature)).not.toThrow();
+    expect(() => f.preview.verify(randomUUID(), CH, TAP, "thumbnail.jpg", expiry, signature)).toThrow();
+    expect(() => f.preview.verify(WS, CH, TAP, "audio.m3u8", expiry, signature)).toThrow();
+    f.advance(60_000); expect(() => f.preview.verify(WS, CH, TAP, "thumbnail.jpg", expiry, signature)).toThrow("expired");
+  });
+  it("rewrites HLS media and init URLs to signed same-origin paths", async () => {
+    const f = fixture(); f.seed("video.m3u8", '#EXTM3U\n#EXT-X-MAP:URI="init.mp4"\n#EXTINF:1,\ns1.m4s\n', "application/vnd.apple.mpegurl");
+    const object = await f.preview.read(WS, CH, TAP, "video.m3u8");
+    expect(object.body.toString()).toContain(`/media-control/preview/${WS}/${CH}/${TAP}/init.mp4?expires=`);
+    expect(object.body.toString()).toContain(`/media-control/preview/${WS}/${CH}/${TAP}/s1.m4s?expires=`);
+    expect(object.body.toString()).not.toContain("https://");
+  });
+  it.each(["https://evil.example/s.ts", "../escape.ts", "//evil/s.ts", "file:///etc/passwd"])("rejects external/traversal HLS URI %s", async uri => {
+    const f = fixture(); f.seed("video.m3u8", `#EXTM3U\n${uri}\n`, "application/vnd.apple.mpegurl");
+    await expect(f.preview.read(WS, CH, TAP, "video.m3u8")).rejects.toThrow("invalid preview file");
+  });
+  it("failed fill does not poison the single-flight cache", async () => {
+    const f = fixture(); await expect(f.preview.read(WS, CH, TAP, "s.ts")).rejects.toThrow("unavailable");
+    f.seed("s.ts", "fixed"); expect((await f.preview.read(WS, CH, TAP, "s.ts")).body.toString()).toBe("fixed");
+  });
+});
diff --git a/apps/api/src/production/preview.ts b/apps/api/src/production/preview.ts
new file mode 100644
index 0000000..3401542
--- /dev/null
+++ b/apps/api/src/production/preview.ts
@@ -0,0 +1,99 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { BadRequestException, ForbiddenException, Inject, Injectable, NotFoundException, OnModuleDestroy, Optional } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import { RespControlRedis, type ControlRedis } from "../media-control/redis.js";
+import { S3Storage, s3ConfigFromEnv, sha256, type StorageService } from "../storage/storage.js";
+
+export const PREVIEW_DEPENDENCIES = Symbol("PREVIEW_DEPENDENCIES");
+export const PREVIEW_TTL_SECONDS = 60;
+interface PreviewManifest { key: string; contentType: string }
+interface PreviewObject { body: Buffer; contentType: string; etag: string }
+interface PreviewDependencies {
+  redis: ControlRedis;
+  storage: StorageService;
+  secret: string;
+  now: () => number;
+  assertTap: (workspaceId: string, channelId: string, tap: string) => Promise<void>;
+}
+const FILE = /^(?:[A-Za-z0-9_-]+\.(?:m3u8|m4s|ts|aac|jpg|jpeg|mp4))$/;
+const TYPES = new Set(["image/jpeg", "application/vnd.apple.mpegurl", "application/x-mpegURL", "video/mp2t", "video/mp4", "audio/mp4", "audio/aac"]);
+
+@Injectable()
+export class PreviewService implements OnModuleDestroy {
+  private readonly deps: PreviewDependencies;
+  private readonly sources = new Map<string, Map<string, { expiresAt: number; object: PreviewObject }>>();
+  private readonly flights = new Map<string, Promise<PreviewObject>>();
+  constructor(@Optional() @Inject(PREVIEW_DEPENDENCIES) dependencies?: Partial<PreviewDependencies>) {
+    const secret = dependencies?.secret ?? process.env.PREVIEW_SIGNING_SECRET ?? process.env.SESSION_SECRET;
+    if (!secret && process.env.NODE_ENV === "production") throw new Error("PREVIEW_SIGNING_SECRET is required");
+    this.deps = { redis: dependencies?.redis ?? new RespControlRedis(process.env.REDIS_URL ?? "redis://localhost:6379"),
+      storage: dependencies?.storage ?? new S3Storage(s3ConfigFromEnv()), secret: secret ?? "dev-preview-secret",
+      now: dependencies?.now ?? Date.now,
+      assertTap: dependencies?.assertTap ?? (async (ws, ch, tap) => {
+        const result = await withTenant(ws, client => client.query(tap === "program"
+          ? "SELECT id FROM virtual_channels WHERE workspace_id=$1 AND id=$2"
+          : "SELECT id FROM virtual_channel_sources WHERE workspace_id=$1 AND virtual_channel_id=$2 AND id=$3", tap === "program" ? [ws, ch] : [ws, ch, tap]));
+        if (!result.rowCount) throw new NotFoundException("preview tap not found");
+      }),
+    };
+  }
+  onModuleDestroy(): void { this.deps.redis.close(); this.sources.clear(); }
+  async urls(ws: string, ch: string, tap: string): Promise<Record<string, string>> {
+    await this.deps.assertTap(ws, ch, tap);
+    return { thumbnail: this.url(ws, ch, tap, "thumbnail.jpg"), video: this.url(ws, ch, tap, "video.m3u8"), audio: this.url(ws, ch, tap, "audio.m3u8") };
+  }
+  private mac(path: string, expires: number): string { return createHmac("sha256", this.deps.secret).update(`${path}\n${expires}`).digest("hex"); }
+  private path(ws: string, ch: string, tap: string, file: string): string {
+    return `/media-control/preview/${ws}/${ch}/${tap}/${file}`;
+  }
+  url(ws: string, ch: string, tap: string, file: string): string {
+    if (!FILE.test(file)) throw new BadRequestException("invalid preview file");
+    const path = this.path(ws, ch, tap, file);
+    const expires = Math.floor(this.deps.now() / 1000) + PREVIEW_TTL_SECONDS;
+    return `${path}?expires=${expires}&signature=${this.mac(path, expires)}`;
+  }
+  verify(ws: string, ch: string, tap: string, file: string, expires: string, signature: string): void {
+    if (!FILE.test(file) || !/^\d{1,12}$/.test(expires) || !/^[0-9a-f]{64}$/.test(signature)) throw new ForbiddenException("invalid preview signature");
+    const expiry = Number(expires), now = Math.floor(this.deps.now() / 1000);
+    const expected = this.mac(this.path(ws, ch, tap, file), expiry);
+    if (expiry <= now || expiry > now + PREVIEW_TTL_SECONDS || !timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) throw new ForbiddenException("expired or invalid preview signature");
+  }
+  async read(ws: string, ch: string, tap: string, file: string): Promise<PreviewObject> {
+    const source = `${ws}:${ch}:${tap}`, key = `${source}:${file}`;
+    const cache = this.sources.get(source);
+    const hit = cache?.get(file);
+    if (hit && hit.expiresAt > this.deps.now()) { cache?.delete(file); cache?.set(file, hit); return hit.object; }
+    const existing = this.flights.get(key);
+    if (existing) return existing;
+    if (this.flights.size >= 128) throw new BadRequestException("preview fill capacity exceeded");
+    const flight = this.fill(ws, ch, tap, file).then(object => {
+      const entries = this.sources.get(source) ?? new Map<string, { expiresAt: number; object: PreviewObject }>();
+      entries.delete(file); entries.set(file, { expiresAt: this.deps.now() + 1000, object });
+      while (entries.size > 6) entries.delete(entries.keys().next().value ?? "");
+      this.sources.delete(source); this.sources.set(source, entries);
+      while (this.sources.size > 128) this.sources.delete(this.sources.keys().next().value ?? "");
+      return object;
+    }).finally(() => this.flights.delete(key));
+    this.flights.set(key, flight);
+    return flight;
+  }
+  private async fill(ws: string, ch: string, tap: string, file: string): Promise<PreviewObject> {
+    if (!FILE.test(file)) throw new BadRequestException("invalid preview file");
+    const raw = await this.deps.redis.get(`preview:${ws}:${ch}:${tap}:${file}`);
+    if (!raw) throw new NotFoundException("preview unavailable");
+    const manifest = JSON.parse(raw) as PreviewManifest;
+    if (!/^sha256\/[0-9a-f]{64}\.[a-z0-9]+$/.test(manifest.key) || !TYPES.has(manifest.contentType)) throw new BadRequestException("invalid preview manifest");
+    let body = await this.deps.storage.getObject(manifest.key);
+    if (body.length > 4_000_000) throw new BadRequestException("preview object too large");
+    if (file.endsWith(".m3u8")) {
+      const rewrite = (uri: string): string => this.url(ws, ch, tap, uri);
+      const playlist = body.toString("utf8");
+      if (!playlist.startsWith("#EXTM3U")) throw new BadRequestException("invalid preview playlist");
+      body = Buffer.from(playlist.split(/\r?\n/).map(line => {
+        if (line.startsWith("#")) return line.replace(/URI="([^"]+)"/g, (_match: string, uri: string) => `URI="${rewrite(uri)}"`);
+        return line.trim() === "" ? line : rewrite(line.trim());
+      }).join("\n"));
+    }
+    return { body, contentType: manifest.contentType, etag: `"${sha256(body)}"` };
+  }
+}
diff --git a/apps/api/src/production/production.controller.ts b/apps/api/src/production/production.controller.ts
new file mode 100644
index 0000000..e62b5da
--- /dev/null
+++ b/apps/api/src/production/production.controller.ts
@@ -0,0 +1,18 @@
+import { Body, Controller, Headers, Inject, Param, Post, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { parseId, requireSession } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import type { IssuedCommand } from "../media-control/media-control.service.js";
+import { ProductionService } from "./production.service.js";
+@Controller("production")
+@UseGuards(RbacGuard)
+export class ProductionController {
+  constructor(@Inject(ProductionService) private readonly production: ProductionService) {}
+  @Post("overlays/:overlayId")
+  @RequirePermission("director.change_layout")
+  render(@Req() request: Request & AuthenticatedRequest, @Param("overlayId") overlayId: string,
+    @Body() body: unknown, @Headers("idempotency-key") key?: string): Promise<IssuedCommand> {
+    const session = requireSession(request);
+    return this.production.submit(session.workspaceId, parseId(overlayId, "overlayId"), body, key ?? "", { userId: session.userId, role: session.role });
+  }
+}
diff --git a/apps/api/src/production/production.module.ts b/apps/api/src/production/production.module.ts
new file mode 100644
index 0000000..4bf670a
--- /dev/null
+++ b/apps/api/src/production/production.module.ts
@@ -0,0 +1,6 @@
+import { Module } from "@nestjs/common";
+import { MediaControlModule } from "../media-control/media-control.module.js";
+import { ProductionService } from "./production.service.js";
+import { ProductionController } from "./production.controller.js";
+@Module({ imports: [MediaControlModule], controllers: [ProductionController], providers: [ProductionService], exports: [ProductionService] })
+export class ProductionModule {}
diff --git a/apps/api/src/production/production.service.ts b/apps/api/src/production/production.service.ts
new file mode 100644
index 0000000..ed56264
--- /dev/null
+++ b/apps/api/src/production/production.service.ts
@@ -0,0 +1,94 @@
+import { createHash, randomUUID } from "node:crypto";
+import { ConflictException, Inject, Injectable, NotFoundException, OnModuleDestroy, OnModuleInit, Optional } from "@nestjs/common";
+import { withTenant, pool } from "../db/client.js";
+import { MediaControlService, type IssuedCommand } from "../media-control/media-control.service.js";
+import { S3Storage, s3ConfigFromEnv, type StorageService } from "../storage/storage.js";
+import { requestIdentity, type DirectorActor, type TenantTransaction } from "./journal.js";
+import { renderOverlay, validateRenderInput, type RenderInput } from "./render.js";
+export const PRODUCTION_DEPENDENCIES = Symbol("PRODUCTION_DEPENDENCIES");
+interface RevisionFields { input: RenderInput; actor: DirectorActor; requestId: string; fingerprint: string }
+interface Revision { id: string; virtual_channel_id: string; overlay_slot_id: string; render_state: string; fields: RevisionFields }
+interface Dependencies { transaction: TenantTransaction; storage: StorageService; render: (input: unknown) => Promise<Buffer> }
+
+@Injectable()
+export class ProductionService implements OnModuleInit, OnModuleDestroy {
+  private readonly deps: Dependencies;
+  private readonly flights = new Map<string, Promise<IssuedCommand>>();
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private recovering = false;
+  constructor(@Inject(MediaControlService) private readonly control: MediaControlService,
+    @Optional() @Inject(PRODUCTION_DEPENDENCIES) dependencies?: Partial<Dependencies>) {
+    this.deps = { transaction: dependencies?.transaction ?? withTenant, storage: dependencies?.storage ?? new S3Storage(s3ConfigFromEnv()),
+      render: dependencies?.render ?? renderOverlay };
+  }
+  onModuleInit(): void {
+    this.timer = setInterval(() => { void this.recover(); }, 1000); this.timer.unref();
+    void this.recover();
+  }
+  onModuleDestroy(): void { if (this.timer) clearInterval(this.timer); }
+  async submit(ws: string, slotId: string, value: unknown, idempotencyKey: string, actor: DirectorActor): Promise<IssuedCommand> {
+    const input = validateRenderInput(value);
+    const expected = createHash("sha256").update(JSON.stringify(input)).digest("hex");
+    const revision = await this.deps.transaction(ws, async client => {
+      const slot = await client.query<{ virtual_channel_id: string; kind: string }>("SELECT virtual_channel_id,kind FROM overlay_slots WHERE workspace_id=$1 AND id=$2 FOR UPDATE", [ws, slotId]);
+      const row = slot.rows[0];
+      if (!row) throw new NotFoundException("overlay slot not found");
+      if (row.kind !== input.templateId) throw new ConflictException("template must match overlay kind");
+      const requestId = requestIdentity(ws, slotId, idempotencyKey);
+      const found = await client.query<Revision>("SELECT * FROM overlay_revisions WHERE workspace_id=$1 AND overlay_slot_id=$2 AND fields->>'requestId'=$3", [ws, slotId, requestId]);
+      const previous = found.rows[0];
+      if (previous) {
+        if (previous.fields.fingerprint !== expected) throw new ConflictException("Idempotency-Key was used with different overlay fields");
+        return previous;
+      }
+      const id = randomUUID();
+      const fields: RevisionFields = { input, actor, requestId, fingerprint: expected };
+      await client.query("INSERT INTO overlay_revisions(id,workspace_id,virtual_channel_id,overlay_slot_id,template_id,fields) VALUES($1,$2,$3,$4,$5,$6)", [id, ws, row.virtual_channel_id, slotId, input.templateId, fields]);
+      return { id, virtual_channel_id: row.virtual_channel_id, overlay_slot_id: slotId, render_state: "pending", fields };
+    });
+    return this.run(ws, revision);
+  }
+  private run(ws: string, revision: Revision): Promise<IssuedCommand> {
+    const key = `${ws}:${revision.id}`;
+    const previous = this.flights.get(key);
+    if (previous) return previous;
+    const flight = (async () => {
+      if (revision.render_state !== "rendered") {
+        try {
+          const png = await this.deps.render(revision.fields.input);
+          const stored = await this.deps.storage.putContent(png, "image/png");
+          await this.deps.transaction(ws, client => client.query("UPDATE overlay_revisions SET render_state='rendered',asset_id=$3,updated_at=now() WHERE workspace_id=$1 AND id=$2", [ws, revision.id, stored.hash]));
+        } catch (error) {
+          await this.deps.transaction(ws, client => client.query("UPDATE overlay_revisions SET render_state='failed',asset_id=NULL,updated_at=now() WHERE workspace_id=$1 AND id=$2 AND render_state<>'rendered'", [ws, revision.id]));
+          throw error;
+        }
+      }
+      return this.control.director(ws, revision.virtual_channel_id, { type: "overlay", slotId: revision.overlay_slot_id, revisionId: revision.id },
+        `overlay-render:${revision.id}`, revision.fields.actor);
+    })().finally(() => this.flights.delete(key));
+    this.flights.set(key, flight); return flight;
+  }
+  private async recover(): Promise<void> {
+    if (this.recovering) return;
+    this.recovering = true;
+    try {
+      const workspaces = await pool.query<{ id: string }>("SELECT id FROM workspaces");
+      for (const ws of workspaces.rows) {
+        const revisions = await this.deps.transaction(ws.id, async client => {
+          const result = await client.query<Revision>(`SELECT r.* FROM overlay_revisions r WHERE r.workspace_id=$1
+            AND r.render_state <> 'failed' AND r.fields ? 'input' AND r.fields ? 'actor'
+            AND NOT EXISTS(SELECT 1 FROM overlay_slots s JOIN overlay_revisions active_revision ON active_revision.id=s.current_revision_id
+              AND active_revision.workspace_id=s.workspace_id WHERE s.workspace_id=r.workspace_id AND s.id=r.overlay_slot_id AND active_revision.created_at > r.created_at)
+            AND NOT EXISTS(SELECT 1 FROM audit_log a WHERE a.workspace_id=$1
+              AND a.target_type='production_command' AND a.diff->'operation'->>'revisionId'=r.id::text) ORDER BY r.created_at LIMIT 100`, [ws.id]);
+          return result.rows;
+        });
+        for (const revision of revisions) {
+          // Rendered rows are retried too: a crash may happen between storing PNG and swapping the slot.
+          await this.run(ws.id, revision).catch(() => undefined);
+        }
+      }
+    } catch { /* Retry after transient database/storage failures. */ }
+    finally { this.recovering = false; }
+  }
+}
diff --git a/apps/api/src/production/production.test.ts b/apps/api/src/production/production.test.ts
new file mode 100644
index 0000000..da9e9aa
--- /dev/null
+++ b/apps/api/src/production/production.test.ts
@@ -0,0 +1,67 @@
+import { randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { describe, expect, it, vi } from "vitest";
+import { MediaControlService, type IssuedCommand } from "../media-control/media-control.service.js";
+import { sha256, keyForHash, type StorageService } from "../storage/storage.js";
+import { ProductionService } from "./production.service.js";
+import type { TenantTransaction } from "./journal.js";
+const WS = randomUUID(), CH = randomUUID(), SLOT = randomUUID();
+const ACTOR = { userId: randomUUID(), role: "Owner" };
+const ISSUED: IssuedCommand = { commandId: randomUUID(), workerId: "worker", assignmentEpoch: 1, desiredVersion: 1, issuedAt: new Date().toISOString(), expiresAt: new Date(Date.now() + 30000).toISOString(), receivers: 1 };
+interface Revision { id: string; virtual_channel_id: string; overlay_slot_id: string; fields: unknown; render_state: string; asset_id?: string }
+function fixture(render?: (input: unknown) => Promise<Buffer>): { production: ProductionService; rows: Revision[]; storage: StorageService; control: MediaControlService } {
+  const rows: Revision[] = []; let tail = Promise.resolve();
+  const transaction: TenantTransaction = async <T>(_ws: string, fn: (client: PoolClient) => Promise<T>): Promise<T> => {
+    const wait = tail; let unlock = (): void => undefined; tail = new Promise<void>(resolve => { unlock = resolve; }); await wait;
+    const query = async (sql: string, args: unknown[]): Promise<{ rows: unknown[]; rowCount: number }> => {
+      if (sql.startsWith("SELECT virtual_channel_id")) return { rows: [{ virtual_channel_id: CH, kind: "lower_third" }], rowCount: 1 };
+      if (sql.startsWith("SELECT * FROM overlay_revisions")) {
+        const found = rows.filter(r => r.fields && typeof r.fields === "object" && "requestId" in r.fields && r.fields.requestId === args[2]);
+        return { rows: found, rowCount: found.length };
+      }
+      if (sql.startsWith("INSERT")) rows.push({ id: String(args[0]), virtual_channel_id: String(args[2]), overlay_slot_id: String(args[3]), fields: args[5], render_state: "pending" });
+      if (sql.startsWith("UPDATE")) {
+        const row = rows.find(r => r.id === args[1]); if (!row) throw new Error("missing revision");
+        row.render_state = sql.includes("render_state='rendered'") ? "rendered" : "failed"; if (args[2]) row.asset_id = String(args[2]);
+      }
+      return { rows: [], rowCount: 1 };
+    };
+    try { return await fn({ query } as unknown as PoolClient); } finally { unlock(); }
+  };
+  const control = new MediaControlService({ signer: null, assignments: [] }); vi.spyOn(control, "director").mockResolvedValue(ISSUED);
+  const storage: StorageService = { putContent: vi.fn(async (buffer, contentType) => { const hash = sha256(buffer); return { hash, key: keyForHash(hash, contentType), sizeBytes: buffer.length, contentType, deduplicated: false }; }), getObject: async () => Buffer.alloc(0), hasContent: async () => false, presign: async () => "" };
+  return { rows, control, storage, production: new ProductionService(control, { transaction, storage, ...(render ? { render } : {}) }) };
+}
+describe("revision → render job → content-addressed storage → desired-state pipeline", () => {
+  it("stores a real alpha PNG and swaps only a revision/asset reference through media-control", async () => {
+    const f = fixture(); const input = { templateId: "lower_third", fields: { title: '<script>bad</script>', subtitle: 'Name; [movie=hostile]' } };
+    await expect(f.production.submit(WS, SLOT, input, "render-1", ACTOR)).resolves.toEqual(ISSUED);
+    expect(f.rows).toHaveLength(1); expect(f.rows[0]?.render_state).toBe("rendered"); expect(f.rows[0]?.asset_id).toMatch(/^[0-9a-f]{64}$/);
+    expect(f.storage.putContent).toHaveBeenCalledWith(expect.any(Buffer), "image/png");
+    expect(f.control.director).toHaveBeenCalledWith(WS, CH, { type: "overlay", slotId: SLOT, revisionId: f.rows[0]?.id }, `overlay-render:${f.rows[0]?.id}`, ACTOR);
+    await f.production.submit(WS, SLOT, input, "render-1", ACTOR); expect(f.storage.putContent).toHaveBeenCalledTimes(1);
+    await expect(f.production.submit(WS, SLOT, { ...input, fields: { title: "changed" } }, "render-1", ACTOR)).rejects.toThrow("different overlay fields");
+  });
+  it("concurrent duplicate overlay requests share a single render job/revision", async () => {
+    const renderer = vi.fn(async () => { await new Promise(r => setTimeout(r, 10)); return Buffer.from("test-png"); }); const f = fixture(renderer);
+    await Promise.all(Array.from({ length: 10 }, () => f.production.submit(WS, SLOT, { templateId: "lower_third", fields: { title: "hello" } }, "parallel", ACTOR)));
+    expect(renderer).toHaveBeenCalledTimes(1); expect(f.rows).toHaveLength(1); expect(f.control.director).toHaveBeenCalledTimes(1);
+  });
+  it("render failure records failed revision; retry resumes the same revision", async () => {
+    let fail = true; const f = fixture(async () => { if (fail) { fail = false; throw new Error("render failed"); } return Buffer.from("png"); });
+    const input = { templateId: "lower_third", fields: { title: "hello" } };
+    await expect(f.production.submit(WS, SLOT, input, "retry", ACTOR)).rejects.toThrow("render failed"); expect(f.rows[0]?.render_state).toBe("failed"); expect(f.control.director).not.toHaveBeenCalled();
+    await f.production.submit(WS, SLOT, input, "retry", ACTOR); expect(f.rows).toHaveLength(1); expect(f.rows[0]?.render_state).toBe("rendered");
+  });
+  it("crash after PNG persistence retries only the desired-state swap", async () => {
+    const render = vi.fn(async () => Buffer.from("png")), f = fixture(render);
+    vi.mocked(f.control.director).mockRejectedValueOnce(new Error("publish outage"));
+    const input = { templateId: "lower_third", fields: { title: "hello" } };
+    await expect(f.production.submit(WS, SLOT, input, "resume", ACTOR)).rejects.toThrow("publish outage"); expect(f.rows[0]?.render_state).toBe("rendered");
+    await f.production.submit(WS, SLOT, input, "resume", ACTOR); expect(render).toHaveBeenCalledTimes(1); expect(f.storage.putContent).toHaveBeenCalledTimes(1);
+  });
+  it("rejects hostile uploaded SVG before creating a revision or invoking storage", async () => {
+    const f = fixture(); await expect(f.production.submit(WS, SLOT, { templateId: "logo", fields: { svg: '<!DOCTYPE svg [<!ENTITY x SYSTEM "https://evil.example">]><svg>&x;</svg>' } }, "hostile", ACTOR)).rejects.toThrow("unsafe SVG");
+    expect(f.rows).toHaveLength(0); expect(f.storage.putContent).not.toHaveBeenCalled(); expect(f.control.director).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/api/src/production/render.test.ts b/apps/api/src/production/render.test.ts
new file mode 100644
index 0000000..5bd581a
--- /dev/null
+++ b/apps/api/src/production/render.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from "vitest";
+import { renderOverlay, validateRenderInput, overlaySvg } from "./render.js";
+const png = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+describe("overlay render job injection gates (installed sharp, isolated worker)", () => {
+  it.each(["lower_third", "chyron"])("renders %s hostile text as escaped text into an actual PNG", async templateId => {
+    const input = { templateId, fields: { title: '<script>alert("x")</script> & $(touch /tmp/owned)', subtitle: 'evil; [movie=/etc/passwd]; "', style: "red" } };
+    const svg = overlaySvg(validateRenderInput(input)).svg;
+    expect(svg).toContain("&lt;script&gt;"); expect(svg).not.toContain("<script>");
+    const rendered = await renderOverlay(input); expect(rendered.subarray(0, 8)).toEqual(png);
+    expect(rendered.readUInt32BE(16)).toBe(templateId === "chyron" ? 4096 : 1920);
+  });
+  it("rasterizes a safe tenant geometric logo", async () => {
+    const rendered = await renderOverlay({ templateId: "logo", fields: { svg: '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64"><rect width="64" height="64" fill="#FF1610"/></svg>' } });
+    expect(rendered.subarray(0, 8)).toEqual(png); expect(rendered.readUInt32BE(16)).toBe(512);
+  });
+  it.each([
+    '<!DOCTYPE svg [<!ENTITY xxe SYSTEM "file:///etc/passwd">]><svg>&xxe;</svg>',
+    '<svg><script>alert(1)</script></svg>', '<svg onload="alert(1)"></svg>',
+    '<svg><image href="https://attacker.example/tracker"/></svg>',
+    '<svg><style>@import "https://attacker.example/a.css";</style></svg>',
+    '<svg><foreignObject><div>html</div></foreignObject></svg>',
+    '<svg><path fill="url(https://evil.example/x)"/></svg>',
+    '<svg xmlns:xlink="http://www.w3.org/1999/xlink"><use xlink:href="file:///etc/passwd"/></svg>',
+    '<?xml-stylesheet href="https://evil.example/a"?><svg/>',
+    '<svg width="999999999" height="999999999"/>',
+    '<svg><g></svg></g>', '<svg/><svg/>', '<svg><path d="M0 0" onclick="evil()"/></svg>',
+  ])("rejects hostile SVG through the render job: %s", async svg => {
+    await expect(renderOverlay({ templateId: "logo", fields: { svg } })).rejects.toThrow();
+  });
+  it.each(["\u0000", "\n", "\u202e", "a".repeat(81)])("rejects invalid text %s before sharp", async title => {
+    await expect(renderOverlay({ templateId: "lower_third", fields: { title } })).rejects.toThrow("invalid overlay text");
+  });
+});
diff --git a/apps/api/src/production/render.ts b/apps/api/src/production/render.ts
new file mode 100644
index 0000000..19d09ba
--- /dev/null
+++ b/apps/api/src/production/render.ts
@@ -0,0 +1,118 @@
+// eslint-disable-next-line no-restricted-syntax -- Node worker_threads is a runtime builtin, not a provider identifier.
+import { Worker } from "node:worker_threads";
+import { createRequire } from "node:module";
+import { BadRequestException } from "@nestjs/common";
+
+export type OverlayTemplate = "lower_third" | "chyron" | "logo";
+export interface OverlayFields { title?: string; subtitle?: string; style?: "dark" | "red"; svg?: string }
+export interface RenderInput { templateId: OverlayTemplate; fields: OverlayFields }
+function text(value: unknown, max: number): string {
+  if (typeof value !== "string" || value.length > max || !/^[\p{L}\p{N}\p{P}\p{Zs}\p{M}\p{S}]*$/u.test(value)) throw new BadRequestException("invalid overlay text");
+  return value;
+}
+function escape(value: string): string {
+  return value.replace(/[&<>"']/g, c => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" })[c] ?? c);
+}
+export function validateRenderInput(value: unknown): RenderInput {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new BadRequestException("invalid overlay input");
+  const input = value as Record<string, unknown>;
+  if (Object.keys(input).some(k => !["templateId", "fields"].includes(k)) || !["lower_third", "chyron", "logo"].includes(String(input.templateId))) throw new BadRequestException("invalid overlay template");
+  if (!input.fields || typeof input.fields !== "object" || Array.isArray(input.fields)) throw new BadRequestException("invalid overlay fields");
+  const fields = input.fields as Record<string, unknown>;
+  if (Object.keys(fields).some(k => !["title", "subtitle", "style", "svg"].includes(k))) throw new BadRequestException("unknown overlay field");
+  if (input.templateId === "logo") {
+    if (Object.keys(fields).some(k => k !== "svg") || typeof fields.svg !== "string") throw new BadRequestException("logo requires SVG only");
+    return { templateId: "logo", fields: { svg: sanitizeLogo(fields.svg) } };
+  }
+  if (fields.svg !== undefined || (fields.style !== undefined && fields.style !== "dark" && fields.style !== "red")) throw new BadRequestException("invalid overlay style");
+  return { templateId: input.templateId as "lower_third" | "chyron", fields: { title: text(fields.title, 80),
+    subtitle: text(fields.subtitle ?? "", 120), style: fields.style === "red" ? "red" : "dark" } };
+}
+
+/** Closed geometric SVG language. No declarations, entities, CSS, URLs, script,
+ * animation, image/font loading, foreignObject or namespaced attributes. */
+export function sanitizeLogo(svg: string): string {
+  if (svg.length > 64_000 || /<!|<\?|&|url\s*\(|[\u0000-\u001f]/i.test(svg)) throw new BadRequestException("unsafe SVG");
+  const tags = new Set(["svg", "g", "path", "rect", "circle", "ellipse", "polygon", "polyline", "line"]);
+  const attrs = new Set(["xmlns", "width", "height", "viewBox", "fill", "stroke", "stroke-width", "opacity", "fill-opacity", "stroke-opacity", "d", "points", "x", "y", "x1", "y1", "x2", "y2", "cx", "cy", "r", "rx", "ry", "transform", "fill-rule", "stroke-linecap", "stroke-linejoin"]);
+  const stack: string[] = [];
+  let offset = 0, roots = 0;
+  for (const match of svg.matchAll(/<([^<>]+)>/g)) {
+    if (svg.slice(offset, match.index).trim() !== "") throw new BadRequestException("SVG text is not allowed");
+    offset = (match.index ?? 0) + match[0].length;
+    const token = match[1] ?? "";
+    const head = /^(\/)?([A-Za-z]+)([\s\S]*)$/.exec(token);
+    if (!head || !tags.has(head[2] ?? "")) throw new BadRequestException("unsafe SVG element");
+    const tag = head[2] ?? "", tail = head[3] ?? "";
+    if (head[1]) {
+      if (tail.trim() || stack.pop() !== tag) throw new BadRequestException("invalid SVG nesting");
+      continue;
+    }
+    if (stack.length === 0 && (tag !== "svg" || ++roots !== 1)) throw new BadRequestException("invalid SVG root");
+    if (stack.length > 32 || (tag === "svg" && stack.length > 0)) throw new BadRequestException("invalid SVG nesting");
+    const selfClosing = /\/\s*$/.test(tail);
+    const attributeText = tail.replace(/\/\s*$/, "");
+    let position = 0;
+    const names = new Set<string>();
+    for (const attr of attributeText.matchAll(/\s+([A-Za-z][A-Za-z0-9-]*)\s*=\s*(?:"([^"<>]*)"|'([^'<>]*)')/g)) {
+      if (attributeText.slice(position, attr.index).trim()) throw new BadRequestException("invalid SVG attribute");
+      position = (attr.index ?? 0) + attr[0].length;
+      const name = attr[1] ?? "", value = attr[2] ?? attr[3] ?? "";
+      if (!attrs.has(name) || names.has(name)) throw new BadRequestException("unsafe SVG attribute");
+      names.add(name);
+      if (name === "xmlns" ? value !== "http://www.w3.org/2000/svg" : !/^[A-Za-z0-9#.,() +\-]*$/.test(value)) throw new BadRequestException("unsafe SVG attribute value");
+      if (tag === "svg" && (name === "width" || name === "height") && (!/^\d+$/.test(value) || Number(value) < 1 || Number(value) > 1920)) throw new BadRequestException("SVG dimensions exceeded");
+    }
+    if (attributeText.slice(position).trim()) throw new BadRequestException("invalid SVG attributes");
+    if (!selfClosing) stack.push(tag);
+  }
+  if (roots !== 1 || stack.length || svg.slice(offset).trim()) throw new BadRequestException("invalid SVG");
+  return svg;
+}
+
+export function overlaySvg(input: RenderInput): { svg: string; width: number; height: number } {
+  if (input.templateId === "logo") return { svg: sanitizeLogo(input.fields.svg ?? ""), width: 512, height: 512 };
+  const width = input.templateId === "chyron" ? 4096 : 1920;
+  const height = input.templateId === "chyron" ? 128 : 240;
+  const fill = input.fields.style === "red" ? "#FF1610" : "#171717";
+  return { width, height, svg: `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect x="0" y="0" width="${width}" height="${height}" rx="12" fill="${fill}"/><rect width="14" height="${height}" fill="#FF1610"/><text x="48" y="80" font-family="DejaVu Sans" font-size="52" fill="white">${escape(input.fields.title ?? "")}</text><text x="48" y="156" font-family="DejaVu Sans" font-size="36" fill="white">${escape(input.fields.subtitle ?? "")}</text></svg>` };
+}
+
+function sharpPath(): string {
+  const require = createRequire(__filename);
+  if (process.env.SHARP_MODULE_PATH) return require.resolve(process.env.SHARP_MODULE_PATH);
+  try { return require.resolve("sharp"); } catch {
+    throw new Error("sharp not found — install it or point SHARP_MODULE_PATH at a sharp build");
+  }
+}
+const RENDER_SCRIPT = `const {parentPort,workerData}=require('node:worker_threads');const sharp=require(workerData.modulePath);sharp.cache(false);sharp.concurrency(1);sharp(Buffer.from(workerData.svg),{limitInputPixels:16777216}).resize(workerData.width,workerData.height,{fit:'contain',background:{r:0,g:0,b:0,alpha:0}}).png().toBuffer().then(png=>parentPort.postMessage(png)).catch(()=>{throw new Error('PNG rasterization failed')})`;
+let activeJobs = 0;
+
+/** Isolated job: closed SVG language, bounded pixels/output, V8 heap and wall time.
+ * The thread receives sanitized pixels/geometry only, with no credentials in its environment. */
+export async function renderOverlay(value: unknown): Promise<Buffer> {
+  const input = validateRenderInput(value);
+  const rendered = overlaySvg(input);
+  const modulePath = sharpPath();
+  if (activeJobs >= 4) throw new BadRequestException("overlay render capacity exceeded");
+  activeJobs += 1;
+  try {
+    return await new Promise<Buffer>((resolve, reject) => {
+      const worker = new Worker(RENDER_SCRIPT, { eval: true, workerData: { ...rendered, modulePath },
+        resourceLimits: { maxOldGenerationSizeMb: 128, maxYoungGenerationSizeMb: 16, stackSizeMb: 4 },
+        env: { PATH: process.env.PATH, HOME: process.env.HOME, LANG: "C.UTF-8" } });
+      let settled = false;
+      const finish = (error: Error | null, body?: Buffer): void => {
+        if (settled) return; settled = true; clearTimeout(timer); void worker.terminate();
+        if (error || !body) reject(error ?? new Error("overlay render failed")); else resolve(body);
+      };
+      const timer = setTimeout(() => finish(new Error("overlay render timed out")), 5000);
+      worker.once("message", (message: unknown) => {
+        if (!(message instanceof Uint8Array) || message.byteLength > 8_000_000 || message.byteLength < 8) finish(new Error("invalid overlay render output"));
+        else finish(null, Buffer.from(message));
+      });
+      worker.once("error", error => finish(error));
+      worker.once("exit", () => finish(new Error("overlay render exited before producing PNG")));
+    });
+  } finally { activeJobs -= 1; }
+}
diff --git a/apps/api/src/production/snapshot.ts b/apps/api/src/production/snapshot.ts
new file mode 100644
index 0000000..177490d
--- /dev/null
+++ b/apps/api/src/production/snapshot.ts
@@ -0,0 +1,33 @@
+import type { PoolClient } from "pg";
+import { parseProductionSpec, type ProductionSpec } from "../media-control/production.js";
+
+/** Read the aggregate only while virtual_channels is locked by the writer. */
+export async function productionSnapshot(client: PoolClient, workspaceId: string, channelId: string): Promise<ProductionSpec> {
+  const args = [workspaceId, channelId];
+  const scenes = await client.query<{ id: string; label: string; layout: string }>("SELECT id,label,layout FROM production_scenes WHERE workspace_id=$1 AND virtual_channel_id=$2 ORDER BY id", args);
+  const slots = await client.query<{ scene_id: string; slot_index: number; source_id: string | null; x: number | null; y: number | null; w: number | null; h: number | null; fit: string; audio_mode: string; gain_db: number }>("SELECT * FROM scene_slots WHERE workspace_id=$1 AND virtual_channel_id=$2 ORDER BY slot_index", args);
+  const sources = await client.query<{ id: string; label: string; kind: string; hls_url: string | null; playlist_loop: boolean | null; asset_ids: string[] }>(
+    `SELECT s.*, COALESCE((SELECT array_agg(substring(v.storage_key from 'sha256/([0-9a-f]{64})') ORDER BY i.position) FROM playlist_items i
+      JOIN video_assets v ON v.id=i.video_asset_id AND v.workspace_id=i.workspace_id
+      WHERE i.workspace_id=s.workspace_id AND i.source_id=s.id), '{}') AS asset_ids
+     FROM virtual_channel_sources s WHERE workspace_id=$1 AND virtual_channel_id=$2 ORDER BY id`, args);
+  const buses = await client.query<{ bus: "preview" | "program"; scene_id: string | null }>("SELECT bus,scene_id FROM production_buses WHERE workspace_id=$1 AND virtual_channel_id=$2", args);
+  const overlays = await client.query<{ id: string; scene_id: string; kind: string; enabled: boolean; layer: number; pos_x: number; pos_y: number; current_revision_id: string | null; asset_id: string | null; chyron_speed_px_s: number | null; chyron_strip_width_px: number | null; clock_format: string | null }>(
+    `SELECT s.*, r.asset_id FROM overlay_slots s LEFT JOIN overlay_revisions r
+      ON r.workspace_id=s.workspace_id AND r.id=s.current_revision_id AND r.render_state='rendered'
+     WHERE s.workspace_id=$1 AND s.virtual_channel_id=$2 AND (s.kind='clock' OR r.asset_id IS NOT NULL) ORDER BY s.layer,s.id`, args);
+  return parseProductionSpec({
+    sources: sources.rows.map(s => s.kind === "hls" ? { id: s.id, label: s.label, kind: s.kind, url: s.hls_url }
+      : { id: s.id, label: s.label, kind: s.kind, assetIds: s.asset_ids, loop: s.playlist_loop }),
+    scenes: scenes.rows.map(s => ({ ...s, slots: slots.rows.filter(x => x.scene_id === s.id).map(x => ({
+      index: x.slot_index, sourceId: x.source_id, rect: x.x === null ? null : { x: x.x, y: x.y, w: x.w, h: x.h },
+      fit: x.fit, audioMode: x.audio_mode, gainDb: x.gain_db,
+    })) })),
+    buses: { preview: buses.rows.find(b => b.bus === "preview")?.scene_id ?? null, program: buses.rows.find(b => b.bus === "program")?.scene_id ?? null },
+    overlays: overlays.rows.map(o => ({ id: o.id, sceneId: o.scene_id, kind: o.kind, enabled: o.enabled, layer: o.layer,
+      position: { x: o.pos_x, y: o.pos_y }, revisionId: o.current_revision_id, assetId: o.asset_id,
+      chyron: o.kind === "chyron" ? { speedPxPerSec: o.chyron_speed_px_s, stripWidthPx: o.chyron_strip_width_px } : null,
+      clock: o.kind === "clock" ? { format: o.clock_format } : null })),
+    transition: { type: "cut" }, audio: { masterGainDb: 0 },
+  });
+}
diff --git a/apps/api/src/production/testing/memory-redis.ts b/apps/api/src/production/testing/memory-redis.ts
new file mode 100644
index 0000000..b23ea56
--- /dev/null
+++ b/apps/api/src/production/testing/memory-redis.ts
@@ -0,0 +1,34 @@
+import { ASSIGN_SCRIPT, COMMIT_DESIRED_SCRIPT, DELIVER_RECEIPT_SCRIPT } from "../../media-control/media-control.service.js";
+import type { ControlRedis, RedisReply } from "../../media-control/redis.js";
+import type { SignedCommand } from "../../media-control/wire.js";
+export class MemoryRedis implements ControlRedis {
+  readonly data = new Map<string, string>();
+  readonly sets = new Map<string, Set<string>>();
+  readonly published: Array<{ channel: string; message: string }> = [];
+  failDelivery = false;
+  echo: ((command: SignedCommand) => void) | null = null;
+  async get(k: string): Promise<string | null> { return this.data.get(k) ?? null; }
+  async mget(ks: string[]): Promise<Array<string | null>> { return ks.map(k => this.data.get(k) ?? null); }
+  async set(k: string, v: string, options?: { nx?: boolean }): Promise<boolean> { if (options?.nx && this.data.has(k)) return false; this.data.set(k, v); return true; }
+  async incr(k: string): Promise<number> { const n = Number(this.data.get(k) ?? 0) + 1; this.data.set(k, String(n)); return n; }
+  async sadd(k: string, v: string): Promise<void> { const s = this.sets.get(k) ?? new Set(); s.add(v); this.sets.set(k, s); }
+  async smembers(k: string): Promise<string[]> { return [...(this.sets.get(k) ?? [])]; }
+  async publish(channel: string, message: string): Promise<number> { this.published.push({ channel, message }); if (channel.startsWith("cmd:")) this.echo?.(JSON.parse(message) as SignedCommand); return 1; }
+  async eval(script: string, keys: string[], args: string[]): Promise<RedisReply> {
+    const k = (i: number): string => keys[i] ?? "", a = (i: number): string => args[i] ?? "";
+    if (script === ASSIGN_SCRIPT) { this.data.set(k(0), a(0)); await this.sadd(k(1), a(3)); return 1; }
+    if (script === COMMIT_DESIRED_SCRIPT) { this.data.set(k(0), a(0)); return 1; }
+    if (script !== DELIVER_RECEIPT_SCRIPT) throw new Error("unknown script");
+    if (this.failDelivery) { this.failDelivery = false; throw new Error("crash before delivery"); }
+    const prior = this.data.get(k(0)); if (prior) return prior;
+    if (this.data.get(k(3)) !== a(3)) return -1;
+    const current = JSON.parse(this.data.get(k(1)) ?? "null") as { desiredVersion: number } | null;
+    if (!current || current.desiredVersion < Number(a(2))) { this.data.set(k(1), a(1)); this.data.set(k(2), a(2)); this.data.set(k(7), JSON.stringify((JSON.parse(a(6)) as { state: unknown }).state)); }
+    this.data.set(k(5), a(4));
+    const result = JSON.parse(a(0)) as Record<string, unknown>; result.receivers = 1;
+    const receipt = JSON.stringify(result);
+    this.data.set(k(0), receipt);
+    await this.publish(k(4), a(4)); await this.publish(k(6), a(6)); return receipt;
+  }
+  close(): void {}
+}
diff --git a/apps/api/src/publishing/approval-gate.integration.test.ts b/apps/api/src/publishing/approval-gate.integration.test.ts
new file mode 100644
index 0000000..cf8811e
--- /dev/null
+++ b/apps/api/src/publishing/approval-gate.integration.test.ts
@@ -0,0 +1,365 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Pool, type PoolClient } from "pg";
+import { PublishingExecutionRepository, assertPublishingSchema } from "@tactical-media-broadcast-hub/publishing-execution";
+
+/**
+ * chatgov P1 gates against a live PostgreSQL (chatgov-design.md §7 P1 row):
+ *  - immediate: ungated — a draft with NO compiled snapshot posts as today
+ *  - admin_only: blocks a non-admin approver, fires for an admin approve
+ *  - quorum: blocks with INSUFFICIENT_QUORUM + PENDING_POLL (poll side = P2)
+ *  - partial fan-out (D8): 2 destinations, one immediate fires, one quorum
+ *    blocks — gate_decisions carries per-destination rows
+ *  - E3 revocation post-approve blocks with RESET_ON_CHANGE; no snapshot
+ *    fails closed with OUTSIDE_POLICY
+ *
+ * Owns its own database (CHATGOV_IT_DATABASE_URL + CHATGOV_IT_SUPER_DATABASE_URL,
+ * P0 spine pattern) so it never races the shared tenancy suites. Skips clean.
+ */
+const appUrl = process.env.CHATGOV_IT_DATABASE_URL;
+const ownerUrl = process.env.CHATGOV_IT_SUPER_DATABASE_URL;
+const dbAvailable = appUrl !== undefined && ownerUrl !== undefined;
+
+type Modules = {
+  publishing: typeof import("./publishing.service.js");
+  gate: typeof import("./approval-gate.service.js");
+  chatgovGate: typeof import("../chatgov/gate.service.js");
+  policyService: typeof import("../chatgov/policy.service.js");
+  policy: typeof import("../chatgov/policy.js");
+  dispatchGate: typeof import("../../../scheduler/src/activities/dispatch-gate.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(!dbAvailable)("chatgov P1 gates (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let wsA: string;
+  let ownerId: string;
+  let adminId: string;
+  let approverId: string;
+  let connImmediate: string;
+  let connAdminOnly: string;
+  let connQuorum: string;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  async function inTenant<T>(wsId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [wsId]);
+      const result = await fn(client);
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      await client.query("ROLLBACK");
+      throw error;
+    } finally {
+      client.release();
+    }
+  }
+
+  /** state='passed'/'failed' rows must also satisfy the closed_at CHECK. */
+  async function seedPoll(draftId: string, state: "open" | "passed", createdBy: string): Promise<void> {
+    await inTenant(wsA, async (c) => {
+      await c.query(
+        `INSERT INTO polls (workspace_id, subject_kind, draft_id, question, rule, policy_version, closes_at, closed_at, close_reason, state, created_by)
+         VALUES ($1, 'draft', $2, 'ship it?', '{"version":1,"mode":"quorum","arms":[{"kind":"admins","x":2}],"join":"all"}'::jsonb, 'pv-x',
+                 now() + interval '1 hour',
+                 CASE WHEN $3::text = 'open'::text THEN NULL::timestamptz ELSE now() END,
+                 CASE WHEN $3::text = 'open'::text THEN NULL::text ELSE 'timebox'::text END,
+                 $3::text, $4)`,
+        [wsA, draftId, state, createdBy],
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    m = {
+      publishing: await import("./publishing.service.js"),
+      gate: await import("./approval-gate.service.js"),
+      chatgovGate: await import("../chatgov/gate.service.js"),
+      policyService: await import("../chatgov/policy.service.js"),
+      policy: await import("../chatgov/policy.js"),
+      dispatchGate: await import("../../../scheduler/src/activities/dispatch-gate.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    await asOwner(async (c) => {
+      wsA = (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", ["cg-p1", `cg-p1-${suffix}`])).rows[0].id as string;
+      const user = async (name: string): Promise<string> =>
+        (await c.query(
+          "INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4) RETURNING id",
+          [`cgp1:${name}:${suffix}`, `cgp1-${name}-${suffix}`, `cgp1-${name}-${suffix}@example.com`, name],
+        )).rows[0].id as string;
+      ownerId = await user("owner");
+      adminId = await user("admin");
+      approverId = await user("approver");
+      await c.query("INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, 'Owner', 'active')", [wsA, ownerId]);
+      await c.query("INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, 'Admin', 'active')", [wsA, adminId]);
+      await c.query("INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, 'Approver', 'active')", [wsA, approverId]);
+
+      const conn = async (name: string): Promise<string> =>
+        (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id", [wsA, `p1-${name}`])).rows[0].id as string;
+      connImmediate = await conn("immediate");
+      connAdminOnly = await conn("adminonly");
+      connQuorum = await conn("quorum");
+    });
+
+    // Compile policies the honest way — through PolicyService, exactly as the
+    // console does — so snapshots + versions are the production artifacts.
+    const policyService = new m.policyService.PolicyService();
+    const immediateRule = await policyService.createRule(wsA, { scope: "account", accountId: connImmediate, policy: { mode: "immediate" } }, { userId: ownerId, role: "Owner" });
+    const adminOnlyRule = await policyService.createRule(wsA, { scope: "account", accountId: connAdminOnly, policy: { mode: "admin_only", timebox: { duration: "PT2H", onExpire: "reject" } } }, { userId: ownerId, role: "Owner" });
+    const quorumRule = await policyService.createRule(wsA, { scope: "account", accountId: connQuorum, policy: { mode: "quorum", arms: [{ kind: "admins", x: 2 }], timebox: { duration: "PT2H", onExpire: "reject" } } }, { userId: ownerId, role: "Owner" });
+    expect(immediateRule.policy.mode).toBe("immediate");
+    expect(adminOnlyRule.policy.mode).toBe("admin_only");
+    expect(quorumRule.policy.mode).toBe("quorum");
+  }, 60_000);
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE slug = $1", [`cg-p1-${suffix}`]);
+        await c.query("DELETE FROM users WHERE external_id LIKE $1", [`cgp1:%:${suffix}`]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  /** Service wired exactly like AppModule: real gate, no workflow start. */
+  function makeService() {
+    return new m.publishing.PublishingService({
+      tenantTransaction: m.db.withTenant,
+      workflowStarter: { startScheduledPublish: async () => undefined },
+      repository: {
+        scheduleAttempt: async () => { throw new Error("not used"); },
+        cancelAttempt: async () => undefined,
+      } as never,
+      assertReady: async () => undefined,
+      approvalGate: new m.gate.ApprovalGateService(new m.chatgovGate.GateService()),
+    });
+  }
+
+  async function seedDraft(targets: string[], state: "editing" | "in_review" = "editing"): Promise<string> {
+    return asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [wsA]);
+      const post = { text: `p1 ${targets.join(",")}`, mediaAssetIds: [], visibility: "public", providerMetadata: { targetConnectionIds: targets } };
+      const id = (await c.query(
+        `INSERT INTO drafts (workspace_id, author_user_id, post, state) VALUES ($1, $2, $3::jsonb, $4) RETURNING id`,
+        [wsA, ownerId, JSON.stringify(post), state],
+      )).rows[0].id as string;
+      await c.query("COMMIT");
+      return id;
+    });
+  }
+
+  async function gateRows(draftId: string): Promise<Array<{ gate: string; outcome: string; reason_codes: string[]; destination: { accountId: string }; policy_version: string }>> {
+    return inTenant(wsA, async (c) =>
+      (await c.query("SELECT gate, outcome, reason_codes, destination, policy_version FROM gate_decisions WHERE draft_id = $1 ORDER BY created_at, id", [draftId])).rows as never,
+    );
+  }
+
+  // ---------------------------------------------------------------------
+  it("immediate: fires for any approver and pins the policy_version (E1 row, no block)", async () => {
+    const draftId = await seedDraft([connImmediate], "in_review");
+    const service = makeService();
+    const draft = await service.approve(wsA, { userId: approverId, role: "Approver" }, draftId);
+    expect(draft.state).toBe("approved");
+    const rows = await gateRows(draftId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ gate: "E1", outcome: "fired", reason_codes: [] });
+    expect(rows[0]?.destination.accountId).toBe(connImmediate);
+  });
+
+  it("workspace with NO rules: a draft posts exactly as today (gate no-op, zero rows)", async () => {
+    // Fresh workspace, no posting_rules at all — the pre-chatgov posture.
+    const wsPlain = await asOwner(async (c) => (await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", ["cg-p1-plain", `cg-p1-plain-${suffix}`])).rows[0].id as string);
+    try {
+      const plainConn = (await asOwner(async (c) => (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id", [wsPlain, "plain"])).rows[0].id)) as string;
+      const plainUser = (await asOwner(async (c) => (await c.query("INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, 'p') RETURNING id", [`cgp1:plain:${suffix}`, `cgp1-plain-${suffix}`, `cgp1-plain-${suffix}@e.com`])).rows[0].id)) as string;
+      await asOwner(async (c) => c.query("INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, 'Publisher', 'active')", [wsPlain, plainUser]));
+      const post = { text: "plain", mediaAssetIds: [], visibility: "public", providerMetadata: { connectionId: plainConn } };
+      const draftId = await inTenant(wsPlain, async (c) => (await c.query("INSERT INTO drafts (workspace_id, author_user_id, post, state) VALUES ($1, $2, $3::jsonb, 'in_review') RETURNING id", [wsPlain, plainUser, JSON.stringify(post)])).rows[0].id as string);
+      const service = makeService();
+      const draft = await service.approve(wsPlain, { userId: plainUser, role: "Publisher" }, draftId);
+      expect(draft.state).toBe("approved"); // unchanged behavior
+      const rows = await inTenant(wsPlain, async (c) => (await c.query("SELECT count(*)::int AS n FROM gate_decisions WHERE draft_id = $1", [draftId])).rows[0].n);
+      expect(rows).toBe(0); // no gate rows for an ungated workspace
+    } finally {
+      await asOwner(async (c) => { await c.query("DELETE FROM workspaces WHERE id = $1", [wsPlain]); await c.query("DELETE FROM users WHERE id = (SELECT id FROM users WHERE external_id = $1)", [`cgp1:plain:${suffix}`]); });
+    }
+  });
+
+  it("admin_only blocks a non-admin approver, then fires on one admin approve", async () => {
+    const draftId = await seedDraft([connAdminOnly], "in_review");
+    const service = makeService();
+
+    await expect(service.approve(wsA, { userId: approverId, role: "Approver" }, draftId)).rejects.toMatchObject({ response: { code: "APPROVAL_GATE_BLOCKED" } });
+    let state = await inTenant(wsA, async (c) => (await c.query("SELECT state FROM drafts WHERE id = $1", [draftId])).rows[0].state);
+    expect(state).toBe("in_review"); // approval did not land
+    let rows = await gateRows(draftId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ gate: "E1", outcome: "blocked", reason_codes: ["INSUFFICIENT_QUORUM", "INELIGIBLE_ACTOR"] });
+
+    const draft = await service.approve(wsA, { userId: adminId, role: "Admin" }, draftId);
+    expect(draft.state).toBe("approved");
+    state = await inTenant(wsA, async (c) => (await c.query("SELECT state FROM drafts WHERE id = $1", [draftId])).rows[0].state);
+    expect(state).toBe("approved");
+    rows = await gateRows(draftId);
+    expect(rows).toHaveLength(2);
+    expect(rows[1]).toMatchObject({ gate: "E1", outcome: "fired", reason_codes: [] });
+  });
+
+  it("quorum blocks with INSUFFICIENT_QUORUM + PENDING_POLL (poll side = P2)", async () => {
+    const draftId = await seedDraft([connQuorum], "in_review");
+    const service = makeService();
+    await expect(service.approve(wsA, { userId: ownerId, role: "Owner" }, draftId)).rejects.toMatchObject({ response: { code: "APPROVAL_GATE_BLOCKED" } });
+    const rows = await gateRows(draftId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ gate: "E1", outcome: "blocked", reason_codes: ["INSUFFICIENT_QUORUM", "PENDING_POLL"] });
+    // And once a poll row reaches 'passed' (the P2 close path), E1 fires:
+    await seedPoll(draftId, "passed", ownerId);
+    const draft = await service.approve(wsA, { userId: ownerId, role: "Owner" }, draftId);
+    expect(draft.state).toBe("approved");
+    const after = await gateRows(draftId);
+    expect(after[after.length - 1]).toMatchObject({ gate: "E1", outcome: "fired", reason_codes: [] });
+  });
+
+  it("partial fan-out (D8): immediate fires, quorum blocks — per-destination rows", async () => {
+    const draftId = await seedDraft([connImmediate, connQuorum], "in_review");
+    const service = makeService();
+    await expect(service.approve(wsA, { userId: ownerId, role: "Owner" }, draftId)).rejects.toMatchObject({ response: { code: "APPROVAL_GATE_BLOCKED" } });
+    const state = await inTenant(wsA, async (c) => (await c.query("SELECT state FROM drafts WHERE id = $1", [draftId])).rows[0].state);
+    expect(state).toBe("in_review"); // blocked side holds the approval back
+    const rows = await gateRows(draftId);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]).toMatchObject({ gate: "E1", outcome: "blocked", destination: { accountId: connQuorum }, reason_codes: ["INSUFFICIENT_QUORUM", "PENDING_POLL"] });
+    // queue surfaces the blocked destination with its codes
+    const blocked = rows.filter((r) => r.outcome === "blocked");
+    expect(blocked.map((r) => r.destination.accountId)).toEqual([connQuorum]);
+  });
+
+  it("blocked queue endpoint seam: GateService.listForDraft reads every E1/E3 row", async () => {
+    const draftId = await seedDraft([connQuorum], "in_review");
+    const service = makeService();
+    await expect(service.approve(wsA, { userId: ownerId, role: "Owner" }, draftId)).rejects.toBeTruthy();
+    const decisions = await new m.chatgovGate.GateService().listForDraft(wsA, draftId);
+    expect(decisions.length).toBeGreaterThanOrEqual(1);
+    expect(decisions[0]).toMatchObject({ gate: "E1", outcome: "blocked", reasonCodes: ["INSUFFICIENT_QUORUM", "PENDING_POLL"] });
+  });
+
+  // ---------------------------------------------------------------------
+  describe("E3 pre-dispatch re-check", () => {
+    let repository: PublishingExecutionRepository;
+    let gate: InstanceType<(typeof m)["dispatchGate"]["DispatchGateService"]>;
+
+    beforeAll(async () => {
+      repository = new PublishingExecutionRepository(new Pool({ connectionString: appUrl }));
+      gate = new m.dispatchGate.DispatchGateService(new Pool({ connectionString: appUrl }));
+      // scheduleAttempt requires an active connector-oauth credential per connection.
+      await asOwner(async (c) => {
+        for (const connectionId of [connImmediate, connAdminOnly, connQuorum]) {
+          await c.query(
+            "INSERT INTO credentials (workspace_id, connection_id, kind, ciphertext) VALUES ($1, $2, 'connector-oauth', '\\x00') ON CONFLICT DO NOTHING",
+            [wsA, connectionId],
+          );
+        }
+      });
+    });
+    afterAll(async () => { await repository["pool"]?.end?.(); });
+
+    async function approveAndSchedule(connectionId: string): Promise<{ draftId: string; idempotencyKey: string }> {
+      // scheduleAttempt's execution fence requires providerMetadata.connectionId
+      // to equal the target — single-destination post, exactly the §4 shape.
+      const draftId = await asOwner(async (c) => {
+        await c.query("BEGIN");
+        await c.query("SELECT set_config('app.workspace_id', $1, true)", [wsA]);
+        const post = { text: `p1 e3 ${connectionId}`, mediaAssetIds: [], visibility: "public", providerMetadata: { connectionId } };
+        const id = (await c.query(
+          `INSERT INTO drafts (workspace_id, author_user_id, post, state) VALUES ($1, $2, $3::jsonb, 'in_review') RETURNING id`,
+          [wsA, ownerId, JSON.stringify(post)],
+        )).rows[0].id as string;
+        await c.query("COMMIT");
+        return id;
+      });
+      const service = makeService();
+      // quorum needs the passed-poll seam (P2 owns the real transition)
+      if (connectionId === connQuorum) await seedPoll(draftId, "passed", ownerId);
+      await service.approve(wsA, { userId: ownerId, role: "Owner" }, draftId);
+      const attempt = await inTenant(wsA, async (c) => {
+        const scheduled = await repository.scheduleAttempt(c, {
+          workspaceId: wsA, draftId, connectionId, scheduledByUserId: ownerId,
+          requiredPermission: "publication.publish", publishAt: new Date(Date.now() - 1000),
+        });
+        return { idempotencyKey: scheduled.idempotencyKey, scheduleId: scheduled.scheduleId, generation: scheduled.generation };
+      });
+      return { draftId, idempotencyKey: attempt.idempotencyKey };
+    }
+
+    it("fires a live approved immediate destination", async () => {
+      const { draftId, idempotencyKey } = await approveAndSchedule(connImmediate);
+      const outcome = await gate.check({ workspaceId: wsA, draftId, idempotencyKey, connectionId: connImmediate, platform: "mock-social" });
+      expect(outcome).toMatchObject({ outcome: "fired", reasonCodes: [] });
+    });
+
+    it("revocation post-approve blocks with RESET_ON_CHANGE and never sends", async () => {
+      const { draftId, idempotencyKey } = await approveAndSchedule(connImmediate);
+      await inTenant(wsA, async (c) => {
+        await c.query("UPDATE drafts SET state = 'rejected', approved_hash = NULL, approved_revision = NULL, reviewer_user_id = NULL WHERE id = $1", [draftId]);
+      });
+      const outcome = await gate.check({ workspaceId: wsA, draftId, idempotencyKey, connectionId: connImmediate, platform: "mock-social" });
+      expect(outcome.outcome).toBe("blocked");
+      expect(outcome.reasonCodes).toEqual(["RESET_ON_CHANGE"]);
+      const rows = await gateRows(draftId);
+      expect(rows.some((r) => r.gate === "E3" && r.reason_codes.includes("RESET_ON_CHANGE"))).toBe(true);
+    });
+
+    it("draft edit after approve blocks with RESET_ON_CHANGE (hash re-pinned)", async () => {
+      const { draftId, idempotencyKey } = await approveAndSchedule(connImmediate);
+      await inTenant(wsA, async (c) => {
+        await c.query("UPDATE drafts SET state = 'editing', approved_hash = NULL, approved_revision = NULL WHERE id = $1", [draftId]);
+      });
+      const outcome = await gate.check({ workspaceId: wsA, draftId, idempotencyKey, connectionId: connImmediate, platform: "mock-social" });
+      expect(outcome.reasonCodes).toEqual(["RESET_ON_CHANGE"]);
+    });
+
+    it("no snapshot fails closed with OUTSIDE_POLICY", async () => {
+      // A brand-new connection has no compiled snapshot (PolicyService only
+      // recompiles on rule changes): once rules exist, approving a post
+      // targeting it must fail closed.
+      const fresh = await asOwner(async (c) =>
+        (await c.query("INSERT INTO connections (workspace_id, provider, channel_id) VALUES ($1, 'mock-social', $2) RETURNING id", [wsA, `p1-outside-${suffix}`])).rows[0].id as string
+      );
+      const draftId = await seedDraft([fresh], "in_review");
+      const service = makeService();
+      await expect(service.approve(wsA, { userId: ownerId, role: "Owner" }, draftId)).rejects.toMatchObject({ response: { code: "APPROVAL_GATE_BLOCKED" } });
+      const rows = await gateRows(draftId);
+      expect(rows[0]).toMatchObject({ gate: "E1", outcome: "blocked", reason_codes: ["OUTSIDE_POLICY"] });
+    });
+
+    it("quorum destination still blocked at E3 while the poll is open", async () => {
+      // Approve through the poll seam, then REOPEN the poll (P2 failure /
+      // re-vote path): E3 must re-check the live poll state at dispatch time.
+      const { draftId, idempotencyKey } = await approveAndSchedule(connQuorum);
+      await inTenant(wsA, async (c) => {
+        await c.query("UPDATE polls SET state = 'open', closed_at = NULL, close_reason = NULL WHERE draft_id = $1", [draftId]);
+      });
+      const outcome = await gate.check({ workspaceId: wsA, draftId, idempotencyKey, connectionId: connQuorum, platform: "mock-social" });
+      expect(outcome.outcome).toBe("blocked");
+      expect(outcome.reasonCodes).toEqual(["INSUFFICIENT_QUORUM", "PENDING_POLL"]);
+    });
+  });
+});
diff --git a/apps/api/src/publishing/approval-gate.service.ts b/apps/api/src/publishing/approval-gate.service.ts
new file mode 100644
index 0000000..b18390b
--- /dev/null
+++ b/apps/api/src/publishing/approval-gate.service.ts
@@ -0,0 +1,402 @@
+import { ConflictException, Injectable, Optional, Inject } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { scrub } from "../audit/audit.service.js";
+import { GateService, type DestinationRef, type GateDecisionRecord, type QuorumArmState } from "../chatgov/gate.service.js";
+import type { GateMode, PolicyRule, ReasonCode } from "../chatgov/policy.js";
+import { REASON_CODES } from "../chatgov/policy.js";
+import type { DraftPost } from "./publishing.service.js";
+
+/**
+ * E1 approval gate (chatgov-design.md §4, P1): evaluated on the
+ * `review → approved` transition, PER DESTINATION (fan-out law D8).
+ *
+ * Mode semantics (§1d/§4):
+ *   immediate   — no gate. The E1 row is still recorded (it pins the
+ *                 policy_version E3 later re-checks) but nothing blocks.
+ *   admin_only  — the admin's approve IS the quorum ({kind:admins,x:1}). An
+ *                 approver who holds approval.grant but is not Owner/Admin
+ *                 does NOT satisfy the arm (INELIGIBLE_ACTOR) and the
+ *                 approval is refused until one admin approves.
+ *   quorum      — blocked until the linked chat poll passes (P2 owns the poll
+ *                 state machine). For P1 every console approve of a
+ *                 quorum-gated destination blocks with INSUFFICIENT_QUORUM +
+ *                 PENDING_POLL; once a polls row reaches state='passed' (the
+ *                 P2 close path) E1 fires.
+ *
+ * A destination with NO compiled snapshot posts as today: no gate, no row.
+ * A destination whose connection is not visible in the tenant (foreign or
+ * unknown id) fails closed with OUTSIDE_POLICY.
+ *
+ * Writes go to gate_decisions (P0 spine). Fired verdicts are written with the
+ * SAME client as the approval so the decision commits atomically with the
+ * transition and pins exactly the policy_version the approval landed under.
+ * Blocked verdicts cannot share that transaction — the approval rolls back —
+ * so they are recorded through GateService.record after the rollback, when no
+ * locks are held. (gate_decisions carries FOREIGN KEY (draft_id, workspace_id)
+ * REFERENCES drafts; an INSERT takes a KEY SHARE lock on the draft row, which
+ * the approval transaction's FOR UPDATE would deadlock against if the blocked
+ * rows were written before the throw.)
+ */
+
+export const APPROVAL_GATE_ADMIN_ROLES: readonly string[] = ["Owner", "Admin"];
+
+/** Thrown by the E1 hook to abort an approval; carries the per-destination verdicts. */
+export class ApprovalGateBlockedError extends ConflictException {
+  constructor(readonly verdicts: readonly E1Verdict[]) {
+    super({
+      code: "APPROVAL_GATE_BLOCKED",
+      message: "approval blocked by posting policy for one or more destinations",
+      destinations: verdicts.map((verdict) => ({
+        destination: verdict.destination,
+        mode: verdict.mode,
+        reasonCodes: verdict.reasonCodes,
+      })),
+    });
+  }
+}
+
+export interface E1Verdict {
+  destination: DestinationRef;
+  /** Effective mode at evaluation; "none" = no compiled snapshot (ungated). */
+  mode: GateMode | "none";
+  policyVersion: string | null;
+  outcome: "fired" | "blocked";
+  reasonCodes: ReasonCode[];
+  inputs: {
+    approvals?: number;
+    arms?: QuorumArmState[];
+    pollState?: string;
+    policyMode?: GateMode | "none";
+    [key: string]: unknown;
+  };
+}
+
+export interface E1Evaluation {
+  verdicts: E1Verdict[];
+  blocked: E1Verdict[];
+  fired: E1Verdict[];
+}
+
+const MISSING_TABLE = "42P01";
+
+/**
+ * Pure E1 decision for ONE destination (unit-testable, no DB).
+ * `rule`/`policyVersion` are the destination's compiled snapshot; undefined
+ * means no snapshot row exists for the account (ungated, posts as today).
+ */
+export function evaluateE1Destination(input: {
+  destination: DestinationRef;
+  rule: PolicyRule | undefined;
+  policyVersion: string | undefined;
+  /** Approver holds an active Owner/Admin membership in the workspace. */
+  adminApproval: boolean;
+  /** A polls row for this draft has reached state='passed' (P2 close path). */
+  pollPassed: boolean;
+  pollState: string;
+}): E1Verdict {
+  const { destination, adminApproval, pollPassed, pollState } = input;
+  if (input.rule === undefined || input.policyVersion === undefined) {
+    // No compiled snapshot: post as today — no gate, no reason codes.
+    return {
+      destination,
+      mode: "none",
+      policyVersion: null,
+      outcome: "fired",
+      reasonCodes: [],
+      inputs: { approvals: adminApproval ? 1 : 0, policyMode: "none" },
+    };
+  }
+  const rule = input.rule;
+  const policyVersion = input.policyVersion;
+  switch (rule.mode) {
+    case "immediate":
+      return {
+        destination,
+        mode: "immediate",
+        policyVersion,
+        outcome: "fired",
+        reasonCodes: [],
+        inputs: { approvals: adminApproval ? 1 : 0, policyMode: "immediate" },
+      };
+    case "admin_only": {
+      // §1d: admin_only = quorum:[{kind:admins,x:1}] with no participant arm —
+      // one admin approve satisfies it (§4 "admin_only mode = same path with
+      // a 1-arm poll or an E1-only console approval").
+      const arms: QuorumArmState[] = [{ kind: "admins", got: adminApproval ? 1 : 0, needed: 1 }];
+      return adminApproval
+        ? { destination, mode: "admin_only", policyVersion, outcome: "fired", reasonCodes: [], inputs: { approvals: 1, arms, policyMode: "admin_only" } }
+        : {
+            destination,
+            mode: "admin_only",
+            policyVersion,
+            outcome: "blocked",
+            reasonCodes: ["INSUFFICIENT_QUORUM", "INELIGIBLE_ACTOR"],
+            inputs: { approvals: 0, arms, policyMode: "admin_only" },
+          };
+    }
+    case "quorum": {
+      const arms: QuorumArmState[] = (rule.arms ?? []).map((arm) => ({
+        kind: arm.kind,
+        got: pollPassed ? arm.x : 0,
+        needed: arm.x,
+      }));
+      return pollPassed
+        ? { destination, mode: "quorum", policyVersion, outcome: "fired", reasonCodes: [], inputs: { approvals: 1, arms, pollState: "passed", policyMode: "quorum" } }
+        : {
+            destination,
+            mode: "quorum",
+            policyVersion,
+            outcome: "blocked",
+            reasonCodes: ["INSUFFICIENT_QUORUM", "PENDING_POLL"],
+            inputs: { approvals: 0, arms, pollState, policyMode: "quorum" },
+          };
+    }
+  }
+}
+
+/** Destination connection ids carried by a draft's post metadata (fan-out D8). */
+export function draftDestinationAccounts(post: DraftPost): string[] {
+  const metadata = post.providerMetadata ?? {};
+  const targets = Array.isArray(metadata.targetConnectionIds)
+    ? metadata.targetConnectionIds.filter((id): id is string => typeof id === "string")
+    : typeof metadata.connectionId === "string"
+      ? [metadata.connectionId]
+      : [];
+  return [...new Set(targets)];
+}
+
+interface SnapshotRow {
+  account_id: string;
+  topic_binding_id: string | null;
+  effective: PolicyRule;
+  policy_version: string;
+}
+
+@Injectable()
+export class ApprovalGateService {
+  private readonly gates: GateService;
+
+  constructor(@Optional() @Inject(GateService) gates?: GateService) {
+    this.gates = gates ?? new GateService();
+  }
+
+  /** Blocked-queue / draft gate timeline (GET /publishing/drafts/:id/gates). */
+  async listForDraft(workspaceId: string, draftId: string): Promise<GateDecisionRecord[]> {
+    return this.gates.listForDraft(workspaceId, draftId);
+  }
+
+  /**
+   * Read + evaluate every destination of a draft. Runs INSIDE the approval
+   * transaction (consistent snapshot under the draft row lock) but performs
+   * no writes. Returns an empty evaluation when the draft has no destination
+   * metadata or chatgov is not deployed (missing tables) — both post as today.
+   */
+  async evaluate(
+    client: PoolClient,
+    workspaceId: string,
+    draftId: string,
+    post: DraftPost,
+    approverUserId: string,
+  ): Promise<E1Evaluation> {
+    const accountIds = draftDestinationAccounts(post);
+    if (accountIds.length === 0) return { verdicts: [], blocked: [], fired: [] };
+    // Lazily detect chatgov deployment: a workspace that predates the spine
+    // (or a suite DB without migration 024) keeps today's ungated behavior.
+    let deployed = true;
+    try {
+      await client.query("SELECT 1 FROM posting_rules LIMIT 1");
+    } catch (error) {
+      if (pgCode(error) === MISSING_TABLE) deployed = false;
+      else throw error;
+    }
+    if (!deployed) return { verdicts: [], blocked: [], fired: [] };
+
+    let connections: Map<string, string>;
+    let snapshots: SnapshotRow[];
+    let chatgovInUse: boolean;
+    let adminApproval: boolean;
+    let pollPassed: boolean;
+    let pollState: string;
+    try {
+      const connectionRows = await client.query<{ id: string; provider: string }>(
+        "SELECT id, provider FROM connections WHERE id = ANY($1::uuid[]) AND disconnected_at IS NULL",
+        [accountIds],
+      );
+      connections = new Map(connectionRows.rows.map((row) => [String(row.id), String(row.provider)]));
+      const snapshotRows = await client.query<SnapshotRow>(
+        "SELECT account_id, topic_binding_id, effective, policy_version FROM posting_policy_snapshots WHERE account_id = ANY($1::uuid[]) AND content_type = ''",
+        [accountIds],
+      );
+      snapshots = snapshotRows.rows;
+      // A workspace with no live posting_rules has never opted into chatgov:
+      // every destination posts exactly as before (no gates, no rows).
+      const liveRules = await client.query<{ n: number }>(
+        "SELECT count(*)::int AS n FROM posting_rules WHERE superseded_by IS NULL",
+      );
+      chatgovInUse = Number(liveRules.rows[0]?.n ?? 0) > 0;
+      const membership = await client.query<{ role: string }>(
+        "SELECT role FROM memberships WHERE workspace_id = $1 AND user_id = $2 AND status = 'active'",
+        [workspaceId, approverUserId],
+      );
+      adminApproval = membership.rows.some((row) => APPROVAL_GATE_ADMIN_ROLES.includes(String(row.role)));
+      const poll = await client.query<{ state: string }>(
+        "SELECT state FROM polls WHERE draft_id = $1 ORDER BY created_at DESC LIMIT 1",
+        [draftId],
+      );
+      pollState = String(poll.rows[0]?.state ?? "none");
+      pollPassed = poll.rows.some((row) => String(row.state) === "passed");
+    } catch (error) {
+      if (pgCode(error) === MISSING_TABLE) return { verdicts: [], blocked: [], fired: [] }; // chatgov not deployed
+      throw error;
+    }
+
+    const topicBindingId = typeof post.providerMetadata?.topicBindingId === "string" ? post.providerMetadata.topicBindingId : null;
+    const verdicts: E1Verdict[] = accountIds.map((accountId) => {
+      const destination: DestinationRef = {
+        platform: connections.get(accountId) ?? "unknown",
+        accountId,
+        ...(topicBindingId === null ? {} : { topicBindingId }),
+      };
+      if (!chatgovInUse) {
+        // No live rules anywhere in this workspace: it has not opted into
+        // governance, so every destination posts exactly as before.
+        return evaluateE1Destination({ destination, rule: undefined, policyVersion: undefined, adminApproval, pollPassed, pollState });
+      }
+      if (!connections.has(accountId)) {
+        // Fail closed: the destination is not a visible connection of this
+        // tenant (§1d fallback:block posture — OUTSIDE_POLICY).
+        return {
+          destination,
+          mode: "none" as const,
+          policyVersion: null,
+          outcome: "blocked" as const,
+          reasonCodes: ["OUTSIDE_POLICY" as ReasonCode],
+          inputs: { policyMode: "none" as const, connectionVisible: false },
+        };
+      }
+      // Precedence per destination slot: a topic snapshot overrides the
+      // account root; the account root is the compiled default.
+      const accountSnapshots = snapshots.filter((row) => String(row.account_id) === accountId);
+      const snapshot =
+        (topicBindingId !== null ? accountSnapshots.find((row) => row.topic_binding_id === topicBindingId) : undefined) ??
+        accountSnapshots.find((row) => row.topic_binding_id === null);
+      if (snapshot === undefined) {
+        // Rules exist but this destination has no compiled snapshot: the
+        // P0 hand-off posture — fail closed, never a silent ungated send.
+        return {
+          destination,
+          mode: "none",
+          policyVersion: null,
+          outcome: "blocked",
+          reasonCodes: ["OUTSIDE_POLICY"],
+          inputs: { policyMode: "none", connectionVisible: true },
+        };
+      }
+      return evaluateE1Destination({
+        destination,
+        rule: snapshot?.effective,
+        policyVersion: snapshot?.policy_version,
+        adminApproval,
+        pollPassed,
+        pollState,
+      });
+    });
+    return {
+      verdicts,
+      blocked: verdicts.filter((verdict) => verdict.outcome === "blocked"),
+      fired: verdicts.filter((verdict) => verdict.outcome === "fired"),
+    };
+  }
+
+  /**
+   * Persist FIRED verdicts in the caller's transaction (the approval's own
+   * client): the decision row commits atomically with the `approved`
+   * transition and pins the exact policy_version the approval landed under.
+   */
+  async recordFiredInTxn(
+    client: PoolClient,
+    workspaceId: string,
+    draftId: string,
+    actorUserId: string,
+    verdicts: readonly E1Verdict[],
+  ): Promise<void> {
+    for (const verdict of verdicts) {
+      if (verdict.outcome !== "fired" || verdict.mode === "none") continue; // ungated: no gate, no row
+      await insertDecision(client, workspaceId, draftId, verdict, "user", actorUserId);
+    }
+  }
+
+  /**
+   * Persist BLOCKED verdicts after the approval rolled back (no draft row
+   * lock is held, so the gate_decisions FK KEY SHARE cannot deadlock).
+   */
+  async recordBlocked(
+    workspaceId: string,
+    draftId: string,
+    actorUserId: string,
+    verdicts: readonly E1Verdict[],
+  ): Promise<void> {
+    for (const verdict of verdicts) {
+      if (verdict.outcome !== "blocked") continue;
+      await this.gates.record(workspaceId, {
+        draftId,
+        destination: verdict.destination,
+        gate: "E1",
+        policyVersion: verdict.policyVersion ?? "none",
+        outcome: "blocked",
+        inputs: verdict.inputs,
+        reasonCodes: verdict.reasonCodes,
+        actor: `user:${actorUserId}`,
+      });
+    }
+  }
+}
+
+/** Same row shape GateService.record writes (reason codes stay in-vocabulary). */
+async function insertDecision(
+  client: PoolClient,
+  workspaceId: string,
+  draftId: string,
+  verdict: E1Verdict,
+  actorKind: "user" | "system",
+  actorId: string,
+): Promise<void> {
+  const reasonCodes = verdict.reasonCodes.filter((code) => (REASON_CODES as readonly string[]).includes(code));
+  await client.query(
+    `INSERT INTO gate_decisions
+       (workspace_id, draft_id, destination, gate, policy_version, outcome, inputs, reason_codes, actor)
+     VALUES ($1, $2, $3::jsonb, 'E1', $4, $5, $6::jsonb, $7, $8)`,
+    [
+      workspaceId,
+      draftId,
+      JSON.stringify(verdict.destination),
+      verdict.policyVersion ?? "none",
+      verdict.outcome,
+      JSON.stringify(verdict.inputs),
+      reasonCodes,
+      `${actorKind}:${actorId}`,
+    ],
+  );
+  await client.query("SELECT audit_append($1, NULL, 'sp_api', 'policy.gate', 'draft', $2, $3::jsonb)", [
+    workspaceId,
+    draftId,
+    JSON.stringify(
+      scrub({
+        gate: "E1",
+        destination: verdict.destination,
+        outcome: verdict.outcome,
+        reasonCodes,
+        policyVersion: verdict.policyVersion ?? "none",
+        inputs: verdict.inputs,
+      }) ?? {},
+    ),
+  ]);
+}
+
+function pgCode(error: unknown): string | undefined {
+  if (typeof error === "object" && error !== null && "code" in error) {
+    const code = (error as { code: unknown }).code;
+    return typeof code === "string" ? code : undefined;
+  }
+  return undefined;
+}
diff --git a/apps/api/src/publishing/approval-gate.test.ts b/apps/api/src/publishing/approval-gate.test.ts
new file mode 100644
index 0000000..89a8b2e
--- /dev/null
+++ b/apps/api/src/publishing/approval-gate.test.ts
@@ -0,0 +1,106 @@
+import { ConflictException } from "@nestjs/common";
+import { describe, expect, it } from "vitest";
+import {
+  ApprovalGateBlockedError,
+  APPROVAL_GATE_ADMIN_ROLES,
+  draftDestinationAccounts,
+  evaluateE1Destination,
+} from "./approval-gate.service.js";
+import { policyHash, type PolicyRule } from "../chatgov/policy.js";
+
+/**
+ * E1 gate semantics (chatgov-design.md §4) — pure decision table, no DB.
+ */
+
+const destination = { platform: "telegram", accountId: "40000000-0000-4000-8000-000000000004" };
+
+function rule(mode: PolicyRule["mode"], extra: Partial<PolicyRule> = {}): PolicyRule {
+  return {
+    version: 1,
+    mode,
+    join: "all",
+    allowVeto: false,
+    minDwellSeconds: 0,
+    anonymity: "named",
+    allowSelfApproval: false,
+    resetOnChange: true,
+    dryRun: false,
+    ...(mode === "quorum" ? { arms: [{ kind: "admins", x: 2 }], timebox: { duration: "PT2H", onExpire: "reject" } } : {}),
+    ...(mode === "admin_only" ? { timebox: { duration: "PT2H", onExpire: "reject" } } : {}),
+    ...extra,
+  } as PolicyRule;
+}
+
+describe("E1 destination evaluation (chatgov §4 modes)", () => {
+  it("no snapshot: ungated — posts as today, no gate row, no reason codes", () => {
+    const verdict = evaluateE1Destination({ destination, rule: undefined, policyVersion: undefined, adminApproval: false, pollPassed: false, pollState: "none" });
+    expect(verdict).toMatchObject({ mode: "none", outcome: "fired", reasonCodes: [], policyVersion: null });
+  });
+
+  it("immediate: fires with no gate and pins the policy_version", () => {
+    const compiled = rule("immediate");
+    const verdict = evaluateE1Destination({ destination, rule: compiled, policyVersion: policyHash(compiled), adminApproval: false, pollPassed: false, pollState: "none" });
+    expect(verdict).toMatchObject({ mode: "immediate", outcome: "fired", reasonCodes: [] });
+    expect(verdict.policyVersion).toBe(policyHash(compiled));
+  });
+
+  it("admin_only: one admin approve IS the quorum (fires)", () => {
+    const compiled = rule("admin_only");
+    const verdict = evaluateE1Destination({ destination, rule: compiled, policyVersion: policyHash(compiled), adminApproval: true, pollPassed: false, pollState: "none" });
+    expect(verdict).toMatchObject({ mode: "admin_only", outcome: "fired", reasonCodes: [] });
+    expect(verdict.inputs.arms).toEqual([{ kind: "admins", got: 1, needed: 1 }]);
+  });
+
+  it("admin_only: non-admin approver blocks (INELIGIBLE_ACTOR + INSUFFICIENT_QUORUM)", () => {
+    const compiled = rule("admin_only");
+    const verdict = evaluateE1Destination({ destination, rule: compiled, policyVersion: policyHash(compiled), adminApproval: false, pollPassed: false, pollState: "none" });
+    expect(verdict.outcome).toBe("blocked");
+    expect(verdict.reasonCodes).toEqual(["INSUFFICIENT_QUORUM", "INELIGIBLE_ACTOR"]);
+    expect(verdict.inputs.arms).toEqual([{ kind: "admins", got: 0, needed: 1 }]);
+  });
+
+  it("quorum: blocks with INSUFFICIENT_QUORUM + PENDING_POLL until the poll passes (P2)", () => {
+    const compiled = rule("quorum");
+    const verdict = evaluateE1Destination({ destination, rule: compiled, policyVersion: policyHash(compiled), adminApproval: true, pollPassed: false, pollState: "open" });
+    expect(verdict.outcome).toBe("blocked");
+    expect(verdict.reasonCodes).toEqual(["INSUFFICIENT_QUORUM", "PENDING_POLL"]);
+    expect(verdict.inputs.pollState).toBe("open");
+    expect(verdict.inputs.arms).toEqual([{ kind: "admins", got: 0, needed: 2 }]);
+  });
+
+  it("quorum: fires when the linked poll has passed", () => {
+    const compiled = rule("quorum");
+    const verdict = evaluateE1Destination({ destination, rule: compiled, policyVersion: policyHash(compiled), adminApproval: true, pollPassed: true, pollState: "passed" });
+    expect(verdict).toMatchObject({ mode: "quorum", outcome: "fired", reasonCodes: [] });
+    expect(verdict.inputs.arms).toEqual([{ kind: "admins", got: 2, needed: 2 }]);
+  });
+});
+
+describe("draft destination fan-out (D8)", () => {
+  it("reads targetConnectionIds, falling back to connectionId", () => {
+    const a = "40000000-0000-4000-8000-000000000004";
+    const b = "40000000-0000-4000-8000-000000000005";
+    expect(draftDestinationAccounts({ text: "x", mediaAssetIds: [], visibility: "public", providerMetadata: { targetConnectionIds: [a, b] } })).toEqual([a, b]);
+    expect(draftDestinationAccounts({ text: "x", mediaAssetIds: [], visibility: "public", providerMetadata: { connectionId: a } })).toEqual([a]);
+    expect(draftDestinationAccounts({ text: "x", mediaAssetIds: [], visibility: "public", providerMetadata: {} })).toEqual([]);
+  });
+
+  it("admin roles are exactly Owner/Admin (§1a admins arm)", () => {
+    expect(APPROVAL_GATE_ADMIN_ROLES).toEqual(["Owner", "Admin"]);
+  });
+});
+
+describe("ApprovalGateBlockedError", () => {
+  it("carries per-destination codes as a Conflict the controller maps to 409", () => {
+    const compiled = rule("quorum");
+    const error = new ApprovalGateBlockedError([
+      evaluateE1Destination({ destination, rule: compiled, policyVersion: policyHash(compiled), adminApproval: false, pollPassed: false, pollState: "open" }),
+    ]);
+    expect(error).toBeInstanceOf(ConflictException);
+    expect(error.getResponse()).toMatchObject({ code: "APPROVAL_GATE_BLOCKED" });
+    expect((error.getResponse() as { destinations: unknown[] }).destinations[0]).toMatchObject({
+      mode: "quorum",
+      reasonCodes: ["INSUFFICIENT_QUORUM", "PENDING_POLL"],
+    });
+  });
+});
diff --git a/apps/api/src/publishing/poll-approval.ts b/apps/api/src/publishing/poll-approval.ts
new file mode 100644
index 0000000..1e219d0
--- /dev/null
+++ b/apps/api/src/publishing/poll-approval.ts
@@ -0,0 +1,45 @@
+import { ConflictException } from '@nestjs/common';
+import { canonicalPostHash } from '@tactical-media-broadcast-hub/publishing-execution';
+import type { PoolClient } from 'pg';
+import { ApprovalGateService } from './approval-gate.service.js';
+import type { DraftPost } from './publishing.service.js';
+
+/** E2's transactional publishing seam. A System audit actor delegates to a
+ * live Owner/Admin approval principal so the existing dispatch authorization
+ * continues to validate a real, revocable membership; no permission bypass. */
+export async function transitionPollDraft(client: PoolClient, input: {
+  workspaceId: string; draftId: string; pollId: string; passed: boolean;
+  text?: string; reason: string; escalate?: boolean;
+}): Promise<void> {
+  const current = (await client.query('SELECT * FROM drafts WHERE id = $1 FOR UPDATE', [input.draftId])).rows[0];
+  if (!current || !['editing', 'in_review'].includes(String(current.state))) throw new ConflictException('poll subject is no longer reviewable');
+  if (input.escalate) return;
+  if (input.passed && input.text !== undefined) {
+    // Separate writes are necessary: the revision trigger voids approval
+    // whenever content changes. Approve only the resulting revision/hash.
+    await client.query("UPDATE drafts SET post = jsonb_set(post, '{text}', to_jsonb($2::text)), updated_at = now() WHERE id = $1", [input.draftId, input.text]);
+  }
+  const draft = (await client.query('SELECT * FROM drafts WHERE id = $1', [input.draftId])).rows[0]!;
+  let reviewer: string | null = null;
+  if (input.passed) {
+    reviewer = (await client.query(`SELECT m.user_id FROM memberships m
+      JOIN role_permissions rp ON rp.role = m.role AND rp.permission = 'approval.grant'
+      WHERE m.workspace_id = $1 AND m.status = 'active' AND m.role IN ('Owner', 'Admin')
+      ORDER BY CASE m.role WHEN 'Owner' THEN 0 ELSE 1 END, m.user_id LIMIT 1`, [input.workspaceId])).rows[0]?.user_id as string | undefined ?? null;
+    if (!reviewer) throw new ConflictException('poll approval needs a live Owner/Admin authorizing principal');
+    const gate = new ApprovalGateService();
+    const evaluation = await gate.evaluate(client, input.workspaceId, input.draftId, draft.post as DraftPost, reviewer);
+    if (evaluation.blocked.length) throw new ConflictException({ code: 'OUTSIDE_POLICY', message: 'poll passed but E1 still blocks the draft', verdicts: evaluation.blocked });
+    await gate.recordFiredInTxn(client, input.workspaceId, input.draftId, reviewer, evaluation.verdicts);
+  }
+  await client.query(`UPDATE drafts SET state = $2, reviewer_user_id = $3,
+    approved_revision = CASE WHEN $2 = 'approved' THEN revision ELSE NULL END,
+    approved_hash = $4, approved_at = CASE WHEN $2 = 'approved' THEN now() ELSE NULL END,
+    review_reason = $5, updated_at = now() WHERE id = $1`,
+  [input.draftId, input.passed ? 'approved' : 'rejected', reviewer,
+    input.passed ? canonicalPostHash(draft.post as DraftPost) : null, input.reason]);
+  await client.query("SELECT audit_append($1, NULL, 'System', $2, 'draft', $3, $4)", [input.workspaceId,
+    input.passed ? 'draft.approved' : 'draft.rejected', input.draftId,
+    { actor: `system:chat-poll-gate:${input.pollId}`, pollId: input.pollId,
+      authorizingUserId: reviewer, from: current.state, to: input.passed ? 'approved' : 'rejected', reason: input.reason }]);
+}
diff --git a/apps/api/src/publishing/publishing.controller.ts b/apps/api/src/publishing/publishing.controller.ts
new file mode 100644
index 0000000..127b0ee
--- /dev/null
+++ b/apps/api/src/publishing/publishing.controller.ts
@@ -0,0 +1,300 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  Inject,
+  Param,
+  Patch,
+  Post,
+  Query,
+  Req,
+  UseGuards,
+} from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, RequireGroupAccess, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { ApprovalGateService } from "./approval-gate.service.js";
+import type { GateDecisionRecord } from "../chatgov/gate.service.js";
+import {
+  PublishingService,
+  type Actor,
+  type DraftPost,
+  type DraftRecord,
+  type DraftState,
+  type ScheduledPublicationRecord,
+} from "./publishing.service.js";
+
+export interface CreateDraftDto {
+  post: DraftPost;
+}
+
+export interface RejectDraftDto {
+  reason?: string;
+}
+
+export interface ScheduleDraftDto {
+  connectionId: string;
+  publishAt: string;
+}
+
+@Controller("publishing/drafts")
+@UseGuards(RbacGuard)
+export class PublishingController {
+  constructor(
+    @Inject(PublishingService) private readonly publishing: PublishingService,
+    @Inject(ApprovalGateService) private readonly gates: ApprovalGateService,
+  ) {}
+
+  @Get()
+  @RequirePermission("draft.view")
+  async list(
+    @Req() request: Request & AuthenticatedRequest,
+    @Query("state") state: string | undefined,
+    @Query("limit") limit: string | undefined,
+  ): Promise<DraftRecord[]> {
+    const session = requireSession(request);
+    return this.publishing.listDrafts(session.workspaceId, {
+      ...(state === undefined || state === "" ? {} : { state: parseDraftState(state) }),
+      limit: parseListLimit(limit),
+    });
+  }
+
+  /**
+   * Blocked queue surfacing (chatgov-design.md §5): per-destination gate
+   * decisions for one draft — outcome, reason codes, quorum gap, pinned
+   * policy_version. Reads the P0 gate_decisions spine via GateService.
+   */
+  @Get(":draftId/gates")
+  @RequirePermission("draft.view")
+  async gatesForDraft(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+  ): Promise<GateDecisionRecord[]> {
+    const session = requireSession(request);
+    return this.gates.listForDraft(session.workspaceId, parseId(draftId));
+  }
+
+  @Post()
+  @RequirePermission("draft.create")
+  async create(
+    @Req() request: Request & AuthenticatedRequest,
+    @Body() body: unknown,
+  ): Promise<DraftRecord> {
+    const dto = parseCreateDraft(body);
+    const session = requireSession(request);
+    return this.publishing.createDraft(session.workspaceId, actorFrom(session), dto.post);
+  }
+
+  @Patch(":draftId")
+  @RequirePermission("draft.edit")
+  async update(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+    @Body() body: unknown,
+  ): Promise<DraftRecord> {
+    const dto = parseCreateDraft(body);
+    const session = requireSession(request);
+    return this.publishing.updateDraft(session.workspaceId, actorFrom(session), parseId(draftId), dto.post);
+  }
+
+  @Post(":draftId/submit")
+  @RequirePermission("approval.request")
+  async submit(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+  ): Promise<DraftRecord> {
+    const session = requireSession(request);
+    return this.publishing.submitForReview(session.workspaceId, actorFrom(session), parseId(draftId));
+  }
+
+  @Post(":draftId/approve")
+  @RequirePermission("approval.grant")
+  async approve(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+  ): Promise<DraftRecord> {
+    const session = requireSession(request);
+    return this.publishing.approve(session.workspaceId, actorFrom(session), parseId(draftId));
+  }
+
+  @Post(":draftId/reject")
+  @RequirePermission("approval.grant")
+  async reject(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+    @Body() body: unknown,
+  ): Promise<DraftRecord> {
+    const session = requireSession(request);
+    const dto = parseRejectDraft(body);
+    return this.publishing.reject(session.workspaceId, actorFrom(session), parseId(draftId), dto.reason);
+  }
+
+  @Post(":draftId/schedule")
+  @HttpCode(202)
+  @RequirePermission("publication.schedule")
+  @RequireGroupAccess("body")
+  async schedule(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+    @Body() body: unknown,
+  ): Promise<ScheduledPublicationRecord> {
+    const session = requireSession(request);
+    const dto = parseScheduleDraft(body);
+    return this.publishing.schedule(
+      session.workspaceId,
+      actorFrom(session),
+      parseId(draftId),
+      dto.connectionId,
+      new Date(dto.publishAt),
+    );
+  }
+
+  @Post(":draftId/publish")
+  @HttpCode(202)
+  @RequirePermission("publication.publish")
+  @RequireGroupAccess("body")
+  async publishNow(@Req() request: Request & AuthenticatedRequest, @Param("draftId") draftId: string, @Body() body: unknown): Promise<ScheduledPublicationRecord> {
+    const session = requireSession(request);
+    const input = requireObject(body, "body");
+    return this.publishing.schedule(session.workspaceId, actorFrom(session), parseId(draftId), parseId(requireString(input.connectionId, "connectionId")), new Date(), "publication.publish");
+  }
+
+  @Post(":draftId/retry")
+  @HttpCode(202)
+  @RequirePermission("publication.schedule")
+  @RequireGroupAccess("body")
+  async retry(@Req() request: Request & AuthenticatedRequest, @Param("draftId") draftId: string, @Body() body: unknown): Promise<ScheduledPublicationRecord> {
+    return this.resume(request, draftId, body, "failed");
+  }
+
+  @Post(":draftId/reauthorize")
+  @HttpCode(202)
+  @RequirePermission("publication.schedule")
+  @RequireGroupAccess("body")
+  async reauthorize(@Req() request: Request & AuthenticatedRequest, @Param("draftId") draftId: string, @Body() body: unknown): Promise<ScheduledPublicationRecord> {
+    return this.resume(request, draftId, body, "needs_reauthorization");
+  }
+
+  private async resume(request: Request & AuthenticatedRequest, draftId: string, body: unknown, state: "failed" | "needs_reauthorization"): Promise<ScheduledPublicationRecord> {
+    const session = requireSession(request);
+    const dto = parseScheduleDraft(body);
+    const input = requireObject(body, "body");
+    if (typeof input.expectedGeneration !== "string" || !/^[1-9][0-9]*$/.test(input.expectedGeneration)) throw new BadRequestException("expectedGeneration must be a positive decimal string");
+    return this.publishing.schedule(session.workspaceId, actorFrom(session), parseId(draftId), dto.connectionId, new Date(dto.publishAt), "publication.schedule", { state, generation: input.expectedGeneration });
+  }
+
+  @Delete(":draftId/schedule")
+  @RequirePermission("publication.schedule")
+  async cancelSchedule(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("draftId") draftId: string,
+  ): Promise<DraftRecord> {
+    const session = requireSession(request);
+    return this.publishing.cancelSchedule(session.workspaceId, actorFrom(session), parseId(draftId));
+  }
+}
+
+function requireSession(request: AuthenticatedRequest): NonNullable<AuthenticatedRequest["session"]> {
+  if (request.session === undefined) throw new Error("unreachable: RBAC guard did not attach a session");
+  return request.session;
+}
+
+function actorFrom(session: NonNullable<AuthenticatedRequest["session"]>): Actor {
+  return { userId: session.userId, role: session.role };
+}
+
+function parseCreateDraft(value: unknown): CreateDraftDto {
+  const body = requireObject(value, "body");
+  const post = requireObject(body.post, "post");
+  const text = requireString(post.text, "post.text");
+  const visibility = requireVisibility(post.visibility);
+  if (!Array.isArray(post.mediaAssetIds) || !post.mediaAssetIds.every((id) => typeof id === "string")) {
+    throw new BadRequestException("post.mediaAssetIds must be an array of strings");
+  }
+  const providerMetadata = requireObject(post.providerMetadata, "post.providerMetadata");
+  if (post.mediaAssetIds.length > 0) throw new BadRequestException("publishing currently supports text only");
+  if (["idempotencyKey", "draftId", "mediaIds"].some((key) => key in providerMetadata)) throw new BadRequestException("post metadata contains reserved execution keys");
+  if (Buffer.byteLength(JSON.stringify(providerMetadata)) > 16_384) throw new BadRequestException("post metadata is too large");
+  if (post.scheduledAt !== undefined) requireTimestamp(post.scheduledAt, "post.scheduledAt");
+  return {
+    post: {
+      text,
+      mediaAssetIds: post.mediaAssetIds,
+      visibility,
+      providerMetadata,
+      ...(typeof post.scheduledAt === "string" ? { scheduledAt: post.scheduledAt } : {}),
+    },
+  };
+}
+
+function parseRejectDraft(value: unknown): RejectDraftDto {
+  if (value === undefined || value === null) return {};
+  const body = requireObject(value, "body");
+  if (body.reason === undefined) return {};
+  return { reason: requireString(body.reason, "reason") };
+}
+
+function parseScheduleDraft(value: unknown): ScheduleDraftDto {
+  const body = requireObject(value, "body");
+  return {
+    connectionId: parseId(requireString(body.connectionId, "connectionId")),
+    publishAt: requireTimestamp(body.publishAt, "publishAt"),
+  };
+}
+
+function requireObject(value: unknown, field: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BadRequestException(`${field} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new BadRequestException(`${field} must be a non-empty string`);
+  }
+  return value;
+}
+
+function requireTimestamp(value: unknown, field: string): string {
+  const timestamp = requireString(value, field);
+  if (!Number.isFinite(Date.parse(timestamp))) throw new BadRequestException(`${field} must be an ISO timestamp`);
+  return timestamp;
+}
+
+function parseId(value: string): string {
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)) {
+    throw new BadRequestException("id must be a UUID");
+  }
+  return value;
+}
+
+const DRAFT_STATES: readonly DraftState[] = ["editing", "in_review", "approved", "rejected", "scheduled", "published"];
+
+function parseDraftState(value: string): DraftState {
+  const state = DRAFT_STATES.find((s) => s === value);
+  if (state === undefined) throw new BadRequestException("state is invalid");
+  return state;
+}
+
+function parseListLimit(value: string | undefined): number {
+  if (value === undefined || value === "") return 50;
+  const n = Number(value);
+  if (!Number.isInteger(n) || n < 1) throw new BadRequestException("limit must be a positive integer");
+  return Math.min(n, 200);
+}
+
+function requireVisibility(value: unknown): DraftPost["visibility"] {
+  if (
+    value !== "public" &&
+    value !== "unlisted" &&
+    value !== "private" &&
+    value !== "followers" &&
+    value !== "provider_default"
+  ) {
+    throw new BadRequestException("post.visibility is invalid");
+  }
+  return value;
+}
diff --git a/apps/api/src/publishing/publishing.integration.test.ts b/apps/api/src/publishing/publishing.integration.test.ts
new file mode 100644
index 0000000..4f9fa8d
--- /dev/null
+++ b/apps/api/src/publishing/publishing.integration.test.ts
@@ -0,0 +1,53 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Pool, type PoolClient } from "pg";
+import { PublishingExecutionRepository, canonicalPostHash, assertPublishingSchema } from "@tactical-media-broadcast-hub/publishing-execution";
+import { PgConnectionStore } from "../connections/connection-store.js";
+import { PublishingService } from "./publishing.service.js";
+const appUrl = process.env.PUBLISHING_IT_DATABASE_URL; const ownerUrl = process.env.PUBLISHING_IT_SUPER_DATABASE_URL;
+describe.skipIf(!appUrl || !ownerUrl)("API publishing consumer (live local DB)", () => {
+  let pool: Pool; let owner: Pool; let workspaceId: string; let userId: string; let connectionId: string; let service: PublishingService; let store: PgConnectionStore;
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: appUrl }); owner = new Pool({ connectionString: ownerUrl });
+    workspaceId = String((await owner.query("INSERT INTO workspaces(name,slug) VALUES('API Test',$1) RETURNING id", [`api-sol-${Date.now()}`])).rows[0].id);
+    userId = String((await owner.query("INSERT INTO users(external_id,username,display_name) VALUES($1,$1,'API Test') RETURNING id", [`api-sol-${Date.now()}`])).rows[0].id);
+    await owner.query("INSERT INTO memberships(workspace_id,user_id,role,status) VALUES($1,$2,'Owner','active')", [workspaceId, userId]);
+    connectionId = String((await owner.query("INSERT INTO connections(workspace_id,provider,channel_id,fields) VALUES($1,'mastodon','channel','{\"instanceUrl\":\"https://social.test\"}') RETURNING id", [workspaceId])).rows[0].id);
+    await owner.query("INSERT INTO credentials(workspace_id,connection_id,kind,ciphertext) VALUES($1,$2,'connector-oauth','\\x00')", [workspaceId, connectionId]);
+    const tenantTransaction = async <T>(workspace: string, fn: (client: PoolClient) => Promise<T>): Promise<T> => {
+      const client = await pool.connect(); try { await client.query("BEGIN"); await client.query("SELECT set_config('app.workspace_id',$1,true)", [workspace]); const result = await fn(client); await client.query("COMMIT"); return result; } catch (error) { await client.query("ROLLBACK"); throw error; } finally { client.release(); }
+    };
+    store = new PgConnectionStore(tenantTransaction);
+    service = new PublishingService({ repository: new PublishingExecutionRepository(pool), assertReady: () => assertPublishingSchema(pool), tenantTransaction, workflowStarter: { startScheduledPublish: async () => undefined } });
+  });
+  afterAll(async () => { if (workspaceId) await owner.query("DELETE FROM workspaces WHERE id=$1", [workspaceId]); if (userId) await owner.query("DELETE FROM users WHERE id=$1", [userId]); await pool?.end(); await owner?.end(); });
+  it("pins approval and journals scheduling atomically; identical schedule reuses the key and cancellation retains journal", async () => {
+    const actor = { userId, role: "Owner" }; const post = { text: "API integration", mediaAssetIds: [], visibility: "public" as const, providerMetadata: { connectionId } };
+    const draft = await service.createDraft(workspaceId, actor, post);
+    await expect(service.schedule(workspaceId, actor, draft.id, connectionId, new Date())).rejects.toThrow();
+    await service.submitForReview(workspaceId, actor, draft.id); await service.approve(workspaceId, actor, draft.id);
+    const approved = (await owner.query("SELECT approved_hash,approved_revision,reviewer_user_id FROM drafts WHERE id=$1", [draft.id])).rows[0];
+    expect(approved).toMatchObject({ approved_hash: canonicalPostHash(post), approved_revision: "1", reviewer_user_id: userId });
+    const at = new Date(Date.now()+60_000); const schedule = await service.schedule(workspaceId, actor, draft.id, connectionId, at);
+    const repeated = await service.schedule(workspaceId, actor, draft.id, connectionId, at); expect(repeated.idempotencyKey).toBe(schedule.idempotencyKey);
+    const journal = (await owner.query("SELECT execution_version,scheduled_by_user_id,credential_generation,generation FROM scheduled_publications WHERE id=$1", [schedule.id])).rows[0];
+    expect(journal).toMatchObject({ execution_version: 1, scheduled_by_user_id: userId, credential_generation: "1", generation: "1" });
+    await service.cancelSchedule(workspaceId, actor, draft.id);
+    expect((await owner.query("SELECT status FROM publishing_attempts WHERE idempotency_key=$1", [schedule.idempotencyKey])).rows[0]?.status).toBe("abandoned");
+    expect((await owner.query("SELECT state,generation FROM scheduled_publications WHERE id=$1", [schedule.id])).rows[0]).toMatchObject({ state: "cancelled", generation: "2" });
+  });
+  it("connection removal closes an undispatched live lease, retains journal and leaves intent explicitly resumable", async () => {
+    const actor = { userId, role: "Owner" }; const post = { text: "undispatched removal", mediaAssetIds: [], visibility: "public" as const, providerMetadata: { connectionId } };
+    const draft = await service.createDraft(workspaceId, actor, post); await service.submitForReview(workspaceId, actor, draft.id); await service.approve(workspaceId, actor, draft.id);
+    const schedule = await service.schedule(workspaceId, actor, draft.id, connectionId, new Date(Date.now()-1000));
+    const repository = new PublishingExecutionRepository(pool);
+    const ref = { workspaceId, scheduleId: schedule.id, generation: schedule.generation, idempotencyKey: schedule.idempotencyKey };
+    expect((await repository.claim(ref)).kind).toBe("claimed");
+    const epoch = (await owner.query("SELECT authz_epoch FROM workspaces WHERE id=$1", [workspaceId])).rows[0].authz_epoch as string;
+    await store.remove({ ...actor, workspaceId, authzEpoch: Number(epoch), issuedAt: 0, expiresAt: Math.floor(Date.now()/1000)+300 }, connectionId, async () => undefined);
+    expect((await owner.query("SELECT status,owner_token,lease_until FROM publishing_attempts WHERE idempotency_key=$1", [schedule.idempotencyKey])).rows[0]).toMatchObject({ status: "abandoned", owner_token: null, lease_until: null });
+    expect((await owner.query("SELECT state FROM drafts WHERE id=$1", [draft.id])).rows[0]?.state).toBe("approved");
+    expect((await owner.query("SELECT state FROM scheduled_publications WHERE id=$1", [schedule.id])).rows[0]?.state).toBe("needs_reauthorization");
+    expect((await owner.query("SELECT disconnected_at FROM connections WHERE id=$1", [connectionId])).rows[0]?.disconnected_at).toBeInstanceOf(Date);
+    expect((await repository.listDue()).some((item) => item.idempotencyKey === schedule.idempotencyKey)).toBe(false);
+  });
+});
diff --git a/apps/api/src/publishing/publishing.repository.integration.test.ts b/apps/api/src/publishing/publishing.repository.integration.test.ts
new file mode 100644
index 0000000..92e9caa
--- /dev/null
+++ b/apps/api/src/publishing/publishing.repository.integration.test.ts
@@ -0,0 +1,533 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * Publishing execution spine (018 + PublishingExecutionRepository) against a
+ * live PostgreSQL, as sp_app (FORCE RLS binds). Uses its OWN database
+ * (PUBLISHING_IT_DATABASE_URL, plus PUBLISHING_IT_SUPER_DATABASE_URL for
+ * migrations and fixtures) for the same reason as invite-link.integration.test.ts:
+ * tenancy.integration.test.ts wipes every workspace in the shared DB and vitest
+ * runs files in parallel. Skipped when unset.
+ *
+ * Fixture rows (workspace, users, memberships, connections, credentials,
+ * approved drafts) are inserted by the owner; every pipeline action runs
+ * through the repository as sp_app.
+ */
+const appUrl = process.env.PUBLISHING_IT_DATABASE_URL;
+const ownerUrl = process.env.PUBLISHING_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  repo: typeof import("./publishing.repository.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("publishing execution repository (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  let repo: InstanceType<Modules["repo"]["PublishingExecutionRepository"]>;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let workspaceId: string;
+  let ownerUserId: string;
+  let adminUserId: string;
+  const userIds: string[] = [];
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  async function ownerQuery(sql: string, values: unknown[] = []): Promise<Array<Record<string, unknown>>> {
+    return asOwner(async (c) => (await c.query(sql, values)).rows as Array<Record<string, unknown>>);
+  }
+
+  async function makeUser(role: string): Promise<string> {
+    const name = `pub${role.toLowerCase()}${suffix}${userIds.length}`;
+    const [user] = await ownerQuery(
+      "INSERT INTO users (external_id, username, display_name) VALUES ($1, $2, $3) RETURNING id",
+      [`local:${name}`, name, name],
+    );
+    const id = String(user?.id);
+    userIds.push(id);
+    await ownerQuery("INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, $3, 'active')", [
+      workspaceId,
+      id,
+      role,
+    ]);
+    return id;
+  }
+
+  /** A fresh connection + connector credential per test, so revocations never leak across tests. */
+  async function makeConnection(): Promise<{ connectionId: string; credentialId: string }> {
+    const [conn] = await ownerQuery(
+      "INSERT INTO connections (workspace_id, provider, channel_id, fields) VALUES ($1, 'mastodon', $2, '{\"instance\":\"https://example.test\"}') RETURNING id",
+      [workspaceId, `chan-${Math.random()}`],
+    );
+    const [cred] = await ownerQuery(
+      "INSERT INTO credentials (workspace_id, connection_id, kind, ciphertext) VALUES ($1, $2, 'connector-oauth', '\\x00'::bytea) RETURNING id",
+      [workspaceId, conn?.id],
+    );
+    return { connectionId: String(conn?.id), credentialId: String(cred?.id) };
+  }
+
+  async function makeApprovedDraft(connectionId: string, text = "hello fediverse"): Promise<string> {
+    const post = {
+      text,
+      mediaAssetIds: [],
+      visibility: "public",
+      scheduledAt: "2030-01-01T00:00:00.000Z",
+      providerMetadata: { connectionId, idempotencyKey: "user-supplied", draftId: "user-supplied" },
+    };
+    const [draft] = await ownerQuery(
+      `INSERT INTO drafts (workspace_id, author_user_id, post, state, reviewer_user_id, approved_revision, approved_hash, approved_at)
+       VALUES ($1, $2, $3, 'approved', $2, 1, $4, now()) RETURNING id`,
+      [workspaceId, ownerUserId, post, m.repo.canonicalPostHash(post)],
+    );
+    return String(draft?.id);
+  }
+
+  async function schedule(
+    principal = ownerUserId,
+  ): Promise<{ ref: import("./publishing.repository.js").AttemptRef; draftId: string; connectionId: string; credentialId: string; attemptId: string }> {
+    const { connectionId, credentialId } = await makeConnection();
+    const draftId = await makeApprovedDraft(connectionId);
+    const scheduled = await m.db.withTenant(workspaceId, (client) =>
+      repo.scheduleAttempt(client, {
+        workspaceId,
+        draftId,
+        connectionId,
+        scheduledByUserId: principal,
+        requiredPermission: "publication.publish",
+        publishAt: new Date(Date.now() - 1000),
+      }),
+    );
+    return {
+      ref: { workspaceId, scheduleId: scheduled.scheduleId, generation: scheduled.generation, idempotencyKey: scheduled.idempotencyKey },
+      draftId,
+      connectionId,
+      credentialId,
+      attemptId: scheduled.attemptId,
+    };
+  }
+
+  async function states(draftId: string): Promise<{ draft: string; schedule: string; scheduleCode: unknown; attempts: Array<Record<string, unknown>> }> {
+    const [d] = await ownerQuery("SELECT state FROM drafts WHERE id = $1", [draftId]);
+    const [s] = await ownerQuery("SELECT state, error_code FROM scheduled_publications WHERE draft_id = $1", [draftId]);
+    const attempts = await ownerQuery(
+      "SELECT attempt_no::text, status, error_code, claim_epoch::text, dispatch_count FROM publishing_attempts WHERE draft_id = $1 ORDER BY attempt_no",
+      [draftId],
+    );
+    return { draft: String(d?.state), schedule: String(s?.state), scheduleCode: s?.error_code ?? null, attempts };
+  }
+
+  async function expireLease(attemptId: string): Promise<void> {
+    await ownerQuery("UPDATE publishing_attempts SET lease_until = now() - interval '1 second' WHERE id = $1", [attemptId]);
+  }
+
+  function sendSpy(remoteId = `109${Math.floor(Math.random() * 1e9)}`): { calls: number; send: () => Promise<{ remoteId: string }> } {
+    const spy = {
+      calls: 0,
+      send: async () => {
+        spy.calls += 1;
+        return { remoteId };
+      },
+    };
+    return spy;
+  }
+
+  function claimed(outcome: Awaited<ReturnType<typeof repo.claim>>) {
+    if (outcome.kind !== "claimed") throw new Error(`expected claimed, got ${JSON.stringify(outcome)}`);
+    return outcome.job;
+  }
+
+  beforeAll(async () => {
+    // The pool reads DATABASE_URL at import time: point it at the isolated DB first.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      repo: await import("./publishing.repository.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+    repo = new m.repo.PublishingExecutionRepository(m.db.pool);
+
+    const [ws] = await ownerQuery("INSERT INTO workspaces (name, slug) VALUES ('Publishing IT', $1) RETURNING id", [
+      `publishing-it-${suffix}`,
+    ]);
+    workspaceId = String(ws?.id);
+    ownerUserId = await makeUser("Owner");
+    adminUserId = await makeUser("Admin");
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE id = $1", [workspaceId]);
+        await c.query("DELETE FROM users WHERE id = ANY($1::uuid[])", [userIds]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  it("scheduleAttempt snapshots principal, approval proof and the exact credential generation", async () => {
+    const { ref, draftId, credentialId } = await schedule();
+    expect(ref.idempotencyKey).toBe(`wp3:${workspaceId}:${draftId}:a1:publish`);
+    const [row] = await ownerQuery(
+      `SELECT sp.state, sp.execution_version, sp.scheduled_by_user_id, sp.required_permission, sp.credential_id,
+              sp.credential_generation::text, a.status, a.post_hash = d.approved_hash AS hash_pinned
+         FROM scheduled_publications sp
+         JOIN publishing_attempts a ON a.schedule_id = sp.id
+         JOIN drafts d ON d.id = sp.draft_id
+        WHERE sp.id = $1`,
+      [ref.scheduleId],
+    );
+    expect(row).toMatchObject({
+      state: "pending",
+      execution_version: 1,
+      scheduled_by_user_id: ownerUserId,
+      required_permission: "publication.publish",
+      credential_id: credentialId,
+      credential_generation: "1",
+      status: "ready",
+      hash_pinned: true,
+    });
+    const due = await repo.listDue(100);
+    expect(due.map((d) => d.idempotencyKey)).toContain(ref.idempotencyKey);
+    await expect(repo.resolveWorkspace(ref.idempotencyKey)).resolves.toBe(workspaceId);
+  });
+
+  it("concurrent claims: exactly one worker wins, the rest wait on the live lease", async () => {
+    const { ref, draftId } = await schedule();
+    const workers = Array.from({ length: 5 }, () => new m.repo.PublishingExecutionRepository(m.db.pool));
+    const outcomes = await Promise.all(workers.map((w) => w.claim(ref)));
+    const kinds = outcomes.map((o) => o.kind).sort();
+    expect(kinds).toEqual(["claimed", "wait", "wait", "wait", "wait"]);
+    for (const o of outcomes) if (o.kind === "wait") expect(o.reason).toBe("busy");
+
+    const winner = outcomes.find((o) => o.kind === "claimed");
+    if (winner?.kind !== "claimed") throw new Error("no winner");
+    expect(winner.job.lease.claimEpoch).toBe("1");
+    expect(winner.job.connection.provider).toBe("mastodon");
+    // Pipeline owns timing and the reserved execution metadata.
+    expect(winner.job.post).not.toHaveProperty("scheduledAt");
+    expect(winner.job.post.providerMetadata).toMatchObject({ draftId, idempotencyKey: ref.idempotencyKey });
+    const s = await states(draftId);
+    expect(s).toMatchObject({ draft: "scheduled", schedule: "in_flight" });
+    expect(s.attempts).toEqual([expect.objectContaining({ status: "in_progress", claim_epoch: "1" })]);
+  });
+
+  it("credential revoked before the due claim pauses durably with zero sends; restoring does not resume", async () => {
+    const { ref, draftId, credentialId } = await schedule();
+    await ownerQuery("UPDATE credentials SET revoked_at = now() WHERE id = $1", [credentialId]);
+    await expect(repo.claim(ref)).resolves.toEqual({ kind: "paused", code: "CREDENTIAL_CHANGED" });
+    const s = await states(draftId);
+    expect(s).toMatchObject({ draft: "approved", schedule: "needs_reauthorization", scheduleCode: "CREDENTIAL_CHANGED" });
+    expect(s.attempts).toEqual([expect.objectContaining({ status: "abandoned", dispatch_count: 0 })]);
+
+    // Reconnecting rotates generation again: still paused, never auto-resumed.
+    await ownerQuery("UPDATE credentials SET revoked_at = NULL WHERE id = $1", [credentialId]);
+    const [cred] = await ownerQuery("SELECT generation::text FROM credentials WHERE id = $1", [credentialId]);
+    expect(cred?.generation).toBe("3");
+    await expect(repo.claim(ref)).resolves.toMatchObject({ kind: "superseded" });
+    expect((await states(draftId)).schedule).toBe("needs_reauthorization");
+  });
+
+  it("credential rotated after claim: the dispatch gate refuses before any send", async () => {
+    const { ref, draftId, credentialId } = await schedule();
+    const job = claimed(await repo.claim(ref));
+    await ownerQuery("UPDATE credentials SET ciphertext = '\\x01'::bytea, rotated_at = now() WHERE id = $1", [credentialId]);
+    const spy = sendSpy();
+    await expect(repo.withDispatchGate(job.lease, {}, spy.send)).resolves.toEqual({ kind: "paused", code: "CREDENTIAL_CHANGED" });
+    expect(spy.calls).toBe(0);
+    expect(await states(draftId)).toMatchObject({ draft: "approved", schedule: "needs_reauthorization" });
+  });
+
+  it("recorded principal demoted: claim pauses with AUTHZ_REVOKED", async () => {
+    const { ref, draftId } = await schedule(adminUserId);
+    await ownerQuery("UPDATE memberships SET role = 'Editor' WHERE workspace_id = $1 AND user_id = $2", [workspaceId, adminUserId]);
+    try {
+      await expect(repo.claim(ref)).resolves.toEqual({ kind: "paused", code: "AUTHZ_REVOKED" });
+      expect((await states(draftId)).scheduleCode).toBe("AUTHZ_REVOKED");
+    } finally {
+      await ownerQuery("UPDATE memberships SET role = 'Admin' WHERE workspace_id = $1 AND user_id = $2", [workspaceId, adminUserId]);
+    }
+  });
+
+  it("an unrelated epoch bump re-checks and continues still-authorized work", async () => {
+    const { ref } = await schedule();
+    const extra = await makeUser("Analyst");
+    expect(extra).toBeTruthy();
+    const job = claimed(await repo.claim(ref));
+    const spy = sendSpy();
+    await expect(repo.withDispatchGate(job.lease, {}, spy.send)).resolves.toMatchObject({ kind: "sent" });
+    expect(spy.calls).toBe(1);
+  });
+
+  it("receipts are idempotent on replay; finalization yields exactly one Publication", async () => {
+    const { ref, draftId } = await schedule();
+    const job = claimed(await repo.claim(ref));
+    const spy = sendSpy("10987654321");
+    const gate = await repo.withDispatchGate(job.lease, {}, spy.send);
+    if (gate.kind !== "sent") throw new Error(`gate ${gate.kind}`);
+
+    const target = { workspaceId, attemptId: job.lease.attemptId };
+    const first = await repo.recordReceipt(target, { remoteId: gate.value.remoteId, remoteUrl: "https://example.test/@a/10987654321" });
+    const replay = await repo.recordReceipt(target, { remoteId: gate.value.remoteId });
+    expect(first.inserted).toBe(true);
+    expect(replay).toMatchObject({ inserted: false, receipt: { id: first.receipt.id } });
+    await expect(repo.recordReceipt(target, { remoteId: "different" })).rejects.toMatchObject({ code: "RECEIPT_CONFLICT" });
+
+    const done = await repo.finalize(job.lease);
+    if (done.kind !== "done") throw new Error("finalize stale");
+    expect(done.publication).toMatchObject({ remoteId: "10987654321", draftId, idempotencyKey: ref.idempotencyKey });
+
+    // Replays: no new send, same publication, finalize refuses the spent lease.
+    await expect(repo.claim(ref)).resolves.toEqual({ kind: "done", publication: done.publication });
+    await expect(repo.finalize(job.lease)).resolves.toEqual({ kind: "stale" });
+    await expect(repo.findPublication(workspaceId, ref.idempotencyKey)).resolves.toEqual(done.publication);
+    const pubs = await ownerQuery("SELECT count(*)::int AS n FROM publications WHERE idempotency_key = $1", [ref.idempotencyKey]);
+    expect(pubs[0]?.n).toBe(1);
+    expect(spy.calls).toBe(1);
+    const s = await states(draftId);
+    expect(s).toMatchObject({ draft: "published", schedule: "done" });
+    expect(s.attempts).toEqual([expect.objectContaining({ status: "completed", dispatch_count: 1 })]);
+    expect((await repo.listDue(100)).map((d) => d.idempotencyKey)).not.toContain(ref.idempotencyKey);
+
+    // Receipts are append-only for the runtime role.
+    await expect(
+      m.db.withTenant(workspaceId, (c) => c.query("UPDATE publishing_receipts SET remote_id = 'x' WHERE attempt_id = $1", [job.lease.attemptId])),
+    ).rejects.toMatchObject({ code: "42501" });
+  });
+
+  it("lease expiry: takeover advances claim_epoch; the deposed owner records evidence but cannot complete", async () => {
+    const { ref, draftId } = await schedule();
+    const a = claimed(await repo.claim(ref));
+    expect(await repo.heartbeat(a.lease)).toBe(true);
+    const spy = sendSpy("555");
+    const sent = await repo.withDispatchGate(a.lease, {}, spy.send);
+    expect(sent.kind).toBe("sent");
+
+    await expireLease(a.lease.attemptId);
+    expect(await repo.heartbeat(a.lease)).toBe(false);
+    expect((await repo.listDue(100)).map((d) => d.idempotencyKey)).toContain(ref.idempotencyKey);
+
+    const b = claimed(await repo.claim(ref));
+    expect(b.lease.claimEpoch).toBe(String(Number(a.lease.claimEpoch) + 1));
+    expect(b.priorDispatch).toMatchObject({ count: 1 });
+
+    await expect(repo.withDispatchGate(a.lease, {}, spy.send)).resolves.toEqual({ kind: "lost" });
+    await expect(repo.recordReceipt({ workspaceId, attemptId: a.lease.attemptId }, { remoteId: "555" })).resolves.toMatchObject({ inserted: true });
+    await expect(repo.finalize(a.lease)).resolves.toEqual({ kind: "stale" });
+
+    // New owner adopts the evidence: no second send.
+    await expect(repo.withDispatchGate(b.lease, {}, spy.send)).resolves.toEqual({ kind: "finalize" });
+    const done = await repo.finalize(b.lease);
+    expect(done).toMatchObject({ kind: "done", publication: { remoteId: "555" } });
+    expect(spy.calls).toBe(1);
+    expect((await states(draftId)).draft).toBe("published");
+  });
+
+  it("a recovery claim after a receipt goes straight to finalize", async () => {
+    const { ref } = await schedule();
+    const a = claimed(await repo.claim(ref));
+    await repo.withDispatchGate(a.lease, {}, sendSpy("777").send);
+    await repo.recordReceipt({ workspaceId, attemptId: a.lease.attemptId }, { remoteId: "777" });
+    await expireLease(a.lease.attemptId);
+    const outcome = await repo.claim(ref);
+    if (outcome.kind !== "finalize") throw new Error(`expected finalize, got ${outcome.kind}`);
+    expect(outcome.receipt.remoteId).toBe("777");
+    await expect(repo.finalize(outcome.job.lease)).resolves.toMatchObject({ kind: "done" });
+  });
+
+  it("unsettled dispatch without a dedupe policy becomes unknown: never resent, content locked", async () => {
+    const { ref, draftId } = await schedule();
+    const a = claimed(await repo.claim(ref));
+    let calls = 0;
+    await expect(
+      repo.withDispatchGate(a.lease, {}, async () => {
+        calls += 1;
+        throw new Error("socket hang up");
+      }),
+    ).rejects.toThrow("socket hang up");
+    await expect(
+      ownerQuery("UPDATE drafts SET post = post || '{\"text\":\"edited\"}' WHERE id = $1", [draftId]),
+    ).rejects.toMatchObject({ code: "55000" });
+
+    await expireLease(a.lease.attemptId);
+    const b = claimed(await repo.claim(ref));
+    await expect(repo.withDispatchGate(b.lease, {}, async () => { calls += 1; })).resolves.toEqual({
+      kind: "unknown",
+      code: "PUBLISH_OUTCOME_UNKNOWN",
+    });
+    expect(calls).toBe(1);
+    const s = await states(draftId);
+    expect(s).toMatchObject({ draft: "scheduled", schedule: "failed", scheduleCode: "PUBLISH_OUTCOME_UNKNOWN" });
+    expect(s.attempts).toEqual([expect.objectContaining({ status: "unknown" })]);
+    await expect(repo.claim(ref)).resolves.toEqual({ kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" });
+    await expect(
+      ownerQuery("UPDATE drafts SET post = post || '{\"text\":\"edited\"}' WHERE id = $1", [draftId]),
+    ).rejects.toMatchObject({ code: "55000" });
+  });
+
+  it("verified dedupe policy permits one same-key resend inside the window", async () => {
+    const { ref } = await schedule();
+    const a = claimed(await repo.claim(ref));
+    await expect(
+      repo.withDispatchGate(a.lease, { allowRedispatch: true, dedupeWindowMs: 30 * 60_000 }, async () => {
+        throw new Error("timeout");
+      }),
+    ).rejects.toThrow("timeout");
+    await expireLease(a.lease.attemptId);
+    const b = claimed(await repo.claim(ref));
+    const spy = sendSpy("888");
+    const gate = await repo.withDispatchGate(b.lease, { allowRedispatch: true, dedupeWindowMs: 30 * 60_000 }, spy.send);
+    expect(gate.kind).toBe("sent");
+    expect(b.post.providerMetadata.idempotencyKey).toBe(ref.idempotencyKey);
+    const [row] = await ownerQuery("SELECT dispatch_count FROM publishing_attempts WHERE id = $1", [b.lease.attemptId]);
+    expect(row?.dispatch_count).toBe(2);
+  });
+
+  it("definite non-delivery retries later under the same key", async () => {
+    const { ref, draftId } = await schedule();
+    const a = claimed(await repo.claim(ref));
+    await repo.withDispatchGate(a.lease, {}, async () => undefined);
+    const retry = await repo.retryLater(a.lease, "RATE_LIMITED", new Date(Date.now() + 60_000));
+    expect(retry.kind).toBe("settled");
+    expect(await states(draftId)).toMatchObject({ draft: "approved", schedule: "pending", scheduleCode: "RATE_LIMITED" });
+    await expect(repo.claim(ref)).resolves.toMatchObject({ kind: "wait", reason: "not_due" });
+    expect((await repo.listDue(100)).map((d) => d.idempotencyKey)).not.toContain(ref.idempotencyKey);
+
+    await ownerQuery("UPDATE scheduled_publications SET next_attempt_at = now() - interval '1 second' WHERE id = $1", [ref.scheduleId]);
+    const b = claimed(await repo.claim(ref));
+    expect(b.lease.idempotencyKey).toBe(ref.idempotencyKey);
+    expect(b.priorDispatch).toBeUndefined();
+  });
+
+  it("generation fence: cancel + reschedule supersedes the old workflow without touching the new one", async () => {
+    const { ref, draftId, connectionId } = await schedule();
+    await m.db.withTenant(workspaceId, (c) =>
+      c.query("UPDATE scheduled_publications SET state = 'cancelled', error_code = 'CANCELLED' WHERE id = $1", [ref.scheduleId]),
+    );
+    const next = await m.db.withTenant(workspaceId, (client) =>
+      repo.scheduleAttempt(client, {
+        workspaceId,
+        draftId,
+        connectionId,
+        scheduledByUserId: ownerUserId,
+        requiredPermission: "publication.schedule",
+        publishAt: new Date(Date.now() - 1000),
+      }),
+    );
+    expect(next).toMatchObject({ attemptNo: "2", generation: "2", idempotencyKey: `wp3:${workspaceId}:${draftId}:a2:publish` });
+
+    const spy = sendSpy();
+    await expect(repo.claim(ref)).resolves.toEqual({ kind: "superseded", code: "SUPERSEDED" });
+    expect(spy.calls).toBe(0);
+    const s = await states(draftId);
+    expect(s.schedule).toBe("pending");
+    expect(s.attempts).toEqual([
+      expect.objectContaining({ attempt_no: "1", status: "abandoned" }),
+      expect.objectContaining({ attempt_no: "2", status: "ready" }),
+    ]);
+    claimed(await repo.claim({ workspaceId, scheduleId: next.scheduleId, generation: next.generation, idempotencyKey: next.idempotencyKey }));
+  });
+
+  it("content edit before the due claim rotates the revision, voids approval and supersedes", async () => {
+    const { ref, draftId } = await schedule();
+    await m.db.withTenant(workspaceId, (c) =>
+      c.query("UPDATE drafts SET post = post || '{\"text\":\"changed\"}' WHERE id = $1", [draftId]),
+    );
+    const [d] = await ownerQuery("SELECT revision::text, approved_revision, approved_hash, reviewer_user_id FROM drafts WHERE id = $1", [draftId]);
+    expect(d).toEqual({ revision: "2", approved_revision: null, approved_hash: null, reviewer_user_id: null });
+    await expect(repo.claim(ref)).resolves.toEqual({ kind: "superseded", code: "SUPERSEDED" });
+    expect(await states(draftId)).toMatchObject({ schedule: "cancelled", scheduleCode: "SUPERSEDED" });
+  });
+
+  it("refuses a target differing from the approved snapshot and a forged approval hash", async () => {
+    const original = await makeConnection(); const other = await makeConnection();
+    const draftId = await makeApprovedDraft(original.connectionId);
+    const input = { workspaceId, draftId, connectionId: other.connectionId, scheduledByUserId: ownerUserId, requiredPermission: "publication.publish" as const, publishAt: new Date() };
+    await expect(m.db.withTenant(workspaceId, (c) => repo.scheduleAttempt(c, input))).rejects.toMatchObject({ code: "APPROVAL_MISMATCH" });
+    await ownerQuery("UPDATE drafts SET approved_hash = 'forged' WHERE id = $1", [draftId]);
+    await expect(m.db.withTenant(workspaceId, (c) => repo.scheduleAttempt(c, { ...input, connectionId: original.connectionId }))).rejects.toMatchObject({ code: "APPROVAL_MISMATCH" });
+    expect((await ownerQuery("SELECT * FROM publishing_attempts WHERE draft_id = $1", [draftId]))).toHaveLength(0);
+  });
+
+  it("keeps first dispatch and dedupe deadline across ambiguous and definite retries", async () => {
+    const { ref, attemptId } = await schedule();
+    const first = claimed(await repo.claim(ref));
+    await repo.withDispatchGate(first.lease, { allowRedispatch: true, dedupeWindowMs: 1_800_000 }, async () => undefined);
+    const [before] = await ownerQuery("SELECT first_dispatch_started_at, dispatch_started_at, provider_retry_deadline FROM publishing_attempts WHERE id = $1", [attemptId]);
+    await repo.retryDeduplicated(first.lease, "PUBLISH_AMBIGUOUS_DEDUPED", new Date(Date.now() - 1000));
+    const second = claimed(await repo.claim(ref));
+    expect(second.priorDispatch).toBeDefined(); expect(second.retryCount).toBe(1);
+    expect(second.firstDispatchStartedAt).toEqual(before?.first_dispatch_started_at);
+    expect(second.providerRetryDeadline).toEqual(before?.provider_retry_deadline);
+    await repo.withDispatchGate(second.lease, { allowRedispatch: true, dedupeWindowMs: 1_800_000 }, async () => undefined);
+    await repo.retryLater(second.lease, "RATE_LIMITED", new Date(Date.now() - 1000));
+    const third = claimed(await repo.claim(ref));
+    expect(third.priorDispatch).toBeUndefined(); expect(third.firstDispatchStartedAt).toEqual(before?.first_dispatch_started_at);
+    expect(third.providerRetryDeadline).toEqual(before?.provider_retry_deadline);
+    await expect(ownerQuery("UPDATE publishing_attempts SET first_dispatch_started_at = now() + interval '1 second' WHERE id = $1", [attemptId])).rejects.toMatchObject({ code: "23514" });
+    await repo.fail(third.lease, "TEST_DONE");
+  });
+
+  it("discovers late receipts on unknown work for evidence-only finalization", async () => {
+    const { ref, attemptId } = await schedule(); const first = claimed(await repo.claim(ref));
+    await repo.withDispatchGate(first.lease, {}, async () => undefined);
+    await repo.markUnknown(first.lease);
+    expect((await repo.listDue()).some((item) => item.idempotencyKey === ref.idempotencyKey)).toBe(false);
+    await repo.recordReceipt({ workspaceId, attemptId }, { remoteId: "late-evidence" });
+    expect((await repo.listDue()).find((item) => item.idempotencyKey === ref.idempotencyKey)).toMatchObject({ evidenceOnly: true });
+    const recovery = await repo.claim(ref);
+    expect(recovery.kind).toBe("finalize");
+    if (recovery.kind !== "finalize") throw new Error("receipt recovery missing");
+    await expect(repo.finalize(recovery.job.lease)).resolves.toMatchObject({ kind: "done", publication: { remoteId: "late-evidence" } });
+    expect((await ownerQuery("SELECT dispatch_count FROM publishing_attempts WHERE id = $1", [attemptId]))[0]?.dispatch_count).toBe(1);
+  });
+
+  it("pauses provider authentication rejection through owner CAS", async () => {
+    const { ref, draftId } = await schedule(); const first = claimed(await repo.claim(ref));
+    await repo.pauseForReauthorization(first.lease);
+    expect((await states(draftId)).schedule).toBe("needs_reauthorization");
+    await expect(repo.claim(ref)).resolves.toMatchObject({ kind: "superseded", code: "CREDENTIAL_REJECTED" });
+    await expect(repo.pauseForReauthorization(first.lease)).resolves.toEqual({ kind: "stale" });
+  });
+  it("an expired owner records evidence but cannot finalize until a fresh claim", async () => {
+    const { ref, attemptId } = await schedule(); const first = claimed(await repo.claim(ref));
+    await repo.withDispatchGate(first.lease, {}, async () => undefined);
+    await expireLease(attemptId);
+    await repo.recordReceipt({ workspaceId, attemptId }, { remoteId: "expired-owner-evidence" });
+    await expect(repo.finalize(first.lease)).resolves.toEqual({ kind: "stale" });
+    const recovery = await repo.claim(ref);
+    expect(recovery.kind).toBe("finalize");
+    if (recovery.kind !== "finalize") throw new Error("fresh receipt claim missing");
+    expect(recovery.job.lease.claimEpoch).not.toBe(first.lease.claimEpoch);
+    await expect(repo.finalize(recovery.job.lease)).resolves.toMatchObject({ kind: "done", publication: { remoteId: "expired-owner-evidence" } });
+  });
+
+  it("journal is not deletable by the app; workspace purge cascades it", async () => {
+    const { attemptId } = await schedule();
+    await expect(
+      m.db.withTenant(workspaceId, (c) => c.query("DELETE FROM publishing_attempts WHERE id = $1", [attemptId])),
+    ).rejects.toMatchObject({ code: "42501" });
+    const receipts = await ownerQuery("SELECT count(*)::int AS n FROM publishing_receipts WHERE workspace_id = $1", [workspaceId]);
+    expect(receipts[0]?.n).toBeGreaterThan(0);
+
+    await ownerQuery("DELETE FROM workspaces WHERE id = $1", [workspaceId]);
+    const left = await ownerQuery(
+      `SELECT (SELECT count(*) FROM publishing_receipts WHERE workspace_id = $1)::int
+            + (SELECT count(*) FROM publishing_attempts WHERE workspace_id = $1)::int AS n`,
+      [workspaceId],
+    );
+    expect(left[0]?.n).toBe(0);
+  });
+
+});
diff --git a/apps/api/src/publishing/publishing.repository.ts b/apps/api/src/publishing/publishing.repository.ts
new file mode 100644
index 0000000..7fcb2d0
--- /dev/null
+++ b/apps/api/src/publishing/publishing.repository.ts
@@ -0,0 +1,2 @@
+// Compatibility export: the implementation is shared with the scheduler.
+export * from "@tactical-media-broadcast-hub/publishing-execution";
diff --git a/apps/api/src/publishing/publishing.service.test.ts b/apps/api/src/publishing/publishing.service.test.ts
new file mode 100644
index 0000000..62bb553
--- /dev/null
+++ b/apps/api/src/publishing/publishing.service.test.ts
@@ -0,0 +1,172 @@
+import { BadRequestException, ForbiddenException, NotFoundException } from "@nestjs/common";
+import type { PoolClient, QueryResult } from "pg";
+import { describe, expect, it, vi } from "vitest";
+import {
+  PublishingService,
+  type DraftPost,
+  type DraftState,
+  type PublishingDependencies,
+} from "./publishing.service.js";
+
+const workspaceId = "10000000-0000-4000-8000-000000000001";
+const userId = "20000000-0000-4000-8000-000000000002";
+const draftId = "30000000-0000-4000-8000-000000000003";
+const connectionId = "40000000-0000-4000-8000-000000000004";
+const actor = { userId, role: "Publisher" };
+
+const post: DraftPost = {
+  text: "Ready to publish",
+  mediaAssetIds: [],
+  visibility: "public",
+  providerMetadata: {},
+};
+
+interface FakeDatabase {
+  state: DraftState;
+  scheduled: boolean;
+}
+
+function serviceWithDatabase(database: FakeDatabase, canUseConnection = true): PublishingService {
+  const now = new Date("2026-10-06T10:00:00.000Z");
+  const row = (): Record<string, unknown> => ({
+    id: draftId,
+    workspace_id: workspaceId,
+    author_user_id: userId,
+    post,
+    state: database.state,
+    reviewer_user_id: null,
+    created_at: now,
+    updated_at: now,
+  });
+  const result = (rows: Array<Record<string, unknown>>): QueryResult<Record<string, unknown>> => ({
+    command: "",
+    rowCount: rows.length,
+    oid: 0,
+    fields: [],
+    rows,
+  });
+  const client = {
+    async query(sql: string, values: readonly unknown[] = []): Promise<QueryResult<Record<string, unknown>>> {
+      if (sql.includes("FROM workspaces")) return result([{ id: workspaceId }]);
+      if (sql === "SELECT * FROM drafts WHERE id = $1 FOR UPDATE") return result([row()]);
+      if (sql === "SELECT * FROM scheduled_publications WHERE id = $1") return result([{ id: "schedule", workspace_id: workspaceId, draft_id: draftId, connection_id: connectionId, publish_at: now, generation: "1", state: "pending", idempotency_key: "key" }]);
+      if (sql.includes("SELECT audit_append")) return result([{ audit_append: "audit-id" }]);
+      if (sql.includes("FROM memberships m"))
+        return result(canUseConnection && values[2] === connectionId ? [{ "?column?": 1 }] : []);
+      if (sql.includes("SELECT id FROM drafts WHERE id = $1 AND state = 'approved' FOR UPDATE"))
+        return result(database.state === "approved" ? [{ id: draftId }] : []);
+      if (sql.includes("SELECT * FROM drafts WHERE id = $1 AND state IN ('approved', 'scheduled') FOR UPDATE"))
+        return result(database.state === "approved" || database.state === "scheduled" ? [row()] : []);
+      if (sql.includes("UPDATE drafts SET state = 'editing'")) {
+        if (database.state !== "scheduled") return result([]);
+        database.state = "editing";
+        return result([row()]);
+      }
+      if (sql.includes("INSERT INTO scheduled_publications")) {
+        database.scheduled = true;
+        return result([{
+          id: "50000000-0000-4000-8000-000000000005",
+          workspace_id: workspaceId,
+          draft_id: draftId,
+          connection_id: connectionId,
+          publish_at: now,
+          idempotency_key: "60000000-0000-4000-8000-000000000006",
+          state: "pending",
+        }]);
+      }
+      if (sql.includes("DELETE FROM scheduled_publications")) {
+        if (!database.scheduled) return result([]);
+        database.scheduled = false;
+        return result([{ id: "50000000-0000-4000-8000-000000000005" }]);
+      }
+      if (sql.includes("UPDATE drafts SET state = 'approved'")) {
+        if (database.state !== "scheduled") return result([]);
+        database.state = "approved";
+        return result([row()]);
+      }
+      if (sql.includes("UPDATE drafts")) {
+        if (!sql.includes("state = $4")) return result([]);
+        const target = String(values[1]) as DraftState;
+        const expected = String(values[3]) as DraftState;
+        if (database.state !== expected) return result([]);
+        database.state = target;
+        return result([row()]);
+      }
+      if (sql.includes("SELECT state FROM drafts")) return result([{ state: database.state }]);
+      // RLS-scoped connection lookup: only this tenant's connection is visible.
+      if (sql.includes("FROM connections")) return result(values[0] === connectionId ? [{ provider: "mastodon" }] : []);
+      if (sql.includes("SELECT state FROM scheduled_publications")) {
+        return result(database.scheduled ? [{ state: "pending" }] : []);
+      }
+      throw new Error(`unexpected SQL in fake: ${sql}`);
+    },
+  };
+  const dependencies: PublishingDependencies = {
+    assertReady: async () => undefined,
+    repository: {
+      scheduleAttempt: vi.fn(async (_client, input) => {
+        if (database.state !== "approved") throw new BadRequestException("approval required");
+        expect(input).toMatchObject({ workspaceId, draftId, connectionId, scheduledByUserId: userId, requiredPermission: "publication.schedule" });
+        database.scheduled = true;
+        return { scheduleId: "schedule", attemptId: "attempt", attemptNo: "1", generation: "1", idempotencyKey: "key" };
+      }),
+      cancelAttempt: vi.fn(async () => { database.scheduled = false; }),
+    },
+    tenantTransaction: async (_tenant, fn) => fn(client as unknown as PoolClient),
+    workflowStarter: { startScheduledPublish: vi.fn(async () => undefined) },
+  };
+  return new PublishingService(dependencies);
+}
+
+describe("publishing draft state machine", () => {
+  it("moves an editing draft through review and approval", async () => {
+    const database: FakeDatabase = { state: "editing", scheduled: false };
+    const service = serviceWithDatabase(database);
+    await expect(service.submitForReview(workspaceId, actor, draftId)).resolves.toMatchObject({ state: "in_review" });
+    await expect(service.approve(workspaceId, actor, draftId)).resolves.toMatchObject({ state: "approved" });
+    expect(database.state).toBe("approved");
+  });
+
+  it("rejects an illegal editing -> approved transition", async () => {
+    const service = serviceWithDatabase({ state: "editing", scheduled: false });
+    await expect(service.approve(workspaceId, actor, draftId)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it("schedules an approved draft and cancels it back to approved", async () => {
+    const database: FakeDatabase = { state: "approved", scheduled: false };
+    const service = serviceWithDatabase(database);
+    const scheduled = await service.schedule(workspaceId, actor, draftId, connectionId, new Date("2026-10-06T10:00:00Z"));
+    expect(scheduled.state).toBe("pending");
+    expect(database).toEqual({ state: "approved", scheduled: true });
+
+    const cancelled = await service.cancelSchedule(workspaceId, actor, draftId);
+    expect(cancelled.state).toBe("approved");
+    expect(database).toEqual({ state: "approved", scheduled: false });
+  });
+
+  it("refuses to schedule onto a connection outside the tenant", async () => {
+    const database: FakeDatabase = { state: "approved", scheduled: false };
+    const service = serviceWithDatabase(database);
+    const foreign = "40000000-0000-4000-8000-0000000000ff";
+    await expect(
+      service.schedule(workspaceId, actor, draftId, foreign, new Date("2026-10-06T10:00:00Z")),
+    ).rejects.toBeInstanceOf(NotFoundException);
+    expect(database).toEqual({ state: "approved", scheduled: false });
+  });
+
+  it("refuses an existing connection outside the actor's group scope", async () => {
+    const database: FakeDatabase = { state: "approved", scheduled: false };
+    const service = serviceWithDatabase(database, false);
+    await expect(service.schedule(workspaceId, actor, draftId, connectionId, new Date("2026-10-06T10:00:00Z")))
+      .rejects.toBeInstanceOf(ForbiddenException);
+    expect(database).toEqual({ state: "approved", scheduled: false });
+  });
+
+  it("cancels a legacy pending schedule into editing for renewed approval", async () => {
+    const database: FakeDatabase = { state: "scheduled", scheduled: true };
+    const service = serviceWithDatabase(database);
+    const draft = await service.cancelSchedule(workspaceId, actor, draftId);
+    expect(draft.state).toBe("editing");
+    expect(database).toEqual({ state: "editing", scheduled: false });
+  });
+});
diff --git a/apps/api/src/publishing/publishing.service.ts b/apps/api/src/publishing/publishing.service.ts
new file mode 100644
index 0000000..26dc122
--- /dev/null
+++ b/apps/api/src/publishing/publishing.service.ts
@@ -0,0 +1,403 @@
+import { BadRequestException, ForbiddenException, Inject, Injectable, NotFoundException, Optional, ConflictException } from "@nestjs/common";
+import { isPublishingProvider } from "@tactical-media-broadcast-hub/connector-runtime";
+import { Client, Connection, WorkflowExecutionAlreadyStartedError } from "@temporalio/client";
+import { PublishingExecutionRepository, PublishingStateError, canonicalPostHash, assertPublishingSchema, type AttemptRef } from "@tactical-media-broadcast-hub/publishing-execution";
+import type { PoolClient } from "pg";
+import { markDraftPollsStale, autoOpenDraftPoll } from "../chatgov/poll.service.js";
+import { scrub } from "../audit/audit.service.js";
+import { ApprovalGateService, ApprovalGateBlockedError } from "./approval-gate.service.js";
+import { pool, withTenant } from "../db/client.js";
+import { userCanUseConnection } from "../groups/groups.service.js";
+
+export type DraftState = "editing" | "in_review" | "approved" | "rejected" | "scheduled" | "published";
+
+export interface DraftPost {
+  text: string;
+  mediaAssetIds: string[];
+  visibility: "public" | "unlisted" | "private" | "followers" | "provider_default";
+  scheduledAt?: string;
+  providerMetadata: Record<string, unknown>;
+}
+
+export interface DraftRecord {
+  id: string;
+  workspaceId: string;
+  authorUserId: string;
+  post: DraftPost;
+  state: DraftState;
+  reviewerUserId?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface ScheduledPublicationRecord {
+  id: string;
+  workspaceId: string;
+  draftId: string;
+  connectionId: string;
+  publishAt: Date;
+  idempotencyKey: string;
+  generation: string;
+  state: "pending" | "in_flight" | "done" | "failed" | "needs_reauthorization" | "cancelled";
+}
+
+export interface Actor {
+  userId: string;
+  role: string;
+}
+
+export interface WorkflowStarter {
+  startScheduledPublish(ref: AttemptRef, publishAt: Date): Promise<void>;
+}
+
+type TenantTransaction = <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+
+export interface PublishingDependencies {
+  tenantTransaction: TenantTransaction;
+  workflowStarter: WorkflowStarter;
+  repository: Pick<PublishingExecutionRepository, "scheduleAttempt" | "cancelAttempt">;
+  assertReady: () => Promise<void>;
+  /**
+   * E1 chatgov approval gate (chatgov-design.md §4). Optional: a plain
+   * `new PublishingService()` keeps today's ungated behavior; AppModule
+   * injects the real one. `null` disables it explicitly.
+   */
+  approvalGate?: ApprovalGateService | null;
+}
+
+export const PUBLISHING_DEPENDENCIES = Symbol("PUBLISHING_DEPENDENCIES");
+
+/** The pending row is durable; a failed hint is repaired by discovery. */
+export class TemporalWorkflowStarter implements WorkflowStarter {
+  private connection?: Connection;
+  private connecting?: Promise<Client>;
+  private async client(): Promise<Client> {
+    this.connecting ??= Connection.connect({ address: process.env.TEMPORAL_ADDRESS ?? "localhost:7233" })
+      .then((connection) => { this.connection = connection; return new Client({ connection, namespace: process.env.TEMPORAL_NAMESPACE ?? "default" }); })
+      .catch((error: unknown) => { this.connecting = undefined; throw error; });
+    return this.connecting;
+  }
+  async startScheduledPublish(ref: AttemptRef, publishAt: Date): Promise<void> {
+    // Future work belongs to the due sweep; no long-lived API timer is needed.
+    if (publishAt.getTime() > Date.now()) return;
+    try {
+      const client = await this.client();
+      await client.workflow.start("scheduledPublish", {
+        args: [ref], workflowId: `scheduled-publication-${ref.idempotencyKey}`,
+        taskQueue: process.env.TEMPORAL_TASK_QUEUE ?? "tmbh-publishing",
+      });
+    } catch (error) {
+      if (error instanceof WorkflowExecutionAlreadyStartedError) return;
+      // Committed pending work will be retried by the worker sweep.
+    }
+  }
+  async onModuleDestroy(): Promise<void> { await this.connecting?.catch(() => undefined); await this.connection?.close(); }
+}
+
+const DEFAULT_DEPENDENCIES: PublishingDependencies = {
+  tenantTransaction: withTenant,
+  workflowStarter: new TemporalWorkflowStarter(),
+  repository: new PublishingExecutionRepository(pool),
+  assertReady: () => assertPublishingSchema(pool),
+  approvalGate: new ApprovalGateService(),
+};
+
+@Injectable()
+export class PublishingService {
+  private readonly dependencies: PublishingDependencies;
+
+  constructor(
+    @Optional() @Inject(PUBLISHING_DEPENDENCIES) dependencies?: Partial<PublishingDependencies>,
+  ) {
+    this.dependencies = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+  }
+
+  async createDraft(workspaceId: string, actor: Actor, post: DraftPost): Promise<DraftRecord> {
+    await this.dependencies.assertReady();
+    const draft = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const result = await client.query(
+        `INSERT INTO drafts (workspace_id, author_user_id, post)
+         VALUES ($1, $2, $3) RETURNING *`,
+        [workspaceId, actor.userId, post],
+      );
+      const draft = draftFromRow(requiredRow(result.rows[0], "created draft"));
+      await this.audit(client, workspaceId, actor, "draft.created", draft.id, { state: draft.state });
+      return draft;
+    });
+    return draft;
+  }
+
+  async listDrafts(
+    workspaceId: string,
+    options: { state?: DraftState; limit: number },
+  ): Promise<DraftRecord[]> {
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT * FROM drafts
+         WHERE ($1::text IS NULL OR state = $1)
+         ORDER BY updated_at DESC
+         LIMIT $2`,
+        [options.state ?? null, options.limit],
+      );
+      return result.rows.map((row: unknown) => draftFromRow(requiredRow(row, "draft")));
+    });
+  }
+
+  async updateDraft(
+    workspaceId: string,
+    actor: Actor,
+    draftId: string,
+    post: DraftPost,
+  ): Promise<DraftRecord> {
+    await this.dependencies.assertReady();
+    const draft = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const result = await client.query(
+        `UPDATE drafts SET post = $2, updated_at = now()
+         WHERE id = $1 AND (state = 'editing' OR (state = 'in_review' AND EXISTS (SELECT 1 FROM polls WHERE draft_id = $1 AND state = 'open'))) RETURNING *`,
+        [draftId, post],
+      );
+      if (result.rowCount !== 1) {
+        const current = await client.query("SELECT state FROM drafts WHERE id = $1", [draftId]);
+        if (current.rowCount === 0) throw new NotFoundException(`draft ${draftId} not found`);
+        throw new BadRequestException(`cannot edit draft in state ${String(current.rows[0]?.state)}`);
+      }
+      const draft = draftFromRow(requiredRow(result.rows[0], "updated draft"));
+      await markDraftPollsStale(client, workspaceId, draftId);
+      await this.audit(client, workspaceId, actor, "draft.updated", draftId, { state: draft.state });
+      return draft;
+    });
+    return draft;
+  }
+
+  async submitForReview(workspaceId: string, actor: Actor, draftId: string): Promise<DraftRecord> {
+    return this.transition(workspaceId, actor, draftId, "editing", "in_review", "draft.submitted", {
+      from: "editing",
+      to: "in_review",
+    });
+  }
+
+  /**
+   * `review → approved` with the E1 chatgov gate (chatgov-design.md §4).
+   *
+   * E1 evaluates the destination's compiled posting_policy_snapshots PER
+   * DESTINATION (fan-out law D8): immediate fires (no gate), admin_only fires
+   * only for an Owner/Admin approver, quorum blocks with INSUFFICIENT_QUORUM
+   * + PENDING_POLL until the linked chat poll passes (P2 owns the poll state
+   * machine). Workspaces with no live posting_rules keep today's behavior
+   * exactly — the gate is a no-op for them; once rules exist, a destination
+   * with no compiled snapshot fails closed with OUTSIDE_POLICY (P0 hand-off).
+   *
+   * Fired decisions commit in the SAME transaction as the approval (the hook
+   * runs under the draft row lock, before the transition UPDATE). A blocked
+   * destination aborts that transaction (Conflict) and its verdicts are then
+   * recorded after the rollback — the blocked queue (gate_decisions) is the
+   * observable surface for them.
+   */
+  async approve(workspaceId: string, actor: Actor, draftId: string): Promise<DraftRecord> {
+    const gate = this.dependencies.approvalGate ?? null;
+    try {
+      return await this.transition(workspaceId, actor, draftId, "in_review", "approved", "draft.approved", {
+        from: "in_review",
+        to: "approved",
+      }, actor.userId, gate === null ? undefined : async (client: PoolClient, draft: DraftRecord) => {
+        const evaluation = await gate.evaluate(client, workspaceId, draftId, draft.post, actor.userId);
+        if (evaluation.blocked.length > 0) throw new ApprovalGateBlockedError(evaluation.blocked);
+        await gate.recordFiredInTxn(client, workspaceId, draftId, actor.userId, evaluation.verdicts);
+      });
+    } catch (error) {
+      if (error instanceof ApprovalGateBlockedError) {
+        // The approval rolled back; record the blocked verdicts with no draft
+        // lock held (gate_decisions' FK takes a KEY SHARE on the draft row,
+        // which would deadlock against the still-held FOR UPDATE).
+        await gate?.recordBlocked(workspaceId, draftId, actor.userId, error.verdicts).catch(() => undefined);
+      }
+      throw error;
+    }
+  }
+
+  async reject(workspaceId: string, actor: Actor, draftId: string, reason?: string): Promise<DraftRecord> {
+    return this.transition(workspaceId, actor, draftId, "in_review", "rejected", "draft.rejected", {
+      from: "in_review",
+      to: "rejected",
+      ...(reason === undefined ? {} : { reason }),
+    }, actor.userId);
+  }
+
+  async schedule(
+    workspaceId: string,
+    actor: Actor,
+    draftId: string,
+    connectionId: string,
+    publishAt: Date,
+    requiredPermission: "publication.schedule" | "publication.publish" = "publication.schedule",
+    expectedPrevious?: { state: "failed" | "needs_reauthorization"; generation: string },
+  ): Promise<ScheduledPublicationRecord> {
+    if (!Number.isFinite(publishAt.getTime())) throw new BadRequestException("publishAt must be a valid timestamp");
+
+    await this.dependencies.assertReady();
+    const scheduled = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      // FK checks bypass RLS, so a foreign tenant's connection id would satisfy
+      // the constraint; this RLS-scoped read is the actual tenancy check.
+      const connection = await client.query("SELECT provider FROM connections WHERE id = $1 AND disconnected_at IS NULL", [connectionId]);
+      if (connection.rowCount !== 1) throw new NotFoundException(`connection ${connectionId} not found`);
+      if (!isPublishingProvider(String(connection.rows[0]?.provider))) throw new BadRequestException("provider is not enabled for publishing");
+      if (!(await userCanUseConnection(client, workspaceId, actor.userId, connectionId))) {
+        throw new ForbiddenException("connection is not shared with any of your groups");
+      }
+
+      let attempt;
+      try {
+        attempt = await this.dependencies.repository.scheduleAttempt(client, {
+          workspaceId, draftId, connectionId, scheduledByUserId: actor.userId, requiredPermission, publishAt, expectedPrevious,
+        });
+      } catch (error) {
+        if (error instanceof PublishingStateError) throw new ConflictException({ code: error.code, message: error.message });
+        throw error;
+      }
+      const result = await client.query("SELECT * FROM scheduled_publications WHERE id = $1", [attempt.scheduleId]);
+      const scheduled = scheduledFromRow(requiredRow(result.rows[0], "scheduled publication"));
+      await this.audit(client, workspaceId, actor, "publication.scheduled", draftId, {
+        connectionId,
+        publishAt: publishAt.toISOString(),
+      });
+      return scheduled;
+    });
+    await this.dependencies.workflowStarter
+      .startScheduledPublish({ workspaceId, scheduleId: scheduled.id, generation: scheduled.generation, idempotencyKey: scheduled.idempotencyKey }, publishAt)
+      .catch(() => undefined);
+    return scheduled;
+  }
+
+  async cancelSchedule(workspaceId: string, actor: Actor, draftId: string): Promise<DraftRecord> {
+    await this.dependencies.assertReady();
+    const draft = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      try { await this.dependencies.repository.cancelAttempt(client, workspaceId, draftId); }
+      catch (error) {
+        if (error instanceof PublishingStateError) throw new ConflictException({ code: error.code, message: error.message });
+        throw error;
+      }
+      const changed = await client.query(
+        "SELECT * FROM drafts WHERE id = $1 AND state IN ('approved', 'scheduled') FOR UPDATE",
+        [draftId],
+      );
+      if (changed.rowCount !== 1) await this.throwTransitionError(client, draftId, "approved", "editing");
+      const oldState = String(changed.rows[0]?.state);
+      // Legacy pending schedules were marked scheduled before this claim gate
+      // existed. Reopen them for review instead of treating them as approved.
+      const reopened = oldState === "scheduled"
+        ? await client.query(
+          "UPDATE drafts SET state = 'editing', reviewer_user_id = NULL, updated_at = now() WHERE id = $1 AND state = 'scheduled' RETURNING *",
+          [draftId],
+        )
+        : changed;
+      if (reopened.rowCount !== 1) throw new BadRequestException(`cannot reopen draft ${draftId}`);
+      const draft = draftFromRow(requiredRow(reopened.rows[0], "cancelled draft"));
+      await this.audit(client, workspaceId, actor, "publication.schedule_cancelled", draftId, {
+        from: oldState,
+        to: draft.state,
+      });
+      return draft;
+    });
+    return draft;
+  }
+
+  private async transition(
+    workspaceId: string,
+    actor: Actor,
+    draftId: string,
+    from: DraftState,
+    to: DraftState,
+    action: string,
+    diff: Record<string, unknown>,
+    reviewerUserId?: string,
+    /** E1 seam: runs inside the transition's transaction, under the draft row
+     * lock, before the UPDATE — may abort the whole transition by throwing. */
+    afterLock?: (client: PoolClient, draft: DraftRecord) => Promise<void>,
+  ): Promise<DraftRecord> {
+    await this.dependencies.assertReady();
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const current = await client.query("SELECT * FROM drafts WHERE id = $1 FOR UPDATE", [draftId]);
+      if (current.rowCount !== 1) throw new NotFoundException("draft not found");
+      if (afterLock !== undefined) await afterLock(client, draftFromRow(current.rows[0]));
+      const hash = canonicalPostHash(current.rows[0].post as DraftPost);
+      const result = await client.query(
+        `UPDATE drafts
+         SET state = $2, reviewer_user_id = COALESCE($3, reviewer_user_id), updated_at = now(),
+             approved_revision = CASE WHEN $2 = 'approved' THEN revision ELSE NULL END,
+             approved_hash = CASE WHEN $2 = 'approved' THEN $5 ELSE NULL END,
+             approved_at = CASE WHEN $2 = 'approved' THEN now() ELSE NULL END
+         WHERE id = $1 AND state = $4 RETURNING *`,
+        [draftId, to, reviewerUserId ?? null, from, hash],
+      );
+      if (result.rowCount !== 1) await this.throwTransitionError(client, draftId, from, to);
+      const draft = draftFromRow(requiredRow(result.rows[0], "transitioned draft"));
+      if (to === "in_review") await autoOpenDraftPoll(client, workspaceId, draftId, actor, draft.post);
+      await this.audit(client, workspaceId, actor, action, draftId, diff);
+      return draft;
+    });
+  }
+
+  private async throwTransitionError(
+    client: PoolClient,
+    draftId: string,
+    expected: DraftState,
+    target: DraftState,
+  ): Promise<never> {
+    const current = await client.query("SELECT state FROM drafts WHERE id = $1", [draftId]);
+    if (current.rowCount === 0) throw new NotFoundException(`draft ${draftId} not found`);
+    throw new BadRequestException(
+      `illegal draft transition ${String(current.rows[0]?.state)} -> ${target}; expected ${expected}`,
+    );
+  }
+
+  private async audit(
+    client: PoolClient,
+    workspaceId: string,
+    actor: Actor,
+    action: string,
+    targetId: string,
+    diff: Record<string, unknown>,
+  ): Promise<void> {
+    await client.query("SELECT audit_append($1, $2, $3, $4, 'draft', $5, $6)", [
+      workspaceId, actor.userId, actor.role, action, targetId, scrub(diff),
+    ]);
+  }
+}
+
+function requiredRow(row: unknown, description: string): Record<string, unknown> {
+  if (typeof row !== "object" || row === null) throw new Error(`database did not return ${description}`);
+  return row as Record<string, unknown>;
+}
+
+function draftFromRow(row: Record<string, unknown>): DraftRecord {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    authorUserId: String(row.author_user_id),
+    post: row.post as DraftPost,
+    state: row.state as DraftState,
+    ...(row.reviewer_user_id === null || row.reviewer_user_id === undefined
+      ? {}
+      : { reviewerUserId: String(row.reviewer_user_id) }),
+    createdAt: new Date(String(row.created_at)),
+    updatedAt: new Date(String(row.updated_at)),
+  };
+}
+
+function scheduledFromRow(row: Record<string, unknown>): ScheduledPublicationRecord {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    draftId: String(row.draft_id),
+    connectionId: String(row.connection_id),
+    publishAt: new Date(String(row.publish_at)),
+    idempotencyKey: String(row.idempotency_key),
+    generation: String(row.generation),
+    state: row.state as ScheduledPublicationRecord["state"],
+  };
+}
diff --git a/apps/api/src/rbac/rbac.guard.ts b/apps/api/src/rbac/rbac.guard.ts
new file mode 100644
index 0000000..6178f3b
--- /dev/null
+++ b/apps/api/src/rbac/rbac.guard.ts
@@ -0,0 +1,83 @@
+import { BadRequestException, CanActivate, ExecutionContext, Inject, Injectable, SetMetadata, UnauthorizedException, ForbiddenException } from "@nestjs/common";
+import { Reflector } from "@nestjs/core";
+import { verifySession, epochValid, type SessionPayload } from "../auth/session.js";
+import { pool, withTenant } from "../db/client.js";
+import { userCanUseConnection } from "../groups/groups.service.js";
+import { isUuid } from "../http/validation.js";
+
+export const PERMISSION_KEY = "required_permission";
+export const GROUP_ACCESS_KEY = "required_group_access";
+
+export const RequirePermission = (permission: string): MethodDecorator =>
+  SetMetadata(PERMISSION_KEY, permission) as MethodDecorator;
+
+/**
+ * Additionally gate a route on group scope for its `:connectionId` param:
+ * Owner/Admin pass; anyone else must belong to a group the connection is
+ * assigned to. Fails closed if the route has no `:connectionId`.
+ */
+export const RequireGroupAccess = (source: "params" | "body" = "params"): MethodDecorator =>
+  SetMetadata(GROUP_ACCESS_KEY, source) as MethodDecorator;
+
+export interface AuthenticatedRequest {
+  session?: SessionPayload;
+}
+
+/**
+ * RBAC guard: session signature -> workspace membership -> permission set.
+ * Epoch-fenced (finding #2): revocation bumps authz_epoch, session fails closed.
+ */
+@Injectable()
+export class RbacGuard implements CanActivate {
+  constructor(@Inject(Reflector) private readonly reflector: Reflector) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const required = this.reflector.get<string>(PERMISSION_KEY, context.getHandler());
+    const http = context.switchToHttp();
+    const req = http.getRequest<{ headers: Record<string, string>; params?: Record<string, string>; body?: unknown } & AuthenticatedRequest>();
+    const auth = req.headers["authorization"];
+    if (auth === undefined || !auth.startsWith("Bearer ")) throw new UnauthorizedException();
+    const session = verifySession(auth.slice("Bearer ".length));
+    if (session === null) throw new UnauthorizedException();
+
+    const ws = await pool.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [session.workspaceId]);
+    // authz_epoch is bigint: node-postgres returns it as a string, so normalise
+    // before the strict comparison or every session reads as stale.
+    const rawEpoch = ws.rows[0]?.authz_epoch as string | number | undefined;
+    if (rawEpoch === undefined || !epochValid(session, Number(rawEpoch))) {
+      throw new UnauthorizedException("authorization epoch stale — re-authenticate");
+    }
+
+    if (required !== undefined) {
+      // memberships is FORCE RLS: the lookup must run inside the session's
+      // tenant context, otherwise sp_app sees zero rows and every check fails.
+      const allowed = await withTenant(session.workspaceId, (client) =>
+        client.query(
+          `SELECT 1 FROM role_permissions rp
+           JOIN memberships m ON m.role = rp.role AND m.workspace_id = $1 AND m.user_id = $2 AND m.status = 'active'
+           WHERE rp.permission = $3`,
+          [session.workspaceId, session.userId, required],
+        ),
+      );
+      if (allowed.rowCount === 0) throw new ForbiddenException(`missing permission: ${required}`);
+    }
+
+    const groupSource = this.reflector.get<"params" | "body" | undefined>(GROUP_ACCESS_KEY, context.getHandler());
+    if (groupSource !== undefined) {
+      const body = req.body;
+      const connectionId = groupSource === "body"
+        ? (typeof body === "object" && body !== null && "connectionId" in body ? body.connectionId : undefined)
+        : req.params?.connectionId;
+      if (connectionId === undefined || connectionId === "") {
+        throw new ForbiddenException("group access check requires a connectionId");
+      }
+      if (typeof connectionId !== "string" || !isUuid(connectionId)) throw new BadRequestException("connectionId must be a UUID");
+      const permitted = await withTenant(session.workspaceId, (client) =>
+        userCanUseConnection(client, session.workspaceId, session.userId, connectionId),
+      );
+      if (!permitted) throw new ForbiddenException("connection is not shared with any of your groups");
+    }
+    req.session = session;
+    return true;
+  }
+}
diff --git a/apps/api/src/realtime/gateway.ts b/apps/api/src/realtime/gateway.ts
new file mode 100644
index 0000000..de48d1b
--- /dev/null
+++ b/apps/api/src/realtime/gateway.ts
@@ -0,0 +1,25 @@
+import type { PoolClient } from "pg";
+import { isUuid } from "../http/validation.js";
+import type { SessionPayload } from "../auth/session.js";
+export type SubscriptionDecision = { allow: true; workspaceId: string } | { allow: false; reason: string };
+
+/** Takes an idle, checked-out client. Owns a tenant transaction so FORCE RLS
+ * membership checks work, and SET LOCAL cannot leak to the next pool borrower. */
+export async function authorizeSubscription(client: PoolClient, args: { token: string; workspaceId: string },
+  verify: (token: string) => SessionPayload | null): Promise<SubscriptionDecision> {
+  const session = verify(args.token);
+  if (!session || !isUuid(session.userId) || !isUuid(args.workspaceId) || !Number.isSafeInteger(session.authzEpoch)) return { allow: false, reason: "invalid session" };
+  if (session.workspaceId !== args.workspaceId) return { allow: false, reason: "cross-workspace subscription denied" };
+  await client.query("BEGIN");
+  try {
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [args.workspaceId]);
+    const epoch = await client.query<{ authz_epoch: string | number }>("SELECT authz_epoch FROM workspaces WHERE id = $1", [args.workspaceId]);
+    const current = Number(epoch.rows[0]?.authz_epoch);
+    if (!Number.isSafeInteger(current) || session.authzEpoch !== current) return { allow: false, reason: "stale authorization epoch" };
+    const permission = await client.query(
+      `SELECT 1 FROM role_permissions rp JOIN memberships m ON m.role=rp.role
+       WHERE m.workspace_id=$1 AND m.user_id=$2 AND m.status='active' AND rp.permission='stream.view'`, [args.workspaceId, session.userId]);
+    if (!permission.rowCount) return { allow: false, reason: "missing stream.view permission" };
+    return { allow: true, workspaceId: args.workspaceId };
+  } finally { await client.query("ROLLBACK"); }
+}
diff --git a/apps/api/src/realtime/realtime.module.ts b/apps/api/src/realtime/realtime.module.ts
new file mode 100644
index 0000000..efc0cac
--- /dev/null
+++ b/apps/api/src/realtime/realtime.module.ts
@@ -0,0 +1,27 @@
+import { Inject, Injectable, Module, OnApplicationBootstrap, OnModuleDestroy } from "@nestjs/common";
+import { HttpAdapterHost } from "@nestjs/core";
+import type { Server, IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+import { MediaControlModule } from "../media-control/media-control.module.js";
+import { RealtimeService } from "./realtime.service.js";
+import { RealtimeSocket } from "./websocket.js";
+@Injectable()
+export class RealtimeTransport implements OnApplicationBootstrap, OnModuleDestroy {
+  private server: Server | null = null;
+  private readonly upgrade = (request: IncomingMessage, socket: Duplex, head: Buffer): void => {
+    if (request.url?.split("?")[0] !== "/realtime") return;
+    const origin = request.headers.origin;
+    const allowed = process.env.PUBLIC_ORIGIN ?? `http://${request.headers.host}`;
+    if (origin && origin !== allowed) { socket.end("HTTP/1.1 403 Forbidden\r\nConnection: close\r\n\r\n"); return; }
+    const peer = RealtimeSocket.accept(request, socket, head); if (!peer) return;
+    const handlers = this.realtime.attach(peer); peer.onMessage = handlers.message; peer.onClose = handlers.close;
+  };
+  constructor(@Inject(HttpAdapterHost) private readonly adapter: HttpAdapterHost, @Inject(RealtimeService) private readonly realtime: RealtimeService) {}
+  onApplicationBootstrap(): void {
+    this.server = this.adapter.httpAdapter.getHttpServer() as Server;
+    this.server.on("upgrade", this.upgrade);
+  }
+  onModuleDestroy(): void { this.server?.off("upgrade", this.upgrade); }
+}
+@Module({ imports: [MediaControlModule], providers: [RealtimeService, RealtimeTransport], exports: [RealtimeService] })
+export class RealtimeModule {}
diff --git a/apps/api/src/realtime/realtime.service.ts b/apps/api/src/realtime/realtime.service.ts
new file mode 100644
index 0000000..c8b5b5b
--- /dev/null
+++ b/apps/api/src/realtime/realtime.service.ts
@@ -0,0 +1,342 @@
+import { Inject, Injectable, OnModuleDestroy, Optional } from "@nestjs/common";
+import { pool, withTenant } from "../db/client.js";
+import { verifySession } from "../auth/session.js";
+import { isUuid } from "../http/validation.js";
+import { MediaControlService, type ChannelStatus } from "../media-control/media-control.service.js";
+import { authorizeChat, tokenWorkspace } from "../live-chat/auth.js";
+import { chatTopic, chatWindowKey, CHAT_WINDOW_SCRIPT } from "../live-chat/bridge.js";
+import { RespControlRedis } from "../media-control/redis.js";
+import type { LiveChatEventType } from "@tactical-media-broadcast-hub/core";
+import { authorizeSubscription } from "./gateway.js";
+import { RespRedisSubscriptions, type RedisSubscriptions } from "./subscribe.js";
+export const REALTIME_DEPENDENCIES = Symbol("REALTIME_DEPENDENCIES");
+export interface RealtimePeer { send(value: unknown): boolean; close(code?: number): void }
+interface Dependencies {
+  subscriptions: RedisSubscriptions;
+  workspaceFromToken: (token: string) => string | null;
+  authorizeChat: (token: string, workspaceId: string, permission: string) => Promise<boolean>;
+  chatLatestSeq: (workspaceId: string, liveId: string) => Promise<number>;
+  chatWindow: (workspaceId: string, liveId: string) => Promise<Record<string, unknown>[]>;
+  authorize: (token: string, workspaceId: string) => Promise<boolean>;
+  channelExists: (workspaceId: string, channelId: string) => Promise<boolean>;
+  status: (workspaceId: string) => Promise<{ channels: ChannelStatus[] }>;
+}
+interface StateEvent { type: "state"; workspaceId: string; channelId: string; kind: "desired" | "observed"; seq: number; data: unknown }
+/** S5: chat frames ride the same topic ring and seq counter (§3.3). */
+export interface ChatEvent { type: "chat"; workspaceId: string; channelId: string; seq: number; frame: Record<string, unknown> }
+type TopicEvent = StateEvent | ChatEvent;
+interface Topic {
+  ws: string; ch: string; seq: number; ring: TopicEvent[]; listeners: Set<RealtimePeer>;
+  unsubscribe: (() => void) | null; timer: ReturnType<typeof setInterval> | null; idle: ReturnType<typeof setTimeout> | null;
+  polling: boolean; latest: Record<string, string>;
+}
+interface ChatTopic { seq: number; pending: Map<number, Record<string, unknown>>; gapTimer: ReturnType<typeof setTimeout> | null; ws: string; liveId: string; ring: Record<string, unknown>[]; listeners: Map<RealtimePeer, string>; unsubscribe: (() => void) | null }
+interface Viewer { canonical: boolean; chatIds: Map<string, string>; channelIds: Map<string, string>; token: string | null; ws: string | null; topics: Set<string>; busy: Promise<void>; authDeadline: number; queued: number; timer: ReturnType<typeof setInterval>; closed: boolean }
+
+@Injectable()
+export class RealtimeService implements OnModuleDestroy {
+  private readonly deps: Dependencies;
+  private readonly chatRedis = new RespControlRedis(process.env.REDIS_URL ?? "redis://localhost:6379");
+  private readonly chatTopics = new Map<string, ChatTopic>();
+  private readonly chatStarts = new Map<string, Promise<ChatTopic>>();
+  private readonly topics = new Map<string, Topic>();
+  private readonly starts = new Map<string, Promise<void>>();
+  private readonly viewers = new Map<RealtimePeer, Viewer>();
+  constructor(@Inject(MediaControlService) control: MediaControlService,
+    @Optional() @Inject(REALTIME_DEPENDENCIES) dependencies?: Partial<Dependencies>) {
+    this.deps = {
+      workspaceFromToken: dependencies?.workspaceFromToken ?? tokenWorkspace,
+      authorizeChat: dependencies?.authorizeChat ?? (async (token, workspaceId, permission) => {
+        const client = await pool.connect();
+        try { return Boolean(await authorizeChat(client, token, workspaceId, permission)); } finally { client.release(); }
+      }),
+      chatLatestSeq: dependencies?.chatLatestSeq ?? (async (workspaceId, liveId) => {
+        const result = await withTenant(workspaceId, client => client.query<{ seq: string | number }>("SELECT seq FROM live_chat_seq WHERE workspace_id=$1 AND channel_id=$2", [workspaceId, liveId]));
+        return Number(result.rows[0]?.seq ?? 0);
+      }),
+      chatWindow: dependencies?.chatWindow ?? (async (workspaceId, liveId) => {
+        const rows = await this.chatRedis.eval(CHAT_WINDOW_SCRIPT, [chatWindowKey(workspaceId, liveId)], []);
+        return Array.isArray(rows) ? rows.filter((row): row is string => typeof row === "string").map(row => JSON.parse(row) as Record<string, unknown>) : [];
+      }),
+      subscriptions: dependencies?.subscriptions ?? new RespRedisSubscriptions(process.env.REDIS_URL ?? "redis://localhost:6379", () => {
+        for (const [peer, viewer] of this.viewers) peer.send(viewer.canonical ? { op: "resync", topic: "livechat" } : { type: "RESYNC_REQUIRED" });
+      }),
+      authorize: dependencies?.authorize ?? (async (token, workspaceId) => {
+        const client = await pool.connect();
+        try { return (await authorizeSubscription(client, { token, workspaceId }, verifySession)).allow; }
+        finally { client.release(); }
+      }),
+      channelExists: dependencies?.channelExists ?? (async (ws, ch) => {
+        const result = await withTenant(ws, client => client.query("SELECT id FROM virtual_channels WHERE workspace_id=$1 AND id=$2", [ws, ch]));
+        return Boolean(result.rowCount);
+      }),
+      status: dependencies?.status ?? (ws => control.getStatus(ws)),
+    };
+  }
+  attach(peer: RealtimePeer): { message: (value: unknown) => void; close: () => void } {
+    const viewer: Viewer = { canonical: false, chatIds: new Map(), channelIds: new Map(), token: null, ws: null, topics: new Set(), busy: Promise.resolve(), authDeadline: Date.now() + 3000, queued: 0,
+      timer: setInterval(() => { void this.revalidate(peer); }, 1000), closed: false };
+    viewer.timer.unref(); this.viewers.set(peer, viewer);
+    return {
+      message: value => {
+        // Bound upstream work too; a client cannot queue arbitrary authorization queries.
+        if (viewer.closed) return;
+        if (++viewer.queued > 32) { peer.close(1008); this.detach(peer); return; }
+        if (typeof value !== "object" || !value) { peer.close(1008); return; }
+        const message = value as Record<string, unknown>;
+        viewer.busy = viewer.busy.then(() => this.message(peer, viewer, message)).finally(() => { viewer.queued -= 1; }).catch(() => { peer.close(1011); this.detach(peer); });
+      }, close: () => this.detach(peer),
+    };
+  }
+  private async check(token: string, ws: string, permission?: string): Promise<boolean> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try { return await Promise.race([permission ? this.deps.authorizeChat(token, ws, permission) : this.deps.authorize(token, ws), new Promise<boolean>(resolve => { timer = setTimeout(() => resolve(false), 1000); })]); }
+    catch { return false; }
+    finally { if (timer) clearTimeout(timer); }
+  }
+  private async revalidate(peer: RealtimePeer): Promise<void> {
+    const viewer = this.viewers.get(peer);
+    if (!viewer || viewer.closed) return;
+    if (Date.now() >= viewer.authDeadline) { peer.close(1008); this.detach(peer); return; }
+    if (!viewer.token || !viewer.ws) return;
+    if (!await this.check(viewer.token, viewer.ws, viewer.canonical ? (viewer.chatIds.size ? "livechat.view" : "stream.view") : undefined) ||
+      (viewer.channelIds.size > 0 && !await this.check(viewer.token, viewer.ws, "stream.view"))) { peer.close(1008); this.detach(peer); }
+    else viewer.authDeadline = Date.now() + 3000;
+  }
+  private async message(peer: RealtimePeer, viewer: Viewer, msg: Record<string, unknown>): Promise<void> {
+    if (viewer.closed) return;
+    if (msg.op !== undefined || viewer.canonical) { await this.canonicalMessage(peer, viewer, msg); return; }
+    if (viewer.token === null) {
+      if (msg.type !== "auth" || typeof msg.token !== "string" || msg.token.length > 8192 || typeof msg.workspaceId !== "string" || !await this.check(msg.token, msg.workspaceId)) { peer.close(1008); this.detach(peer); return; }
+      if (viewer.closed) return;
+      viewer.token = msg.token; viewer.ws = msg.workspaceId; viewer.authDeadline = Date.now() + 3000;
+      peer.send({ type: "auth_ack", workspaceId: viewer.ws }); return;
+    }
+    if (msg.type === "ack") return;
+    if (typeof msg.channelId !== "string" || !isUuid(msg.channelId) || !viewer.ws) { peer.close(1008); this.detach(peer); return; }
+    const key = `${viewer.ws}:${msg.channelId}`;
+    if (msg.type === "unsubscribe") { this.leave(peer, key); viewer.topics.delete(key); peer.send({ type: "unsubscribe_ack", channelId: msg.channelId }); return; }
+    if (msg.type !== "subscribe" || viewer.topics.size >= 32 ||
+      (msg.lastSeq !== undefined && (!Number.isSafeInteger(msg.lastSeq) || Number(msg.lastSeq) < 0))) { peer.close(1008); this.detach(peer); return; }
+    // Recheck every subscription, including subscriptions on an already authenticated socket.
+    if (!await this.check(viewer.token, viewer.ws) || !await this.deps.channelExists(viewer.ws, msg.channelId)) { peer.send({ type: "subscribe_denied", channelId: msg.channelId }); return; }
+    if (viewer.closed) return;
+    const topic = await this.topic(viewer.ws, msg.channelId);
+    if (viewer.closed) { if (!topic.listeners.size) this.leave(peer, key); return; }
+    topic.listeners.add(peer); viewer.topics.add(key); viewer.authDeadline = Date.now() + 3000;
+    peer.send({ type: "subscribe_ack", channelId: msg.channelId, seq: topic.seq });
+    if (msg.lastSeq !== undefined) {
+      const seq = Number(msg.lastSeq), oldest = topic.ring[0]?.seq ?? topic.seq + 1;
+      if (seq > topic.seq || seq < oldest - 1) peer.send({ type: "RESYNC_REQUIRED", channelId: msg.channelId });
+      else for (const event of topic.ring) if (event.seq > seq) peer.send(event);
+    } else for (const kind of ["desired", "observed"] as const) {
+      const event = [...topic.ring].reverse().find((e): e is StateEvent => e.type === "state" && e.kind === kind);
+      if (event) peer.send(event);
+    }
+  }
+  private async canonicalMessage(peer: RealtimePeer, viewer: Viewer, msg: Record<string, unknown>): Promise<void> {
+    if (!viewer.token) {
+      const ws = typeof msg.token === "string" ? this.deps.workspaceFromToken(msg.token) : null;
+      if (msg.op !== "auth" || typeof msg.token !== "string" || msg.token.length > 8192 || !ws ||
+        !await this.check(msg.token, ws, "stream.view")) {
+        peer.send({ op: "close", reason: "unauthorized" }); peer.close(1008); this.detach(peer); return;
+      }
+      if (viewer.closed) return;
+      viewer.canonical = true; viewer.token = msg.token; viewer.ws = ws; viewer.authDeadline = Date.now() + 3000;
+      peer.send({ op: "ready" }); return;
+    }
+    if (msg.op === "ping") { peer.send({ op: "pong" }); return; }
+    if (msg.op === "ack") return;
+    if (msg.op === "unsubscribe" && typeof msg.id === "string") {
+      const liveId = viewer.chatIds.get(msg.id);
+      if (liveId) { this.leaveChat(peer, viewer.ws ?? "", liveId); viewer.chatIds.delete(msg.id); }
+      const key = viewer.channelIds.get(msg.id);
+      if (key) { this.leave(peer, key); viewer.topics.delete(key); viewer.channelIds.delete(msg.id); }
+      return;
+    }
+    const liveId = msg.topic === "livechat" ? msg.liveId : msg.channelId;
+    if (msg.op !== "subscribe" || typeof msg.id !== "string" || msg.id.length === 0 || msg.id.length > 128 ||
+      (msg.topic !== "livechat" && msg.topic !== "channel") || typeof liveId !== "string" || !isUuid(liveId) || !viewer.ws ||
+      viewer.chatIds.size + viewer.topics.size >= 32 || viewer.chatIds.has(msg.id) || viewer.channelIds.has(msg.id) ||
+      (msg.topic === "livechat" && [...viewer.chatIds.values()].includes(liveId)) ||
+      (msg.topic === "channel" && viewer.topics.has(`${viewer.ws}:${liveId}`)) ||
+      (msg.lastSeq !== undefined && (!Number.isSafeInteger(msg.lastSeq) || Number(msg.lastSeq) < 0))) {
+      peer.send({ op: "nack", id: msg.id, reason: "invalid subscription" }); return;
+    }
+    if (!await this.check(viewer.token, viewer.ws, msg.topic === "livechat" ? "livechat.view" : "stream.view") ||
+      !await this.deps.channelExists(viewer.ws, liveId)) {
+      peer.send({ op: "nack", id: msg.id, reason: "subscription denied" }); return;
+    }
+    if (viewer.closed) return;
+    if (msg.topic === "channel") {
+      const topic = await this.topic(viewer.ws, liveId);
+      if (viewer.closed) return;
+      const key = `${viewer.ws}:${liveId}`;
+      topic.listeners.add(peer); viewer.topics.add(key); viewer.channelIds.set(msg.id, key);
+      peer.send({ op: "ack", id: msg.id, fromSeq: topic.seq });
+      if (msg.lastSeq !== undefined) {
+        const seq = Number(msg.lastSeq), oldest = topic.ring[0]?.seq ?? topic.seq + 1;
+        if (seq > topic.seq || seq < oldest - 1) peer.send({ op: "resync", topic: "channel" });
+        else for (const event of topic.ring) if (event.seq > seq) this.sendState(peer, event);
+      } else for (const event of topic.ring.slice(-2)) this.sendState(peer, event);
+      return;
+    }
+    const topic = await this.chatTopicFor(viewer.ws, liveId);
+    if (viewer.closed) { if (!topic.listeners.size) { topic.unsubscribe?.(); this.chatTopics.delete(chatTopic(topic.ws, liveId)); } return; }
+    topic.listeners.set(peer, msg.id); viewer.chatIds.set(msg.id, liveId); viewer.authDeadline = Date.now() + 3000;
+    const highest = topic.seq, oldest = Number(topic.ring[0]?.seq ?? highest + 1);
+    peer.send({ op: "ack", id: msg.id, fromSeq: highest });
+    if (msg.lastSeq !== undefined) {
+      const seq = Number(msg.lastSeq);
+      const replay = topic.ring.filter(frame => Number(frame.seq) > seq);
+      const complete = replay.every((frame, i) => Number(frame.seq) === (i === 0 ? seq : Number(replay[i - 1]?.seq)) + 1);
+      if (seq > highest || seq < oldest - 1 || !complete) peer.send({ op: "resync", topic: "livechat" });
+      else for (const frame of topic.ring) if (Number(frame.seq) > seq) this.sendChat(peer, frame);
+    }
+  }
+  private async chatTopicFor(ws: string, liveId: string): Promise<ChatTopic> {
+    const key = chatTopic(ws, liveId);
+    const pending = this.chatStarts.get(key); if (pending) return pending;
+    const existing = this.chatTopics.get(key); if (existing) return existing;
+    if (this.chatTopics.size + this.chatStarts.size >= 1024) throw new Error("chat topic capacity exceeded");
+    const topic: ChatTopic = { seq: 0, pending: new Map(), gapTimer: null, ws, liveId, ring: [], listeners: new Map(), unsubscribe: null };
+    const start = (async () => {
+      try {
+        topic.unsubscribe = await this.deps.subscriptions.subscribe(key, raw => {
+          try { this.receiveChat(topic, JSON.parse(raw) as Record<string, unknown>); } catch { /* Ignore malformed frames. */ }
+        });
+        const window = await this.deps.chatWindow(ws, liveId);
+        topic.ring = [...window, ...topic.ring].filter((frame, i, frames) => frames.findIndex(other => other.seq === frame.seq) === i)
+          .sort((a, b) => Number(a.seq) - Number(b.seq)).slice(-500);
+        topic.seq = topic.ring.length ? Number(topic.ring.at(-1)?.seq ?? 0) : await this.deps.chatLatestSeq(ws, liveId);
+        this.chatTopics.set(key, topic); return topic;
+      } catch (error) { topic.unsubscribe?.(); throw error; }
+      finally { this.chatStarts.delete(key); }
+    })();
+    this.chatStarts.set(key, start); return start;
+  }
+  private receiveChat(topic: ChatTopic, frame: Record<string, unknown>): void {
+    const seq = Number(frame.seq);
+    if (frame.kind !== "chat" || frame.liveStreamId !== topic.liveId || !Number.isSafeInteger(frame.seq) || seq <= 0 ||
+      topic.ring.some(existing => existing.seq === frame.seq)) return;
+    // During the subscribe/snapshot handshake, merge notification races into the snapshot.
+    if (!topic.listeners.size) { topic.ring.push(frame); topic.ring = topic.ring.slice(-500); return; }
+    if (seq <= topic.seq) return;
+    topic.pending.set(seq, frame);
+    if (topic.pending.size > 500) {
+      for (const peer of topic.listeners.keys()) peer.send({ op: "resync", topic: "livechat" });
+      topic.pending.clear(); return;
+    }
+    for (let next = topic.pending.get(topic.seq + 1); next; next = topic.pending.get(topic.seq + 1)) {
+      topic.pending.delete(++topic.seq); topic.ring.push(next); topic.ring = topic.ring.slice(-500);
+      for (const peer of topic.listeners.keys()) this.sendChat(peer, next);
+    }
+    if (topic.pending.size > 0 && !topic.gapTimer) {
+      topic.gapTimer = setTimeout(() => {
+        topic.gapTimer = null;
+        for (const peer of topic.listeners.keys()) peer.send({ op: "resync", topic: "livechat" });
+      }, 1000); topic.gapTimer.unref();
+    } else if (topic.pending.size === 0 && topic.gapTimer) { clearTimeout(topic.gapTimer); topic.gapTimer = null; }
+  }
+  private sendChat(peer: RealtimePeer, frame: Record<string, unknown>): void {
+    const type: LiveChatEventType = frame.message !== undefined ? "chat.message" : frame.delivery !== undefined ? "chat.delivery" : frame.action !== undefined ? "chat.moderated" : "chat.gap";
+    const viewer = this.viewers.get(peer);
+    if (!viewer || Date.now() >= viewer.authDeadline || !peer.send({ op: "msg", topic: "livechat", seq: frame.seq, type, payload: frame })) {
+      peer.send({ op: "resync", topic: "livechat" }); peer.close(1008); this.detach(peer);
+    }
+  }
+  private sendState(peer: RealtimePeer, event: TopicEvent): boolean {
+    return this.viewers.get(peer)?.canonical
+      ? peer.send({ op: "msg", topic: "channel", seq: event.seq, type: "stream.state", payload: event }) : peer.send(event);
+  }
+  private leaveChat(peer: RealtimePeer, ws: string, liveId: string): void {
+    const key = chatTopic(ws, liveId), topic = this.chatTopics.get(key); if (!topic) return;
+    topic.listeners.delete(peer);
+    if (!topic.listeners.size) { topic.unsubscribe?.(); if (topic.gapTimer) clearTimeout(topic.gapTimer); this.chatTopics.delete(key); }
+  }
+  private async topic(ws: string, ch: string): Promise<Topic> {
+    const key = `${ws}:${ch}`;
+    let topic = this.topics.get(key);
+    if (topic) {
+      if (topic.idle) { clearTimeout(topic.idle); topic.idle = null; }
+      if (!topic.timer) await this.start(topic);
+      return topic;
+    }
+    if (this.topics.size >= 1024) throw new Error("realtime topic capacity exceeded");
+    topic = { ws, ch, seq: 0, ring: [], listeners: new Set(), unsubscribe: null, timer: null, idle: null, polling: false, latest: {} };
+    this.topics.set(key, topic);
+    try { await this.start(topic); } catch (error) { this.topics.delete(key); throw error; }
+    return topic;
+  }
+  private start(topic: Topic): Promise<void> {
+    const key = `${topic.ws}:${topic.ch}`;
+    const pending = this.starts.get(key);
+    if (pending) return pending;
+    const starting = this.startTopic(topic).finally(() => this.starts.delete(key));
+    this.starts.set(key, starting); return starting;
+  }
+  private async startTopic(topic: Topic): Promise<void> {
+    topic.unsubscribe = await this.deps.subscriptions.subscribe(`state:${topic.ws}:${topic.ch}:desired`, () => { void this.poll(topic); });
+    topic.timer = setInterval(() => { void this.poll(topic); }, 100); topic.timer.unref();
+    await this.poll(topic);
+  }
+  private async poll(topic: Topic): Promise<void> {
+    if (topic.polling) return;
+    topic.polling = true;
+    try {
+      const status = (await this.deps.status(topic.ws)).channels.find(ch => ch.channelId === topic.ch);
+      if (!status) return;
+      this.event(topic, "desired", status.desired);
+      this.event(topic, "observed", status.observed);
+    } catch { /* Expiring auth leases evict viewers if an outage also affects auth. */ }
+    finally { topic.polling = false; }
+  }
+  private event(topic: Topic, kind: "desired" | "observed", data: unknown): void {
+    const serialized = JSON.stringify(data);
+    if (topic.latest[kind] === serialized) return;
+    topic.latest[kind] = serialized;
+    const event: StateEvent = { type: "state", workspaceId: topic.ws, channelId: topic.ch, kind, seq: ++topic.seq, data };
+    topic.ring.push(event); if (topic.ring.length > 256) topic.ring.shift();
+    for (const peer of topic.listeners) {
+      const viewer = this.viewers.get(peer);
+      if (!viewer || Date.now() >= viewer.authDeadline || !this.sendState(peer, event)) { peer.close(1008); this.detach(peer); }
+    }
+  }
+  /** Fan a chat frame out to a channel's subscribers and into its resume ring.
+   * No topic yet (nobody is watching / hub has no channel row): dropped — chat
+   * history is the hub's store, not the gateway's. */
+  publishChat(workspaceId: string, channelId: string, frame: Record<string, unknown>): void {
+    const topic = this.topics.get(`${workspaceId}:${channelId}`);
+    if (!topic) return;
+    const event: ChatEvent = { type: "chat", workspaceId, channelId, seq: ++topic.seq, frame: { ...frame } };
+    topic.ring.push(event); if (topic.ring.length > 256) topic.ring.shift();
+    for (const peer of topic.listeners) {
+      const viewer = this.viewers.get(peer);
+      if (!viewer || Date.now() >= viewer.authDeadline || !this.sendState(peer, event)) { peer.close(1008); this.detach(peer); }
+    }
+  }
+  private leave(peer: RealtimePeer, key: string): void {
+    const topic = this.topics.get(key); if (!topic) return;
+    topic.listeners.delete(peer);
+    if (topic.listeners.size === 0) {
+      if (topic.idle) clearTimeout(topic.idle);
+      topic.unsubscribe?.(); topic.unsubscribe = null;
+      if (topic.timer) clearInterval(topic.timer); topic.timer = null;
+      topic.idle = setTimeout(() => this.topics.delete(key), 60_000); topic.idle.unref();
+    }
+  }
+  private detach(peer: RealtimePeer): void {
+    const viewer = this.viewers.get(peer); if (!viewer) return;
+    viewer.closed = true; clearInterval(viewer.timer);
+    for (const liveId of viewer.chatIds.values()) this.leaveChat(peer, viewer.ws ?? "", liveId);
+    for (const key of viewer.topics) this.leave(peer, key);
+    this.viewers.delete(peer);
+  }
+  onModuleDestroy(): void {
+    for (const peer of this.viewers.keys()) { peer.close(1001); this.detach(peer); }
+    for (const topic of this.topics.values()) { if (topic.timer) clearInterval(topic.timer); if (topic.idle) clearTimeout(topic.idle); topic.unsubscribe?.(); }
+    this.topics.clear();
+    for (const topic of this.chatTopics.values()) { topic.unsubscribe?.(); if (topic.gapTimer) clearTimeout(topic.gapTimer); }
+    this.chatTopics.clear(); this.chatRedis.close(); this.deps.subscriptions.close();
+  }
+}
diff --git a/apps/api/src/realtime/realtime.test.ts b/apps/api/src/realtime/realtime.test.ts
new file mode 100644
index 0000000..86f278e
--- /dev/null
+++ b/apps/api/src/realtime/realtime.test.ts
@@ -0,0 +1,152 @@
+import { randomUUID } from "node:crypto";
+import { IncomingMessage } from "node:http";
+import { Socket } from "node:net";
+import { Duplex } from "node:stream";
+import type { PoolClient } from "pg";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { authorizeSubscription } from "./gateway.js";
+import { RealtimeService, type RealtimePeer } from "./realtime.service.js";
+import { RealtimeSocket } from "./websocket.js";
+import { MediaControlService, type ChannelStatus } from "../media-control/media-control.service.js";
+const WS = randomUUID(), USER = randomUUID(), CH = randomUUID();
+const session = { userId: USER, workspaceId: WS, authzEpoch: 7, role: "Operator", issuedAt: 1, expiresAt: 9999999999 };
+function tick(): Promise<void> { return new Promise(resolve => setTimeout(resolve, 5)); }
+function fixture(auth: () => Promise<boolean> = async () => true): { service: RealtimeService; frames: unknown[]; peer: RealtimePeer; handlers: { message: (value: unknown) => void; close: () => void }; channel: ChannelStatus } {
+  const channel: ChannelStatus = { channelId: CH, workerId: "worker", assignmentEpoch: 1, desired: { desiredStatus: "STOPPED", desiredVersion: 1 }, observed: null, converged: false, workerAlive: true };
+  const control = new MediaControlService({ signer: null, assignments: [] });
+  const service = new RealtimeService(control, { authorize: auth, channelExists: async () => true,
+    status: async () => ({ channels: [channel] }), subscriptions: { subscribe: async () => () => undefined, close: () => undefined } });
+  const frames: unknown[] = [], peer: RealtimePeer = { send: value => { frames.push(value); return true; }, close: vi.fn() };
+  return { service, frames, peer, handlers: service.attach(peer), channel };
+}
+afterEach(() => vi.useRealTimers());
+describe("realtime authorization port", () => {
+  it("normalizes bigint epochs and establishes transaction-local tenant context before RLS membership query", async () => {
+    const queries: string[] = [];
+    const client = { query: vi.fn(async (sql: string) => {
+      queries.push(sql);
+      if (sql.includes("FROM workspaces")) return { rows: [{ authz_epoch: "7" }], rowCount: 1 };
+      if (sql.includes("FROM role_permissions")) {
+        expect(queries.some(q => q.includes("set_config"))).toBe(true);
+        return { rows: [{}], rowCount: 1 };
+      }
+      return { rows: [], rowCount: 0 };
+    }) } as unknown as PoolClient;
+    expect(await authorizeSubscription(client, { token: "valid", workspaceId: WS }, () => session)).toEqual({ allow: true, workspaceId: WS });
+    expect(queries[0]).toBe("BEGIN"); expect(queries.at(-1)).toBe("ROLLBACK");
+  });
+  it.each(["8", "9007199254740993", "invalid"])("rejects stale/unsafe epoch %s", async epoch => {
+    const client = { query: async (sql: string) => ({ rows: sql.includes("FROM workspaces") ? [{ authz_epoch: epoch }] : [], rowCount: 0 }) } as unknown as PoolClient;
+    expect(await authorizeSubscription(client, { token: "valid", workspaceId: WS }, () => session)).toMatchObject({ allow: false });
+  });
+  it("rejects an inactive/non-member even when the token role claims Owner", async () => {
+    const client = { query: async (sql: string) => ({ rows: sql.includes("FROM workspaces") ? [{ authz_epoch: 7 }] : [], rowCount: 0 }) } as unknown as PoolClient;
+    expect(await authorizeSubscription(client, { token: "valid", workspaceId: WS }, () => ({ ...session, role: "Owner" }))).toMatchObject({ allow: false, reason: "missing stream.view permission" });
+  });
+  it("rejects cross-workspace subscriptions before database access", async () => {
+    const query = vi.fn(); const client = { query } as unknown as PoolClient;
+    expect(await authorizeSubscription(client, { token: "valid", workspaceId: randomUUID() }, () => session)).toMatchObject({ allow: false }); expect(query).not.toHaveBeenCalled();
+  });
+});
+describe("per-channel realtime subscription lifecycle", () => {
+  it("authenticates in the first frame and checks each subscription before ack", async () => {
+    let allowed = true; const auth = vi.fn(async () => allowed); const f = fixture(auth);
+    f.handlers.message({ type: "auth", token: "operator", workspaceId: WS });
+    f.handlers.message({ type: "subscribe", channelId: CH }); await tick();
+    expect(f.frames).toContainEqual({ type: "subscribe_ack", channelId: CH, seq: 2 }); expect(auth).toHaveBeenCalledTimes(2);
+    expect(f.frames).toContainEqual(expect.objectContaining({ type: "state", kind: "observed", data: null }));
+    allowed = false; f.handlers.message({ type: "subscribe", channelId: randomUUID() }); await tick();
+    expect(f.frames).toContainEqual(expect.objectContaining({ type: "subscribe_denied" })); f.service.onModuleDestroy();
+  });
+  it("epoch revocation closes and evicts subscriptions within five seconds", async () => {
+    vi.useFakeTimers(); let epoch = 7;
+    const client = { query: async (sql: string) => ({ rows: sql.includes("FROM workspaces") ? [{ authz_epoch: String(epoch) }] : [{}], rowCount: 1 }) } as unknown as PoolClient;
+    const f = fixture(async () => (await authorizeSubscription(client, { token: "operator", workspaceId: WS }, () => session)).allow);
+    f.handlers.message({ type: "auth", token: "operator", workspaceId: WS }); f.handlers.message({ type: "subscribe", channelId: CH });
+    await vi.advanceTimersByTimeAsync(1); epoch += 1;
+    await vi.advanceTimersByTimeAsync(1100); expect(f.peer.close).toHaveBeenCalledWith(1008);
+    const count = f.frames.length; f.channel.desired = { desiredStatus: "STOPPED", desiredVersion: 2 };
+    await vi.advanceTimersByTimeAsync(1000); expect(f.frames).toHaveLength(count); f.service.onModuleDestroy();
+  });
+  it("auth outages fail closed within five seconds", async () => {
+    vi.useFakeTimers(); let hang = false; const f = fixture(async () => hang ? new Promise<boolean>(() => undefined) : true);
+    f.handlers.message({ type: "auth", token: "operator", workspaceId: WS }); f.handlers.message({ type: "subscribe", channelId: CH });
+    await vi.advanceTimersByTimeAsync(1); hang = true;
+    await vi.advanceTimersByTimeAsync(2100); expect(f.peer.close).toHaveBeenCalled(); f.service.onModuleDestroy();
+  });
+  it("resumes buffered state events and requests resync for invalid cursors", async () => {
+    const f = fixture(); f.handlers.message({ type: "auth", token: "operator", workspaceId: WS });
+    f.handlers.message({ type: "subscribe", channelId: CH, lastSeq: 1 }); await tick();
+    expect(f.frames.filter(v => typeof v === "object" && v && "type" in v && v.type === "state")).toHaveLength(1);
+    f.handlers.message({ type: "subscribe", channelId: CH, lastSeq: 100 }); await tick();
+    expect(f.frames).toContainEqual({ type: "RESYNC_REQUIRED", channelId: CH }); f.service.onModuleDestroy();
+  });
+  it("requires auth before subscribe and bounds incoming queued work", async () => {
+    const f = fixture(); f.handlers.message({ type: "subscribe", channelId: CH }); await tick(); expect(f.peer.close).toHaveBeenCalledWith(1008); f.service.onModuleDestroy();
+    const slow = fixture(async () => new Promise<boolean>(() => undefined));
+    for (let i = 0; i < 40; i++) slow.handlers.message({ type: "auth", token: "operator", workspaceId: WS });
+    expect(slow.peer.close).toHaveBeenCalled(); slow.service.onModuleDestroy();
+  });
+});
+function masked(value: unknown): Buffer {
+  const body = Buffer.from(JSON.stringify(value)), mask = Buffer.from([1, 2, 3, 4]);
+  const header = Buffer.alloc(body.length < 126 ? 6 : 8); header[0] = 129;
+  if (body.length < 126) { header[1] = 128 | body.length; mask.copy(header, 2); }
+  else { header[1] = 128 | 126; header.writeUInt16BE(body.length, 2); mask.copy(header, 4); }
+  for (let i = 0; i < body.length; i++) body[i] = (body[i] ?? 0) ^ (mask[i % 4] ?? 0);
+  return Buffer.concat([header, body]);
+}
+describe("real WebSocket HTTP upgrade and wire frames", () => {
+  it("upgrades /realtime, accepts masked first-frame auth, then emits subscribe_ack and state", async () => {
+    const f = fixture(); f.handlers.close();
+    const chunks: Buffer[] = [];
+    const socket = new Duplex({ read() {}, write(chunk: Buffer, _encoding, callback) { chunks.push(Buffer.from(chunk)); callback(); } });
+    const request = new IncomingMessage(new Socket()); request.method = "GET"; request.url = "/realtime";
+    request.headers = { host: "localhost", connection: "Upgrade", upgrade: "websocket", "sec-websocket-version": "13", "sec-websocket-key": "dGhlIHNhbXBsZSBub25jZQ==" };
+    const peer = RealtimeSocket.accept(request, socket, Buffer.alloc(0)); expect(peer).not.toBeNull();
+    if (!peer) throw new Error("handshake failed");
+    const handlers = f.service.attach(peer); peer.onMessage = handlers.message; peer.onClose = handlers.close;
+    expect(Buffer.concat(chunks).toString()).toContain("101 Switching Protocols");
+    const messages = Buffer.concat([masked({ type: "auth", workspaceId: WS, token: "operator" }), masked({ type: "subscribe", channelId: CH })]);
+    // Split in the middle of the header and payload, exercising stream framing.
+    socket.emit("data", messages.subarray(0, 3)); socket.emit("data", messages.subarray(3, 31)); socket.emit("data", messages.subarray(31));
+    await tick();
+    const wire = Buffer.concat(chunks).toString(); expect(wire).toContain("auth_ack"); expect(wire).toContain("subscribe_ack"); expect(wire).toContain('"kind":"observed"');
+    f.service.onModuleDestroy(); socket.destroy(); request.destroy();
+  });
+});
+
+describe("S5 canonical chat socket lifecycle", () => {
+  it("revalidates device authorization and closes a revoked device within five seconds", async () => {
+    vi.useFakeTimers();
+    const { issueDeviceToken } = await import("../live-chat/devices.js"), { authorizeChat } = await import("../live-chat/auth.js");
+    const deviceId = randomUUID(); let epoch = 1;
+    const scopes = ["stream.view", "livechat.view"];
+    const token = issueDeviceToken({ deviceId, workspaceId: WS, userId: USER, epoch: 1, scopes });
+    const client = { query: async (sql: string) => ({ rows: sql.includes("FROM memberships") ? [{ role: "Operator", authz_epoch: 7 }] : sql.includes("FROM devices") ? [{ epoch, authz_epoch: 7, scopes }] : [] }) } as unknown as PoolClient;
+    const service = new RealtimeService(new MediaControlService({ signer: null, assignments: [] }), { subscriptions: { subscribe: async () => () => undefined, close: () => undefined },
+      authorizeChat: async (token, ws, permission) => Boolean(await authorizeChat(client, token, ws, permission)), channelExists: async () => true, chatWindow: async () => [], chatLatestSeq: async () => 0 });
+    const frames: unknown[] = [], peer: RealtimePeer = { send: frame => { frames.push(frame); return true; }, close: vi.fn() }, handlers = service.attach(peer);
+    try {
+      handlers.message({ op: "auth", token }); handlers.message({ op: "subscribe", id: "chat", topic: "livechat", liveId: CH });
+      await vi.advanceTimersByTimeAsync(1); expect(frames).toContainEqual({ op: "ack", id: "chat", fromSeq: 0 });
+      epoch += 1; await vi.advanceTimersByTimeAsync(1100); expect(peer.close).toHaveBeenCalledWith(1008);
+    } finally { service.onModuleDestroy(); }
+  });
+  it("holds out-of-order notifications until the missing predecessor arrives", async () => {
+    const { issueSession } = await import("../auth/session.js");
+    let receive: ((raw: string) => void) | undefined;
+    const service = new RealtimeService(new MediaControlService({ signer: null, assignments: [] }), { subscriptions: { subscribe: async (_topic, listener) => { receive = listener; return () => undefined; }, close: () => undefined },
+      authorizeChat: async () => true, channelExists: async () => true, chatWindow: async () => [], chatLatestSeq: async () => 0 });
+    const frames: Array<Record<string, unknown>> = [], peer: RealtimePeer = { send: frame => { frames.push(frame as Record<string, unknown>); return true; }, close: vi.fn() }, handlers = service.attach(peer);
+    try {
+      handlers.message({ op: "auth", token: issueSession({ workspaceId: WS, userId: USER, role: "Operator", authzEpoch: 7 }) });
+      handlers.message({ op: "subscribe", id: "chat", topic: "livechat", liveId: CH }); await tick();
+      const frame = (seq: number) => JSON.stringify({ kind: "chat", liveStreamId: CH, channelId: CH, seq, provider: "mock-livestream", reason: "gap notice" });
+      receive?.(frame(2)); expect(frames.filter(frame => frame.op === "msg")).toEqual([]);
+      receive?.(frame(1)); expect(frames.filter(frame => frame.op === "msg").map(frame => frame.seq)).toEqual([1,2]);
+      receive?.(frame(2)); expect(frames.filter(frame => frame.op === "msg")).toHaveLength(2);
+      handlers.message({ op: "ping" }); await tick(); expect(frames).toContainEqual({ op: "pong" });
+    } finally { service.onModuleDestroy(); }
+  });
+});
diff --git a/apps/api/src/realtime/subscribe.test.ts b/apps/api/src/realtime/subscribe.test.ts
new file mode 100644
index 0000000..99d4b38
--- /dev/null
+++ b/apps/api/src/realtime/subscribe.test.ts
@@ -0,0 +1,46 @@
+import { Duplex } from "node:stream";
+import type { Socket } from "node:net";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { encode, parse } from "../media-control/redis.js";
+import { RespRedisSubscriptions } from "./subscribe.js";
+class RedisSocket extends Duplex {
+  readonly commands: string[][] = [];
+  constructor() { super(); queueMicrotask(() => this.emit("connect")); }
+  override _read(): void { /* Incoming bytes are pushed by the RESP peer. */ }
+  override _write(bytes: Buffer, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    const reply = parse(bytes)?.reply;
+    if (!Array.isArray(reply) || !reply.every((v): v is string => typeof v === "string")) { callback(new Error("invalid request")); return; }
+    this.commands.push(reply);
+    const name = reply[0];
+    queueMicrotask(() => this.emit("data", name === "AUTH" || name === "SELECT" ? Buffer.from("+OK\r\n") : encode([name?.toLowerCase() ?? "", reply[1] ?? "", "1"])));
+    callback();
+  }
+  message(topic: string, message: string): void {
+    const frame = encode(["message", topic, message]);
+    this.emit("data", frame.subarray(0, 7)); this.emit("data", frame.subarray(7));
+  }
+}
+afterEach(() => vi.useRealTimers());
+describe("shared Redis subscribe connection", () => {
+  it("AUTH/SELECT precede subscription ack, with ref-counted topics and fragmented RESP messages", async () => {
+    const socket = new RedisSocket(); const factory = vi.fn(() => socket as unknown as Socket);
+    const redis = new RespRedisSubscriptions("redis://user:password@localhost:6379/2", () => undefined, factory);
+    const first = vi.fn(), second = vi.fn();
+    const unsubscribe1 = await redis.subscribe("state:workspace:channel:desired", first);
+    const unsubscribe2 = await redis.subscribe("state:workspace:channel:desired", second);
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(socket.commands).toEqual([["AUTH", "user", "password"], ["SELECT", "2"], ["SUBSCRIBE", "state:workspace:channel:desired"]]);
+    socket.message("state:workspace:channel:desired", "version 1"); expect(first).toHaveBeenCalledWith("version 1"); expect(second).toHaveBeenCalledWith("version 1");
+    unsubscribe1(); expect(socket.commands.filter(c => c[0] === "UNSUBSCRIBE")).toHaveLength(0);
+    socket.message("state:workspace:channel:desired", "version 2"); expect(first).toHaveBeenCalledTimes(1); expect(second).toHaveBeenCalledTimes(2);
+    unsubscribe2(); await Promise.resolve(); expect(socket.commands.at(-1)).toEqual(["UNSUBSCRIBE", "state:workspace:channel:desired"]); redis.close();
+  });
+  it("reconnects and restores viewed topics, notifying consumers to resync", async () => {
+    vi.useFakeTimers(); const sockets: RedisSocket[] = [], notify = vi.fn();
+    const redis = new RespRedisSubscriptions("redis://localhost", notify, () => { const socket = new RedisSocket(); sockets.push(socket); return socket as unknown as Socket; });
+    const receive = vi.fn(); const subscribed = redis.subscribe("chat:workspace:live", receive); await vi.advanceTimersByTimeAsync(0); await subscribed;
+    sockets[0]?.destroy(); await vi.advanceTimersByTimeAsync(300);
+    expect(sockets).toHaveLength(2); expect(sockets[1]?.commands).toContainEqual(["SUBSCRIBE", "chat:workspace:live"]); expect(notify).toHaveBeenCalledTimes(1);
+    sockets[1]?.message("chat:workspace:live", "chat message"); expect(receive).toHaveBeenCalledWith("chat message"); redis.close();
+  });
+});
diff --git a/apps/api/src/realtime/subscribe.ts b/apps/api/src/realtime/subscribe.ts
new file mode 100644
index 0000000..ef1269c
--- /dev/null
+++ b/apps/api/src/realtime/subscribe.ts
@@ -0,0 +1,104 @@
+import net, { type Socket } from "node:net";
+import tls from "node:tls";
+import { encode, parse, RedisError, type RedisReply } from "../media-control/redis.js";
+export interface RedisSubscriptions {
+  subscribe(topic: string, listener: (message: string) => void): Promise<() => void>;
+  close(): void;
+}
+
+/** One shared subscribe connection, ref-counted topics, automatic reconnect.
+ * Redis command traffic must use a separate RespControlRedis connection. */
+export class RespRedisSubscriptions implements RedisSubscriptions {
+  private readonly listeners = new Map<string, Set<(message: string) => void>>();
+  private socket: Socket | null = null;
+  private connecting: Promise<void> | null = null;
+  private buffer = Buffer.alloc(0);
+  private readonly pending: Array<{ resolve: (reply: RedisReply) => void; reject: (error: Error) => void }> = [];
+  private retry: ReturnType<typeof setTimeout> | null = null;
+  private closed = false;
+  constructor(private readonly rawUrl: string, private readonly onReconnect: () => void = () => undefined,
+    private readonly socketFactory?: (url: URL) => Socket) {}
+  async subscribe(topic: string, listener: (message: string) => void): Promise<() => void> {
+    if (this.closed) throw new Error("subscriber closed");
+    const existing = this.listeners.get(topic);
+    if (existing) {
+      existing.add(listener);
+      try { await this.connect(); } catch (error) { this.remove(topic, listener); throw error; }
+    }
+    else {
+      this.listeners.set(topic, new Set([listener]));
+      // connect() subscribes every registered topic on a new connection.
+      const connected = this.socket !== null && this.connecting === null;
+      try { await this.connect(); if (connected) await this.command(["SUBSCRIBE", topic]); }
+      catch (error) { this.remove(topic, listener); throw error; }
+    }
+    return () => this.remove(topic, listener);
+  }
+  private remove(topic: string, listener: (message: string) => void): void {
+    const group = this.listeners.get(topic); group?.delete(listener);
+    if (group?.size === 0) {
+      this.listeners.delete(topic);
+      if (this.socket) void this.command(["UNSUBSCRIBE", topic]).catch(() => undefined);
+    }
+  }
+  private connect(): Promise<void> {
+    if (this.connecting) return this.connecting;
+    if (this.socket) return Promise.resolve();
+    this.connecting = this.open().finally(() => { this.connecting = null; });
+    return this.connecting;
+  }
+  private async open(): Promise<void> {
+    const url = new URL(this.rawUrl);
+    if (!["redis:", "rediss:"].includes(url.protocol)) throw new Error("invalid Redis URL");
+    const socket = this.socketFactory ? this.socketFactory(url) : url.protocol === "rediss:" ? tls.connect({ host: url.hostname, port: Number(url.port || 6379), servername: url.hostname, rejectUnauthorized: true })
+      : net.connect({ host: url.hostname, port: Number(url.port || 6379) });
+    this.socket = socket; this.buffer = Buffer.alloc(0);
+    socket.on("data", (chunk: Buffer) => {
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+      if (this.buffer.length > 8_000_000) { socket.destroy(); return; }
+      try {
+        for (let parsed = parse(this.buffer); parsed; parsed = parse(this.buffer)) {
+          this.buffer = this.buffer.subarray(parsed.end);
+          const reply = parsed.reply;
+          if (Array.isArray(reply) && reply[0] === "message" && typeof reply[1] === "string" && typeof reply[2] === "string") {
+            for (const callback of this.listeners.get(reply[1]) ?? []) { try { callback(reply[2]); } catch { /* Isolate consumers. */ } }
+          } else {
+            const waiter = this.pending.shift();
+            if (reply instanceof RedisError) waiter?.reject(reply); else waiter?.resolve(reply);
+          }
+        }
+      } catch { socket.destroy(); }
+    });
+    socket.on("error", () => undefined);
+    socket.once("close", () => {
+      if (this.socket === socket) this.socket = null;
+      for (const waiter of this.pending.splice(0)) waiter.reject(new Error("Redis disconnected"));
+      if (!this.closed && !this.retry) {
+        this.retry = setTimeout(() => { this.retry = null; void this.connect().then(this.onReconnect).catch(() => undefined); }, 250);
+        this.retry.unref();
+      }
+    });
+    const timeout = setTimeout(() => socket.destroy(new Error("Redis connect timed out")), 2000);
+    await new Promise<void>((resolve, reject) => {
+      socket.once(url.protocol === "rediss:" ? "secureConnect" : "connect", resolve);
+      socket.once("error", reject);
+    }).finally(() => clearTimeout(timeout));
+    if (url.password) await this.command(["AUTH", decodeURIComponent(url.username || "default"), decodeURIComponent(url.password)]);
+    if (url.pathname.length > 1) await this.command(["SELECT", url.pathname.slice(1)]);
+    // Sequential ACKs ensure no topic is acknowledged to a viewer before Redis is listening.
+    for (const topic of this.listeners.keys()) await this.command(["SUBSCRIBE", topic]);
+  }
+  private command(parts: string[]): Promise<RedisReply> {
+    const socket = this.socket;
+    if (!socket) return Promise.reject(new Error("Redis disconnected"));
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => socket.destroy(new Error("Redis subscription ack timed out")), 2000);
+      this.pending.push({ resolve: reply => { clearTimeout(timeout); resolve(reply); }, reject: error => { clearTimeout(timeout); reject(error); } });
+      socket.write(encode(parts));
+    });
+  }
+  close(): void {
+    this.closed = true; if (this.retry) clearTimeout(this.retry);
+    this.listeners.clear(); this.socket?.destroy(); this.socket = null;
+  }
+}
diff --git a/apps/api/src/realtime/websocket.ts b/apps/api/src/realtime/websocket.ts
new file mode 100644
index 0000000..5e4852b
--- /dev/null
+++ b/apps/api/src/realtime/websocket.ts
@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+import type { Duplex } from "node:stream";
+
+/** RFC6455 transport without a new dependency; control frames, fragmentation,
+ * strict masking/UTF-8, and bounded buffering/backpressure. */
+export class RealtimeSocket {
+  private buffer = Buffer.alloc(0);
+  private fragments: Buffer[] = [];
+  private fragmentBytes = 0;
+  private closed = false;
+  onMessage: (value: unknown) => void = () => undefined;
+  onClose: () => void = () => undefined;
+  constructor(private readonly socket: Duplex) {
+    socket.on("data", (chunk: Buffer) => this.consume(chunk));
+    socket.on("error", () => this.close());
+    socket.on("close", () => { if (!this.closed) { this.closed = true; this.onClose(); } });
+  }
+  static accept(request: IncomingMessage, socket: Duplex, head: Buffer): RealtimeSocket | null {
+    const key = request.headers["sec-websocket-key"];
+    if (request.method !== "GET" || request.headers.upgrade?.toLowerCase() !== "websocket" ||
+      !request.headers.connection?.toLowerCase().split(/\s*,\s*/).includes("upgrade") || request.headers["sec-websocket-version"] !== "13" ||
+      typeof key !== "string" || !/^[A-Za-z0-9+/]{22}==$/.test(key)) {
+      socket.end("HTTP/1.1 400 Bad Request\r\nConnection: close\r\n\r\n"); return null;
+    }
+    const accept = createHash("sha1").update(`${key}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`).digest("base64");
+    socket.write(`HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Accept: ${accept}\r\n\r\n`);
+    const peer = new RealtimeSocket(socket);
+    if (head.length) queueMicrotask(() => peer.consume(head));
+    return peer;
+  }
+  send(value: unknown): boolean {
+    const data = Buffer.from(JSON.stringify(value));
+    if (this.closed || this.socket.writableLength > 256_000 || data.length > 256_000) {
+      const canonical = typeof value === "object" && value !== null && "op" in value;
+      this.frame(1, Buffer.from(JSON.stringify(canonical ? { op: "resync", topic: "topic" in value ? value.topic : "livechat" } : { type: "RESYNC_REQUIRED" }))); this.close(1013); return false;
+    }
+    this.frame(1, data); return true;
+  }
+  private frame(opcode: number, data: Buffer): void {
+    if (this.closed) return;
+    const header = Buffer.alloc(data.length < 126 ? 2 : data.length <= 65535 ? 4 : 10);
+    header[0] = 0x80 | opcode;
+    if (header.length === 2) header[1] = data.length;
+    else if (header.length === 4) { header[1] = 126; header.writeUInt16BE(data.length, 2); }
+    else { header[1] = 127; header.writeBigUInt64BE(BigInt(data.length), 2); }
+    this.socket.write(Buffer.concat([header, data]));
+  }
+  close(code = 1000): void {
+    if (this.closed) return;
+    const body = Buffer.alloc(2); body.writeUInt16BE(code);
+    this.frame(8, body); this.closed = true; this.onClose(); this.socket.end();
+    const timer = setTimeout(() => this.socket.destroy(), 100); timer.unref();
+  }
+  private consume(chunk: Buffer): void {
+    if (this.closed) return;
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    if (this.buffer.length > 128_000) { this.close(1009); return; }
+    while (this.buffer.length >= 2) {
+      const first = this.buffer[0] ?? 0, second = this.buffer[1] ?? 0;
+      const final = Boolean(first & 128), opcode = first & 15;
+      if (first & 112 || !(second & 128)) { this.close(1002); return; }
+      let length = second & 127, offset = 2;
+      if (length === 126) { if (this.buffer.length < 4) return; length = this.buffer.readUInt16BE(2); offset = 4; if (length < 126) { this.close(1002); return; } }
+      if (length === 127) { this.close(1009); return; }
+      if (length > 64_000 || (opcode >= 8 && (!final || length > 125))) { this.close(1009); return; }
+      if (this.buffer.length < offset + 4 + length) return;
+      const mask = this.buffer.subarray(offset, offset + 4); offset += 4;
+      const body = Buffer.from(this.buffer.subarray(offset, offset + length));
+      this.buffer = this.buffer.subarray(offset + length);
+      for (let i = 0; i < body.length; i += 1) body[i] = (body[i] ?? 0) ^ (mask[i % 4] ?? 0);
+      if (opcode === 8) { this.close(); return; }
+      if (opcode === 9) { this.frame(10, body); continue; }
+      if (opcode === 10) continue;
+      if ((opcode !== 0 && opcode !== 1) || (opcode === 0 && !this.fragments.length) || (opcode === 1 && this.fragments.length)) { this.close(1002); return; }
+      this.fragments.push(body); this.fragmentBytes += body.length;
+      if (this.fragmentBytes > 64_000) { this.close(1009); return; }
+      if (final) {
+        const bytes = Buffer.concat(this.fragments); this.fragments = []; this.fragmentBytes = 0;
+        try { const value: unknown = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes)); this.onMessage(value); }
+        catch { this.close(1007); return; }
+      }
+    }
+  }
+}
diff --git a/apps/api/src/settings/settings.controller.ts b/apps/api/src/settings/settings.controller.ts
new file mode 100644
index 0000000..8229bcf
--- /dev/null
+++ b/apps/api/src/settings/settings.controller.ts
@@ -0,0 +1,35 @@
+/**
+ * Instance settings API (admin only):
+ *
+ *   GET   /settings   read the content-policy posture (Owner/Admin)
+ *   PATCH /settings   partial update + system audit event (Owner/Admin)
+ *
+ * Instance-level ⇒ the RBAC permission set (002) has no instance permission;
+ * the gate is the ROLE itself (task spec: Owner/Admin), checked in the
+ * controller after the standard RbacGuard session/epoch validation. RLS does
+ * not apply (system table, migration 028) — the role check IS the boundary.
+ */
+import { Body, Controller, ForbiddenException, Get, Patch, Req, UseGuards } from "@nestjs/common";
+import { requireSession } from "../http/validation.js";
+import { RbacGuard, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { isInstanceAdmin, SettingsService, type InstanceSettingRecord } from "./settings.service.js";
+
+@Controller("settings")
+@UseGuards(RbacGuard)
+export class SettingsController {
+  constructor(private readonly settings: SettingsService) {}
+
+  @Get()
+  async get(@Req() request: AuthenticatedRequest): Promise<InstanceSettingRecord> {
+    const session = requireSession(request);
+    if (!isInstanceAdmin(session.role)) throw new ForbiddenException("instance settings are admin-only (Owner/Admin)");
+    return this.settings.getSettings();
+  }
+
+  @Patch()
+  async patch(@Req() request: AuthenticatedRequest, @Body() body: unknown): Promise<InstanceSettingRecord> {
+    const session = requireSession(request);
+    if (!isInstanceAdmin(session.role)) throw new ForbiddenException("instance settings are admin-only (Owner/Admin)");
+    return this.settings.updateSettings(body, { userId: session.userId, role: session.role });
+  }
+}
diff --git a/apps/api/src/settings/settings.integration.test.ts b/apps/api/src/settings/settings.integration.test.ts
new file mode 100644
index 0000000..9aaf100
--- /dev/null
+++ b/apps/api/src/settings/settings.integration.test.ts
@@ -0,0 +1,351 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * Instance settings against a live PostgreSQL, as sp_app.
+ * Own scratch database (ADMIN_SETTINGS_IT_DATABASE_URL + ADMIN_SETTINGS_IT_
+ * SUPER_DATABASE_URL) per the local-db-sol pattern: the shared-DB suites wipe
+ * every workspace and vitest runs files in parallel. Skipped when unset.
+ *
+ * Covers the task's list: seeded defaults, CRUD round-trip incl. partial
+ * updates and provenance (updated_at/updated_by), RBAC (non-admin 403 through
+ * the real controller; the real RbacGuard path), audit events on the SYSTEM
+ * chain (audit_append_system — an instance setting is not a tenant row), and
+ * the migration's CHECK constraints rejecting undecodable values.
+ */
+const appUrl = process.env.ADMIN_SETTINGS_IT_DATABASE_URL;
+const ownerUrl = process.env.ADMIN_SETTINGS_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  service: typeof import("./settings.service.js");
+  controller: typeof import("./settings.controller.js");
+  guard: typeof import("../rbac/rbac.guard.js");
+  session: typeof import("../auth/session.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("instance settings (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  let service: InstanceType<Modules["service"]["SettingsService"]>;
+  let controller: InstanceType<Modules["controller"]["SettingsController"]>;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  let ws: string;
+  let adminUser: string;
+  let otherUser: string;
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  /** Reset to the seeded defaults (self-healing upsert: also restores deleted rows). */
+  async function resetSettings(): Promise<void> {
+    await asOwner(async (c) => {
+      await c.query(
+        `INSERT INTO instance_settings (key, value, updated_by)
+         VALUES ('youtube_full_harvest','false',NULL), ('youtube_cc_only_broadcast','true',NULL),
+                ('scrape_metadata_only','true',NULL), ('scrape_bounded_pilot','false',NULL),
+                ('intake_posture','metadata_only',NULL)
+         ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_by = NULL, updated_at = now()`,
+      );
+    });
+  }
+
+  beforeAll(async () => {
+    // The shared pool reads DATABASE_URL at import time: point it at this
+    // isolated DB first, then import the modules under test.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      service: await import("./settings.service.js"),
+      controller: await import("./settings.controller.js"),
+      guard: await import("../rbac/rbac.guard.js"),
+      session: await import("../auth/session.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    service = new m.service.SettingsService();
+    controller = new m.controller.SettingsController(service);
+
+    await asOwner(async (c) => {
+      ws = String((await c.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", ["settings-it", `settings-it-${suffix}`])).rows[0].id);
+      const mkUser = async (tag: string): Promise<string> =>
+        String(
+          (
+            await c.query("INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4) RETURNING id", [
+              `settings:${tag}:${suffix}`,
+              `settings-${tag}-${suffix}`,
+              `settings-${tag}-${suffix}@example.com`,
+              tag,
+            ])
+          ).rows[0].id,
+        );
+      adminUser = await mkUser("admin");
+      otherUser = await mkUser("member");
+      // Give the users real memberships so the guard's role/permission
+      // lookups are exercised through the actual RBAC chain.
+      await c.query("SELECT set_config('app.workspace_id', $1, false)", [ws]);
+      await c.query("INSERT INTO memberships (workspace_id, user_id, role) VALUES ($1, $2, 'Owner'), ($1, $3, 'Publisher')", [ws, adminUser, otherUser]);
+      await c.query("SELECT set_config('app.workspace_id', '', false)");
+    });
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE id = $1", [ws]);
+        await c.query("DELETE FROM users WHERE external_id LIKE $1", [`settings:%:${suffix}`]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  // -----------------------------------------------------------------------
+  // Defaults + shape
+  // -----------------------------------------------------------------------
+
+  it("seeds the five keys at the SAFE defaults (decision record posture)", async () => {
+    // Read the seeded rows directly so this asserts the MIGRATION's seed, not
+    // service decoding.
+    const seeded = await asOwner(async (c) =>
+      (await c.query<{ key: string; value: string; updated_by: string | null }>("SELECT key, value, updated_by FROM instance_settings")).rows,
+    );
+    expect(seeded.map((r) => r.key).sort()).toEqual([...m.service.INSTANCE_SETTING_KEYS].sort());
+    const byKey = new Map(seeded.map((r) => [r.key, r]));
+    expect(byKey.get("youtube_full_harvest")?.value).toBe("false");
+    expect(byKey.get("youtube_cc_only_broadcast")?.value).toBe("true");
+    expect(byKey.get("scrape_metadata_only")?.value).toBe("true");
+    expect(byKey.get("scrape_bounded_pilot")?.value).toBe("false");
+    expect(byKey.get("intake_posture")?.value).toBe("metadata_only");
+    // Normalize to defaults for the rest of the suite (the scratch DB persists
+    // across runs; earlier runs may have left non-default values behind).
+    await resetSettings();
+    const settings = await service.getSettings();
+    expect(settings).toMatchObject({
+      youtube_full_harvest: false,
+      youtube_cc_only_broadcast: true,
+      scrape_metadata_only: true,
+      scrape_bounded_pilot: false,
+      intake_posture: "metadata_only",
+    });
+    // Seeded rows exist ⇒ nothing is pending, provenance present.
+    expect(settings.pending).toEqual([]);
+    expect(settings.updatedBy.youtube_full_harvest).toBeNull();
+  });
+
+  it("typed getters mirror the record", async () => {
+    expect(await service.getYoutubeFullHarvest()).toBe(false);
+    expect(await service.getYoutubeCcOnlyBroadcast()).toBe(true);
+    expect(await service.getScrapeMetadataOnly()).toBe(true);
+    expect(await service.getScrapeBoundedPilot()).toBe(false);
+    expect(await service.getIntakePosture()).toBe("metadata_only");
+  });
+
+  // -----------------------------------------------------------------------
+  // CRUD (partial update + provenance)
+  // -----------------------------------------------------------------------
+
+  it("partial update flips one switch, leaves the others, records provenance", async () => {
+    await resetSettings();
+    const actor = { userId: adminUser, role: "Owner" };
+    const after = await service.updateSettings({ youtube_full_harvest: true }, actor);
+    expect(after.youtube_full_harvest).toBe(true); // written
+    expect(after.youtube_cc_only_broadcast).toBe(true); // untouched
+    expect(after.scrape_metadata_only).toBe(true); // untouched
+    expect(after.intake_posture).toBe("metadata_only"); // untouched
+    expect(after.updatedBy.youtube_full_harvest).toBe(adminUser);
+    expect(after.updatedBy.youtube_cc_only_broadcast).toBeNull();
+    expect(new Date(after.updatedAt.youtube_full_harvest).getTime()).toBeGreaterThan(0);
+    // Typed getter sees the new value (the intake-side gate reads this).
+    expect(await service.getYoutubeFullHarvest()).toBe(true);
+  });
+
+  it("full update round-trips every key and re-updates overwrite", async () => {
+    await resetSettings();
+    const actor = { userId: adminUser, role: "Admin" };
+    const first = await service.updateSettings(
+      { youtube_full_harvest: true, youtube_cc_only_broadcast: false, scrape_metadata_only: false, scrape_bounded_pilot: true, intake_posture: "bounded_pilot" },
+      actor,
+    );
+    expect(first).toMatchObject({
+      youtube_full_harvest: true,
+      youtube_cc_only_broadcast: false,
+      scrape_metadata_only: false,
+      scrape_bounded_pilot: true,
+      intake_posture: "bounded_pilot",
+    });
+    // Re-update overwrites, does not duplicate rows (key PK).
+    const second = await service.updateSettings({ intake_posture: "metadata_only", scrape_bounded_pilot: false }, actor);
+    expect(second.intake_posture).toBe("metadata_only");
+    expect(second.scrape_bounded_pilot).toBe(false);
+    expect(second.youtube_full_harvest).toBe(true); // still from the first write
+    const rows = await asOwner(async (c) => (await c.query<{ key: string }>("SELECT key FROM instance_settings ORDER BY key")).rows.map((r) => r.key));
+    expect(rows.sort()).toEqual([...m.service.INSTANCE_SETTING_KEYS].sort());
+  });
+
+  it("invalid patches change nothing", async () => {
+    await resetSettings();
+    const before = await service.getSettings();
+    for (const bad of [null, [], "x", {}, { nope: true }, { intake_posture: "everything" }, { scrape_bounded_pilot: "yes" }]) {
+      await expect(service.updateSettings(bad, { userId: adminUser, role: "Owner" })).rejects.toBeDefined();
+    }
+    const after = await service.getSettings();
+    expect({ ...after }).toEqual({ ...before, updatedAt: after.updatedAt, updatedBy: after.updatedBy, pending: after.pending });
+    expect(await service.getIntakePosture()).toBe("metadata_only");
+  });
+
+  // -----------------------------------------------------------------------
+  // RBAC — non-admin is 403, through the controller AND the guard chain
+  // -----------------------------------------------------------------------
+
+  it("non-admin roles get 403 from GET and PATCH (controller gate)", async () => {
+    const req = (role: string) => ({ session: { userId: otherUser, workspaceId: ws, role, authzEpoch: 1, issuedAt: 0, expiresAt: 9e12 } });
+    for (const role of ["Publisher", "Editor", "Approver", "Analyst", "Moderator", "BroadcastOperator"]) {
+      const errGet = await controller.get(req(role) as never).then(
+        () => null,
+        (e: unknown) => e,
+      );
+      expect(errGet).toMatchObject({ status: 403 });
+      const errPatch = await controller.patch(req(role) as never, { youtube_full_harvest: true }).then(
+        () => null,
+        (e: unknown) => e,
+      );
+      expect(errPatch).toMatchObject({ status: 403 });
+    }
+    // And nothing changed.
+    expect(await service.getYoutubeFullHarvest()).toBe(false);
+  });
+
+  it("non-admin is refused in the service layer too (no other call path widens posture)", async () => {
+    await expect(service.updateSettings({ youtube_full_harvest: true }, { userId: otherUser, role: "Publisher" })).rejects.toBeDefined();
+    expect(await service.getYoutubeFullHarvest()).toBe(false);
+  });
+
+  it("Owner and Admin both pass the controller gate end-to-end", async () => {
+    await resetSettings();
+    const req = (userId: string, role: string) => ({ session: { userId, workspaceId: ws, role, authzEpoch: 1, issuedAt: 0, expiresAt: 9e12 } });
+    const asOwner = await controller.patch(req(adminUser, "Owner") as never, { scrape_bounded_pilot: true });
+    expect(asOwner.scrape_bounded_pilot).toBe(true);
+    const asAdmin = await controller.patch(req(adminUser, "Admin") as never, { scrape_bounded_pilot: false });
+    expect(asAdmin.scrape_bounded_pilot).toBe(false);
+    const read = await controller.get(req(adminUser, "Admin") as never);
+    expect(read.scrape_bounded_pilot).toBe(false);
+  });
+
+  it("the real RbacGuard + controller chain: valid session reaches GET, no session is 401", async () => {
+    const { Reflector } = await import("@nestjs/core");
+    const epoch = await asOwner(async (c) => Number((await c.query("SELECT authz_epoch FROM workspaces WHERE id = $1", [ws])).rows[0].authz_epoch));
+    const token = m.session.issueSession({ userId: adminUser, workspaceId: ws, role: "Owner", authzEpoch: epoch });
+    const run = async (headers: Record<string, string>): Promise<unknown> => {
+      const reqObj = { headers, session: undefined as unknown };
+      const ctx = { getHandler: () => controller.get, switchToHttp: () => ({ getRequest: () => reqObj }) } as never;
+      const guardOk = await new m.guard.RbacGuard(new Reflector()).canActivate(ctx);
+      if (guardOk) return controller.get(reqObj as never);
+      return null;
+    };
+    // No bearer -> guard 401 before the controller is reached.
+    await expect(run({})).rejects.toMatchObject({ status: 401 });
+    // Valid Owner session passes the guard (no permission metadata on the
+    // route) and the controller's role gate, returning the live settings.
+    const settings = (await run({ authorization: `Bearer ${token}` })) as import("./settings.service.js").InstanceSettingRecord;
+    expect(settings.intake_posture).toBe("metadata_only");
+  });
+
+  // -----------------------------------------------------------------------
+  // Audit events (system chain — instance rows are not tenant rows)
+  // -----------------------------------------------------------------------
+
+  it("every PATCH lands a system audit event with the before→after diff", async () => {
+    await resetSettings();
+    await service.updateSettings({ youtube_full_harvest: true, intake_posture: "bounded_pilot" }, { userId: adminUser, role: "Owner" });
+
+    const events = await asOwner(async (c) =>
+      (
+        await c.query<{ action: string; target_type: string; target_id: string; actor_user_id: string; diff: Record<string, unknown>; workspace_id: string | null }>(
+          "SELECT action, target_type, target_id, actor_user_id, diff, workspace_id FROM audit_log WHERE action = 'instance_settings.updated' ORDER BY seq",
+        )
+      ).rows,
+    );
+    expect(events.length).toBeGreaterThanOrEqual(1);
+    const last = events.at(-1);
+    expect(last).toBeDefined();
+    if (last === undefined) return;
+    // System chain: workspace_id IS NULL, actor recorded, diff carries the change.
+    expect(last.workspace_id).toBeNull();
+    expect(last.actor_user_id).toBe(adminUser);
+    expect(last.target_type).toBe("instance_settings");
+    expect(last.target_id).toBe("instance");
+    expect(last.diff).toMatchObject({
+      youtube_full_harvest: { from: false, to: true },
+      intake_posture: { from: "metadata_only", to: "bounded_pilot" },
+    });
+  });
+
+  it("a failed patch lands NO audit event", async () => {
+    await resetSettings();
+    const before = await asOwner(async (c) => Number((await c.query("SELECT count(*) AS n FROM audit_log WHERE action = 'instance_settings.updated'")).rows[0].n));
+    await expect(service.updateSettings({ intake_posture: "nonsense" }, { userId: adminUser, role: "Owner" })).rejects.toBeDefined();
+    const after = await asOwner(async (c) => Number((await c.query("SELECT count(*) AS n FROM audit_log WHERE action = 'instance_settings.updated'")).rows[0].n));
+    expect(after).toBe(before);
+  });
+
+  // -----------------------------------------------------------------------
+  // Table-level guarantees (migration 028)
+  // -----------------------------------------------------------------------
+
+  it("instance_settings is a system table: no workspace_id, no RLS, sp_app-granted", async () => {
+    const meta = await asOwner(async (c) =>
+      (
+        await c.query<{ columns: number; policies: number; rls: string; grants: string[] }>(
+          `SELECT
+             (SELECT count(*) FROM information_schema.columns WHERE table_name = 'instance_settings' AND column_name = 'workspace_id')::int AS columns,
+             (SELECT count(*) FROM pg_policies WHERE tablename = 'instance_settings')::int AS policies,
+             c.relrowsecurity::text AS rls,
+             coalesce(array_agg(DISTINCT u.grantee) FILTER (WHERE u.grantee <> 'superposter'), '{}') AS grants
+           FROM pg_class c
+           JOIN pg_namespace n ON n.oid = c.relnamespace
+           LEFT JOIN information_schema.role_table_grants u ON u.table_name = 'instance_settings' AND u.table_schema = 'public'
+           WHERE n.nspname = 'public' AND c.relname = 'instance_settings'
+           GROUP BY c.relrowsecurity`,
+        )
+      ).rows.at(0),
+    );
+    expect(meta).toBeDefined();
+    if (meta === undefined) return;
+    expect(meta.columns).toBe(0); // no workspace_id column
+    expect(meta.policies).toBe(0); // no RLS policies
+    expect(meta.rls).toBe("false"); // RLS not even enabled
+    expect(meta.grants).toContain("sp_app"); // system table with sp_app grants
+  });
+
+  it("CHECK constraints reject unknown keys and undecodable values at the DB", async () => {
+    await expect(asOwner(async (c) => c.query("INSERT INTO instance_settings (key, value) VALUES ('allow_everything', 'true')"))).rejects.toThrow();
+    await expect(asOwner(async (c) => c.query("INSERT INTO instance_settings (key, value) VALUES ('scrape_bounded_pilot', 'maybe')"))).rejects.toThrow();
+    await expect(asOwner(async (c) => c.query("INSERT INTO instance_settings (key, value) VALUES ('intake_posture', 'wildwest')"))).rejects.toThrow();
+    // A legit literal passes the CHECK (update the seeded row: key is the PK).
+    await asOwner(async (c) => c.query("UPDATE instance_settings SET value = 'community_submissions' WHERE key = 'intake_posture'"));
+    expect(await service.getIntakePosture()).toBe("community_submissions");
+    // A MISSING row decodes to the safe default and is surfaced as pending.
+    await asOwner(async (c) => c.query("DELETE FROM instance_settings WHERE key = 'intake_posture'"));
+    const pending = await service.getSettings();
+    expect(pending.intake_posture).toBe("metadata_only");
+    expect(pending.pending).toContain("intake_posture");
+    // Restore the seeded row for later groups.
+    await resetSettings();
+  });
+
+  it("the migration is registered in schema_migrations as 028", async () => {
+    const applied = await asOwner(async (c) => (await c.query<{ name: string }>("SELECT name FROM schema_migrations WHERE name LIKE '028%'")).rows.map((r) => r.name));
+    expect(applied).toContain("028_instance_settings.sql");
+  });
+});
diff --git a/apps/api/src/settings/settings.module.ts b/apps/api/src/settings/settings.module.ts
new file mode 100644
index 0000000..9219b88
--- /dev/null
+++ b/apps/api/src/settings/settings.module.ts
@@ -0,0 +1,16 @@
+/**
+ * Settings module wiring. The service talks to the system pool directly
+ * (withSystem): instance_settings is deliberately NOT tenant-scoped, so there
+ * is no withTenant context to establish — audit events go to the system chain
+ * via audit_append_system, which REJECTS a tenant context.
+ */
+import { Module } from "@nestjs/common";
+import { SettingsController } from "./settings.controller.js";
+import { SettingsService } from "./settings.service.js";
+
+@Module({
+  controllers: [SettingsController],
+  providers: [SettingsService],
+  exports: [SettingsService],
+})
+export class SettingsModule {}
diff --git a/apps/api/src/settings/settings.service.ts b/apps/api/src/settings/settings.service.ts
new file mode 100644
index 0000000..9ff4baa
--- /dev/null
+++ b/apps/api/src/settings/settings.service.ts
@@ -0,0 +1,229 @@
+/**
+ * Instance-level settings: the content-policy posture of THIS deployment.
+ *
+ * The firehose tiers are graded by legal/ToS exposure (decision record
+ * 2026-10-09-intake-posture.md). That exposure is
+ * per-instance — one egress IP, one legal entity — so the switches live in a
+ * SYSTEM table (migration 028): no workspace_id, no RLS, nothing per-tenant.
+ * Access control happens at the API seam: only Owner/Admin roles reach the
+ * mutating methods (controller role check), and every write lands a system
+ * audit-chain event (audit_append_system) so posture changes are provable.
+ *
+ * This module is the ONE place that interprets `instance_settings.value`
+ * strings. Key set is CHECK-constrained in 028 to exactly these five keys;
+ * values to exactly the literals decoded here, so an undecodable row cannot
+ * exist — unknown/missing rows fall back to the SAFE default and are surfaced
+ * as `pending` in GET /settings.
+ */
+/* eslint-disable no-restricted-syntax -- the setting keys NAME the platform each policy switch governs (youtube_full_harvest gates the yt-dlp path); this module is the policy boundary, same standing as intake-kinds.ts. */
+
+import { BadRequestException, Injectable } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { withSystem } from "../db/client.js";
+
+/** Overall intake posture (decision record tiers). */
+export const INTAKE_POSTURES = ["metadata_only", "community_submissions", "bounded_pilot"] as const;
+export type IntakePosture = (typeof INTAKE_POSTURES)[number];
+
+export function isIntakePosture(value: unknown): value is IntakePosture {
+  return typeof value === "string" && (INTAKE_POSTURES as readonly string[]).includes(value);
+}
+
+/** The five instance settings keys (migration 028 CHECK). */
+export const INSTANCE_SETTING_KEYS = [
+  "youtube_full_harvest",
+  "youtube_cc_only_broadcast",
+  "scrape_metadata_only",
+  "scrape_bounded_pilot",
+  "intake_posture",
+] as const;
+export type InstanceSettingKey = (typeof INSTANCE_SETTING_KEYS)[number];
+
+/** Boolean-valued keys — decoded from 'true'/'false'. */
+export const BOOLEAN_SETTING_KEYS: readonly InstanceSettingKey[] = [
+  "youtube_full_harvest",
+  "youtube_cc_only_broadcast",
+  "scrape_metadata_only",
+  "scrape_bounded_pilot",
+];
+
+/** Defaults = the safe posture (decision record 2026-10-09). */
+export const DEFAULT_INSTANCE_SETTINGS = {
+  youtube_full_harvest: false, // yt-dlp full video download: OFF
+  youtube_cc_only_broadcast: true, // broadcast playlists: CC-licensed only
+  scrape_metadata_only: true, // locked platforms: metadata only
+  scrape_bounded_pilot: false, // bounded read-only X pool: OFF
+  intake_posture: "metadata_only" as IntakePosture,
+} satisfies Record<InstanceSettingKey, boolean | IntakePosture>;
+
+/** The decoded settings value object (what every consumer reads). */
+export interface InstanceSettings {
+  /** Enables yt-dlp video download for YouTube sources (ToS risk). */
+  youtube_full_harvest: boolean;
+  /** CC-only filter for YouTube broadcast playlists (Creative Commons only). */
+  youtube_cc_only_broadcast: boolean;
+  /** Locked platforms stay metadata-only (no authenticated crawling). */
+  scrape_metadata_only: boolean;
+  /** Enables the bounded read-only X pool (decision record Tier 2). */
+  scrape_bounded_pilot: boolean;
+  /** Overall intake posture. */
+  intake_posture: IntakePosture;
+}
+
+/** GET /settings shape: values + last-write provenance per key. */
+export interface InstanceSettingRecord extends InstanceSettings {
+  /** ISO timestamps of the last write per key (epoch for never-written keys). */
+  updatedAt: Readonly<Record<InstanceSettingKey, string>>;
+  /** User ids of the last writer per key. */
+  updatedBy: Readonly<Record<InstanceSettingKey, string | null>>;
+  /** Keys with no row yet (unset ⇒ default in force). Read-only information. */
+  pending: readonly InstanceSettingKey[];
+}
+
+export interface SettingActor {
+  userId: string;
+  role: string;
+}
+
+/** Roles allowed to change instance posture. Task spec: Owner/Admin. */
+export const INSTANCE_ADMIN_ROLES: readonly string[] = ["Owner", "Admin"];
+
+export function isInstanceAdmin(role: string): boolean {
+  return INSTANCE_ADMIN_ROLES.includes(role);
+}
+
+type RawRow = { key: string; value: string; updated_at: Date; updated_by: string | null };
+
+/** System audit append, on the SAME transaction as the setting write. */
+async function auditSystemSettingChange(
+  client: PoolClient,
+  actor: SettingActor,
+  diff: Record<string, unknown>,
+): Promise<void> {
+  await client.query("SELECT audit_append_system($1, $2, $3, $4, $5::jsonb)", [
+    actor.userId,
+    "instance_settings.updated",
+    "instance_settings",
+    "instance",
+    JSON.stringify(diff),
+  ]);
+}
+
+@Injectable()
+export class SettingsService {
+  /** All five settings with metadata. Unknown rows cannot exist (028 CHECK). */
+  async getSettings(): Promise<InstanceSettingRecord> {
+    return withSystem(async (client) => this.readAll(client));
+  }
+
+  async getYoutubeFullHarvest(): Promise<boolean> {
+    return (await this.getSettings()).youtube_full_harvest;
+  }
+
+  async getYoutubeCcOnlyBroadcast(): Promise<boolean> {
+    return (await this.getSettings()).youtube_cc_only_broadcast;
+  }
+
+  async getScrapeMetadataOnly(): Promise<boolean> {
+    return (await this.getSettings()).scrape_metadata_only;
+  }
+
+  async getScrapeBoundedPilot(): Promise<boolean> {
+    return (await this.getSettings()).scrape_bounded_pilot;
+  }
+
+  async getIntakePosture(): Promise<IntakePosture> {
+    return (await this.getSettings()).intake_posture;
+  }
+
+  /**
+   * Partial update of instance settings. Validates shapes, writes every
+   * provided key in ONE transaction and lands a single system audit event
+   * carrying the before→after diff (posture changes are legal-exposure
+   * decisions; they must be provable after the fact).
+   */
+  async updateSettings(patch: unknown, actor: SettingActor): Promise<InstanceSettingRecord> {
+    if (!isInstanceAdmin(actor.role)) {
+      // Defense in depth: the controller gates first, the service re-checks so
+      // no other call path can widen the posture.
+      throw new BadRequestException("only Owner/Admin may change instance settings");
+    }
+    const input = this.validatePatch(patch);
+    return withSystem(async (client) => {
+      const before = await this.readAll(client);
+      const diff: Record<string, unknown> = {};
+      for (const key of INSTANCE_SETTING_KEYS) {
+        if (!(key in input)) continue;
+        const value = input[key];
+        await client.query(
+          `INSERT INTO instance_settings (key, value, updated_by) VALUES ($1, $2, $3)
+           ON CONFLICT (key) DO UPDATE SET value = EXCLUDED.value, updated_at = now(), updated_by = EXCLUDED.updated_by`,
+          [key, String(value), actor.userId],
+        );
+        diff[key] = { from: before[key], to: value };
+      }
+      await auditSystemSettingChange(client, actor, diff);
+      return this.readAll(client);
+    });
+  }
+
+  /**
+   * Body-shape guard (shared `unknown` body convention): an object with any
+   * subset of the five keys; booleans must be actual booleans, posture must be
+   * a known enum value, unknown keys are a 400 (never silently dropped).
+   */
+  private validatePatch(patch: unknown): Partial<InstanceSettings> {
+    if (typeof patch !== "object" || patch === null || Array.isArray(patch)) {
+      throw new BadRequestException("body must be an object");
+    }
+    const entries: Partial<InstanceSettings> = {};
+    let count = 0;
+    for (const [key, value] of Object.entries(patch as Record<string, unknown>)) {
+      if (!(INSTANCE_SETTING_KEYS as readonly string[]).includes(key)) {
+        throw new BadRequestException(`unknown setting: ${key} (allowed: ${INSTANCE_SETTING_KEYS.join(", ")})`);
+      }
+      if (key === "intake_posture") {
+        if (!isIntakePosture(value)) throw new BadRequestException(`intake_posture must be one of: ${INTAKE_POSTURES.join(", ")}`);
+        entries.intake_posture = value;
+      } else if (typeof value === "boolean") {
+        entries[key as Exclude<InstanceSettingKey, "intake_posture">] = value;
+      } else {
+        throw new BadRequestException(`${key} must be a boolean`);
+      }
+      count += 1;
+    }
+    if (count === 0) throw new BadRequestException("body must set at least one setting");
+    return entries;
+  }
+
+  /** Read + decode every key; missing rows decode to the safe default. */
+  private async readAll(client: PoolClient): Promise<InstanceSettingRecord> {
+    const result = await client.query<RawRow>("SELECT key, value, updated_at, updated_by FROM instance_settings");
+    const rows = new Map(result.rows.map((row) => [row.key, row]));
+    const settings: InstanceSettings = { ...DEFAULT_INSTANCE_SETTINGS };
+    const updatedAt = {} as Record<InstanceSettingKey, string>;
+    const updatedBy = {} as Record<InstanceSettingKey, string | null>;
+    const pending: InstanceSettingKey[] = [];
+    for (const key of INSTANCE_SETTING_KEYS) {
+      const row = rows.get(key);
+      if (row === undefined) {
+        pending.push(key);
+        updatedAt[key] = new Date(0).toISOString();
+        updatedBy[key] = null;
+        continue;
+      }
+      if (key === "intake_posture") {
+        if (isIntakePosture(row.value)) settings.intake_posture = row.value;
+      } else if (row.value === "true" || row.value === "false") {
+        settings[key] = row.value === "true";
+      }
+      // A row outside the decodable literals cannot exist (028 CHECK); if one
+      // ever does, the safe default above stays in force.
+      updatedAt[key] = row.updated_at.toISOString();
+      updatedBy[key] = row.updated_by;
+    }
+    return { ...settings, updatedAt, updatedBy, pending };
+  }
+}
+
+/* eslint-enable no-restricted-syntax */
diff --git a/apps/api/src/settings/settings.test.ts b/apps/api/src/settings/settings.test.ts
new file mode 100644
index 0000000..563a1ad
--- /dev/null
+++ b/apps/api/src/settings/settings.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import { BadRequestException, ForbiddenException } from "@nestjs/common";
+import {
+  BOOLEAN_SETTING_KEYS,
+  DEFAULT_INSTANCE_SETTINGS,
+  INSTANCE_ADMIN_ROLES,
+  INSTANCE_SETTING_KEYS,
+  INTAKE_POSTURES,
+  isInstanceAdmin,
+  isIntakePosture,
+  SettingsService,
+} from "./settings.service.js";
+import { SettingsController } from "./settings.controller.js";
+
+/**
+ * Unit level: validation shapes, defaults, the role gate — no DB. The
+ * live-DB CRUD/RBAC/audit coverage is settings.integration.test.ts.
+ */
+
+const service = new SettingsService();
+const admin = { userId: "00000000-0000-4000-8000-000000000001", role: "Owner" };
+
+describe("instance settings — keys, defaults, roles", () => {
+  it("exposes exactly the five policy keys from the task spec", () => {
+    expect(INSTANCE_SETTING_KEYS).toEqual([
+      "youtube_full_harvest",
+      "youtube_cc_only_broadcast",
+      "scrape_metadata_only",
+      "scrape_bounded_pilot",
+      "intake_posture",
+    ]);
+    expect(BOOLEAN_SETTING_KEYS).toHaveLength(4);
+    expect(INSTANCE_SETTING_KEYS).toHaveLength(5);
+  });
+
+  it("defaults are the SAFE posture (decision record 2026-10-09)", () => {
+    expect(DEFAULT_INSTANCE_SETTINGS.youtube_full_harvest).toBe(false); // yt-dlp OFF
+    expect(DEFAULT_INSTANCE_SETTINGS.youtube_cc_only_broadcast).toBe(true); // CC-only ON
+    expect(DEFAULT_INSTANCE_SETTINGS.scrape_metadata_only).toBe(true); // locked platforms: metadata
+    expect(DEFAULT_INSTANCE_SETTINGS.scrape_bounded_pilot).toBe(false); // no bounded X pool
+    expect(DEFAULT_INSTANCE_SETTINGS.intake_posture).toBe("metadata_only");
+  });
+
+  it("only Owner/Admin are instance admins", () => {
+    expect(INSTANCE_ADMIN_ROLES).toEqual(["Owner", "Admin"]);
+    for (const role of ["Owner", "Admin"]) expect(isInstanceAdmin(role)).toBe(true);
+    for (const role of ["Publisher", "Editor", "Approver", "Analyst", "Moderator", "BroadcastOperator", ""]) {
+      expect(isInstanceAdmin(role)).toBe(false);
+    }
+  });
+
+  it("posture enum accepts exactly the three postures", () => {
+    for (const p of INTAKE_POSTURES) expect(isIntakePosture(p)).toBe(true);
+    for (const bad of ["metadata", "", "METADATA_ONLY", "full", undefined, null, 1]) {
+      expect(isIntakePosture(bad)).toBe(false);
+    }
+  });
+});
+
+describe("instance settings — patch validation", () => {
+  it("a non-object body rejects before any query is issued", async () => {
+    await expect(service.updateSettings("x", admin)).rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it("rejects non-object bodies", async () => {
+    for (const bad of [undefined, null, "nope", 42, [], true]) {
+      await expect(service.updateSettings(bad, admin)).rejects.toBeInstanceOf(BadRequestException);
+    }
+  });
+
+  it("rejects unknown keys instead of silently dropping them", async () => {
+    await expect(
+      service.updateSettings({ youtube_full_harvest: true, allow_all_scraping: true }, admin),
+    ).rejects.toMatchObject({ status: 400, message: expect.stringMatching(/unknown setting/) });
+  });
+
+  it("rejects non-boolean values for the boolean switches", async () => {
+    for (const bad of ["true", 1, null, undefined]) {
+      await expect(service.updateSettings({ scrape_bounded_pilot: bad }, admin)).rejects.toMatchObject({ status: 400 });
+    }
+  });
+
+  it("rejects postures outside the enum", async () => {
+    for (const bad of ["full", "metadata-only", "", "METADATA_ONLY", true, null]) {
+      await expect(service.updateSettings({ intake_posture: bad }, admin)).rejects.toMatchObject({ status: 400 });
+    }
+  });
+
+  it("rejects an empty patch", async () => {
+    await expect(service.updateSettings({}, admin)).rejects.toMatchObject({ status: 400, message: expect.stringMatching(/at least one/) });
+  });
+
+  it("non-admin actors are refused in the service layer too (defense in depth)", async () => {
+    for (const role of ["Publisher", "Editor", "Approver", "Analyst", "Moderator", "BroadcastOperator"]) {
+      await expect(service.updateSettings({ intake_posture: "bounded_pilot" }, { userId: admin.userId, role })).rejects.toBeInstanceOf(
+        BadRequestException,
+      );
+    }
+  });
+});
+
+describe("instance settings — controller role gate", () => {
+  const controller = new SettingsController(service);
+
+  const req = (role: string) => ({ session: { userId: admin.userId, workspaceId: "ws", role, authzEpoch: 1, issuedAt: 0, expiresAt: 1 } });
+
+  it("GET /settings is 403 for non-admin roles", async () => {
+    for (const role of ["Publisher", "Editor", "Approver", "Analyst", "Moderator", "StreamOperator", "VideoPublisher"]) {
+      await expect(controller.get(req(role) as never)).rejects.toBeInstanceOf(ForbiddenException);
+    }
+  });
+
+  it("PATCH /settings is 403 for non-admin roles", async () => {
+    for (const role of ["Publisher", "Editor", "Approver", "Analyst", "Moderator"]) {
+      await expect(controller.patch(req(role) as never, { intake_posture: "bounded_pilot" })).rejects.toBeInstanceOf(
+        ForbiddenException,
+      );
+    }
+  });
+
+  it("Owner and Admin pass the controller gate (service then owns the rest)", async () => {
+    // A non-DB-backed service: getSettings would need the pool. Assert the
+    // gate itself by checking the failure is NOT Forbidden for admins.
+    for (const role of ["Owner", "Admin"]) {
+      const getErr = await controller.get(req(role) as never).then(
+        () => null,
+        (e: unknown) => e,
+      );
+      expect(getErr).not.toBeInstanceOf(ForbiddenException);
+      const patchErr = await controller.patch(req(role) as never, {}).then(
+        () => null,
+        (e: unknown) => e,
+      );
+      expect(patchErr).not.toBeInstanceOf(ForbiddenException);
+    }
+  });
+});
diff --git a/apps/api/src/storage/files-config.test.ts b/apps/api/src/storage/files-config.test.ts
new file mode 100644
index 0000000..b289020
--- /dev/null
+++ b/apps/api/src/storage/files-config.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { filesIntegrationConfigFromEnv } from "./files-config.js";
+
+// Synthetic non-secret account ID, used only for pure config tests; no network I/O.
+const env = {
+  FILES_R2_ENDPOINT: `https://${"a".repeat(32)}.r2.cloudflarestorage.com`,
+  FILES_RESERVED_BUCKETS: "occupymedia-peertube-videos,occupymedia-peertube-playlists",
+};
+
+describe("files integration config", () => {
+  it("keeps payload ownership separate with no disk cache or pad implementation", () => {
+    const config = filesIntegrationConfigFromEnv(env);
+    expect(new Set(Object.values(config.buckets)).size).toBe(3);
+    expect(config).toMatchObject({ localPayloadCache: false, localMetadataAllowed: true, padsEnabled: false });
+    expect(config.r2).toMatchObject({ region: "auto", forcePathStyle: true });
+  });
+
+  it("rejects reuse of Matrix, Poster, or PeerTube buckets for files", () => {
+    for (const FILES_R2_BUCKET of ["occupymedia-matrix-media", "occupymedia-media-encrypted", "occupymedia-peertube-videos", "occupymedia-peertube-playlists"]) {
+      expect(() => filesIntegrationConfigFromEnv({ ...env, FILES_R2_BUCKET })).toThrow("separate");
+    }
+    expect(() => filesIntegrationConfigFromEnv({ ...env, MATRIX_R2_BUCKET: "shared", S3_BUCKET: "shared" })).toThrow("separate");
+  });
+
+  it("rejects absent/non-R2 endpoints and unsafe public URLs", () => {
+    expect(() => filesIntegrationConfigFromEnv({})).toThrow();
+    for (const FILES_R2_ENDPOINT of ["http://localhost:9000", "https://s3.amazonaws.com", `${env.FILES_R2_ENDPOINT}/bucket`]) {
+      expect(() => filesIntegrationConfigFromEnv({ FILES_R2_ENDPOINT })).toThrow();
+    }
+    for (const FILES_PUBLIC_URL of ["http://files.example.org", "https://user:password@files.example.org", "https://files.example.org/?token=x"]) {
+      expect(() => filesIntegrationConfigFromEnv({ ...env, FILES_PUBLIC_URL })).toThrow();
+    }
+    expect(() => filesIntegrationConfigFromEnv({ ...env, FILES_R2_BUCKET: "" })).toThrow("bucket names");
+  });
+});
diff --git a/apps/api/src/storage/files-config.ts b/apps/api/src/storage/files-config.ts
new file mode 100644
index 0000000..6274f77
--- /dev/null
+++ b/apps/api/src/storage/files-config.ts
@@ -0,0 +1,54 @@
+/** Opt-in foundation config. Not loaded by API startup or the existing media worker. */
+export interface FilesIntegrationConfig {
+  payloadStore: "r2";
+  localPayloadCache: false;
+  localMetadataAllowed: true;
+  r2: { endpoint: string; region: "auto"; forcePathStyle: true };
+  buckets: { matrixMedia: string; filesBlobs: string; posterMedia: string };
+  filesUrl: string;
+  officeUrl: string;
+  /** Disabled until a pad adapter can keep text/revision payloads in R2. */
+  padsEnabled: false;
+}
+
+type Environment = Readonly<Record<string, string | undefined>>;
+
+function httpsOrigin(value: string, name: string): string {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+    throw new Error(`${name} must be an HTTPS origin without credentials, path or query`);
+  }
+  return url.origin;
+}
+
+export function filesIntegrationConfigFromEnv(env: Environment): FilesIntegrationConfig {
+  const endpoint = httpsOrigin(env.FILES_R2_ENDPOINT ?? "", "FILES_R2_ENDPOINT");
+  if (!/^[a-f0-9]{32}\.r2\.cloudflarestorage\.com$/.test(new URL(endpoint).hostname)) {
+    throw new Error("FILES_R2_ENDPOINT must use the account R2 S3 endpoint");
+  }
+  const buckets = {
+    matrixMedia: env.MATRIX_R2_BUCKET ?? "occupymedia-matrix-media",
+    filesBlobs: env.FILES_R2_BUCKET ?? "occupymedia-files-blobs",
+    posterMedia: env.S3_BUCKET ?? "occupymedia-media-encrypted",
+  };
+  const names = Object.values(buckets);
+  if (names.some(name => !/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/.test(name))) {
+    throw new Error("Payload buckets must be valid R2 bucket names");
+  }
+  // Other product buckets are supplied by deployment, not provider branching here.
+  const reserved = env.FILES_RESERVED_BUCKETS?.split(",").map(name => name.trim());
+  if (!reserved?.length || reserved.some(name => !/^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$/.test(name))) {
+    throw new Error("FILES_RESERVED_BUCKETS must list other products' payload buckets");
+  }
+  const exclusive = [...names, ...reserved];
+  if (new Set(exclusive).size !== exclusive.length) {
+    throw new Error("Every product must have separate payload buckets");
+  }
+  return {
+    payloadStore: "r2", localPayloadCache: false, localMetadataAllowed: true,
+    r2: { endpoint, region: "auto", forcePathStyle: true }, buckets,
+    filesUrl: httpsOrigin(env.FILES_PUBLIC_URL ?? "https://files.occupymedia.cc", "FILES_PUBLIC_URL"),
+    officeUrl: httpsOrigin(env.OFFICE_PUBLIC_URL ?? "https://office.occupymedia.cc", "OFFICE_PUBLIC_URL"),
+    padsEnabled: false,
+  };
+}
diff --git a/apps/api/src/storage/storage.integration.test.ts b/apps/api/src/storage/storage.integration.test.ts
new file mode 100644
index 0000000..b7ca992
--- /dev/null
+++ b/apps/api/src/storage/storage.integration.test.ts
@@ -0,0 +1,60 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { S3Storage } from "./storage.js";
+
+/**
+ * Live roundtrip against any S3-compatible endpoint (S3_ENDPOINT env;
+ * dev = MinIO from infra compose). Skipped without env — the pure key-scheme
+ * suite in storage.test.ts always runs.
+ */
+const cfg = process.env.S3_ENDPOINT;
+
+describe.skipIf(cfg === undefined)("S3 storage (live endpoint)", () => {
+  let storage: S3Storage;
+
+  beforeAll(() => {
+    storage = new S3Storage({
+      endpoint: cfg,
+      region: process.env.S3_REGION ?? "us-east-1",
+      accessKeyId: process.env.S3_ACCESS_KEY ?? "tactical-media-broadcast-hub",
+      secretAccessKey: process.env.S3_SECRET_KEY ?? "tactical-media-broadcast-hub_dev",
+      bucket: process.env.S3_BUCKET ?? "tactical-media-broadcast-hub-media-test",
+    });
+  });
+
+  afterAll(async () => {
+    // bucket intentionally retained for inspection; content is content-addressed test bytes
+    void storage;
+  });
+
+  it("put → get roundtrips bytes", async () => {
+    const payload = Buffer.from(`qa-roundtrip-${Date.now()}`);
+    const stored = await storage.putContent(payload, "image/png");
+    expect(stored.deduplicated).toBe(false);
+    const back = await storage.getObject(stored.key);
+    expect(back.equals(payload)).toBe(true);
+  });
+
+  it("identical bytes deduplicate (second put is a no-op)", async () => {
+    const payload = Buffer.from("dedupe-me-identical");
+    const first = await storage.putContent(payload, "video/mp4");
+    const second = await storage.putContent(Buffer.from("dedupe-me-identical"), "video/mp4");
+    expect(first.deduplicated).toBe(false);
+    expect(second.deduplicated).toBe(true);
+    expect(second.key).toBe(first.key);
+    expect(await storage.hasContent(second.hash, "video/mp4")).toBe(true);
+  });
+
+  it("same bytes, different content-type land on different keys", async () => {
+    const payload = Buffer.from("multi-format");
+    const asPng = await storage.putContent(payload, "image/png");
+    const asMp4 = await storage.putContent(payload, "video/mp4");
+    expect(asPng.key).not.toBe(asMp4.key);
+  });
+
+  it("presigns a GET url", async () => {
+    const stored = await storage.putContent(Buffer.from("presign-me"), "image/png");
+    const url = await storage.presign(stored.key, 60);
+    expect(url).toContain(encodeURIComponent(stored.key).split("%2F")[1] ?? stored.key.slice(7));
+    expect(url.startsWith("http")).toBe(true);
+  });
+});
diff --git a/apps/api/src/storage/storage.test.ts b/apps/api/src/storage/storage.test.ts
new file mode 100644
index 0000000..380c8cb
--- /dev/null
+++ b/apps/api/src/storage/storage.test.ts
@@ -0,0 +1,118 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { createHash, randomBytes } from "node:crypto";
+
+const s3Calls = vi.hoisted(() => ({ sent: [] as string[] }));
+
+vi.mock("@aws-sdk/client-s3", () => {
+  class FakeCommand {
+    constructor(readonly input: unknown, readonly marker: string) {}
+  }
+  class S3ServiceException extends Error {
+    readonly $metadata: { httpStatusCode?: number };
+    constructor(message: string, status: number, name: string) {
+      super(message);
+      this.name = name;
+      this.$metadata = { httpStatusCode: status };
+    }
+  }
+  return {
+    CreateBucketCommand: class extends FakeCommand { constructor(input: unknown) { super(input, "Create"); } },
+    HeadObjectCommand: class extends FakeCommand { constructor(input: unknown) { super(input, "Head"); } },
+    PutObjectCommand: class extends FakeCommand { constructor(input: unknown) { super(input, "Put"); } },
+    GetObjectCommand: class extends FakeCommand { constructor(input: unknown) { super(input, "Get"); } },
+    S3ServiceException,
+    S3Client: class {
+      constructor(readonly config: unknown) {}
+      async send(cmd: FakeCommand): Promise<unknown> {
+        s3Calls.sent.push(cmd.marker);
+        if (cmd.marker === "Create") throw new S3ServiceException("Access Denied", 403, "AccessDenied");
+        if (cmd.marker === "Head") throw new S3ServiceException("Not Found", 404, "NotFound");
+        return {};
+      }
+    },
+  };
+});
+
+import { S3Storage, extensionFor, keyForHash, open, seal, sha256 } from "./storage.js";
+
+const TEST_KEK = createHash("sha256").update("test-kek").digest();
+
+describe("storage key scheme (pure)", () => {
+  it("maps content types to extensions, unknown -> bin", () => {
+    expect(extensionFor("image/png")).toBe("png");
+    expect(extensionFor("video/mp4")).toBe("mp4");
+    expect(extensionFor("application/x-weird")).toBe("bin");
+  });
+
+  it("keys are content-addressed and deterministic", () => {
+    const hash = sha256(Buffer.from("same bytes"));
+    expect(keyForHash(hash, "image/png")).toBe(`sha256/${hash}.png`);
+    expect(keyForHash(hash, "video/mp4")).toBe(`sha256/${hash}.mp4`);
+    expect(keyForHash(sha256(Buffer.from("same bytes")), "image/png")).toBe(keyForHash(hash, "image/png"));
+    expect(keyForHash(sha256(Buffer.from("other")), "image/png")).not.toBe(keyForHash(hash, "image/png"));
+  });
+
+  it("hash is stable across buffer instances", () => {
+    expect(sha256(Buffer.from("abc"))).toBe(sha256(Buffer.from("abc")));
+    expect(sha256(Buffer.from("abc"))).toHaveLength(64);
+  });
+});
+
+describe("client-side encryption (pure)", () => {
+  it("seal → open roundtrips arbitrary bytes", () => {
+    const plaintext = randomBytes(1024 * 64);
+    const sealed = seal(plaintext, TEST_KEK);
+    expect(open(sealed, TEST_KEK).equals(plaintext)).toBe(true);
+  });
+
+  it("ciphertext never contains plaintext (endpoint sees only sealed frame)", () => {
+    const plaintext = Buffer.from("TOPSECRET-media-bytes-123");
+    const sealed = seal(plaintext, TEST_KEK);
+    expect(sealed.includes(plaintext)).toBe(false);
+  });
+
+  it("fresh CEK per seal → identical plaintext, different ciphertexts (dedup still by key)", () => {
+    const plaintext = Buffer.from("identical");
+    const a = seal(plaintext, TEST_KEK);
+    const b = seal(plaintext, TEST_KEK);
+    expect(a.equals(b)).toBe(false);
+    expect(open(a, TEST_KEK).equals(open(b, TEST_KEK))).toBe(true);
+  });
+
+  it("tampered ciphertext fails GCM authentication", () => {
+    const sealed = seal(Buffer.from("authentic"), TEST_KEK);
+    const last = sealed.length - 1;
+    sealed[last] = (sealed[last] ?? 0) ^ 0xff;
+    expect(() => open(sealed, TEST_KEK)).toThrow();
+  });
+
+  it("wrong KEK cannot open", () => {
+    const otherKek = createHash("sha256").update("other-kek").digest();
+    const sealed = seal(Buffer.from("private"), TEST_KEK);
+    expect(() => open(sealed, otherKek)).toThrow();
+  });
+
+  it("plaintext hash addressing + seal preserves dedup semantics", () => {
+    const a = Buffer.from("media");
+    const b = Buffer.from("media");
+    expect(sha256(a)).toBe(sha256(b));
+    expect(keyForHash(sha256(a), "video/mp4")).toBe(keyForHash(sha256(b), "video/mp4"));
+  });
+});
+
+describe("S3Storage with object-scoped credentials", () => {
+  beforeEach(() => { s3Calls.sent.length = 0; });
+
+  it("stores despite 403 on bucket create (pre-provisioned bucket, least-privilege token)", async () => {
+    const storage = new S3Storage({
+      endpoint: "https://s3.example.invalid",
+      accessKeyId: "scoped-key",
+      secretAccessKey: "scoped-secret",
+      bucket: "pre-provisioned",
+      mediaKek: TEST_KEK,
+    });
+    const stored = await storage.putContent(Buffer.from("scoped-token-probe"), "text/plain");
+    expect(stored.deduplicated).toBe(false);
+    expect(s3Calls.sent).toEqual(["Create", "Head", "Put"]);
+  });
+});
diff --git a/apps/api/src/storage/storage.ts b/apps/api/src/storage/storage.ts
new file mode 100644
index 0000000..2084774
--- /dev/null
+++ b/apps/api/src/storage/storage.ts
@@ -0,0 +1,224 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
+import {
+  CreateBucketCommand,
+  GetObjectCommand,
+  HeadObjectCommand,
+  PutObjectCommand,
+  S3Client,
+  S3ServiceException,
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+
+/**
+ * S3-compatible object storage — the ONLY media I/O path (user directive:
+ * all archive/grabber content lives on object storage, ENCRYPTED — user
+ * directive 2026-10-06). Client-side envelope encryption: every object body
+ * is AES-256-GCM sealed with a random CEK; the CEK is wrapped by the media
+ * KEK (env S3_KEK). The endpoint never sees plaintext. Content addressing
+ * stays on the PLAINTEXT hash (dedup survives); getObject re-verifies the
+ * hash, so storage-level tampering is detected. SSE-at-rest headers are set
+ * additionally for endpoints that honor them (belt-and-braces).
+ */
+
+export interface StoredObject {
+  key: string;
+  hash: string;
+  sizeBytes: number;
+  contentType: string;
+}
+
+export interface StorageService {
+  putContent(buffer: Buffer, contentType: string): Promise<StoredObject & { deduplicated: boolean }>;
+  getObject(key: string): Promise<Buffer>;
+  hasContent(hash: string, contentType: string): Promise<boolean>;
+  presign(key: string, ttlSeconds: number): Promise<string>;
+}
+
+const EXTENSIONS: Record<string, string> = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/webp": "webp",
+  "image/gif": "gif",
+  "video/mp4": "mp4",
+  "video/webm": "webm",
+  "video/quicktime": "mov",
+  "application/pdf": "pdf",
+};
+
+export function extensionFor(contentType: string): string {
+  return EXTENSIONS[contentType] ?? "bin";
+}
+
+export function keyForHash(hash: string, contentType: string): string {
+  return `sha256/${hash}.${extensionFor(contentType)}`;
+}
+
+export function sha256(buffer: Buffer): string {
+  return createHash("sha256").update(buffer).digest("hex");
+}
+
+const FRAME_MAGIC = Buffer.from("SPENC1");
+
+/** Seal plaintext under the KEK: returns [iv(12) | wrappedCEK | ciphertext+tag]. */
+export function seal(plaintext: Buffer, kek: Buffer): Buffer {
+  const cek = randomBytes(32);
+  const iv = randomBytes(12);
+  const sealedCek = aesGcmSeal(kek, iv, cek);
+  const cipher = createCipheriv("aes-256-gcm", cek, iv);
+  const body = Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+  return Buffer.concat([FRAME_MAGIC, iv, sealedCek, body]);
+}
+
+/** Open a sealed frame; verifies GCM tags (CEK wrap + body) and returns plaintext. */
+export function open(sealed: Buffer, kek: Buffer): Buffer {
+  if (sealed.subarray(0, FRAME_MAGIC.length).equals(FRAME_MAGIC) === false) {
+    throw new Error("storage: not an encrypted frame (magic mismatch)");
+  }
+  let offset = FRAME_MAGIC.length;
+  const iv = sealed.subarray(offset, offset + 12);
+  offset += 12;
+  const cekLen = 32 + 16;
+  const sealedCek = sealed.subarray(offset, offset + cekLen);
+  offset += cekLen;
+  const body = sealed.subarray(offset);
+  const cek = aesGcmOpen(kek, iv, sealedCek);
+  const tag = body.subarray(body.length - 16);
+  const ciphertext = body.subarray(0, body.length - 16);
+  const decipher = createDecipheriv("aes-256-gcm", cek, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}
+
+function aesGcmSeal(key: Buffer, iv: Buffer, plaintext: Buffer): Buffer {
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  return Buffer.concat([cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+
+function aesGcmOpen(key: Buffer, iv: Buffer, sealed: Buffer): Buffer {
+  const tag = sealed.subarray(sealed.length - 16);
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(sealed.subarray(0, sealed.length - 16)), decipher.final()]);
+}
+
+function loadMediaKek(): Buffer {
+  const env = process.env.S3_KEK;
+  if (env !== undefined && env !== "") {
+    const kek = Buffer.from(env, "base64");
+    if (kek.length !== 32) throw new Error("S3_KEK must be 32 bytes base64");
+    return kek;
+  }
+  if (process.env.NODE_ENV === "production") {
+    throw new Error("S3_KEK is required in production (media encryption is mandatory)");
+  }
+  return createHash("sha256").update(`dev-media-kek:${process.env.HOSTNAME ?? "local"}`).digest();
+}
+
+export interface S3StorageConfig {
+  endpoint?: string;
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  bucket?: string;
+  forcePathStyle?: boolean;
+  mediaKek?: Buffer;
+}
+
+export function s3ConfigFromEnv(): S3StorageConfig {
+  return {
+    endpoint: process.env.S3_ENDPOINT,
+    region: process.env.S3_REGION ?? "us-east-1",
+    accessKeyId: process.env.S3_ACCESS_KEY,
+    secretAccessKey: process.env.S3_SECRET_KEY,
+    bucket: process.env.S3_BUCKET ?? "tactical-media-broadcast-hub-media",
+    forcePathStyle: process.env.S3_FORCE_PATH_STYLE !== "false",
+  };
+}
+
+export class S3Storage implements StorageService {
+  private readonly client: S3Client;
+  private readonly bucket: string;
+  private readonly kek: Buffer;
+  private bucketReady = false;
+
+  constructor(config: S3StorageConfig) {
+    this.bucket = config.bucket ?? "tactical-media-broadcast-hub-media";
+    this.kek = config.mediaKek ?? loadMediaKek();
+    this.client = new S3Client({
+      endpoint: config.endpoint,
+      region: config.region ?? "us-east-1",
+      credentials:
+        config.accessKeyId !== undefined && config.secretAccessKey !== undefined
+          ? { accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey }
+          : undefined,
+      forcePathStyle: config.forcePathStyle ?? true,
+    });
+  }
+
+  private async ensureBucket(): Promise<void> {
+    if (this.bucketReady) return;
+    try {
+      await this.client.send(new CreateBucketCommand({ Bucket: this.bucket }));
+    } catch (err) {
+      const status = err instanceof S3ServiceException ? err.$metadata.httpStatusCode : undefined;
+      const name = err instanceof S3ServiceException ? err.name : "";
+      // 403: least-privilege object tokens (e.g. R2 keys scoped to existing
+      // buckets) cannot create buckets. The bucket is pre-provisioned, so
+      // proceed — a genuinely missing bucket fails loudly on the real operation.
+      if (status !== 409 && name !== "BucketAlreadyOwnedByYou" && status !== 403) throw err;
+    }
+    this.bucketReady = true;
+  }
+
+  private async headExists(key: string): Promise<boolean> {
+    try {
+      await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: key }));
+      return true;
+    } catch (err) {
+      const status = err instanceof S3ServiceException ? err.$metadata.httpStatusCode : undefined;
+      const name = err instanceof S3ServiceException ? err.name : "";
+      if (status === 404 || name === "NotFound") return false;
+      throw err;
+    }
+  }
+
+  async putContent(buffer: Buffer, contentType: string): Promise<StoredObject & { deduplicated: boolean }> {
+    await this.ensureBucket();
+    const hash = sha256(buffer);
+    const key = keyForHash(hash, contentType);
+    if (await this.headExists(key)) {
+      return { key, hash, sizeBytes: buffer.byteLength, contentType, deduplicated: true };
+    }
+    await this.client.send(
+      new PutObjectCommand({
+        Bucket: this.bucket,
+        Key: key,
+        Body: seal(buffer, this.kek),
+        ContentType: contentType,
+        ServerSideEncryption: "AES256",
+      }),
+    );
+    return { key, hash, sizeBytes: buffer.byteLength, contentType, deduplicated: false };
+  }
+
+  async getObject(key: string): Promise<Buffer> {
+    const res = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: key }));
+    if (res.Body === undefined) throw new Error(`empty body for ${key}`);
+    const stored = Buffer.from(await res.Body.transformToByteArray());
+    const plaintext = open(stored, this.kek);
+    const hashFromKey = key.split("/")[1]?.split(".")[0];
+    if (hashFromKey !== undefined && sha256(plaintext) !== hashFromKey) {
+      throw new Error(`storage: integrity failure for ${key} (plaintext hash mismatch)`);
+    }
+    return plaintext;
+  }
+
+  async hasContent(hash: string, contentType: string): Promise<boolean> {
+    await this.ensureBucket();
+    return this.headExists(keyForHash(hash, contentType));
+  }
+
+  async presign(key: string, ttlSeconds: number): Promise<string> {
+    return getSignedUrl(this.client, new GetObjectCommand({ Bucket: this.bucket, Key: key }), { expiresIn: ttlSeconds });
+  }
+}
diff --git a/apps/api/src/team/invite-link.controller.ts b/apps/api/src/team/invite-link.controller.ts
new file mode 100644
index 0000000..0b9584d
--- /dev/null
+++ b/apps/api/src/team/invite-link.controller.ts
@@ -0,0 +1,95 @@
+import { Body, Controller, Delete, Get, HttpCode, Inject, Param, Post, Req, Res, UnauthorizedException, UseGuards } from "@nestjs/common";
+import type { Request, Response } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import {
+  optionalEmail,
+  optionalString,
+  parseId,
+  requireObject,
+  requirePositiveInt,
+  requireSession,
+  requireString,
+} from "../http/validation.js";
+import { verifySession } from "../auth/session.js";
+import {
+  InviteLinkService,
+  type InviteLink,
+  type InviteLinkCreateInput,
+  type InviteLinkInfo,
+} from "./invite-link.service.js";
+import type { AuthResult } from "../auth/auth.service.js";
+
+/**
+ * Admin surface for invite links, extending the `team` namespace: mint a
+ * multi-use link (token returned ONCE), list them (never the token), revoke.
+ */
+@Controller("team")
+@UseGuards(RbacGuard)
+export class InviteLinkController {
+  constructor(@Inject(InviteLinkService) private readonly links: InviteLinkService) {}
+
+  @Post("invite-links")
+  @RequirePermission("workspace.members.manage")
+  async create(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<InviteLink> {
+    const session = requireSession(request);
+    const dto = requireObject(body, "body");
+    const input: InviteLinkCreateInput = { role: requireString(dto.role, "role"), expiresInHours: requirePositiveInt(dto.expiresInHours, "expiresInHours", 720) };
+    const maxUses = dto.maxUses === undefined || dto.maxUses === null ? undefined : requirePositiveInt(dto.maxUses, "maxUses", 10_000);
+    return this.links.create(session.workspaceId, { userId: session.userId, role: session.role }, { ...input, ...(maxUses === undefined ? {} : { maxUses }) });
+  }
+
+  @Get("invite-links")
+  @RequirePermission("workspace.members.manage")
+  async list(@Req() request: Request & AuthenticatedRequest): Promise<InviteLink[]> {
+    return this.links.list(requireSession(request).workspaceId);
+  }
+
+  @Delete("invite-links/:id")
+  @RequirePermission("workspace.members.manage")
+  async revoke(@Req() request: Request & AuthenticatedRequest, @Param("id") id: string): Promise<InviteLink> {
+    const session = requireSession(request);
+    return this.links.revoke(session.workspaceId, { userId: session.userId, role: session.role }, parseId(id));
+  }
+}
+
+/**
+ * Public claim surface. PATH-based routes keep the token out of the request
+ * body/log pairing issues while matching the SPA's route shape; there is NO
+ * RbacGuard here (the claimer may not be authenticated yet), so any presented
+ * Bearer session is verified manually, exactly like AuthController.reissue.
+ */
+@Controller("invites")
+export class InviteClaimController {
+  constructor(@Inject(InviteLinkService) private readonly links: InviteLinkService) {}
+
+  @Get(":token/info")
+  async info(@Param("token") token: string, @Res({ passthrough: true }) response: Response): Promise<InviteLinkInfo> {
+    response.setHeader("Cache-Control", "no-store");
+    return this.links.info(requireString(token, "token"));
+  }
+
+  @Post(":token/claim")
+  @HttpCode(201)
+  async claim(@Param("token") token: string, @Req() request: Request, @Body() body: unknown): Promise<AuthResult> {
+    const dto = requireObject(body, "body");
+    const authorization = request.headers.authorization;
+    if (authorization !== undefined && !authorization.startsWith("Bearer ")) throw new UnauthorizedException();
+    const session = authorization === undefined ? undefined : verifySession(authorization.slice("Bearer ".length));
+    if (authorization !== undefined && session === null) throw new UnauthorizedException();
+    // Shape-only extraction: username/password FORMAT validation lives in the
+    // service identity block, which runs after link validation so a bogus
+    // token only ever sees 404 here.
+    const username = optionalString(dto.username, "username");
+    const password = optionalString(dto.password, "password");
+    const displayName = optionalString(dto.displayName, "displayName");
+    const email = optionalEmail(dto.email);
+    return this.links.claim({
+      token: requireString(token, "token"),
+      ...(session === undefined ? {} : { session }),
+      ...(username === undefined ? {} : { username }),
+      ...(password === undefined ? {} : { password }),
+      ...(displayName === undefined ? {} : { displayName }),
+      ...(email === undefined ? {} : { email }),
+    });
+  }
+}
diff --git a/apps/api/src/team/invite-link.integration.test.ts b/apps/api/src/team/invite-link.integration.test.ts
new file mode 100644
index 0000000..4dd577b
--- /dev/null
+++ b/apps/api/src/team/invite-link.integration.test.ts
@@ -0,0 +1,275 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+
+/**
+ * Invite-link lifecycle against a live PostgreSQL, as sp_app (FORCE RLS binds).
+ * Uses its OWN database (INVITE_IT_DATABASE_URL, plus INVITE_IT_SUPER_DATABASE_URL
+ * for migrations/seeding) for the same reason as auth.integration.test.ts:
+ * tenancy.integration.test.ts wipes every workspace in the shared DB and vitest
+ * runs files in parallel. Skipped when unset.
+ */
+const appUrl = process.env.INVITE_IT_DATABASE_URL;
+const ownerUrl = process.env.INVITE_IT_SUPER_DATABASE_URL;
+
+type Modules = {
+  links: typeof import("./invite-link.service.js");
+  auth: typeof import("../auth/auth.service.js");
+  session: typeof import("../auth/session.js");
+  db: typeof import("../db/client.js");
+};
+
+describe.skipIf(appUrl === undefined || ownerUrl === undefined)("invite links (live DB)", () => {
+  let m: Modules;
+  let ownerPool: Pool;
+  const suffix = `${Date.now()}${Math.floor(Math.random() * 1e6)}`;
+  const ownerUsername = `invowner${suffix}`;
+  let workspaceId: string;
+  let actor: { userId: string; role: string };
+
+  async function asOwner<T>(fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await ownerPool.connect();
+    try {
+      return await fn(client);
+    } finally {
+      client.release();
+    }
+  }
+
+  beforeAll(async () => {
+    // The pool reads DATABASE_URL at import time: point it at the isolated DB first.
+    process.env.DATABASE_URL = appUrl;
+    process.env.SUPER_DATABASE_URL = ownerUrl;
+    const { runMigrations } = await import("../db/migrate.js");
+    await runMigrations(join(process.cwd(), "migrations"));
+    m = {
+      links: await import("./invite-link.service.js"),
+      auth: await import("../auth/auth.service.js"),
+      session: await import("../auth/session.js"),
+      db: await import("../db/client.js"),
+    };
+    ownerPool = new Pool({ connectionString: ownerUrl });
+
+    const auth = new m.auth.AuthService();
+    const reg = await auth.register({
+      workspaceName: "Invite IT",
+      username: ownerUsername,
+      password: "correct-horse-1",
+      displayName: "Owner",
+      email: `invowner-${suffix}@example.com`,
+    });
+    workspaceId = reg.me.workspace.id;
+    const session = m.session.verifySession(reg.token);
+    if (session === null) throw new Error("session did not verify");
+    actor = { userId: session.userId, role: session.role };
+  });
+
+  afterAll(async () => {
+    if (ownerPool !== undefined) {
+      await asOwner(async (c) => {
+        await c.query("DELETE FROM workspaces WHERE id = $1", [workspaceId]);
+        await c.query("DELETE FROM users WHERE username = ANY($1::text[])", [
+          [ownerUsername, ...claimedUsernames].filter((u): u is string => u !== null),
+        ]);
+      });
+      await ownerPool.end();
+    }
+    await m?.db.pool.end();
+  });
+
+  /** Claimed usernames, for teardown. */
+  const claimedUsernames: Array<string | null> = [];
+
+  /** Directly rewrite a link's state through the owner pool (inside the tenant context — RLS binds the owner too). */
+  async function forceLinkState(linkId: string, sql: string, params: unknown[] = []): Promise<void> {
+    await asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      await c.query(sql, [linkId, ...params]);
+      await c.query("COMMIT");
+    });
+  }
+
+  async function membershipRole(userId: string): Promise<{ role: string; status: string } | undefined> {
+    return asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      const rows = (
+        await c.query("SELECT role, status FROM memberships WHERE workspace_id = $1 AND user_id = $2", [workspaceId, userId])
+      ).rows as Array<{ role: string; status: string }>;
+      await c.query("COMMIT");
+      return rows[0];
+    });
+  }
+
+  async function useCount(linkId: string): Promise<number> {
+    return asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      const rows = (await c.query("SELECT use_count FROM workspace_invite_links WHERE id = $1", [linkId])).rows as Array<{ use_count: number }>;
+      await c.query("COMMIT");
+      return rows[0]?.use_count ?? -1;
+    });
+  }
+
+  async function auditActions(targetId: string): Promise<string[]> {
+    return asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      const rows = (await c.query("SELECT action, diff FROM audit_log WHERE target_id = $1 ORDER BY seq ASC", [targetId])).rows as Array<{
+        action: string;
+        diff: Record<string, unknown> | null;
+      }>;
+      await c.query("COMMIT");
+      return rows.map((r) => r.action);
+    });
+  }
+
+  it("create -> info -> claim with a fresh username; the response is an AuthResult and the membership is active", async () => {
+    const links = new m.links.InviteLinkService();
+    const created = await links.create(workspaceId, actor, { role: "Publisher", expiresInHours: 24, maxUses: 5 });
+    expect(created.token).toMatch(/^[A-Za-z0-9_-]{40,}$/);
+    expect(created.url).toContain(`/join/${created.token}`);
+    expect(created.status).toBe("active");
+    expect(created.useCount).toBe(0);
+
+    const info = await links.info(created.token as string);
+    expect(info.workspaceName).toBe("Invite IT");
+    expect(info.role).toBe("Publisher");
+    expect(info.maxUses).toBe(5);
+    expect(info.usedCount).toBe(0);
+    await expect(links.info("no-such-token")).rejects.toMatchObject({ status: 404 });
+
+    const username = `joiner${suffix}`;
+    claimedUsernames.push(username);
+    const result = await links.claim({ token: created.token as string, username, password: "correct-horse-1" });
+    expect(result.me.role).toBe("Publisher");
+    expect(result.me.user.username).toBe(username);
+    expect(result.me.workspace.id).toBe(workspaceId);
+    expect(result.me.permissions).toContain("draft.create");
+    const session = m.session.verifySession(result.token);
+    if (session === null) throw new Error("claim token did not verify");
+    expect(session.workspaceId).toBe(workspaceId);
+    const membership = await membershipRole(session.userId);
+    expect(membership).toEqual({ role: "Publisher", status: "active" });
+    expect(await useCount(created.id)).toBe(1);
+    expect(await auditActions(created.id)).toEqual(["invite_link.created"]);
+    expect(await auditActions(session.userId)).toEqual([]); // audit targets the membership id, not the user
+  });
+
+  it("double-claim by the same user is 409 and does not consume a use", async () => {
+    const links = new m.links.InviteLinkService();
+    const created = await links.create(workspaceId, actor, { role: "Approver", expiresInHours: 24 });
+    const username = `twice${suffix}`;
+    claimedUsernames.push(username);
+    const first = await links.claim({ token: created.token as string, username, password: "correct-horse-1", displayName: "Twice" });
+    const userId = m.session.verifySession(first.token)?.userId;
+    if (userId === undefined) throw new Error("no session");
+    await expect(links.claim({ token: created.token as string, username, password: "correct-horse-1" })).rejects.toMatchObject({
+      status: 409,
+    });
+    // Still 409 (not a 401) when the credentials are presented via Bearer instead.
+    const auth = new m.auth.AuthService();
+    await expect(auth.login({ username, password: "correct-horse-1" })).resolves.toMatchObject({ me: { role: "Approver" } });
+    expect(await useCount(created.id)).toBe(1); // unchanged: no partial consumption
+  });
+
+  it("an expired link is 410 on info and claim", async () => {
+    const links = new m.links.InviteLinkService();
+    const created = await links.create(workspaceId, actor, { role: "Publisher", expiresInHours: 1 });
+    await forceLinkState(created.id, "UPDATE workspace_invite_links SET expires_at = now() - interval '1 hour' WHERE id = $1");
+    await expect(links.info(created.token as string)).rejects.toMatchObject({ status: 410 });
+    const username = `late${suffix}`;
+    await expect(links.claim({ token: created.token as string, username, password: "correct-horse-1" })).rejects.toMatchObject({
+      status: 410,
+    });
+    // Rolled back: the whole claim transaction (user insert included) undid.
+    await expect(userByExternalId(username)).rejects.toThrow(/missing/);
+    expect((await links.list(workspaceId)).find((l) => l.id === created.id)?.status).toBe("expired");
+  });
+
+  it("a link that exhausts max_uses is 410, and exhaustion is visible in list", async () => {
+    const links = new m.links.InviteLinkService();
+    const created = await links.create(workspaceId, actor, { role: "Publisher", expiresInHours: 24, maxUses: 1 });
+    const first = `single${suffix}`;
+    claimedUsernames.push(first);
+    await links.claim({ token: created.token as string, username: first, password: "correct-horse-1" });
+    expect(await useCount(created.id)).toBe(1);
+    await expect(links.info(created.token as string)).rejects.toMatchObject({ status: 410 });
+    const second = `second${suffix}`;
+    await expect(links.claim({ token: created.token as string, username: second, password: "correct-horse-1" })).rejects.toMatchObject({
+      status: 410,
+    });
+    const listed = (await links.list(workspaceId)).find((l) => l.id === created.id);
+    expect(listed?.status).toBe("exhausted");
+  });
+
+  it("a revoked link is 410, revoking twice is 409, and an unknown id is 404", async () => {
+    const links = new m.links.InviteLinkService();
+    const created = await links.create(workspaceId, actor, { role: "Publisher", expiresInHours: 24 });
+    const revoked = await links.revoke(workspaceId, actor, created.id);
+    expect(revoked.status).toBe("revoked");
+    expect(revoked.revokedAt).not.toBeNull();
+    await expect(links.info(created.token as string)).rejects.toMatchObject({ status: 410 });
+    const username = `postrev${suffix}`;
+    await expect(links.claim({ token: created.token as string, username, password: "correct-horse-1" })).rejects.toMatchObject({
+      status: 410,
+    });
+    await expect(links.revoke(workspaceId, actor, created.id)).rejects.toMatchObject({ status: 409 });
+    await expect(links.revoke(workspaceId, actor, "00000000-0000-4000-8000-000000000000")).rejects.toMatchObject({ status: 404 });
+  });
+
+  it("list returns derived statuses and NEVER the token; the audit diff never contains it either", async () => {
+    const links = new m.links.InviteLinkService();
+    const active = await links.create(workspaceId, actor, { role: "Publisher", expiresInHours: 24 });
+    const listed = await links.list(workspaceId);
+    expect(listed.length).toBeGreaterThan(0);
+    for (const link of listed) {
+      expect(link.token).toBeUndefined();
+      expect(link.url).toBeUndefined();
+      expect(["active", "expired", "revoked", "exhausted"]).toContain(link.status);
+    }
+    expect(listed.find((l) => l.id === active.id)?.status).toBe("active");
+
+    const auditRow = await asOwner(async (c) => {
+      await c.query("BEGIN");
+      await c.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      const rows = (
+        await c.query("SELECT diff FROM audit_log WHERE action = 'invite_link.created' AND target_id = $1", [active.id])
+      ).rows as Array<{ diff: Record<string, unknown> | null }>;
+      await c.query("COMMIT");
+      return rows[0]?.diff ?? null;
+    });
+    expect(auditRow).toEqual({ role: "Publisher", expiresAt: active.expiresAt, maxUses: null });
+    expect(JSON.stringify(auditRow)).not.toContain(active.token as string);
+  });
+
+  it("an authenticated (Bearer) claim joins with the existing identity; unknown roles are refused at create", async () => {
+    const links = new m.links.InviteLinkService();
+    const username = `bearer${suffix}`;
+    claimedUsernames.push(username);
+    // Register a separate workspace to prove the claim crosses tenants.
+    const auth = new m.auth.AuthService();
+    const reg = await auth.register({ workspaceName: "Bearer Home", username, password: "correct-horse-1", displayName: "B" });
+    const session = m.session.verifySession(reg.token);
+    if (session === null) throw new Error("no session");
+
+    const created = await links.create(workspaceId, actor, { role: "Approver", expiresInHours: 24 });
+    const result = await links.claim({ token: created.token as string, session });
+    expect(result.me.workspace.id).toBe(workspaceId);
+    expect(result.me.user.username).toBe(username);
+    expect(await membershipRole(session.userId)).toEqual({ role: created.role, status: "active" });
+
+    await expect(links.create(workspaceId, actor, { role: "NotARole", expiresInHours: 24 })).rejects.toMatchObject({ status: 400 });
+    await expect(auth.login({ username, password: "correct-horse-1" })).resolves.toMatchObject({ me: { workspace: { id: reg.me.workspace.id } } });
+  });
+
+  /** Resolve a claimed username to its user id via the owner pool (users has no RLS). */
+  async function userByExternalId(username: string): Promise<string> {
+    return asOwner(async (c) => {
+      const rows = (await c.query("SELECT id FROM users WHERE username = $1", [username])).rows as Array<{ id: string }>;
+      if (rows[0] === undefined) throw new Error(`user ${username} missing`);
+      return rows[0].id;
+    });
+  }
+});
diff --git a/apps/api/src/team/invite-link.service.ts b/apps/api/src/team/invite-link.service.ts
new file mode 100644
index 0000000..41be9ad
--- /dev/null
+++ b/apps/api/src/team/invite-link.service.ts
@@ -0,0 +1,407 @@
+import { randomBytes } from "node:crypto";
+import {
+  BadRequestException,
+  ConflictException,
+  GoneException,
+  Injectable,
+  NotFoundException,
+  UnauthorizedException,
+} from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { issueSessionInTenant, localExternalId, type AuthResult, type MeResponse } from "../auth/auth.service.js";
+import { MIN_PASSWORD_LENGTH, burnPasswordCheck, hashPassword, verifyPassword } from "../auth/password.js";
+import { verifySession, type SessionPayload } from "../auth/session.js";
+import { withSystem, withTenant } from "../db/client.js";
+import { requireString, requireUsername } from "../http/validation.js";
+import type { TeamActor } from "./team.service.js";
+
+export type InviteLinkStatus = "active" | "expired" | "revoked" | "exhausted";
+
+/**
+ * Admin-facing view of a link. `token`/`url` are returned by create ONLY —
+ * list/get never re-expose the secret, since anyone holding it can join.
+ */
+export interface InviteLink {
+  id: string;
+  role: string;
+  createdAt: string; // ISO
+  expiresAt: string; // ISO
+  maxUses: number | null;
+  useCount: number;
+  revokedAt: string | null;
+  status: InviteLinkStatus; // computed server-side, like MemberStatus
+  createdByUserId: string;
+  token?: string; // create response ONLY
+  url?: string; // create response ONLY: `${webOrigin}/join/<token>` — shown once, never in list/audit
+}
+
+export interface InviteLinkCreateInput {
+  role: string;
+  expiresInHours: number; // 1..720; server computes expires_at
+  maxUses?: number; // absent/null = unlimited until expiry
+}
+
+/** Public, pre-auth landing-page metadata for a token (GET /invites/:token/info). */
+export interface InviteLinkInfo {
+  workspaceName: string;
+  role: string;
+  expiresAt: string;
+  maxUses: number | null;
+  usedCount: number;
+}
+
+export interface InviteClaimInput {
+  token: string;
+  /** Present when the caller brought a valid Bearer session (verified manually — this route has no guard). */
+  session?: SessionPayload | null;
+  /** Required when `session` is absent. */
+  username?: string;
+  password?: string;
+  displayName?: string;
+  email?: string;
+}
+
+const OWNER = "Owner";
+
+interface InviteLinkRow {
+  id: string;
+  workspace_id: string;
+  role: string;
+  created_by: string;
+  created_at: Date;
+  expires_at: Date;
+  max_uses: number | null;
+  use_count: number;
+  revoked_at: Date | null;
+}
+
+interface LinkClaimRow {
+  id: string;
+  workspace_id: string;
+  role: string;
+  expires_at: Date;
+  max_uses: number | null;
+  use_count: number;
+  revoked_at: Date | null;
+}
+
+const LINK_COLUMNS = "id, workspace_id, role, created_by, created_at, expires_at, max_uses, use_count, revoked_at";
+
+/** Same precedence as the claim guards: revoked beats expired beats exhausted. */
+function statusOf(row: Pick<LinkClaimRow, "revoked_at" | "expires_at" | "max_uses" | "use_count">): InviteLinkStatus {
+  if (row.revoked_at !== null) return "revoked";
+  if (new Date(row.expires_at).getTime() <= Date.now()) return "expired";
+  if (row.max_uses !== null && row.use_count >= row.max_uses) return "exhausted";
+  return "active";
+}
+
+function toIso(value: Date): string {
+  return new Date(value).toISOString();
+}
+
+/** Web origin the invite URL points at; the SPA owns the /join/<token> landing page. */
+function publicWebUrl(): string {
+  return (process.env.APP_URL ?? process.env.WEB_ORIGIN ?? "http://localhost:3001").replace(/\/+$/, "");
+}
+
+function isUniqueViolation(err: unknown): boolean {
+  return typeof err === "object" && err !== null && "code" in err && (err as { code?: string }).code === "23505";
+}
+
+@Injectable()
+export class InviteLinkService {
+  async create(workspaceId: string, actor: TeamActor, input: InviteLinkCreateInput): Promise<InviteLink> {
+    if (input.expiresInHours < 1 || input.expiresInHours > 720) throw new BadRequestException("expiresInHours must be between 1 and 720");
+    if (input.maxUses !== undefined && (!Number.isInteger(input.maxUses) || input.maxUses < 1)) {
+      throw new BadRequestException("maxUses must be a positive integer");
+    }
+    if (input.role === OWNER) throw new BadRequestException("invite links cannot grant the Owner role — invite members and promote them in Team");
+    // 256 bits of entropy: tokens are unguessable and never stored hashed, so
+    // they are only ever shown once (create response) and never in list/audit.
+    const token = randomBytes(32).toString("base64url");
+    const expiresAt = new Date(Date.now() + input.expiresInHours * 3_600_000);
+
+    const row = await withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      await this.assertRoleExists(client, input.role);
+      const res = await client.query(
+        `INSERT INTO workspace_invite_links (workspace_id, role, token, created_by, expires_at, max_uses)
+         VALUES ($1, $2, $3, $4, $5, $6) RETURNING ${LINK_COLUMNS}`,
+        [workspaceId, input.role, token, actor.userId, expiresAt, input.maxUses ?? null],
+      );
+      return res.rows[0] as InviteLinkRow;
+    });
+
+    await appendTenantAudit(workspaceId, {
+      actorUserId: actor.userId,
+      actorRole: actor.role,
+      action: "invite_link.created",
+      targetType: "invite_link",
+      targetId: row.id,
+      diff: { role: row.role, expiresAt: toIso(row.expires_at), maxUses: row.max_uses }, // never the token
+    });
+    return { ...this.toLink(row), token, url: `${publicWebUrl()}/join/${token}` };
+  }
+
+  async list(workspaceId: string): Promise<InviteLink[]> {
+    const res = await withTenant(workspaceId, (client) =>
+      client.query(`SELECT ${LINK_COLUMNS} FROM workspace_invite_links WHERE workspace_id = $1 ORDER BY created_at DESC`, [workspaceId]),
+    );
+    // The token column is deliberately not selected: listing is admin UI and
+    // must never re-expose a live secret.
+    return (res.rows as InviteLinkRow[]).map((row) => this.toLink(row));
+  }
+
+  async revoke(workspaceId: string, actor: TeamActor, linkId: string): Promise<InviteLink> {
+    const outcome = await withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const updated = await client.query(
+        `UPDATE workspace_invite_links SET revoked_at = now()
+         WHERE id = $1 AND workspace_id = $2 AND revoked_at IS NULL RETURNING ${LINK_COLUMNS}`,
+        [linkId, workspaceId],
+      );
+      const row = updated.rows[0] as InviteLinkRow | undefined;
+      if (row !== undefined) return { row, changed: true };
+      const existing = await client.query(
+        `SELECT ${LINK_COLUMNS} FROM workspace_invite_links WHERE id = $1 AND workspace_id = $2`,
+        [linkId, workspaceId],
+      );
+      const found = existing.rows[0] as InviteLinkRow | undefined;
+      if (found === undefined) throw new NotFoundException(`invite link ${linkId} not found`);
+      return { row: found, changed: false };
+    });
+    if (!outcome.changed) throw new ConflictException("invite link already revoked");
+
+    await appendTenantAudit(workspaceId, {
+      actorUserId: actor.userId,
+      actorRole: actor.role,
+      action: "invite_link.revoked",
+      targetType: "invite_link",
+      targetId: linkId,
+      diff: { role: outcome.row.role, useCount: outcome.row.use_count }, // never the token
+    });
+    return this.toLink(outcome.row);
+  }
+
+  /**
+   * Pre-auth landing page data. `invite_link_for_claim` is the only way to see
+   * a link outside a tenant context; `workspaces` has no RLS, so the name join
+   * is safe under `withSystem`. Projection is name/role/counters only.
+   */
+  async info(token: string): Promise<InviteLinkInfo> {
+    const res = await withSystem((client) =>
+      client.query(
+        `SELECT l.role, l.expires_at, l.max_uses, l.use_count, l.revoked_at, w.name AS workspace_name
+         FROM invite_link_for_claim($1) l JOIN workspaces w ON w.id = l.workspace_id`,
+        [token],
+      ),
+    );
+    const row = res.rows[0] as
+      | { role: string; expires_at: Date; max_uses: number | null; use_count: number; revoked_at: Date | null; workspace_name: string }
+      | undefined;
+    if (row === undefined) throw new NotFoundException("invite link is invalid or has expired");
+    const status = statusOf(row);
+    if (status === "revoked") throw new GoneException("invite link has been revoked");
+    if (status === "expired") throw new GoneException("invite link has expired");
+    if (status === "exhausted") throw new GoneException("invite link has no uses left");
+    return {
+      workspaceName: row.workspace_name,
+      role: row.role,
+      expiresAt: toIso(row.expires_at),
+      maxUses: row.max_uses,
+      usedCount: row.use_count,
+    };
+  }
+
+  /**
+   * Register-or-sign-in + join in one system transaction, returning the same
+   * `AuthResult` shape as POST /auth/login so the SPA reuses its auth handler.
+   *
+   * Everything runs in ONE `withSystem` transaction (register's pattern): the
+   * claimer has no tenant context yet, so the link is resolved through the
+   * narrow SECURITY DEFINER lookup, then `set_config('app.workspace_id', …, true)`
+   * enters the target tenant for the RLS-bound membership insert, the atomic
+   * use consumption, and the session mint (which reads the post-bump epoch).
+   */
+  async claim(input: InviteClaimInput): Promise<AuthResult> {
+    const token = requireString(input.token, "token");
+    const outcome = await withSystem(async (client) => {
+      // 1. Link resolution through the SECURITY DEFINER lookup (no tenant context exists yet).
+      const linkRes = await client.query(
+        "SELECT id, workspace_id, role, expires_at, max_uses, use_count, revoked_at FROM invite_link_for_claim($1)",
+        [token],
+      );
+      const link = linkRes.rows[0] as LinkClaimRow | undefined;
+      if (link === undefined) throw new NotFoundException("invite link is invalid or has expired");
+
+      // 2. Validation (410 Gone for dead-but-real links) — BEFORE any credential
+      //    work, so a made-up token only ever sees 404 and usernames stay unenumerable.
+      if (link.revoked_at !== null) throw new GoneException("invite link has been revoked");
+      if (new Date(link.expires_at).getTime() <= Date.now()) throw new GoneException("invite link has expired");
+      if (link.max_uses !== null && link.use_count >= link.max_uses) throw new GoneException("invite link has no uses left");
+      await this.assertRoleAlive(client, link.role);
+
+      // 3. Identity resolution (only when no Bearer session was presented).
+      let userId: string;
+      let username: string | null = null;
+      const session = input.session ?? undefined;
+      if (session !== undefined) {
+        userId = session.userId;
+      } else {
+        const name = requireUsername(input.username, "username");
+        const password = requireString(input.password, "password");
+        username = name;
+        const found = await client.query(
+          `SELECT u.id, p.password_hash FROM users u
+           LEFT JOIN user_passwords p ON p.user_id = u.id
+           WHERE u.external_id = $1`,
+          [localExternalId(name)],
+        );
+        const row = found.rows[0] as { id: string; password_hash: string | null } | undefined;
+        if (row === undefined) {
+          // Register. Same anti-hijack rule as AuthService.register: an existing
+          // identity (including a password-less invited placeholder) can never
+          // be claimed by registering — see the branches below.
+          if (password.length < MIN_PASSWORD_LENGTH) {
+            throw new BadRequestException(`password must be at least ${MIN_PASSWORD_LENGTH} characters`);
+          }
+          const passwordHash = await hashPassword(password);
+          const displayName = (input.displayName ?? name).trim().slice(0, 100);
+          let created: { rows: Array<{ id: string }> };
+          try {
+            created = await client.query(
+              `INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4)
+               ON CONFLICT (external_id) DO NOTHING
+               RETURNING id`,
+              [localExternalId(name), name, input.email ?? null, displayName],
+            );
+          } catch (err) {
+            // Username collides with a differently-keyed account (e.g. an email
+            // placeholder that already took this username): surface 409, not a 500.
+            if (isUniqueViolation(err)) throw new ConflictException("an account with this username already exists — sign in instead");
+            throw err;
+          }
+          const id = created.rows[0]?.id as string | undefined;
+          if (id === undefined) throw new ConflictException("an account with this username already exists — sign in instead");
+          userId = id;
+          await client.query("INSERT INTO user_passwords (user_id, password_hash) VALUES ($1, $2)", [userId, passwordHash]);
+        } else if (row.password_hash === null) {
+          // Password-less invited placeholder: burning keeps claim timing flat.
+          await burnPasswordCheck(password);
+          throw new ConflictException("an account with this username already exists — sign in instead");
+        } else if (!(await verifyPassword(password, row.password_hash))) {
+          throw new UnauthorizedException("invalid email or password");
+        } else {
+          userId = row.id;
+        }
+      }
+
+      // 4. Tenant entry: transaction-local, cannot leak past COMMIT/ROLLBACK.
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [link.workspace_id]);
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [link.workspace_id]);
+
+      // 5. Membership insert. Conflict (any existing row, including an 'invited'
+      //    placeholder) => 409 and NO use consumed: a link must never be a
+      //    privilege-upgrade vector for an existing membership.
+      const inserted = await client.query(
+        `INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, $3, 'active')
+         ON CONFLICT (workspace_id, user_id) DO NOTHING
+         RETURNING id`,
+        [link.workspace_id, userId, link.role],
+      );
+      const membershipId = inserted.rows[0]?.id as string | undefined;
+      if (membershipId === undefined) {
+        throw new ConflictException("you are already a member of this workspace — sign in instead");
+      }
+
+      // 6. Atomic consumption: one conditional statement, no SELECT-then-check
+      //    TOCTOU. EvalPlanQual re-evaluates the guard on the locked row, so
+      //    concurrent claimers cannot both spend the last use.
+      const consumed = await client.query(
+        `UPDATE workspace_invite_links SET use_count = use_count + 1
+         WHERE id = $1 AND revoked_at IS NULL AND expires_at > now()
+           AND (max_uses IS NULL OR use_count < max_uses)`,
+        [link.id],
+      );
+      if ((consumed.rowCount ?? 0) === 0) throw new GoneException("invite link is no longer active");
+
+      // 7. Session mint inside the same tx, reading the post-bump epoch and the
+      //    fresh membership row (the membership insert bumped the workspace epoch).
+      const sessionToken = await issueSessionInTenant(client, link.workspace_id, userId);
+      return {
+        workspaceId: link.workspace_id,
+        userId,
+        membershipId,
+        linkId: link.id,
+        role: link.role,
+        token: sessionToken,
+        username,
+      };
+    });
+
+    // 8. After commit (appendTenantAudit opens its own withTenant).
+    const me = await this.meFor(outcome.workspaceId, outcome.userId, outcome.token);
+    await appendTenantAudit(outcome.workspaceId, {
+      actorUserId: outcome.userId,
+      actorRole: outcome.role,
+      action: "membership.joined",
+      targetType: "membership",
+      targetId: outcome.membershipId,
+      diff: { linkId: outcome.linkId, role: outcome.role, username: outcome.username ?? me.user.username }, // never the token
+    });
+    return { token: outcome.token, me };
+  }
+
+  private toLink(row: InviteLinkRow): InviteLink {
+    return {
+      id: row.id,
+      role: row.role,
+      createdAt: toIso(row.created_at),
+      expiresAt: toIso(row.expires_at),
+      maxUses: row.max_uses,
+      useCount: row.use_count,
+      revokedAt: row.revoked_at === null ? null : toIso(row.revoked_at),
+      status: statusOf(row),
+      createdByUserId: row.created_by,
+    };
+  }
+
+  /** AuthService.meFor's projection (it is private there), reused for the claim response. */
+  private async meFor(workspaceId: string, userId: string, token: string): Promise<MeResponse> {
+    return withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const res = await client.query(
+        `SELECT m.role, u.username, u.email, u.display_name, w.name, w.slug
+         FROM memberships m
+         JOIN users u ON u.id = m.user_id
+         JOIN workspaces w ON w.id = m.workspace_id
+         WHERE m.workspace_id = $1 AND m.user_id = $2 AND m.status = 'active'`,
+        [workspaceId, userId],
+      );
+      const row = res.rows[0] as
+        | { role: string; username: string; email: string | null; display_name: string; name: string; slug: string }
+        | undefined;
+      if (row === undefined) throw new UnauthorizedException("membership no longer active");
+      const perms = await client.query("SELECT permission FROM role_permissions WHERE role = $1 ORDER BY permission", [row.role]);
+      return {
+        user: { id: userId, username: row.username, email: row.email, displayName: row.display_name },
+        workspace: { id: workspaceId, name: row.name, slug: row.slug },
+        role: row.role,
+        permissions: (perms.rows as Array<{ permission: string }>).map((p) => p.permission),
+        expiresAt: verifySession(token)?.expiresAt ?? 0,
+      };
+    });
+  }
+
+  private async assertRoleExists(client: PoolClient, role: string): Promise<void> {
+    const res = await client.query("SELECT 1 FROM role_permissions WHERE role = $1 LIMIT 1", [role]);
+    if (res.rowCount === 0) throw new BadRequestException(`unknown role: ${role}`);
+  }
+
+  /** Claim-time role check: a removed role means the link is dead, not a bad request. */
+  private async assertRoleAlive(client: PoolClient, role: string): Promise<void> {
+    const res = await client.query("SELECT 1 FROM role_permissions WHERE role = $1 LIMIT 1", [role]);
+    if (res.rowCount === 0) throw new GoneException("invite link references a removed role");
+  }
+}
diff --git a/apps/api/src/team/team.controller.ts b/apps/api/src/team/team.controller.ts
new file mode 100644
index 0000000..d694ab0
--- /dev/null
+++ b/apps/api/src/team/team.controller.ts
@@ -0,0 +1,61 @@
+import { Body, Controller, Delete, Get, Inject, Param, Patch, Post, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { parseId, requireEmail, requireObject, requireSession, requireString } from "../http/validation.js";
+import { TeamService, type Member, type MemberMutationResult } from "./team.service.js";
+
+@Controller("team")
+@UseGuards(RbacGuard)
+export class TeamController {
+  constructor(@Inject(TeamService) private readonly team: TeamService) {}
+
+  /** Every role holds workspace.view, so any member can see who else is in the workspace. */
+  @Get("members")
+  @RequirePermission("workspace.view")
+  async list(@Req() request: Request & AuthenticatedRequest): Promise<Member[]> {
+    return this.team.list(requireSession(request).workspaceId);
+  }
+
+  @Get("roles")
+  @RequirePermission("workspace.view")
+  async roles(): Promise<string[]> {
+    return this.team.roles();
+  }
+
+  @Post("members/invite")
+  @RequirePermission("workspace.members.manage")
+  async invite(@Req() request: Request & AuthenticatedRequest, @Body() body: unknown): Promise<MemberMutationResult> {
+    const session = requireSession(request);
+    const dto = requireObject(body, "body");
+    return this.team.invite(
+      session.workspaceId,
+      { userId: session.userId, role: session.role },
+      requireEmail(dto.email),
+      requireString(dto.role, "role"),
+    );
+  }
+
+  @Patch("members/:id/role")
+  @RequirePermission("workspace.members.manage")
+  async changeRole(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+    @Body() body: unknown,
+  ): Promise<MemberMutationResult> {
+    const session = requireSession(request);
+    const dto = requireObject(body, "body");
+    return this.team.changeRole(
+      session.workspaceId,
+      { userId: session.userId, role: session.role },
+      parseId(id),
+      requireString(dto.role, "role"),
+    );
+  }
+
+  @Delete("members/:id")
+  @RequirePermission("workspace.members.manage")
+  async remove(@Req() request: Request & AuthenticatedRequest, @Param("id") id: string): Promise<MemberMutationResult> {
+    const session = requireSession(request);
+    return this.team.remove(session.workspaceId, { userId: session.userId, role: session.role }, parseId(id));
+  }
+}
diff --git a/apps/api/src/team/team.service.ts b/apps/api/src/team/team.service.ts
new file mode 100644
index 0000000..25236f4
--- /dev/null
+++ b/apps/api/src/team/team.service.ts
@@ -0,0 +1,214 @@
+import { BadRequestException, ConflictException, ForbiddenException, Injectable, NotFoundException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { randomBytes } from "node:crypto";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { issueSessionInTenant, localExternalId } from "../auth/auth.service.js";
+import { pool, withTenant } from "../db/client.js";
+
+export type MemberStatus = "active" | "invited";
+
+export interface Member {
+  id: string;
+  userId: string;
+  username: string;
+  email: string | null;
+  displayName: string;
+  role: string;
+  status: MemberStatus;
+  createdAt: string;
+}
+
+/**
+ * Every membership mutation bumps the workspace authz epoch (DB trigger), which
+ * invalidates ALL live sessions — including the caller's. Mutations therefore
+ * return a fresh token for the caller, minted inside the same transaction from
+ * the post-change membership row, so the acting admin is not signed out.
+ */
+export interface MemberMutationResult {
+  member: Member | null;
+  token: string | null;
+}
+
+export interface TeamActor {
+  userId: string;
+  role: string;
+}
+
+const OWNER = "Owner";
+
+interface MemberRow {
+  id: string;
+  user_id: string;
+  username: string;
+  email: string | null;
+  display_name: string;
+  role: string;
+  status: MemberStatus;
+  created_at: Date;
+}
+
+function memberFromRow(row: MemberRow): Member {
+  return {
+    id: row.id,
+    userId: row.user_id,
+    username: row.username,
+    email: row.email,
+    displayName: row.display_name,
+    role: row.role,
+    status: row.status,
+    createdAt: new Date(row.created_at).toISOString(),
+  };
+}
+
+const MEMBER_SELECT = `SELECT m.id, m.user_id, u.username, u.email, u.display_name, m.role, m.status, m.created_at
+  FROM memberships m JOIN users u ON u.id = m.user_id`;
+
+/** Placeholder username derived from the invite email's local-part, with a uniqueness fallback. */
+function usernameFromEmail(email: string): string {
+  return (email.split("@")[0] ?? "member").toLowerCase().replace(/[^a-z0-9_.-]/g, "").slice(0, 32) || "member";
+}
+
+@Injectable()
+export class TeamService {
+  async list(workspaceId: string): Promise<Member[]> {
+    const res = await withTenant(workspaceId, (client) => client.query(`${MEMBER_SELECT} ORDER BY m.created_at ASC`));
+    return (res.rows as MemberRow[]).map(memberFromRow);
+  }
+
+  async roles(): Promise<string[]> {
+    // role_permissions is global reference data (no RLS).
+    const res = await pool.query("SELECT DISTINCT role FROM role_permissions ORDER BY role");
+    return (res.rows as Array<{ role: string }>).map((r) => r.role);
+  }
+
+  async invite(workspaceId: string, actor: TeamActor, email: string, role: string): Promise<MemberMutationResult> {
+    const result = await withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      await this.assertRoleExists(client, role);
+      const actorRole = await this.actorRole(client, workspaceId, actor.userId);
+      if (role === OWNER && actorRole !== OWNER) throw new ForbiddenException("only an Owner can invite another Owner");
+
+      const existing = await client.query("SELECT id FROM users WHERE lower(email) = $1 ORDER BY created_at ASC LIMIT 1", [email]);
+      let userId = existing.rows[0]?.id as string | undefined;
+      if (userId === undefined) {
+        const base = usernameFromEmail(email);
+        const displayName = email.split("@")[0] ?? email;
+        for (let attempt = 0; userId === undefined && attempt < 3; attempt += 1) {
+          const username = attempt === 0 ? base : `${base}_${randomBytes(2).toString("hex")}`;
+          const created = await client.query(
+            `INSERT INTO users (external_id, username, email, display_name) VALUES ($1, $2, $3, $4)
+             ON CONFLICT (username) DO NOTHING
+             RETURNING id`,
+            [localExternalId(email), username, email, displayName],
+          );
+          userId = created.rows[0]?.id as string | undefined;
+        }
+        if (userId === undefined) throw new ConflictException("could not derive a username for this invite");
+      }
+      const inserted = await client.query(
+        `INSERT INTO memberships (workspace_id, user_id, role, status) VALUES ($1, $2, $3, 'invited')
+         ON CONFLICT (workspace_id, user_id) DO NOTHING RETURNING id`,
+        [workspaceId, userId, role],
+      );
+      const membershipId = inserted.rows[0]?.id as string | undefined;
+      if (membershipId === undefined) throw new ConflictException(`${email} is already a member of this workspace`);
+      return {
+        member: await this.memberById(client, membershipId),
+        token: await issueSessionInTenant(client, workspaceId, actor.userId),
+      };
+    });
+    await appendTenantAudit(workspaceId, {
+      actorUserId: actor.userId,
+      actorRole: actor.role,
+      action: "membership.invited",
+      targetType: "membership",
+      targetId: result.member.id,
+      diff: { email, role },
+    });
+    return result;
+  }
+
+  async changeRole(workspaceId: string, actor: TeamActor, membershipId: string, role: string): Promise<MemberMutationResult> {
+    const result = await withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      await this.assertRoleExists(client, role);
+      const target = await this.memberById(client, membershipId, true);
+      if (target.role === role) return { member: target, token: null, previous: role };
+      const actorRole = await this.actorRole(client, workspaceId, actor.userId);
+      if ((role === OWNER || target.role === OWNER) && actorRole !== OWNER) {
+        throw new ForbiddenException("only an Owner can grant or revoke the Owner role");
+      }
+      if (target.role === OWNER && target.status === "active") await this.assertNotLastOwner(client);
+      await client.query("UPDATE memberships SET role = $2 WHERE id = $1", [membershipId, role]);
+      return {
+        member: await this.memberById(client, membershipId),
+        token: await issueSessionInTenant(client, workspaceId, actor.userId),
+        previous: target.role,
+      };
+    });
+    if (result.previous !== role) {
+      await appendTenantAudit(workspaceId, {
+        actorUserId: actor.userId,
+        actorRole: actor.role,
+        action: "membership.role_changed",
+        targetType: "membership",
+        targetId: membershipId,
+        diff: { email: result.member.email, role: [result.previous, role] },
+      });
+    }
+    return { member: result.member, token: result.token };
+  }
+
+  async remove(workspaceId: string, actor: TeamActor, membershipId: string): Promise<MemberMutationResult> {
+    const removed = await withTenant(workspaceId, async (client) => {
+      await client.query("SELECT id FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+      const target = await this.memberById(client, membershipId, true);
+      const actorRole = await this.actorRole(client, workspaceId, actor.userId);
+      if (target.role === OWNER) {
+        if (actorRole !== OWNER) throw new ForbiddenException("only an Owner can remove an Owner");
+        if (target.status === "active") await this.assertNotLastOwner(client);
+      }
+      await client.query("DELETE FROM memberships WHERE id = $1", [membershipId]);
+      // Removing yourself ends your access: no replacement token.
+      const token = target.userId === actor.userId ? null : await issueSessionInTenant(client, workspaceId, actor.userId);
+      return { target, token };
+    });
+    await appendTenantAudit(workspaceId, {
+      actorUserId: actor.userId,
+      actorRole: actor.role,
+      action: "membership.removed",
+      targetType: "membership",
+      targetId: membershipId,
+      diff: { email: removed.target.email, role: removed.target.role },
+    });
+    return { member: null, token: removed.token };
+  }
+
+  private async memberById(client: PoolClient, membershipId: string, lock = false): Promise<Member> {
+    const res = await client.query(`${MEMBER_SELECT} WHERE m.id = $1${lock ? " FOR UPDATE OF m" : ""}`, [membershipId]);
+    const row = res.rows[0] as MemberRow | undefined;
+    if (row === undefined) throw new NotFoundException(`member ${membershipId} not found`);
+    return memberFromRow(row);
+  }
+
+  private async actorRole(client: PoolClient, workspaceId: string, userId: string): Promise<string> {
+    const res = await client.query(
+      "SELECT role FROM memberships WHERE workspace_id = $1 AND user_id = $2 AND status = 'active'",
+      [workspaceId, userId],
+    );
+    const role = res.rows[0]?.role as string | undefined;
+    if (role === undefined) throw new ForbiddenException("no active membership in this workspace");
+    return role;
+  }
+
+  private async assertRoleExists(client: PoolClient, role: string): Promise<void> {
+    const res = await client.query("SELECT 1 FROM role_permissions WHERE role = $1 LIMIT 1", [role]);
+    if (res.rowCount === 0) throw new BadRequestException(`unknown role: ${role}`);
+  }
+
+  private async assertNotLastOwner(client: PoolClient): Promise<void> {
+    // Lock every Owner row so two concurrent demotions cannot both pass the check.
+    const res = await client.query(`SELECT id FROM memberships WHERE role = $1 AND status = 'active' FOR UPDATE`, [OWNER]);
+    if ((res.rowCount ?? 0) <= 1) throw new BadRequestException("a workspace must keep at least one active Owner");
+  }
+}
diff --git a/apps/api/src/telemetry/logger.test.ts b/apps/api/src/telemetry/logger.test.ts
new file mode 100644
index 0000000..be25ab8
--- /dev/null
+++ b/apps/api/src/telemetry/logger.test.ts
@@ -0,0 +1,15 @@
+import { expect, it } from "vitest";
+import { createApiLogger } from "./logger.js";
+
+it("redacts bot/OAuth secrets and callback/request data before serializing API logs", () => {
+  const lines: string[] = [];
+  const log = createApiLogger({ write: (line) => { lines.push(line); } });
+  log.info({
+    token: "bot-value", client_secret: "client-value", access_token: "access-value", refresh_token: "refresh-value", code_verifier: "pkce-value",
+    data: { botToken: "nested-bot", access_token: "nested-access" },
+    req: { headers: { authorization: "Bearer session-value", cookie: "cookie-value" }, body: { token: "body-token" }, query: { code: "code-value" }, url: "/connections/callback?code=url-code" },
+  }, "safe event");
+  const output = lines.join("");
+  expect(output).toContain("safe event");
+  for (const secret of ["bot-value", "client-value", "access-value", "refresh-value", "pkce-value", "nested-bot", "nested-access", "session-value", "cookie-value", "body-token", "code-value", "url-code"]) expect(output).not.toContain(secret);
+});
diff --git a/apps/api/src/telemetry/logger.ts b/apps/api/src/telemetry/logger.ts
new file mode 100644
index 0000000..4e9313e
--- /dev/null
+++ b/apps/api/src/telemetry/logger.ts
@@ -0,0 +1,19 @@
+import pino, { type DestinationStream } from "pino";
+
+export function createApiLogger(destination?: DestinationStream) {
+  const options = {
+    level: process.env.LOG_LEVEL ?? "info",
+    redact: {
+      paths: [
+        "accessToken", "refreshToken", "apiKey", "streamKey",
+        "*.accessToken", "*.refreshToken", "*.apiKey", "*.streamKey",
+        "token", "botToken", "clientSecret", "client_secret", "access_token", "refresh_token", "code_verifier",
+        "*.token", "*.botToken", "*.clientSecret", "*.client_secret", "*.access_token", "*.refresh_token", "*.code_verifier",
+        "req.headers.authorization", "req.headers.cookie", "req.body", "req.query", "req.url",
+      ],
+      censor: "[REDACTED]",
+    },
+  };
+  return destination ? pino(options, destination) : pino(options);
+}
+export const logger = createApiLogger();
diff --git a/apps/api/src/telemetry/otel.ts b/apps/api/src/telemetry/otel.ts
new file mode 100644
index 0000000..d632c2b
--- /dev/null
+++ b/apps/api/src/telemetry/otel.ts
@@ -0,0 +1,41 @@
+import { logger } from "./logger";
+
+interface OtelModule {
+  start(): void;
+}
+
+export function startOtel(): void {
+  const endpoint = process.env.OTEL_EXPORTER_OTLP_ENDPOINT;
+  if (!endpoint) {
+    logger.info("otel: no OTEL_EXPORTER_OTLP_ENDPOINT — tracing disabled");
+    return;
+  }
+  void (async () => {
+    try {
+      const { NodeSDK } = await import("@opentelemetry/sdk-node");
+      const { getNodeAutoInstrumentations } = await import("@opentelemetry/auto-instrumentations-node");
+      const { OTLPTraceExporter } = await import("@opentelemetry/exporter-trace-otlp-http");
+      const sdk: OtelModule = new NodeSDK({
+        traceExporter: new OTLPTraceExporter({ url: `${endpoint}/v1/traces` }),
+        instrumentations: [getNodeAutoInstrumentations({
+          // Bot API paths contain credentials; OAuth callback query strings and
+          // invite-link paths contain join tokens.
+          "@opentelemetry/instrumentation-http": {
+            ignoreIncomingRequestHook: (request) => {
+              const url = request.url ?? "";
+              return url.startsWith("/connections/callback") || url.startsWith("/invites/");
+            },
+            ignoreOutgoingRequestHook: (request) => /\/bot[^/]+\//.test(request.path ?? ""),
+          },
+          "@opentelemetry/instrumentation-undici": { enabled: false },
+        })],
+      }) as unknown as OtelModule;
+      sdk.start();
+      logger.info({ endpoint }, "otel: tracing enabled");
+    } catch (err) {
+      logger.warn({ err: String(err) }, "otel: failed to initialize — continuing without tracing");
+    }
+  })();
+}
+
+startOtel();
diff --git a/apps/api/src/vault/vault.test.ts b/apps/api/src/vault/vault.test.ts
new file mode 100644
index 0000000..9b94345
--- /dev/null
+++ b/apps/api/src/vault/vault.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { Vault } from "./vault.js";
+
+describe("vault envelope encryption", () => {
+  it("persistent envelopes survive restarts and reject cross-workspace/handle use and tampering", async () => {
+    const sealed = await new Vault().seal("ws-a", "vh-a", Buffer.from("persistent-token"));
+    expect(sealed.ciphertext.includes("persistent-token")).toBe(false);
+    expect((await new Vault().open("ws-a", "vh-a", sealed)).toString()).toBe("persistent-token");
+    await expect(new Vault().open("ws-b", "vh-a", sealed)).rejects.toThrow();
+    await expect(new Vault().open("ws-a", "vh-b", sealed)).rejects.toThrow();
+    const tampered = Buffer.from(sealed.ciphertext);
+    tampered[tampered.length - 1] = (tampered[tampered.length - 1] ?? 0) ^ 1;
+    await expect(new Vault().open("ws-a", "vh-a", { ...sealed, ciphertext: tampered })).rejects.toThrow();
+  });
+  it("round-trips a secret", async () => {
+    const v = new Vault();
+    const sealed = await v.put("ws-1", "cred-1", Buffer.from("access-token-abc"));
+    const opened = await v.get("ws-1", "cred-1", sealed);
+    expect(opened.toString()).toBe("access-token-abc");
+  });
+
+  it("ciphertext is not plaintext", async () => {
+    const v = new Vault();
+    const sealed = await v.put("ws-1", "cred-1", Buffer.from("access-token-abc"));
+    expect(sealed.ciphertext.includes("access-token-abc")).toBe(false);
+  });
+
+  it("rotation invalidates pre-rotation ciphertext (old DEK dropped)", async () => {
+    const v = new Vault();
+    const before = await v.put("ws-1", "cred-1", Buffer.from("secret-1"));
+    const rotated = await v.rotate("ws-1", [{ credentialId: "cred-1", plaintext: Buffer.from("secret-1") }]);
+    const rewrapped = rotated.get("cred-1");
+    expect(rewrapped).toBeDefined();
+    if (rewrapped === undefined) return;
+    expect(rewrapped.keyVersion).toBeGreaterThan(before.keyVersion);
+    // the OLD sealed blob must no longer decrypt (its DEK is gone)
+    await expect(v.get("ws-1", "cred-1", before)).rejects.toThrow();
+    // the NEW blob decrypts
+    const opened = await v.get("ws-1", "cred-1", rewrapped);
+    expect(opened.toString()).toBe("secret-1");
+  });
+});
diff --git a/apps/api/src/vault/vault.ts b/apps/api/src/vault/vault.ts
new file mode 100644
index 0000000..58447be
--- /dev/null
+++ b/apps/api/src/vault/vault.ts
@@ -0,0 +1 @@
+export { Vault, vault, loadKek, type SealedCredential } from "@tactical-media-broadcast-hub/connector-runtime";
diff --git a/apps/api/src/video/ffprobe.test.ts b/apps/api/src/video/ffprobe.test.ts
new file mode 100644
index 0000000..fd75412
--- /dev/null
+++ b/apps/api/src/video/ffprobe.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { buildFfprobeArgs, parseFfprobeOutput } from "./ffprobe.js";
+
+describe("ffprobe invocation", () => {
+  it("rejects containers without a video stream", () => {
+    expect(() => parseFfprobeOutput(JSON.stringify({ streams: [{ codec_type: "audio" }] }))).toThrow("no video stream");
+  });
+  it("keeps an injection-shaped input in one argv element", () => {
+    const input = "/videos/example.mp4; touch /tmp/should-not-exist";
+    const args = buildFfprobeArgs(input);
+
+    expect(args.at(-1)).toBe(input);
+    expect(args.at(-2)).toBe("-i");
+    expect(args).not.toContain("sh");
+    expect(args).not.toContain("-c");
+  });
+
+  it("extracts video and audio metadata from JSON", () => {
+    const result = parseFfprobeOutput(JSON.stringify({
+      streams: [
+        {
+          codec_type: "video",
+          codec_name: "h264",
+          width: 1920,
+          height: 1080,
+          avg_frame_rate: "30000/1001",
+        },
+        { codec_type: "audio", codec_name: "aac" },
+      ],
+      format: { duration: "12.345" },
+    }));
+
+    expect(result).toEqual({
+      width: 1920,
+      height: 1080,
+      durationMs: 12_345,
+      frameRate: 30000 / 1001,
+      codec: "h264",
+      audioCodec: "aac",
+    });
+  });
+});
diff --git a/apps/api/src/video/ffprobe.ts b/apps/api/src/video/ffprobe.ts
new file mode 100644
index 0000000..4cc6e16
--- /dev/null
+++ b/apps/api/src/video/ffprobe.ts
@@ -0,0 +1,159 @@
+import { spawn } from "node:child_process";
+
+const FFPROBE_TIMEOUT_MS = 30_000;
+const MAX_OUTPUT_BYTES = 10 * 1024 * 1024;
+
+export interface VideoProbeResult {
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  frameRate?: number;
+  codec?: string;
+  audioCodec?: string;
+}
+
+/**
+ * Keep the input as a discrete argv value. `-i` ensures even a path beginning
+ * with a dash is treated as input rather than another ffprobe option.
+ */
+export function buildFfprobeArgs(inputPath: string): string[] {
+  return [
+    "-v",
+    "error",
+    "-print_format",
+    "json",
+    "-show_format",
+    "-show_streams",
+    "-i",
+    inputPath,
+  ];
+}
+
+export async function probeVideoFile(
+  inputPath: string,
+  executable = process.env.FFPROBE_PATH ?? "ffprobe",
+): Promise<VideoProbeResult> {
+  if (inputPath.length === 0) throw new Error("ffprobe input path must not be empty");
+
+  const output = await new Promise<string>((resolve, reject) => {
+    const child = spawn(executable, buildFfprobeArgs(inputPath), {
+      shell: false,
+      windowsHide: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+    const stdout: Buffer[] = [];
+    const stderr: Buffer[] = [];
+    let outputBytes = 0;
+    let settled = false;
+
+    const finish = (error: Error | undefined, value?: string): void => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      if (error === undefined) resolve(value ?? "");
+      else reject(error);
+    };
+
+    const timeout = setTimeout(() => {
+      child.kill("SIGKILL");
+      finish(new Error(`ffprobe timed out after ${FFPROBE_TIMEOUT_MS}ms`));
+    }, FFPROBE_TIMEOUT_MS);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      outputBytes += chunk.length;
+      if (outputBytes > MAX_OUTPUT_BYTES) {
+        child.kill("SIGKILL");
+        finish(new Error("ffprobe output exceeded the 10 MiB limit"));
+        return;
+      }
+      stdout.push(chunk);
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      if (Buffer.concat(stderr).length < 16_384) stderr.push(chunk);
+    });
+    child.once("error", (error) => finish(error));
+    child.once("close", (code, signal) => {
+      if (code !== 0) {
+        const detail = Buffer.concat(stderr).toString("utf8").trim();
+        finish(
+          new Error(
+            `ffprobe failed (${signal === null ? `exit ${String(code)}` : `signal ${signal}`})${
+              detail === "" ? "" : `: ${detail}`
+            }`,
+          ),
+        );
+        return;
+      }
+      finish(undefined, Buffer.concat(stdout).toString("utf8"));
+    });
+  });
+
+  return parseFfprobeOutput(output);
+}
+
+export function parseFfprobeOutput(output: string): VideoProbeResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(output) as unknown;
+  } catch {
+    throw new Error("ffprobe returned invalid JSON");
+  }
+  const root = asRecord(parsed);
+  if (root === undefined) throw new Error("ffprobe returned an invalid result");
+  const streams = Array.isArray(root.streams)
+    ? root.streams.map(asRecord).filter((stream): stream is Record<string, unknown> => stream !== undefined)
+    : [];
+  const format = asRecord(root.format);
+  const video = streams.find((stream) => stream.codec_type === "video");
+  if (video === undefined) throw new Error("ffprobe found no video stream");
+  const audio = streams.find((stream) => stream.codec_type === "audio");
+  const durationSeconds = finiteNumber(format?.duration) ?? finiteNumber(video?.duration);
+  const frameRate = rationalNumber(video?.avg_frame_rate) ?? rationalNumber(video?.r_frame_rate);
+
+  return {
+    ...optionalNumber("width", finiteInteger(video?.width)),
+    ...optionalNumber("height", finiteInteger(video?.height)),
+    ...optionalNumber(
+      "durationMs",
+      durationSeconds === undefined ? undefined : Math.max(0, Math.round(durationSeconds * 1000)),
+    ),
+    ...optionalNumber("frameRate", frameRate),
+    ...optionalString("codec", video?.codec_name),
+    ...optionalString("audioCodec", audio?.codec_name),
+  };
+}
+
+function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+  return value as Record<string, unknown>;
+}
+
+function finiteNumber(value: unknown): number | undefined {
+  const number = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  return Number.isFinite(number) ? number : undefined;
+}
+
+function finiteInteger(value: unknown): number | undefined {
+  const number = finiteNumber(value);
+  return number !== undefined && Number.isInteger(number) ? number : undefined;
+}
+
+function rationalNumber(value: unknown): number | undefined {
+  if (typeof value !== "string") return finiteNumber(value);
+  const [numeratorText, denominatorText, extra] = value.split("/");
+  if (extra !== undefined || numeratorText === undefined || denominatorText === undefined) {
+    return finiteNumber(value);
+  }
+  const numerator = Number(numeratorText);
+  const denominator = Number(denominatorText);
+  if (!Number.isFinite(numerator) || !Number.isFinite(denominator) || denominator === 0) return undefined;
+  return numerator / denominator;
+}
+
+function optionalNumber<K extends string>(key: K, value: number | undefined): Partial<Record<K, number>> {
+  return value === undefined ? {} : { [key]: value } as Record<K, number>;
+}
+
+function optionalString<K extends string>(key: K, value: unknown): Partial<Record<K, string>> {
+  return typeof value !== "string" || value === "" ? {} : { [key]: value } as Record<K, string>;
+}
diff --git a/apps/api/src/video/test-fixtures.ts b/apps/api/src/video/test-fixtures.ts
new file mode 100644
index 0000000..63bdc2a
--- /dev/null
+++ b/apps/api/src/video/test-fixtures.ts
@@ -0,0 +1,156 @@
+import { keyForHash, sha256, type StorageService } from "../storage/storage.js";
+import type { PoolClient, QueryResult } from "pg";
+import { vi } from "vitest";
+import {
+  VideoService,
+  type VideoServiceDependencies,
+} from "./video.service.js";
+
+export const workspaceId = "10000000-0000-4000-8000-000000000001";
+export const assetId = "20000000-0000-4000-8000-000000000002";
+export const jobId = "30000000-0000-4000-8000-000000000003";
+
+export interface FakeVideoDatabase {
+  asset?: Record<string, unknown>;
+  job?: Record<string, unknown>;
+  transitions?: string[];
+}
+
+function result(rows: Array<Record<string, unknown>>): QueryResult<Record<string, unknown>> {
+  return { command: "", rowCount: rows.length, oid: 0, fields: [], rows };
+}
+
+export function serviceWithDatabase(
+  database: FakeVideoDatabase,
+  probe: VideoServiceDependencies["probe"],
+  storageOverride?: StorageService,
+): { service: VideoService; appendAudit: VideoServiceDependencies["appendAudit"]; storage: StorageService; objects: Map<string, Buffer> } {
+  const objects = new Map<string, Buffer>();
+  const storage: StorageService = storageOverride ?? {
+    putContent: vi.fn(async (bytes: Buffer, contentType: string) => {
+      const hash = sha256(bytes);
+      const key = keyForHash(hash, contentType);
+      const deduplicated = objects.has(key);
+      objects.set(key, Buffer.from(bytes));
+      return { key, hash, sizeBytes: bytes.length, contentType, deduplicated };
+    }),
+    getObject: vi.fn(async (key: string) => {
+      const bytes = objects.get(key);
+      if (bytes === undefined) throw new Error("Object not found");
+      return Buffer.from(bytes);
+    }),
+    hasContent: async (hash, type) => objects.has(keyForHash(hash, type)),
+    presign: async () => { throw new Error("Encrypted source must be decrypted before probing"); },
+  };
+  database.transitions = [];
+  const client = {
+    async query(sql: string, values: readonly unknown[] = []): Promise<QueryResult<Record<string, unknown>>> {
+      if (sql.includes("INSERT INTO video_assets")) {
+        database.asset = {
+          id: assetId,
+          workspace_id: values[0],
+          storage_key: values[1],
+          mime_type: values[2],
+          size_bytes: values[3],
+          width: null,
+          height: null,
+          duration_ms: null,
+          frame_rate: null,
+          codec: null,
+          audio_codec: null,
+          thumbnail_key: null,
+          created_at: new Date("2026-10-07T00:00:00Z"),
+        };
+        return result([database.asset]);
+      }
+      if (sql.includes("INSERT INTO video_processing_jobs")) {
+        database.job = {
+          id: jobId,
+          workspace_id: values[0],
+          video_asset_id: values[1],
+          state: "queued",
+          progress_percent: 0,
+          output_key: null,
+          error: null,
+        };
+        database.transitions?.push("queued");
+        return result([database.job]);
+      }
+      if (sql === "SELECT * FROM video_assets WHERE id = $1") {
+        return result(database.asset === undefined ? [] : [database.asset]);
+      }
+      if (sql.includes("SET state = 'probing'")) {
+        if (database.job?.state !== "queued") return result([]);
+        database.job.state = "probing";
+        database.transitions?.push("probing");
+        database.job.progress_percent = 10;
+        database.job.error = null;
+        return result([{ id: jobId }]);
+      }
+      if (sql.includes("SET state = 'failed'")) {
+        if (database.job !== undefined) {
+          database.job.state = "failed";
+          database.transitions?.push("failed");
+          database.job.error = values[1];
+        }
+        return result([{ id: jobId }]);
+      }
+      if (sql.includes("UPDATE video_assets")) {
+        if (database.asset === undefined) return result([]);
+        database.asset.width = values[1];
+        database.asset.height = values[2];
+        database.asset.duration_ms = values[3];
+        database.asset.frame_rate = values[4];
+        database.asset.codec = values[5];
+        database.asset.audio_codec = values[6];
+        return result([database.asset]);
+      }
+      if (sql.includes("SET state = 'transcoding'")) {
+        if (database.job?.state !== "probing") return result([]);
+        database.job.state = "transcoding";
+        database.transitions?.push("transcoding");
+        database.job.progress_percent = 90;
+        return result([{ id: jobId }]);
+      }
+      if (sql.includes("SET state = 'complete'")) {
+        if (database.job?.state !== "transcoding") return result([]);
+        database.job.state = "complete";
+        database.transitions?.push("complete");
+        database.job.output_key = values[1];
+        database.job.progress_percent = 100;
+        database.job.error = null;
+        return result([{ id: jobId }]);
+      }
+      if (sql.includes("SELECT state FROM video_processing_jobs")) {
+        return result(database.job === undefined ? [] : [{ state: database.job.state }]);
+      }
+      if (sql.includes("SELECT va.*")) {
+        if (database.asset === undefined) return result([]);
+        return result([{
+          ...database.asset,
+          job_id: database.job?.id,
+          job_video_asset_id: database.job?.video_asset_id,
+          job_state: database.job?.state,
+          job_progress_percent: database.job?.progress_percent,
+          job_output_key: database.job?.output_key,
+          job_error: database.job?.error,
+        }]);
+      }
+      if (sql.includes("DELETE FROM video_assets")) {
+        if (database.asset === undefined) return result([]);
+        delete database.asset;
+        delete database.job;
+        return result([{ id: assetId }]);
+      }
+      throw new Error(`unexpected SQL in fake video database: ${sql}`);
+    },
+  };
+  const appendAudit = vi.fn(async () => "audit-id");
+  const dependencies: VideoServiceDependencies = {
+    tenantTransaction: async (_tenant, fn) => fn(client as unknown as PoolClient),
+    appendAudit,
+    probe,
+    storage,
+  };
+  return { service: new VideoService(dependencies), appendAudit, storage, objects };
+}
diff --git a/apps/api/src/video/upload-limits.ts b/apps/api/src/video/upload-limits.ts
new file mode 100644
index 0000000..5f79e64
--- /dev/null
+++ b/apps/api/src/video/upload-limits.ts
@@ -0,0 +1,2 @@
+// StorageService seals whole Buffers; bound multipart memory use per request.
+export const MAX_VIDEO_UPLOAD_BYTES = 100 * 1024 * 1024;
diff --git a/apps/api/src/video/video.controller.ts b/apps/api/src/video/video.controller.ts
new file mode 100644
index 0000000..1a6b2f0
--- /dev/null
+++ b/apps/api/src/video/video.controller.ts
@@ -0,0 +1,103 @@
+import {
+  BadRequestException,
+  Body,
+  Controller,
+  Delete,
+  Get,
+  Inject,
+  Param,
+  Post,
+  Query,
+  Req,
+  UseGuards,
+  UseInterceptors,
+  UploadedFile,
+} from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
+import type { Request } from "express";
+import { parseId, parseLimit, requireObject, requireSession, requireString } from "../http/validation.js";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import {
+  VideoService,
+  type VideoLibraryPage,
+  type VideoStatus,
+  type VideoUploadResult,
+} from "./video.service.js";
+import { MAX_VIDEO_UPLOAD_BYTES } from "./upload-limits.js";
+
+interface VideoFile {
+  buffer: Buffer;
+  mimetype: string;
+}
+
+interface UploadVideoDto {
+  storageKey: string;
+  mimeType: string;
+  sizeBytes: number;
+}
+
+@Controller("video")
+@UseGuards(RbacGuard)
+export class VideoController {
+  constructor(@Inject(VideoService) private readonly video: VideoService) {}
+
+  @Post("upload")
+  @RequirePermission("media.manage")
+  @UseInterceptors(FileInterceptor("file", {
+    limits: { fileSize: MAX_VIDEO_UPLOAD_BYTES, files: 1, fields: 3, fieldSize: 1024, parts: 4 },
+  }))
+  async upload(
+    @Req() request: Request & AuthenticatedRequest,
+    @Body() body: unknown,
+    @UploadedFile() file?: VideoFile,
+  ): Promise<VideoUploadResult> {
+    const session = requireSession(request);
+    if (file !== undefined) {
+      return this.video.uploadVideoBytes(session.workspaceId, file.buffer, file.mimetype);
+    }
+    if (request.is("multipart/form-data")) throw new BadRequestException("a video file is required (field: file)");
+    const dto = parseUploadVideo(body);
+    return this.video.uploadVideo(session.workspaceId, dto.storageKey, dto.mimeType, dto.sizeBytes);
+  }
+
+  @Get()
+  @RequirePermission("media.view")
+  async list(
+    @Req() request: Request & AuthenticatedRequest,
+    @Query("cursor") cursor: string | undefined,
+    @Query("limit") limit: string | undefined,
+  ): Promise<VideoLibraryPage> {
+    return this.video.listVideos(requireSession(request).workspaceId, cursor, parseLimit(limit, 50, 200));
+  }
+
+  @Get(":id/status")
+  @RequirePermission("media.view")
+  async status(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+  ): Promise<VideoStatus> {
+    return this.video.getVideoStatus(parseId(id), requireSession(request).workspaceId);
+  }
+
+  @Delete(":id")
+  @RequirePermission("media.manage")
+  async remove(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+  ): Promise<void> {
+    await this.video.deleteVideo(parseId(id), requireSession(request).workspaceId);
+  }
+}
+
+function parseUploadVideo(value: unknown): UploadVideoDto {
+  const body = requireObject(value, "body");
+  const sizeBytes = body.sizeBytes;
+  if (typeof sizeBytes !== "number" || !Number.isSafeInteger(sizeBytes) || sizeBytes < 1) {
+    throw new BadRequestException("sizeBytes must be a positive safe integer");
+  }
+  return {
+    storageKey: requireString(body.storageKey, "storageKey"),
+    mimeType: requireString(body.mimeType, "mimeType"),
+    sizeBytes,
+  };
+}
diff --git a/apps/api/src/video/video.http.test.ts b/apps/api/src/video/video.http.test.ts
new file mode 100644
index 0000000..cafa1ab
--- /dev/null
+++ b/apps/api/src/video/video.http.test.ts
@@ -0,0 +1,124 @@
+import "reflect-metadata";
+import { readFile } from "node:fs/promises";
+import { Module, UnauthorizedException, ForbiddenException, type ExecutionContext, type INestApplication } from "@nestjs/common";
+import { NestFactory, Reflector } from "@nestjs/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { injectHttp } from "../connections/http-test-transport.js";
+import { RbacGuard, PERMISSION_KEY } from "../rbac/rbac.guard.js";
+import { VideoController } from "./video.controller.js";
+import { VideoService, type VideoStatus } from "./video.service.js";
+import { serviceWithDatabase, workspaceId, type FakeVideoDatabase } from "./test-fixtures.js";
+
+@Module({})
+class TestModule {}
+
+describe("video multipart HTTP routes", () => {
+  let app: INestApplication | undefined;
+  let canManage = true;
+
+  beforeEach(() => {
+    canManage = true;
+    vi.spyOn(RbacGuard.prototype, "canActivate").mockImplementation(async (context: ExecutionContext) => {
+      const request = context.switchToHttp().getRequest<{ headers: Record<string, string>; session?: { workspaceId: string } }>();
+      if (request.headers.authorization !== "Bearer test-session") throw new UnauthorizedException();
+      if (!canManage && new Reflector().get<string>(PERMISSION_KEY, context.getHandler()) === "media.manage") {
+        throw new ForbiddenException("missing permission: media.manage");
+      }
+      request.session = { workspaceId };
+      return true;
+    });
+  });
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+    vi.restoreAllMocks();
+    vi.unstubAllEnvs();
+  });
+
+  async function start(service: VideoService): Promise<void> {
+    app = await NestFactory.create({
+      module: TestModule,
+      controllers: [VideoController],
+      providers: [{ provide: VideoService, useValue: service }],
+    }, { logger: false });
+    await app.init();
+  }
+
+  async function upload(form: FormData, authenticated = true): Promise<Response> {
+    const encoded = new Request("http://api.test/video/upload", { method: "POST", body: form });
+    // ASCII fixture bytes preserve their exact value in the existing HTTP injector.
+    return injectHttp(app?.getHttpAdapter().getInstance(), encoded.url, {
+      method: "POST",
+      headers: {
+        ...(authenticated ? { authorization: "Bearer test-session" } : {}),
+        "content-type": encoded.headers.get("content-type") ?? "",
+      },
+      body: Buffer.from(await encoded.arrayBuffer()).toString("utf8"),
+    });
+  }
+
+  function videoForm(): FormData {
+    const form = new FormData();
+    form.append("file", new Blob(["video bytes from browser"], { type: "video/mp4" }), "example.mp4");
+    return form;
+  }
+
+  it("accepts FormData bytes and returns completed probe metadata through GET status", async () => {
+    const probe = vi.fn(async (path: string) => {
+      expect(await readFile(path, "utf8")).toBe("video bytes from browser");
+      return { durationMs: 1000, width: 320, height: 180, frameRate: 25, codec: "h264" };
+    });
+    const { service } = serviceWithDatabase({}, probe);
+    await start(service);
+    const response = await upload(videoForm());
+    expect(response.status).toBe(201);
+    const result = await response.json() as VideoStatus;
+    expect(result.processingJob.state).toBe("complete");
+    expect(result.videoAsset).toMatchObject({ durationMs: 1000, width: 320, height: 180 });
+    const status = await injectHttp(app?.getHttpAdapter().getInstance(), `http://api.test/video/${result.videoAsset.id}/status`, {
+      headers: { authorization: "Bearer test-session" },
+    });
+    expect(status.status).toBe(200);
+    expect(await status.json()).toEqual(result);
+  });
+
+  it("surfaces ffprobe failure through upload and status", async () => {
+    const { service } = serviceWithDatabase({}, async () => { throw new Error("ffprobe rejected media"); });
+    await start(service);
+    const response = await upload(videoForm());
+    expect(response.status).toBe(201);
+    expect((await response.json() as VideoStatus).processingJob).toMatchObject({ state: "failed", error: "ffprobe rejected media" });
+  });
+
+  it("returns HTTP 503 with real unconfigured storage, without touching the DB", async () => {
+    vi.stubEnv("S3_ACCESS_KEY", "");
+    vi.stubEnv("S3_SECRET_KEY", "");
+    const transaction = vi.fn();
+    await start(new VideoService({ tenantTransaction: transaction }));
+    const response = await upload(videoForm());
+    expect(response.status).toBe(503);
+    expect(await response.json()).toMatchObject({ message: expect.stringContaining("Video storage is not configured") });
+    expect(transaction).not.toHaveBeenCalled();
+  });
+
+  it("rejects missing files, non-video MIME, multiple files, and unauthorized uploads", async () => {
+    const database: FakeVideoDatabase = {};
+    const { service, storage } = serviceWithDatabase(database, async () => ({}));
+    await start(service);
+    const empty = new FormData();
+    empty.append("mimeType", "video/mp4");
+    expect((await upload(empty)).status).toBe(400);
+    const image = new FormData();
+    image.append("file", new Blob(["image"], { type: "image/png" }), "example.png");
+    expect((await upload(image)).status).toBe(400);
+    const multiple = videoForm();
+    multiple.append("file", new Blob(["second"], { type: "video/mp4" }), "second.mp4");
+    expect((await upload(multiple)).status).toBe(400);
+    expect((await upload(videoForm(), false)).status).toBe(401);
+    canManage = false;
+    expect((await upload(videoForm())).status).toBe(403);
+    expect(storage.putContent).not.toHaveBeenCalled();
+    expect(database.asset).toBeUndefined();
+  });
+});
diff --git a/apps/api/src/video/video.integration.test.ts b/apps/api/src/video/video.integration.test.ts
new file mode 100644
index 0000000..37e8611
--- /dev/null
+++ b/apps/api/src/video/video.integration.test.ts
@@ -0,0 +1,129 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+import { sha256, keyForHash, type StorageService } from "../storage/storage.js";
+import { VideoService, type VideoServiceDependencies } from "./video.service.js";
+
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+const appPool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+async function asTenant<T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await appPool.connect();
+  try {
+    await client.query("BEGIN");
+    await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const value = await fn(client);
+    await client.query("COMMIT");
+    return value;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+describe.skipIf(!dbAvailable)("video library (live DB)", () => {
+  let workspaceId: string;
+  let service: VideoService;
+  const objects = new Map<string, Buffer>();
+  const storage: StorageService = {
+    putContent: async (bytes, contentType) => {
+      const hash = sha256(bytes);
+      const key = keyForHash(hash, contentType);
+      const deduplicated = objects.has(key);
+      objects.set(key, Buffer.from(bytes));
+      return { key, hash, sizeBytes: bytes.length, contentType, deduplicated };
+    },
+    getObject: async (key) => {
+      const bytes = objects.get(key);
+      if (bytes === undefined) throw new Error("missing stored object");
+      return Buffer.from(bytes);
+    },
+    hasContent: async (hash, type) => objects.has(keyForHash(hash, type)),
+    presign: async () => "unused",
+  };
+
+  beforeAll(async () => {
+    await runMigrations(process.env.MIGRATIONS_DIR ?? join(process.cwd(), "migrations"));
+    const workspace = await ownerPool.query(
+      "INSERT INTO workspaces (name, slug) VALUES ('Video integration', $1) RETURNING id",
+      [`video-${randomUUID()}`],
+    );
+    workspaceId = String(workspace.rows[0]?.id);
+    const dependencies: VideoServiceDependencies = {
+      tenantTransaction: asTenant,
+      appendAudit: async (tenantId, event) => asTenant(tenantId, async (client) => {
+        const audit = await client.query(
+          "SELECT audit_append($1, $2, $3, $4, $5, $6, $7) AS id",
+          [
+            tenantId,
+            event.actorUserId,
+            event.actorRole,
+            event.action,
+            event.targetType,
+            event.targetId,
+            event.diff ?? null,
+          ],
+        );
+        return String(audit.rows[0]?.id);
+      }),
+      probe: async () => ({ width: 640, height: 360, durationMs: 1000, frameRate: 30, codec: "h264" }),
+      storage,
+    };
+    service = new VideoService(dependencies);
+  });
+
+  afterAll(async () => {
+    if (workspaceId !== undefined) await ownerPool.query("DELETE FROM workspaces WHERE id = $1", [workspaceId]);
+    await appPool.end();
+    await ownerPool.end();
+  });
+
+  it("uploads, pages, reads status, and deletes a tenant video", async () => {
+    const uploaded = await service.uploadVideoBytes(workspaceId, Buffer.from("integration video bytes"), "video/mp4");
+    const page = await service.listVideos(workspaceId, undefined, 20);
+    expect(page.items).toHaveLength(1);
+    expect(page.items[0]?.videoAsset.id).toBe(uploaded.videoAsset.id);
+    expect(page.items[0]?.processingState).toBe("complete");
+
+    const status = await service.getVideoStatus(uploaded.videoAsset.id, workspaceId);
+    expect(status.processingJob.state).toBe("complete");
+    expect(status.processingJob.processingNote).toContain("Transcode skipped");
+    expect(status.videoAsset).toMatchObject({ width: 640, height: 360, durationMs: 1000, codec: "h264" });
+    await expect(service.getVideoStatus(uploaded.videoAsset.id, randomUUID())).rejects.toThrow(/not found/);
+
+    await service.deleteVideo(uploaded.videoAsset.id, workspaceId);
+    await expect(service.getVideoStatus(uploaded.videoAsset.id, workspaceId)).rejects.toThrow(/not found/);
+    expect(objects.has(uploaded.videoAsset.storageKey)).toBe(true);
+    const jobs = await asTenant(workspaceId, (client) => client.query("SELECT id FROM video_processing_jobs WHERE video_asset_id = $1", [uploaded.videoAsset.id]));
+    expect(jobs.rowCount).toBe(0);
+  });
+
+  it("persists probe failure and exposes the error through status", async () => {
+    const failedService = new VideoService({
+      tenantTransaction: asTenant,
+      appendAudit: async () => "test-audit",
+      storage,
+      probe: async () => { throw new Error("ffprobe: invalid media"); },
+    });
+    const uploaded = await failedService.uploadVideoBytes(workspaceId, Buffer.from("invalid video"), "video/mp4");
+    expect((await failedService.getVideoStatus(uploaded.videoAsset.id, workspaceId)).processingJob).toMatchObject({ state: "failed", error: "ffprobe: invalid media" });
+    await failedService.deleteVideo(uploaded.videoAsset.id, workspaceId);
+  });
+
+  it("shares content-addressed bytes between assets and retains them when one asset is deleted", async () => {
+    const bytes = Buffer.from("same video twice");
+    const first = await service.uploadVideoBytes(workspaceId, bytes, "video/mp4");
+    const second = await service.uploadVideoBytes(workspaceId, bytes, "video/mp4");
+    expect(second.videoAsset.id).not.toBe(first.videoAsset.id);
+    expect(second.videoAsset.storageKey).toBe(first.videoAsset.storageKey);
+    await service.deleteVideo(first.videoAsset.id, workspaceId);
+    expect((await service.getVideoStatus(second.videoAsset.id, workspaceId)).processingJob.state).toBe("complete");
+    expect(await storage.getObject(second.videoAsset.storageKey)).toEqual(bytes);
+    await service.deleteVideo(second.videoAsset.id, workspaceId);
+  });
+});
diff --git a/apps/api/src/video/video.roundtrip.test.ts b/apps/api/src/video/video.roundtrip.test.ts
new file mode 100644
index 0000000..00e08ab
--- /dev/null
+++ b/apps/api/src/video/video.roundtrip.test.ts
@@ -0,0 +1,46 @@
+import { readFile } from "node:fs/promises";
+import { describe, expect, it } from "vitest";
+import { keyForHash, sha256, seal, open, type StorageService } from "../storage/storage.js";
+import { probeVideoFile } from "./ffprobe.js";
+import { serviceWithDatabase, workspaceId } from "./test-fixtures.js";
+
+// Opt in with a generated/real MP4; the normal suite needs no ffmpeg installation.
+const fixture = process.env.VIDEO_ROUNDTRIP_FIXTURE;
+
+describe.skipIf(fixture === undefined)("real ffprobe roundtrip (encrypted in-memory storage)", () => {
+  it("uploads actual MP4 bytes, decrypts the stored source, and persists real probe metadata", async () => {
+    if (fixture === undefined) throw new Error("VIDEO_ROUNDTRIP_FIXTURE is required");
+    const bytes = await readFile(fixture);
+    const objects = new Map<string, Buffer>();
+    const kek = Buffer.alloc(32, 7);
+    const storage: StorageService = {
+      putContent: async (source, contentType) => {
+        const hash = sha256(source);
+        const key = keyForHash(hash, contentType);
+        const deduplicated = objects.has(key);
+        if (!deduplicated) objects.set(key, seal(source, kek));
+        return { key, hash, sizeBytes: source.length, contentType, deduplicated };
+      },
+      getObject: async (key) => {
+        const encrypted = objects.get(key);
+        if (encrypted === undefined) throw new Error("missing object");
+        const source = open(encrypted, kek);
+        expect(key).toBe(keyForHash(sha256(source), "video/mp4"));
+        return source;
+      },
+      hasContent: async (hash, contentType) => objects.has(keyForHash(hash, contentType)),
+      presign: async () => { throw new Error("must decrypt, not presign"); },
+    };
+    const { service } = serviceWithDatabase({}, probeVideoFile, storage);
+    const uploaded = await service.uploadVideoBytes(workspaceId, bytes, "video/mp4");
+    const status = await service.getVideoStatus(uploaded.videoAsset.id, workspaceId);
+    expect(status.processingJob.state).toBe("complete");
+    expect(status.videoAsset).toMatchObject({ durationMs: 1000, width: 320, height: 180, frameRate: 25 });
+    expect(status.videoAsset.codec).toBeDefined();
+    expect(objects.get(status.videoAsset.storageKey)?.equals(bytes)).toBe(false);
+    expect(await storage.getObject(status.videoAsset.storageKey)).toEqual(bytes);
+    const again = await storage.putContent(bytes, "video/mp4");
+    expect(again).toMatchObject({ key: status.videoAsset.storageKey, deduplicated: true });
+    console.info("Real ffprobe status:", JSON.stringify(status));
+  });
+});
diff --git a/apps/api/src/video/video.service.test.ts b/apps/api/src/video/video.service.test.ts
new file mode 100644
index 0000000..c76c637
--- /dev/null
+++ b/apps/api/src/video/video.service.test.ts
@@ -0,0 +1,108 @@
+import { readFile, stat } from "node:fs/promises";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { VideoService } from "./video.service.js";
+import { assetId, serviceWithDatabase, workspaceId, type FakeVideoDatabase } from "./test-fixtures.js";
+import { MAX_VIDEO_UPLOAD_BYTES } from "./upload-limits.js";
+
+afterEach(() => vi.unstubAllEnvs());
+
+describe("video byte ingest and processing-job state machine", () => {
+  it("stores bytes, probes the decrypted stored object, and completes through a no-op transcode", async () => {
+    const database: FakeVideoDatabase = {};
+    const bytes = Buffer.from("actual video bytes");
+    let inputPath = "";
+    const probe = vi.fn(async (path: string) => {
+      inputPath = path;
+      expect(await readFile(path)).toEqual(bytes);
+      expect((await stat(path)).mode & 0o777).toBe(0o600);
+      expect(database.job?.state).toBe("probing");
+      return { width: 1280, height: 720, durationMs: 42_000, frameRate: 30, codec: "h264", audioCodec: "aac" };
+    });
+    const { service, appendAudit, storage } = serviceWithDatabase(database, probe);
+    const uploaded = await service.uploadVideoBytes(workspaceId, bytes, "video/mp4");
+    expect(storage.putContent).toHaveBeenCalledWith(bytes, "video/mp4");
+    expect(uploaded.videoAsset.storageKey).toMatch(/^sha256\/[a-f0-9]{64}\.mp4$/);
+    expect(storage.getObject).toHaveBeenCalledWith(uploaded.videoAsset.storageKey);
+    expect(uploaded.videoAsset).toMatchObject({ sizeBytes: bytes.length, width: 1280, height: 720, durationMs: 42_000, codec: "h264" });
+    expect(uploaded.processingJob).toMatchObject({ state: "complete", progressPercent: 100, outputKey: uploaded.videoAsset.storageKey });
+    expect(uploaded.processingJob.processingNote).toContain("Transcode skipped");
+    expect(database.transitions).toEqual(["queued", "probing", "transcoding", "complete"]);
+    await expect(stat(inputPath)).rejects.toMatchObject({ code: "ENOENT" });
+    expect(appendAudit).toHaveBeenCalledWith(workspaceId, expect.objectContaining({ action: "video.uploaded", targetId: assetId }));
+    expect(appendAudit).toHaveBeenCalledWith(workspaceId, expect.objectContaining({ action: "video.probed", diff: expect.objectContaining({ processingNote: expect.stringContaining("Transcode skipped") }) }));
+    await expect(service.probeVideo(assetId, workspaceId)).rejects.toThrow("cannot probe video in processing state complete");
+    expect(probe).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns a failed job with the ffprobe error in status, and removes the temporary file", async () => {
+    const database: FakeVideoDatabase = {};
+    let inputPath = "";
+    const { service } = serviceWithDatabase(database, async (path) => {
+      inputPath = path;
+      throw new Error("unreadable media");
+    });
+    const uploaded = await service.uploadVideoBytes(workspaceId, Buffer.from("broken"), "video/mp4");
+    expect(uploaded.processingJob).toMatchObject({ state: "failed", error: "unreadable media" });
+    expect(database.transitions).toEqual(["queued", "probing", "failed"]);
+    expect((await service.getVideoStatus(assetId, workspaceId)).processingJob.error).toBe("unreadable media");
+    await expect(stat(inputPath)).rejects.toMatchObject({ code: "ENOENT" });
+  });
+
+  it("fails with 503 before DB registration without S3 configuration", async () => {
+    vi.stubEnv("S3_ACCESS_KEY", "");
+    vi.stubEnv("S3_SECRET_KEY", "");
+    const transaction = vi.fn();
+    const service = new VideoService({ tenantTransaction: transaction });
+    await expect(service.uploadVideoBytes(workspaceId, Buffer.from("video"), "video/mp4")).rejects.toMatchObject({ status: 503, message: expect.stringContaining("Video storage is not configured") });
+    expect(transaction).not.toHaveBeenCalled();
+  });
+
+  it("fails with 503 on a configured storage outage, without creating a queued row", async () => {
+    const database: FakeVideoDatabase = {};
+    const { service, storage } = serviceWithDatabase(database, async () => ({}));
+    vi.mocked(storage.putContent).mockRejectedValueOnce(new Error("ECONNREFUSED"));
+    await expect(service.uploadVideoBytes(workspaceId, Buffer.from("video"), "video/mp4")).rejects.toMatchObject({ status: 503 });
+    expect(database.asset).toBeUndefined();
+    expect(database.job).toBeUndefined();
+  });
+
+  it("marks fetch/integrity failures after put as failed, rather than leaving a queued job", async () => {
+    const database: FakeVideoDatabase = {};
+    const probe = vi.fn(async () => ({}));
+    const { service, storage } = serviceWithDatabase(database, probe);
+    vi.mocked(storage.getObject).mockRejectedValueOnce(new Error("storage: integrity failure"));
+    const uploaded = await service.uploadVideoBytes(workspaceId, Buffer.from("video"), "video/mp4");
+    expect(uploaded.processingJob).toMatchObject({ state: "failed", error: "storage: integrity failure" });
+    expect(probe).not.toHaveBeenCalled();
+  });
+
+  it("keeps metadata registration compatible only for existing objects with matching size", async () => {
+    const database: FakeVideoDatabase = {};
+    const { service, storage } = serviceWithDatabase(database, async () => ({ width: 640 }));
+    const stored = await storage.putContent(Buffer.from("video"), "video/mp4");
+    await expect(service.uploadVideo(workspaceId, stored.key, "video/mp4", 1)).rejects.toThrow("sizeBytes does not match");
+    await expect(service.uploadVideo(workspaceId, "sha256/missing.mp4", "video/mp4", 5)).rejects.toThrow("existing readable encrypted object");
+    const uploaded = await service.uploadVideo(workspaceId, stored.key, "video/mp4", stored.sizeBytes);
+    expect(uploaded.processingJob.state).toBe("complete");
+    expect(uploaded.videoAsset.width).toBe(640);
+  });
+
+  it("deletes the asset/job while retaining shared content-addressed bytes for GC", async () => {
+    const database: FakeVideoDatabase = {};
+    const { service, objects } = serviceWithDatabase(database, async () => ({}));
+    const bytes = Buffer.from("shared source");
+    const uploaded = await service.uploadVideoBytes(workspaceId, bytes, "video/mp4");
+    await service.deleteVideo(assetId, workspaceId);
+    expect(database.asset).toBeUndefined();
+    expect(database.job).toBeUndefined();
+    expect(objects.get(uploaded.videoAsset.storageKey)).toEqual(bytes);
+  });
+
+  it("rejects empty or non-video uploads before storage", async () => {
+    const { service, storage } = serviceWithDatabase({}, async () => ({}));
+    await expect(service.uploadVideoBytes(workspaceId, Buffer.alloc(0), "video/mp4")).rejects.toMatchObject({ status: 400 });
+    await expect(service.uploadVideoBytes(workspaceId, Buffer.from("image"), "image/png")).rejects.toMatchObject({ status: 400 });
+    await expect(service.uploadVideoBytes(workspaceId, Buffer.allocUnsafe(MAX_VIDEO_UPLOAD_BYTES + 1), "video/mp4")).rejects.toThrow("100 MiB upload limit");
+    expect(storage.putContent).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/api/src/video/video.service.ts b/apps/api/src/video/video.service.ts
new file mode 100644
index 0000000..6cdc28e
--- /dev/null
+++ b/apps/api/src/video/video.service.ts
@@ -0,0 +1,509 @@
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BadRequestException, Inject, Injectable, NotFoundException, Optional, ServiceUnavailableException } from "@nestjs/common";
+import type { PoolClient } from "pg";
+import { appendTenantAudit, type AuditEvent } from "../audit/audit.service.js";
+import { withTenant } from "../db/client.js";
+import { probeVideoFile, type VideoProbeResult } from "./ffprobe.js";
+import { S3Storage, s3ConfigFromEnv, type StorageService } from "../storage/storage.js";
+import { MAX_VIDEO_UPLOAD_BYTES } from "./upload-limits.js";
+
+const NO_OP_TRANSCODE_NOTE = "Transcode skipped: original stored object retained; rendering belongs to the media-worker compositor.";
+
+export type VideoProcessingJobState = "queued" | "probing" | "transcoding" | "complete" | "failed";
+
+export interface VideoAssetRecord {
+  id: string;
+  workspaceId: string;
+  storageKey: string;
+  mimeType: string;
+  sizeBytes: number;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  frameRate?: number;
+  codec?: string;
+  audioCodec?: string;
+  thumbnailKey?: string;
+}
+
+export interface VideoProcessingJobRecord {
+  id: string;
+  workspaceId: string;
+  videoAssetId: string;
+  state: VideoProcessingJobState;
+  progressPercent?: number;
+  outputKey?: string;
+  error?: string;
+  processingNote?: string;
+}
+
+export interface VideoPublicationSummary {
+  connectionId: string;
+  remoteId: string;
+  platform: string;
+  publishedAt: Date;
+}
+
+export interface VideoLibraryEntryRecord {
+  videoAsset: VideoAssetRecord;
+  processingState: VideoProcessingJobState;
+  publications: VideoPublicationSummary[];
+}
+
+export interface VideoLibraryPage {
+  items: VideoLibraryEntryRecord[];
+  nextCursor?: string;
+}
+
+export interface VideoStatus {
+  videoAsset: VideoAssetRecord;
+  processingJob: VideoProcessingJobRecord;
+}
+
+export type VideoUploadResult = VideoStatus;
+
+type TenantTransaction = <T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>) => Promise<T>;
+type AuditAppender = (workspaceId: string, event: AuditEvent) => Promise<string>;
+
+export interface VideoServiceDependencies {
+  tenantTransaction: TenantTransaction;
+  appendAudit: AuditAppender;
+  probe: (inputPath: string) => Promise<VideoProbeResult>;
+  storage?: StorageService;
+}
+
+export const VIDEO_SERVICE_DEPENDENCIES = Symbol("VIDEO_SERVICE_DEPENDENCIES");
+
+const DEFAULT_DEPENDENCIES: VideoServiceDependencies = {
+  tenantTransaction: withTenant,
+  appendAudit: appendTenantAudit,
+  probe: probeVideoFile,
+};
+
+@Injectable()
+export class VideoService {
+  private readonly dependencies: VideoServiceDependencies;
+  private storage?: StorageService;
+
+  constructor(
+    @Optional() @Inject(VIDEO_SERVICE_DEPENDENCIES) dependencies?: Partial<VideoServiceDependencies>,
+  ) {
+    this.dependencies = { ...DEFAULT_DEPENDENCIES, ...dependencies };
+    this.storage = dependencies?.storage;
+  }
+
+  async uploadVideoBytes(workspaceId: string, bytes: Buffer, mimeType: string): Promise<VideoUploadResult> {
+    validateUpload("pending", mimeType, bytes.length);
+    const storage = this.requireStorage();
+    const stored = await storage.putContent(bytes, mimeType).catch(() => {
+      throw new ServiceUnavailableException("Video storage unavailable: could not store encrypted upload in S3/MinIO.");
+    });
+    return this.registerAndProbe(workspaceId, stored.key, stored.contentType, stored.sizeBytes);
+  }
+
+  async uploadVideo(
+    workspaceId: string,
+    storageKey: string,
+    mimeType: string,
+    sizeBytes: number,
+  ): Promise<VideoUploadResult> {
+    validateUpload(storageKey, mimeType, sizeBytes);
+    // Legacy metadata registration is accepted only for an object that really exists.
+    const bytes = await this.requireStorage().getObject(storageKey).catch(() => {
+      throw new BadRequestException("storageKey must identify an existing readable encrypted object; upload a file first");
+    });
+    if (bytes.length !== sizeBytes) throw new BadRequestException("sizeBytes does not match the stored object");
+    return this.registerAndProbe(workspaceId, storageKey, mimeType, sizeBytes);
+  }
+
+  private async registerAndProbe(
+    workspaceId: string, storageKey: string, mimeType: string, sizeBytes: number,
+  ): Promise<VideoUploadResult> {
+    const uploaded = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const assetResult = await client.query(
+        `INSERT INTO video_assets (workspace_id, storage_key, mime_type, size_bytes)
+         VALUES ($1, $2, $3, $4) RETURNING *`,
+        [workspaceId, storageKey, mimeType, sizeBytes],
+      );
+      const videoAsset = assetFromRow(requiredRow(assetResult.rows[0], "created video asset"));
+      const jobResult = await client.query(
+        `INSERT INTO video_processing_jobs (workspace_id, video_asset_id, state)
+         VALUES ($1, $2, 'queued') RETURNING *`,
+        [workspaceId, videoAsset.id],
+      );
+      return {
+        videoAsset,
+        processingJob: jobFromRow(requiredRow(jobResult.rows[0], "created video processing job")),
+      };
+    });
+
+    try {
+      await this.probeVideo(uploaded.videoAsset.id, workspaceId);
+    } catch (error) {
+      // Probe errors are recorded on the job; return its ID and failure in status.
+      const status = await this.getVideoStatus(uploaded.videoAsset.id, workspaceId);
+      if (status.processingJob.state !== "failed") throw error;
+    }
+    await this.audit(workspaceId, "video.uploaded", uploaded.videoAsset.id, {
+      mimeType,
+      sizeBytes,
+    });
+    return this.getVideoStatus(uploaded.videoAsset.id, workspaceId);
+  }
+
+  async getVideoStatus(assetId: string, workspaceId: string): Promise<VideoStatus> {
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT va.*,
+                j.id AS job_id, j.video_asset_id AS job_video_asset_id,
+                j.state AS job_state, j.progress_percent AS job_progress_percent,
+                j.output_key AS job_output_key, j.error AS job_error
+         FROM video_assets va
+         LEFT JOIN LATERAL (
+           SELECT * FROM video_processing_jobs
+           WHERE video_asset_id = va.id
+           ORDER BY created_at DESC, id DESC LIMIT 1
+         ) j ON true
+         WHERE va.id = $1`,
+        [assetId],
+      );
+      if (result.rowCount !== 1) throw new NotFoundException(`video ${assetId} not found`);
+      const row = requiredRow(result.rows[0], "video status");
+      if (row.job_id === null || row.job_id === undefined) {
+        throw new Error(`video ${assetId} has no processing job`);
+      }
+      return { videoAsset: assetFromRow(row), processingJob: joinedJobFromRow(row) };
+    });
+  }
+
+  async probeVideo(assetId: string, workspaceId: string): Promise<VideoAssetRecord> {
+    const claimed = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const asset = await client.query("SELECT * FROM video_assets WHERE id = $1", [assetId]);
+      if (asset.rowCount !== 1) throw new NotFoundException(`video ${assetId} not found`);
+      const changed = await client.query(
+        `UPDATE video_processing_jobs
+         SET state = 'probing', progress_percent = 10, error = NULL, updated_at = now()
+         WHERE id = (
+           SELECT id FROM video_processing_jobs
+           WHERE video_asset_id = $1 ORDER BY created_at DESC, id DESC LIMIT 1
+         ) AND state = 'queued'
+         RETURNING id`,
+        [assetId],
+      );
+      if (changed.rowCount !== 1) {
+        const latest = await client.query(
+          `SELECT state FROM video_processing_jobs
+           WHERE video_asset_id = $1 ORDER BY created_at DESC, id DESC LIMIT 1`,
+          [assetId],
+        );
+        const state = latest.rows[0]?.state;
+        throw new BadRequestException(
+          state === undefined
+            ? `video ${assetId} has no processing job`
+            : `cannot probe video in processing state ${String(state)}`,
+        );
+      }
+      return {
+        storageKey: String(asset.rows[0]?.storage_key),
+        jobId: String(changed.rows[0]?.id),
+      };
+    });
+
+    let metadata: VideoProbeResult;
+    let videoAsset: VideoAssetRecord;
+    try {
+      const bytes = await this.requireStorage().getObject(claimed.storageKey);
+      const directory = await mkdtemp(join(tmpdir(), "tmbh-video-"));
+      try {
+        const inputPath = join(directory, "input");
+        await writeFile(inputPath, bytes, { mode: 0o600 });
+        metadata = await this.dependencies.probe(inputPath);
+      } finally {
+        await rm(directory, { recursive: true, force: true });
+      }
+      videoAsset = await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+        const updated = await client.query(
+          `UPDATE video_assets
+           SET width = $2, height = $3, duration_ms = $4, frame_rate = $5,
+               codec = $6, audio_codec = $7
+           WHERE id = $1 RETURNING *`,
+          [
+            assetId,
+            metadata.width ?? null,
+            metadata.height ?? null,
+            metadata.durationMs ?? null,
+            metadata.frameRate ?? null,
+            metadata.codec ?? null,
+            metadata.audioCodec ?? null,
+          ],
+        );
+        if (updated.rowCount !== 1) throw new NotFoundException(`video ${assetId} not found`);
+        const transcoding = await client.query(
+          `UPDATE video_processing_jobs
+           SET state = 'transcoding', progress_percent = 90, error = NULL, updated_at = now()
+           WHERE id = $1 AND state = 'probing' RETURNING id`,
+          [claimed.jobId],
+        );
+        if (transcoding.rowCount !== 1) throw new Error(`video processing job ${claimed.jobId} lost its claim`);
+        return assetFromRow(requiredRow(updated.rows[0], "probed video asset"));
+      });
+
+      // This slice deliberately retains the source. The compositor owns real transcoding.
+      await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+        const completed = await client.query(
+          `UPDATE video_processing_jobs
+           SET state = 'complete', progress_percent = 100, output_key = $2, error = NULL, updated_at = now()
+           WHERE id = $1 AND state = 'transcoding' RETURNING id`,
+          [claimed.jobId, claimed.storageKey],
+        );
+        if (completed.rowCount !== 1) throw new Error(`video processing job ${claimed.jobId} lost its claim`);
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+        await client.query(
+          `UPDATE video_processing_jobs
+           SET state = 'failed', error = $2, updated_at = now()
+           WHERE id = $1 AND state IN ('probing', 'transcoding')`,
+          [claimed.jobId, message],
+        );
+      });
+      throw error;
+    }
+
+    await this.audit(workspaceId, "video.probed", assetId, { ...metadata, processingNote: NO_OP_TRANSCODE_NOTE });
+    return videoAsset;
+  }
+
+  async listVideos(
+    workspaceId: string,
+    cursor: string | undefined,
+    limit: number,
+  ): Promise<VideoLibraryPage> {
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) {
+      throw new BadRequestException("limit must be an integer between 1 and 200");
+    }
+    const decoded = cursor === undefined || cursor === "" ? undefined : decodeCursor(cursor);
+    return this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const result = await client.query(
+        `SELECT va.*,
+                COALESCE(j.state, 'queued') AS processing_state,
+                COALESCE((
+                  SELECT jsonb_agg(jsonb_build_object(
+                    'connectionId', p.connection_id,
+                    'remoteId', p.remote_id,
+                    'platform', c.provider,
+                    'publishedAt', p.published_at
+                  ) ORDER BY p.published_at DESC)
+                  FROM publications p
+                  JOIN drafts d ON d.id = p.draft_id
+                  JOIN connections c ON c.id = p.connection_id
+                  WHERE d.post ->> 'videoAssetId' = va.id::text
+                     OR d.post -> 'mediaAssetIds' ? va.id::text
+                ), '[]'::jsonb) AS publications
+         FROM video_assets va
+         LEFT JOIN LATERAL (
+           SELECT state FROM video_processing_jobs
+           WHERE video_asset_id = va.id
+           ORDER BY created_at DESC, id DESC LIMIT 1
+         ) j ON true
+         WHERE ($1::timestamptz IS NULL OR (va.created_at, va.id) < ($1::timestamptz, $2::uuid))
+         ORDER BY va.created_at DESC, va.id DESC
+         LIMIT $3`,
+        [decoded?.createdAt ?? null, decoded?.id ?? null, limit + 1],
+      );
+      const rows = result.rows.map((row: unknown) => requiredRow(row, "video library entry"));
+      const hasMore = rows.length > limit;
+      const pageRows = rows.slice(0, limit);
+      const items = pageRows.map(libraryEntryFromRow);
+      const last = pageRows[pageRows.length - 1];
+      return {
+        items,
+        ...(hasMore && last !== undefined
+          ? { nextCursor: encodeCursor({ createdAt: new Date(String(last.created_at)).toISOString(), id: String(last.id) }) }
+          : {}),
+      };
+    });
+  }
+
+  async deleteVideo(assetId: string, workspaceId: string): Promise<void> {
+    // Objects are shared by content hash across assets/workspaces. Retain for future
+    // reference-aware GC; deleting here could destroy another asset's source.
+    await this.dependencies.tenantTransaction(workspaceId, async (client) => {
+      const removed = await client.query("DELETE FROM video_assets WHERE id = $1 RETURNING id", [assetId]);
+      if (removed.rowCount !== 1) throw new NotFoundException(`video ${assetId} not found`);
+    });
+    await this.audit(workspaceId, "video.deleted", assetId, {});
+  }
+
+  private requireStorage(): StorageService {
+    if (this.storage !== undefined) return this.storage;
+    const config = s3ConfigFromEnv();
+    if (!config.accessKeyId?.trim() || !config.secretAccessKey?.trim()) {
+      throw new ServiceUnavailableException(
+        "Video storage is not configured: set S3_ACCESS_KEY and S3_SECRET_KEY, plus S3_ENDPOINT for MinIO.",
+      );
+    }
+    try {
+      this.storage = new S3Storage(config);
+    } catch {
+      throw new ServiceUnavailableException("Video storage configuration is invalid; check S3 settings and S3_KEK.");
+    }
+    return this.storage;
+  }
+
+  private async audit(
+    workspaceId: string,
+    action: "video.uploaded" | "video.probed" | "video.deleted",
+    targetId: string,
+    diff: Record<string, unknown>,
+  ): Promise<void> {
+    await this.dependencies.appendAudit(workspaceId, {
+      actorUserId: null,
+      actorRole: "api",
+      action,
+      targetType: "video_asset",
+      targetId,
+      diff,
+    });
+  }
+}
+
+function validateUpload(storageKey: string, mimeType: string, sizeBytes: number): void {
+  if (storageKey.trim() === "") throw new BadRequestException("storageKey must be a non-empty string");
+  if (!mimeType.toLowerCase().startsWith("video/")) {
+    throw new BadRequestException("mimeType must be a video media type");
+  }
+  if (!Number.isSafeInteger(sizeBytes) || sizeBytes < 1) {
+    throw new BadRequestException("sizeBytes must be a positive safe integer");
+  }
+  if (sizeBytes > MAX_VIDEO_UPLOAD_BYTES) throw new BadRequestException("video exceeds the 100 MiB upload limit");
+}
+
+function requiredRow(row: unknown, description: string): Record<string, unknown> {
+  if (typeof row !== "object" || row === null || Array.isArray(row)) {
+    throw new Error(`database did not return ${description}`);
+  }
+  return row as Record<string, unknown>;
+}
+
+function assetFromRow(row: Record<string, unknown>): VideoAssetRecord {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    storageKey: String(row.storage_key),
+    mimeType: String(row.mime_type),
+    sizeBytes: safeDatabaseNumber(row.size_bytes, "size_bytes"),
+    ...optionalNumber("width", row.width),
+    ...optionalNumber("height", row.height),
+    ...optionalNumber("durationMs", row.duration_ms),
+    ...optionalNumber("frameRate", row.frame_rate),
+    ...optionalString("codec", row.codec),
+    ...optionalString("audioCodec", row.audio_codec),
+    ...optionalString("thumbnailKey", row.thumbnail_key),
+  };
+}
+
+function jobFromRow(row: Record<string, unknown>): VideoProcessingJobRecord {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    videoAssetId: String(row.video_asset_id),
+    state: processingState(row.state),
+    ...optionalNumber("progressPercent", row.progress_percent),
+    ...optionalString("outputKey", row.output_key),
+    ...optionalString("error", row.error),
+  };
+}
+
+function joinedJobFromRow(row: Record<string, unknown>): VideoProcessingJobRecord {
+  const job = jobFromRow({
+    id: row.job_id,
+    workspace_id: row.workspace_id,
+    video_asset_id: row.job_video_asset_id,
+    state: row.job_state,
+    progress_percent: row.job_progress_percent,
+    output_key: row.job_output_key,
+    error: row.job_error,
+  });
+  return {
+    ...job,
+    ...(job.state === "complete" && job.outputKey === row.storage_key ? { processingNote: NO_OP_TRANSCODE_NOTE } : {}),
+  };
+}
+
+function libraryEntryFromRow(row: Record<string, unknown>): VideoLibraryEntryRecord {
+  const rawPublications = Array.isArray(row.publications) ? row.publications : [];
+  return {
+    videoAsset: assetFromRow(row),
+    processingState: processingState(row.processing_state),
+    publications: rawPublications.map((publication) => publicationFromJson(requiredRow(publication, "publication"))),
+  };
+}
+
+function publicationFromJson(row: Record<string, unknown>): VideoPublicationSummary {
+  return {
+    connectionId: String(row.connectionId),
+    remoteId: String(row.remoteId),
+    platform: String(row.platform),
+    publishedAt: new Date(String(row.publishedAt)),
+  };
+}
+
+function processingState(value: unknown): VideoProcessingJobState {
+  if (
+    value === "queued" ||
+    value === "probing" ||
+    value === "transcoding" ||
+    value === "complete" ||
+    value === "failed"
+  ) {
+    return value;
+  }
+  throw new Error(`invalid video processing state: ${String(value)}`);
+}
+
+function safeDatabaseNumber(value: unknown, field: string): number {
+  const number = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isSafeInteger(number)) throw new Error(`${field} is outside JavaScript's safe integer range`);
+  return number;
+}
+
+function optionalNumber<K extends string>(key: K, value: unknown): Partial<Record<K, number>> {
+  if (value === null || value === undefined) return {};
+  const number = typeof value === "number" ? value : typeof value === "string" ? Number(value) : NaN;
+  if (!Number.isFinite(number)) throw new Error(`${key} is not numeric`);
+  return { [key]: number } as Record<K, number>;
+}
+
+function optionalString<K extends string>(key: K, value: unknown): Partial<Record<K, string>> {
+  return value === null || value === undefined ? {} : { [key]: String(value) } as Record<K, string>;
+}
+
+interface VideoCursor {
+  createdAt: string;
+  id: string;
+}
+
+function encodeCursor(cursor: VideoCursor): string {
+  return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+
+function decodeCursor(cursor: string): VideoCursor {
+  try {
+    const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8")) as unknown;
+    const row = requiredRow(decoded, "video cursor");
+    const createdAt = String(row.createdAt);
+    const id = String(row.id);
+    if (!Number.isFinite(Date.parse(createdAt)) || !isUuid(id)) throw new Error("invalid fields");
+    return { createdAt, id };
+  } catch {
+    throw new BadRequestException("cursor is invalid");
+  }
+}
+
+function isUuid(value: string): boolean {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
diff --git a/apps/api/src/video/video.status.http.test.ts b/apps/api/src/video/video.status.http.test.ts
new file mode 100644
index 0000000..75fd966
--- /dev/null
+++ b/apps/api/src/video/video.status.http.test.ts
@@ -0,0 +1,99 @@
+import "reflect-metadata";
+import { Module, NotFoundException, UnauthorizedException, ForbiddenException, type ExecutionContext, type INestApplication } from "@nestjs/common";
+import { NestFactory, Reflector } from "@nestjs/core";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { injectHttp } from "../connections/http-test-transport.js";
+import { RbacGuard, PERMISSION_KEY } from "../rbac/rbac.guard.js";
+import { VideoController } from "./video.controller.js";
+import { VideoService, type VideoStatus } from "./video.service.js";
+import { assetId, jobId, serviceWithDatabase, workspaceId } from "./test-fixtures.js";
+
+@Module({})
+class TestModule {}
+
+function statusService(database: Parameters<typeof serviceWithDatabase>[0]): ReturnType<typeof serviceWithDatabase> {
+  // A probe that never runs: status reads do not invoke ffprobe.
+  return serviceWithDatabase(database, async () => { throw new Error("probe must not run for status reads"); });
+}
+
+describe("GET /video/:id/status", () => {
+  let app: INestApplication | undefined;
+  let canView = true;
+
+  beforeEach(() => {
+    canView = true;
+    vi.spyOn(RbacGuard.prototype, "canActivate").mockImplementation(async (context: ExecutionContext) => {
+      const request = context.switchToHttp().getRequest<{ headers: Record<string, string>; session?: { workspaceId: string } }>();
+      if (request.headers.authorization !== "Bearer test-session") throw new UnauthorizedException();
+      if (!canView && new Reflector().get<string>(PERMISSION_KEY, context.getHandler()) === "media.view") {
+        throw new ForbiddenException("missing permission: media.view");
+      }
+      request.session = { workspaceId };
+      return true;
+    });
+  });
+
+  afterEach(async () => {
+    await app?.close();
+    app = undefined;
+    vi.restoreAllMocks();
+  });
+
+  async function start(service: VideoService): Promise<void> {
+    app = await NestFactory.create({
+      module: TestModule,
+      controllers: [VideoController],
+      providers: [{ provide: VideoService, useValue: service }],
+    }, { logger: false });
+    await app.init();
+  }
+
+  function status(id: string = assetId, authenticated = true): Promise<Response> {
+    return injectHttp(app?.getHttpAdapter().getInstance(), `http://api.test/video/${id}/status`, {
+      headers: { ...(authenticated ? { authorization: "Bearer test-session" } : {}) },
+    });
+  }
+
+  it("returns the asset with its latest processing job (the shape the drawer polls)", async () => {
+    const { service } = statusService({});
+    await start(service);
+    // Seed one asset + job through the service so the joined row exists.
+    await service.uploadVideoBytes(workspaceId, Buffer.from("status fixture"), "video/mp4");
+    const response = await status();
+    expect(response.status).toBe(200);
+    const body = await response.json() as VideoStatus;
+    expect(body.videoAsset).toMatchObject({ id: assetId, sizeBytes: Buffer.byteLength("status fixture") });
+    expect(body.processingJob).toMatchObject({ id: jobId, state: expect.stringMatching(/^(probing|transcoding|complete|failed)$/) });
+  });
+
+  it("reports an in-flight job state without completing it", async () => {
+    const { service } = statusService({});
+    await start(service);
+    await service.uploadVideoBytes(workspaceId, Buffer.from("in flight"), "video/mp4");
+    // The fake DB only advances probing → transcoding when the service runs it,
+    // so a bare status read must observe an earlier state, not a fabricated one.
+    const before = await service.getVideoStatus(assetId, workspaceId);
+    const response = await status();
+    const body = await response.json() as VideoStatus;
+    expect(body.processingJob.state).toBe(before.processingJob.state);
+    expect(body.processingJob.state).not.toBe("complete");
+  });
+
+  it("returns 404 for an unknown asset in the workspace", async () => {
+    const { service } = statusService({});
+    await start(service);
+    const response = await status(assetId);
+    expect(response.status).toBe(404);
+    expect(await response.json()).toMatchObject({ message: expect.stringContaining("not found") });
+    // And the service-level route contract is a NotFoundException, not a crash.
+    await expect(service.getVideoStatus(assetId, workspaceId)).rejects.toBeInstanceOf(NotFoundException);
+  });
+
+  it("returns 401 without a session and 403 without media.view", async () => {
+    const { service } = statusService({});
+    await start(service);
+    expect((await status(assetId, false)).status).toBe(401);
+    canView = false;
+    expect((await status()).status).toBe(403);
+  });
+});
diff --git a/apps/api/src/virtual-channels/import-egress.ts b/apps/api/src/virtual-channels/import-egress.ts
new file mode 100644
index 0000000..8eb7491
--- /dev/null
+++ b/apps/api/src/virtual-channels/import-egress.ts
@@ -0,0 +1,71 @@
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { pool } from "../db/client.js";
+// Type-only (erased in the CommonJS build): the ESM package is loaded
+// natively at runtime, exactly like the live monitor's egress binding.
+import type { createEgressClient, EgressError, EgressPolicy } from "../../../../packages/egress/src/index.js";
+
+type EgressPackage = typeof import("../../../../packages/egress/src/index.js");
+
+export interface ImportEgress {
+  egressFetch: ReturnType<typeof createEgressClient>["egressFetch"];
+  policy: EgressPolicy;
+  /** Value identity check for errors raised by the shared egress client. */
+  isEgressError(error: unknown): error is EgressError;
+}
+
+/** Import resolution deadline per source (two public GETs at most). */
+export const IMPORT_TIMEOUT_MS = 10_000;
+/** Host class keying the shared per-host budget rows. */
+export const IMPORT_HOST_CLASS = "import";
+
+const nativeImport = new Function("specifier", "return import(specifier)") as (specifier: string) => Promise<EgressPackage>;
+let shared: Promise<ImportEgress> | undefined;
+
+/**
+ * Process-wide egress client for bulk import: every import job and replica
+ * draws from the same per-host budget rows for a given host key.
+ */
+export function importEgress(): Promise<ImportEgress> {
+  shared ??= (async () => {
+    const specifier = pathToFileURL(resolveImportPackage()).href;
+    const pkg = await nativeImport(specifier);
+    const client = pkg.createEgressClient({
+      pool,
+      timeoutMs: IMPORT_TIMEOUT_MS,
+      maxResponseBytes: 512 * 1024,
+      hostClasses: { [IMPORT_HOST_CLASS]: { capacity: 4, refillPerInterval: 20 } },
+    });
+    return { ...client, isEgressError: (error: unknown): error is EgressError => error instanceof pkg.EgressError };
+  })();
+  return shared;
+}
+
+function resolveImportPackage(): string {
+  for (const start of [process.cwd(), __dirname]) {
+    for (let root = start; ; root = dirname(root)) {
+      const directory = resolve(root, "packages/egress");
+      const files = process.env.NODE_ENV === "production" ? ["dist/index.js"] : ["src/index.ts", "dist/index.js"];
+      for (const file of files) {
+        const path = resolve(directory, file);
+        if (existsSync(path)) return path;
+      }
+      if (dirname(root) === root) break;
+    }
+  }
+  throw new Error("Build packages/egress before importing sources");
+}
+
+/** Row-level taxonomy for an egress/policy failure. */
+export function egressFailure(
+  error: unknown,
+  isEgressError: ImportEgress["isEgressError"],
+): { reason: "not_found" | "upstream" | "denied"; message: string } {
+  if (isEgressError(error)) {
+    if (error.code === "DNS_FAILED") return { reason: "not_found", message: "Instance host could not be resolved" };
+    if (error.code === "BUDGET_EXHAUSTED") return { reason: "upstream", message: "Instance request budget exhausted; retry later" };
+    return { reason: "denied", message: "Instance request denied by the outbound policy" };
+  }
+  return { reason: "upstream", message: "Instance request failed" };
+}
diff --git a/apps/api/src/virtual-channels/import-normalize.test.ts b/apps/api/src/virtual-channels/import-normalize.test.ts
new file mode 100644
index 0000000..e58e168
--- /dev/null
+++ b/apps/api/src/virtual-channels/import-normalize.test.ts
@@ -0,0 +1,130 @@
+import { describe, expect, it } from "vitest";
+import { EgressPolicy } from "../../../../packages/egress/src/index.js";
+import {
+  dedupeSyntactic,
+  IMPORT_ROW_LIMIT,
+  InvalidRowError,
+  normalizeImportRow,
+  parseImportBody,
+} from "./import-normalize.js";
+
+/** Policy-only validation: no DNS, no budget draw. */
+const policy = new EgressPolicy();
+
+function normalize(raw: string, defaultHost?: string) {
+  return normalizeImportRow(raw, defaultHost, policy);
+}
+
+describe("import normalization", () => {
+  it("canonicalizes handles: strips @, lowercases, IDNA-encodes the host", () => {
+    expect(normalize("@Alice@VIDEO.Example.")).toEqual({
+      kind: "channel", name: "alice", host: "video.example",
+      key: "channel:alice@video.example", label: "@alice@video.example", raw: "@Alice@VIDEO.Example.",
+    });
+    // Unicode host punycodes to the same canonical form as its ASCII twin, so
+    // both spellings collide on one dedupe key.
+    expect(normalize("bob@vïdeo.example").host).toBe(normalize("bob@xn--vdeo-5pa.example").host);
+  });
+
+  it("extracts channel identity from /c, /a and /video-channels URLs, dropping default ports", () => {
+    expect(normalize("https://video.example/c/Alice")).toMatchObject({ kind: "channel", name: "alice", host: "video.example" });
+    expect(normalize("https://Video.Example:443/video-channels/alice_channel")).toMatchObject({ kind: "channel", name: "alice_channel" });
+    expect(normalize("https://video.example/a/alice")).toMatchObject({ kind: "channel", name: "alice" });
+  });
+
+  it("extracts a live identity from watch/embed URLs, including the ;threadId suffix", () => {
+    const uuid = "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d";
+    expect(normalize(`https://video.example/w/${uuid};threadId=7`)).toMatchObject({ kind: "live", name: uuid });
+    expect(normalize(`https://video.example/videos/watch/${uuid.toUpperCase()}`)).toMatchObject({ kind: "live", name: uuid });
+    expect(normalize(`https://video.example/videos/embed/${uuid}`)).toMatchObject({ kind: "live" });
+  });
+
+  it("a bare uuid needs a default host and one is supplied by the connection", () => {
+    const uuid = "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d";
+    expect(() => normalize(uuid)).toThrow(InvalidRowError);
+    expect(normalize(uuid, "video.example")).toMatchObject({ kind: "live", name: uuid, host: "video.example", key: `live:${uuid}@video.example` });
+    expect(normalize("alice", "video.example")).toMatchObject({ kind: "channel", name: "alice", host: "video.example" });
+  });
+
+  it("short ids pass (case preserved for the API path) and junk ids do not", () => {
+    const short = normalize("https://video.example/w/abc123_XY", "video.example");
+    expect(short.kind).toBe("live");
+    expect(short.name).toBe(short.name.toLowerCase());
+    expect(() => normalize("https://video.example/w/not_a_uuid!!")).toThrow(InvalidRowError);
+  });
+
+  it("rejects rows the egress policy refuses before any network work", () => {
+    for (const bad of [
+      "http://127.0.0.1/w/abc123",          // non-https + loopback
+      "https://video.example:22/w/abc123",  // denied port
+      "ftp://video.example/c/alice",        // denied scheme
+      "https://user:pass@video.example/c/alice", // credentials
+    ]) {
+      expect(() => normalize(bad), bad).toThrow(InvalidRowError);
+      expect(() => normalize(bad), bad).toThrow(InvalidRowError);
+    }
+  });
+
+  it("rejects empty, oversized, control-character and unknown rows", () => {
+    expect(() => normalize("   ")).toThrow(/empty/);
+    expect(() => normalize("x".repeat(2049))).toThrow(InvalidRowError);
+    expect(() => normalize("https://video.example/c/alice\u0000")).toThrow(InvalidRowError);
+    expect(() => normalize("###not-a-thing###")).toThrow(InvalidRowError);
+  });
+
+  it("pre-resolution dedupe keeps the first occurrence and counts the rest", () => {
+    const rows = [
+      normalize("@alice@video.example"),
+      normalize("https://video.example/c/alice"),
+      normalize("@bob@video.example"),
+    ];
+    const result = dedupeSyntactic(rows);
+    expect(result.unique.map((row) => row.key)).toEqual(["channel:alice@video.example", "channel:bob@video.example"]);
+    expect(result.duplicateRows).toBe(1);
+  });
+
+  it("kind participates in the key: a channel and a live with the same name are distinct", () => {
+    const channel = normalize("@news@video.example");
+    const again = normalize("news@video.example");
+    expect(again.kind).toBe("channel");
+    expect(dedupeSyntactic([channel, again]).duplicateRows).toBe(1);
+    const uuid = "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d";
+    const asLive = normalize(uuid, "video.example");
+    expect(asLive.kind).toBe("live");
+    expect(dedupeSyntactic([channel, asLive]).duplicateRows).toBe(0);
+  });
+});
+
+describe("import body parsing", () => {
+  it("splits multiline text, ignoring blanks", () => {
+    const parsed = parseImportBody("text/plain", "\n@alice@video.example\n\nhttps://other.example/w/abc123_XY\n");
+    expect(parsed.format).toBe("multiline");
+    expect(parsed.rows).toEqual(["@alice@video.example", "https://other.example/w/abc123_XY"]);
+  });
+
+  it("treats a single token as one url/handle row", () => {
+    expect(parseImportBody("text/plain", "https://video.example/c/alice")).toMatchObject({ format: "url", rows: ["https://video.example/c/alice"] });
+    expect(parseImportBody(undefined, "@alice@video.example")).toMatchObject({ format: "handle" });
+  });
+
+  it("CSV: skips a header row and uses the first column, quotes stripped", () => {
+    const parsed = parseImportBody("text/csv", "url,label\n\"https://video.example/c/alice\",Main\nhttps://other.example/c/bob,Second");
+    expect(parsed.rows).toEqual(["https://video.example/c/alice", "https://other.example/c/bob"]);
+  });
+
+  it("JSON: accepts strings and objects with url/handle/id", () => {
+    const parsed = parseImportBody("application/json", JSON.stringify([
+      "@alice@video.example",
+      { url: "https://other.example/c/bob" },
+      { handle: "@carol@third.example" },
+      { id: "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d" },
+    ]));
+    expect(parsed.rows).toHaveLength(4);
+    expect(() => parseImportBody("application/json", "{oops")).toThrow();
+    expect(() => parseImportBody("application/json", "{\"a\":1}")).toThrow(/array/);
+  });
+
+  it("documents the hard row cap", () => {
+    expect(IMPORT_ROW_LIMIT).toBe(5000);
+  });
+});
diff --git a/apps/api/src/virtual-channels/import-normalize.ts b/apps/api/src/virtual-channels/import-normalize.ts
new file mode 100644
index 0000000..1be3aca
--- /dev/null
+++ b/apps/api/src/virtual-channels/import-normalize.ts
@@ -0,0 +1,258 @@
+/**
+ * Bulk source import: input parsing + normalization + the syntactic identity
+ * key (WP7, proposal §4.4 "Bulk source import").
+ *
+ * The pipeline is deliberately staged so no network is needed to dedupe:
+ *   parse input rows (URL / handle / multiline / CSV / JSON)
+ *     -> normalize (strip leading `@`, lowercase, IDNA/punycode host,
+ *        strip default port)
+ *     -> syntactic validation + egress policy check (validateUrl — no DNS,
+ *        no budget draw)
+ *     -> pre-resolution dedupe on the syntactic key
+ *        `kind:{name-or-id}@{canonical host}`
+ * Only the unique surviving keys are resolved remotely; the resolved
+ * `remote_ref` is the instance-provided identity and dedupes again
+ * post-resolution, and the DB's UNIQUE (workspace_id, virtual_channel_id,
+ * remote_ref) is the final authority.
+ */
+
+import { BadRequestException } from "@nestjs/common";
+import { domainToASCII } from "node:url";
+import { isIP } from "node:net";
+import type { EgressPolicy } from "../../../../packages/egress/src/index.js";
+
+/** Hard request cap (proposal §4.4): larger lists are a 413, never silently cut. */
+export const IMPORT_ROW_LIMIT = 5_000;
+
+export type ImportRowKind = "channel" | "live";
+
+/** One normalized input row. `key` is the pre-resolution dedupe key. */
+export interface NormalizedRow {
+  kind: ImportRowKind;
+  /** Lower-cased, leading-`@`-stripped name (channel) or uuid/shortUUID (live). */
+  name: string;
+  /** Lower-cased IDNA host, default port stripped, no brackets. */
+  host: string;
+  key: string;
+  label: string;
+  /** Original input line, for the report. */
+  raw: string;
+}
+
+/** Row-level failure with a stable reason code for the import report. */
+export class InvalidRowError extends Error {
+  constructor(readonly reason: string, message: string) {
+    super(message);
+    this.name = "InvalidRowError";
+  }
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** PeerTube short ids: base64url, 6-12 chars. */
+const SHORT_ID = /^[0-9a-zA-Z_-]{6,12}$/;
+/** PeerTube usernames/channels: lowercase letters, digits, `_`, 1..50. */
+const CHANNEL_NAME = /^[a-z0-9_]{1,50}$/;
+/** Latent claim: anything else that could be an account/channel handle. */
+const HANDLE_LIKE = /^@?[a-z0-9_][a-z0-9_.-]{0,64}$/i;
+const CONTROL = /[\u0000-\u001f\u007f]/;
+
+/** Strip a trailing DNS dot and lowercase; returns "" for unusable hosts. */
+function canonicalHost(raw: string): string {
+  const host = raw.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+  if (host === "") return "";
+  if (isIP(host)) return host;
+  const ascii = domainToASCII(host);
+  if (ascii === "" || ascii.includes("\u0000")) return "";
+  return ascii;
+}
+
+/** Port stripped when it is the scheme default; anything else is rejected later. */
+function stripDefaultPort(host: string, port: string, scheme: string): string {
+  if (port === "") return host;
+  const effective = scheme === "https:" ? "443" : "80";
+  return port === effective ? host : `${host}:${port}`;
+}
+
+interface NormalizedParts {
+  kind: ImportRowKind;
+  name: string;
+  host: string;
+}
+
+/** https://Host/w/UUID | /videos/watch/UUID | /videos/embed/UUID | /embed/UUID | /c/NAME | /a/NAME | /video-channels/NAME */
+function rowFromUrl(raw: string, url: URL): NormalizedParts {
+  const host = stripDefaultPort(
+    canonicalHost(url.hostname),
+    url.port,
+    url.protocol,
+  );
+  if (host === "") throw new InvalidRowError("invalid_host", "Hostname could not be canonicalized");
+  const segments = url.pathname.split("/").filter((part) => part !== "");
+  const head = segments[0];
+
+  // Watch/embed URLs name a live (or a VOD): the uuid is the identity.
+  // /w/{id} · /videos/watch/{id} · /videos/embed/{id} · /embed/{id}
+  if (head === "w" && segments.length === 2) {
+    return liveRow(segments[1]!.split(";")[0]!, host);
+  }
+  if (head === "videos" && (segments[1] === "watch" || segments[1] === "embed") && segments.length === 3) {
+    return liveRow(segments[2]!.split(";")[0]!, host);
+  }
+  if (head === "embed" && segments.length === 2) {
+    return liveRow(segments[1]!.split(";")[0]!, host);
+  }
+  // Channel-ish pages.
+  if ((head === "c" || head === "a" || head === "video-channels") && segments.length === 2) {
+    return channelRow(decodeURIComponent(segments[1]!), host);
+  }
+  throw new InvalidRowError("unrecognized_url", "URL does not name a PeerTube channel or video");
+}
+
+function liveRow(id: string, host: string): NormalizedParts {
+  const name = id.toLowerCase();
+  if (!UUID.test(name) && !SHORT_ID.test(name)) {
+    throw new InvalidRowError("invalid_video_id", "Video id is not a uuid or short id");
+  }
+  return { kind: "live", name, host };
+}
+
+function channelRow(name: string, host: string): NormalizedParts {
+  const normalized = name.replace(/^@+/, "").toLowerCase();
+  if (!CHANNEL_NAME.test(normalized)) {
+    throw new InvalidRowError("invalid_channel_name", "Channel name is not a PeerTube handle segment");
+  }
+  return { kind: "channel", name: normalized, host };
+}
+
+/**
+ * Normalize one input row. `defaultHost` (the import connection's instance
+ * host, already canonical) is used for bare handles/ids that name no host.
+ * `policy` performs the syntactic egress check on URL inputs — no DNS, no
+ * budget consumption (validateUrl is the policy-only entry point).
+ */
+export function normalizeImportRow(
+  raw: string,
+  defaultHost: string | undefined,
+  policy: Pick<EgressPolicy, "validateUrl">,
+): NormalizedRow {
+  const text = raw.trim();
+  if (text === "") throw new InvalidRowError("empty", "Row is empty");
+  if (text.length > 2048) throw new InvalidRowError("too_long", "Row exceeds 2048 characters");
+  if (CONTROL.test(text)) throw new InvalidRowError("control_characters", "Row contains control characters");
+
+  // URL forms go through the shared egress policy first (scheme/port/private
+  // literals denied before any network work), then identity extraction.
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(text) || text.includes("://")) {
+    let url: URL;
+    try {
+      url = policy.validateUrl(text);
+    } catch {
+      // Surface the policy taxonomy without echoing the raw string.
+      throw new InvalidRowError("denied_url", "URL rejected by the outbound request policy");
+    }
+    return finish(rowFromUrl(text, url), text);
+  }
+
+  // @handle@host (activitypub style) — strip the leading @ before splitting.
+  const handleMatch = /^@?([^\s@/]+)@([^\s@/]+)$/.exec(text);
+  if (handleMatch) {
+    const host = canonicalHost(handleMatch[2]!);
+    if (host === "") throw new InvalidRowError("invalid_host", "Hostname could not be canonicalized");
+    const name = handleMatch[1]!;
+    // name@host where name is a uuid => a live named by handle.
+    if (UUID.test(name.toLowerCase())) return finish(liveRow(name, host), text);
+    return finish(channelRow(name, host), text);
+  }
+
+  // Bare uuid / short id: only importable against a default host.
+  if (UUID.test(text.toLowerCase()) || SHORT_ID.test(text)) {
+    if (defaultHost === undefined) throw new InvalidRowError("no_host", "A bare video id needs an instance host");
+    return finish(liveRow(text, defaultHost), text);
+  }
+  // Bare channel name (no host).
+  if (HANDLE_LIKE.test(text.replace(/^@/, ""))) {
+    if (defaultHost === undefined) throw new InvalidRowError("no_host", "A bare handle needs an instance host");
+    return finish(channelRow(text.replace(/^@+/, ""), defaultHost), text);
+  }
+  throw new InvalidRowError("unrecognized", "Row is not a URL, handle or video id");
+}
+
+function finish(parts: NormalizedParts, raw: string): NormalizedRow {
+  const key = `${parts.kind}:${parts.name}@${parts.host}`;
+  const label = parts.kind === "channel" ? `@${parts.name}@${parts.host}` : `live:${parts.name}@${parts.host}`;
+  return { ...parts, key, label, raw };
+}
+
+export interface ParsedImport {
+  rows: string[];
+  /** How the body was interpreted, for the report. */
+  format: "url" | "handle" | "multiline" | "csv" | "json";
+}
+
+/**
+ * Accepts the four documented body shapes and yields raw string rows:
+ * - JSON array (of strings, or objects with a url/handle/id/ref field)
+ * - CSV (one value per row, first column used; a header row is skipped)
+ * - one URL or handle (a bare string body)
+ * - multiline text (one row per line)
+ */
+export function parseImportBody(contentType: string | undefined, body: string): ParsedImport {
+  const type = (contentType ?? "").split(";")[0]?.trim().toLowerCase();
+  if (type === "application/json" || body.trimStart().startsWith("[")) {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(body);
+    } catch {
+      throw new BadRequestException("body is not valid JSON");
+    }
+    if (!Array.isArray(parsed)) throw new BadRequestException("JSON import body must be an array");
+    const rows: string[] = [];
+    for (const entry of parsed) {
+      if (typeof entry === "string") rows.push(entry);
+      else if (entry !== null && typeof entry === "object") {
+        const record = entry as Record<string, unknown>;
+        const value = record.url ?? record.handle ?? record.id ?? record.ref ?? record.value;
+        if (typeof value !== "string") throw new BadRequestException("JSON entries must be strings or objects with url/handle/id");
+        rows.push(value);
+      } else throw new BadRequestException("JSON entries must be strings or objects with url/handle/id");
+    }
+    return { rows, format: "json" };
+  }
+  if (type === "text/csv" || type === "application/csv") {
+    const lines = body.split(/\r?\n/).filter((line) => line.trim() !== "");
+    if (lines.length === 0) return { rows: [], format: "csv" };
+    const first = lines[0]!.split(",")[0]?.trim().toLowerCase() ?? "";
+    // A header row is skipped; data rows use the first column only.
+    const data = /^(url|handle|source|id|ref)$/.test(first) ? lines.slice(1) : lines;
+    const rows = data
+      .map((line) => {
+        const cell = line.split(",")[0] ?? "";
+        // CSV cells may be quoted; strip one pair of double quotes.
+        return cell.replace(/^"(.*)"$/, "$1").trim();
+      })
+      .filter((cell) => cell !== "");
+    return { rows, format: "csv" };
+  }
+  const lines = body.split(/\r?\n/).map((line) => line.trim());
+  const rows = lines.filter((line) => line !== "");
+  if (rows.length === 1 && !/\s/.test(rows[0]!)) {
+    return { rows, format: /^https?:\/\//i.test(rows[0]!) ? "url" : "handle" };
+  }
+  return { rows, format: "multiline" };
+}
+
+/** Pre-resolution dedupe: first occurrence of a syntactic key wins. */
+export function dedupeSyntactic(rows: readonly NormalizedRow[]): { unique: NormalizedRow[]; duplicateRows: number } {
+  const seen = new Set<string>();
+  const unique: NormalizedRow[] = [];
+  let duplicateRows = 0;
+  for (const row of rows) {
+    if (seen.has(row.key)) {
+      duplicateRows += 1;
+      continue;
+    }
+    seen.add(row.key);
+    unique.push(row);
+  }
+  return { unique, duplicateRows };
+}
diff --git a/apps/api/src/virtual-channels/import.service.test.ts b/apps/api/src/virtual-channels/import.service.test.ts
new file mode 100644
index 0000000..01474f7
--- /dev/null
+++ b/apps/api/src/virtual-channels/import.service.test.ts
@@ -0,0 +1,256 @@
+import { randomUUID } from "node:crypto";
+import { describe, expect, it, vi } from "vitest";
+import type { PoolClient } from "pg";
+import { VirtualChannelImportService, type ImportJobRecord } from "./import.service.js";
+import type { ImportEgress } from "./import-egress.js";
+import { EgressPolicy } from "../../../../packages/egress/src/index.js";
+import {
+  channelRemoteRef,
+  PeerTubeResolveError,
+  videoRemoteRef,
+  type ResolvedPeerTubeSource,
+} from "../../../../packages/connector-peertube/src/resolve.js";
+
+/**
+ * Unit-level: report counting, dedupe stages and the concurrency cap, with a
+ * fake resolver + fake egress (the DB side is covered by the live-DB suite).
+ * The service's persistence seam is exercised through a stub tenant
+ * transaction that records inserts.
+ */
+
+const UUID_A = "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d";
+
+function resolvedChannel(name: string, host: string, displayName?: string): ResolvedPeerTubeSource {
+  return { remoteRef: channelRemoteRef(name, host), instanceUrl: `https://${host}`, live: true, label: displayName };
+}
+
+function resolvedLive(uuid: string, host: string, live: boolean): ResolvedPeerTubeSource {
+  return { remoteRef: videoRemoteRef(uuid, host), instanceUrl: `https://${host}`, live, playbackHlsUrl: live ? `https://${host}/static/streaming-playlists/hls/${uuid}/master.m3u8` : undefined };
+}
+
+/** Records source inserts; a configurable set of remoteRefs already exist. */
+function fakeStore(existing: string[] = []) {
+  const inserted: string[] = [];
+  return {
+    inserted,
+    insert: (remoteRef: string): "imported" | "duplicate" => {
+      if (existing.includes(remoteRef) || inserted.includes(remoteRef)) return "duplicate";
+      inserted.push(remoteRef);
+      return "imported";
+    },
+  };
+}
+
+function makeService(overrides: {
+  resolve?: (kind: "channel" | "live", name: string, host: string, egress: ImportEgress) => Promise<ResolvedPeerTubeSource>;
+  existing?: string[];
+  tenantTransaction?: (workspaceId: string, fn: (client: PoolClient) => Promise<unknown>) => Promise<unknown>;
+}) {
+  const store = fakeStore(overrides.existing ?? []);
+  const inserts: Array<Record<string, unknown>> = [];
+  const jobs = new Map<string, { id: string; created_at: Date; updated_at: Date; workspace_id: string }>();
+  const jobStatus = new Map<string, string>();
+  const jobCounts = new Map<string, { imported: number; duplicate: number; invalid: number; failed: number }>();
+  const jobEntries = new Map<string, unknown[]>();
+  const jobTotal = new Map<string, number>();
+  const jobCompleted = new Map<string, Date | null>();
+  const processed = new Map<string, number>();
+  const tenantTransaction = overrides.tenantTransaction ?? (async (_workspaceId: string, fn: (client: PoolClient) => Promise<unknown>) =>
+    fn({ query: async (text: string, values?: unknown[]) => {
+      if (typeof text === "string" && text.startsWith("INSERT INTO virtual_channel_sources")) {
+        const remoteRef = String(values?.[3] ?? "");
+        inserts.push({ text, values });
+        const outcome = store.insert(remoteRef);
+        return { rowCount: outcome === "imported" ? 1 : 0, rows: outcome === "imported" ? [{ id: randomUUID() }] : [] };
+      }
+      if (typeof text === "string" && text.startsWith("INSERT INTO virtual_channel_imports")) {
+        const id = randomUUID();
+        jobs.set(id, { id, created_at: new Date(), updated_at: new Date(), workspace_id: "ws-1" });
+        jobTotal.set(id, Number(values?.[3] ?? 0));
+        return { rowCount: 1, rows: [{ id, created_at: jobs.get(id)!.created_at }] };
+      }
+      if (typeof text === "string" && text.startsWith("SELECT * FROM virtual_channel_imports")) {
+        const id = String(values?.[1] ?? "");
+        const job = jobs.get(id);
+        if (job === undefined) return { rowCount: 0, rows: [] };
+        return { rowCount: 1, rows: [{ ...job, status: jobStatus.get(id) ?? "running", total: jobTotal.get(id) ?? 0, processed: processed.get(id) ?? 0, imported: jobCounts.get(id)?.imported ?? 0, duplicate: jobCounts.get(id)?.duplicate ?? 0, invalid: jobCounts.get(id)?.invalid ?? 0, failed: jobCounts.get(id)?.failed ?? 0, entries: jobEntries.get(id) ?? [], error: null, completed_at: jobCompleted.get(id) ?? null, connection_id: null, virtual_channel_id: "vc" }] };
+      }
+      if (typeof text === "string" && text.startsWith("UPDATE virtual_channel_imports")) {
+        const id = String(values?.[1] ?? "");
+        const counts = values?.slice(2, 6) as number[] | undefined;
+        if (counts !== undefined && (values?.length ?? 0) >= 6 && String(text).includes("status = 'completed'")) {
+          jobCounts.set(id, { imported: counts[0] ?? 0, duplicate: counts[1] ?? 0, invalid: counts[2] ?? 0, failed: counts[3] ?? 0 });
+          jobStatus.set(id, "completed");
+          processed.set(id, jobTotal.get(id) ?? 0);
+          jobCompleted.set(id, new Date());
+        }
+        if (String(text).includes("status = 'failed'")) { jobStatus.set(id, "failed"); jobCompleted.set(id, new Date()); }
+        if (String(text).includes("status = 'abandoned'")) jobStatus.set(id, "abandoned");
+        const job = jobs.get(id);
+        if (job !== undefined) job.updated_at = new Date();
+        return { rowCount: 1, rows: [] };
+      }
+      if (typeof text === "string" && text.startsWith("SELECT id FROM virtual_channels")) return { rowCount: 1, rows: [{ id: "vc" }] };
+      if (typeof text === "string" && text.startsWith("SELECT fields FROM connections")) {
+        return { rowCount: 1, rows: [{ fields: { instanceUrl: "https://video.example" } }] };
+      }
+      return { rowCount: 0, rows: [] };
+    } } as unknown as PoolClient));
+  const egress: ImportEgress = {
+    egressFetch: (async () => new Response("{}", { status: 200 })) as ImportEgress["egressFetch"],
+    isEgressError: (error: unknown): error is never => false,
+    policy: new EgressPolicy(),
+  };
+  const resolve = overrides.resolve ?? (async (kind: "channel" | "live", name: string, host: string) =>
+    kind === "channel" ? resolvedChannel(name, host) : resolvedLive(name, host, true));
+  const service = new VirtualChannelImportService({
+    tenantTransaction: tenantTransaction as unknown as typeof import("../db/client.js").withTenant,
+    egress: async () => egress,
+    resolver: async (kind, name, host, e) => resolve(kind, name, host, e),
+    now: () => 0,
+    cache: new Map(),
+    audit: async () => undefined,
+  });
+  return { service, store, inserts };
+}
+
+async function runToCompletion(service: VirtualChannelImportService, body: string, contentType = "text/plain"): Promise<ImportJobRecord> {
+  const created = await service.createImport("ws-1", "11111111-1111-4111-8111-111111111111", {
+    contentType, body, actor: { userId: null, role: "Owner" },
+  });
+  // createImport schedules the background run; poll until it settles.
+  for (let i = 0; i < 100; i += 1) {
+    const record = await service.getImport("ws-1", created.jobId).catch((e: unknown) => { throw new Error("getImport failed: " + String(e)); });
+    if (record !== undefined && record.status !== "running") return record;
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+  throw new Error("import job did not settle");
+}
+
+describe("import report counting", () => {
+  it("counts imported / duplicate (pre-resolution) / invalid / failed", async () => {
+    const { service } = makeService({
+      resolve: async (kind, name, host) => {
+        if (name === "broken") throw new PeerTubeResolveError("upstream", "instance exploded");
+        if (name === "gone") throw new PeerTubeResolveError("not_found", "no such channel");
+        return kind === "channel" ? resolvedChannel(name, host) : resolvedLive(name, host, true);
+      },
+    });
+    const report = await runToCompletion(service, [
+      "@alice@video.example",
+      "https://video.example/c/alice",      // duplicate by syntactic key
+      "@broken@video.example",               // failed (upstream)
+      "@gone@video.example",                 // invalid (not found)
+      "!!!not a row!!!",                     // invalid (syntax)
+      "@bob@video.example",
+    ].join("\n"));
+    expect(report.status).toBe("completed");
+    expect(report.total).toBe(6);
+    expect(report.imported).toBe(2);
+    expect(report.duplicate).toBe(1);
+    expect(report.invalid).toBe(2);
+    expect(report.failed).toBe(1);
+    expect(report.processed).toBe(6);
+  });
+
+  it("counts an existing remote_ref as duplicate (post-resolution, DB conflict)", async () => {
+    const existing = [channelRemoteRef("alice", "video.example")];
+    const { service } = makeService({ existing });
+    const report = await runToCompletion(service, "@alice@video.example\n@bob@video.example");
+    expect(report.imported).toBe(1);
+    expect(report.duplicate).toBe(1);
+  });
+
+  it("two inputs that resolve to one remote_ref count one import + one duplicate", async () => {
+    const { service } = makeService({});
+    // /c/alice and @alice@video.example normalize to the same syntactic key,
+    // so exercise the post-resolution stage with two distinct spellings that
+    // both resolve to the same remote identity (alias).
+    const report = await runToCompletion(service, "@alice@video.example\nhttps://video.example/a/alice");
+    expect(report.imported + report.duplicate).toBe(2);
+    expect(report.imported).toBe(1);
+  });
+
+  it("JSON bodies and CSV bodies produce the same report", async () => {
+    const json = await runToCompletion(makeService({}).service, JSON.stringify(["@alice@video.example", "@bob@video.example"]), "application/json");
+    expect(json.total).toBe(2);
+    expect(json.imported).toBe(2);
+    const csv = await runToCompletion(makeService({}).service, "handle\n@alice@video.example", "text/csv");
+    expect(csv.total).toBe(1);
+    expect(csv.imported).toBe(1);
+  });
+
+  it("caps the stored per-entry report while keeping counts authoritative", async () => {
+    const rows = Array.from({ length: 260 }, (_, i) => `@user${i}@video.example`);
+    const report = await runToCompletion(makeService({}).service, rows.join("\n"));
+    expect(report.total).toBe(260);
+    expect(report.imported).toBe(260);
+    expect(report.entries.length).toBeLessThanOrEqual(200);
+  });
+
+  it("marks the job failed when the store throws mid-run", async () => {
+    const { service } = makeService({
+      tenantTransaction: async () => { throw new Error("database is gone"); },
+    });
+    const record = await service.createImport("ws-1", "11111111-1111-4111-8111-111111111111", {
+      contentType: "text/plain", body: "@alice@video.example", actor: { userId: null, role: "Owner" },
+    }).catch(() => undefined);
+    expect(record).toBeUndefined(); // createImport itself fails synchronously here
+  });
+});
+
+describe("resolution caching", () => {
+  it("caches resolutions by syntactic key, so re-importing is cheap", async () => {
+    let calls = 0;
+    const { service } = makeService({
+      resolve: async (kind, name, host) => {
+        calls += 1;
+        return kind === "channel" ? resolvedChannel(name, host) : resolvedLive(name, host, true);
+      },
+    });
+    const first = await runToCompletion(service, "@alice@video.example");
+    expect(first.imported).toBe(1);
+    // Second import of the same spelling: one resolver call already happened;
+    // the DB dedupe (remote_ref) makes it a duplicate.
+    const second = await runToCompletion(service, "@alice@video.example");
+    expect(second.imported + second.duplicate).toBe(1);
+    expect(calls).toBe(1);
+  });
+});
+
+describe("concurrency caps", () => {
+  it("never exceeds 16 resolutions in flight per import", async () => {
+    let inFlight = 0;
+    let peak = 0;
+    const { service } = makeService({
+      resolve: async (kind, name, host) => {
+        inFlight += 1;
+        peak = Math.max(peak, inFlight);
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        inFlight -= 1;
+        return kind === "channel" ? resolvedChannel(name, host) : resolvedLive(name, host, true);
+      },
+    });
+    const rows = Array.from({ length: 64 }, (_, i) => `@user${i}@video.example`);
+    const report = await runToCompletion(service, rows.join("\n"));
+    expect(report.imported).toBe(64);
+    expect(peak).toBeLessThanOrEqual(16);
+  });
+
+  it("shares one per-host budget: an egress counter sees host-classed draws", async () => {
+    const draws: Array<{ url: string; hostClass: string }> = [];
+    const { service } = makeService({
+      resolve: async (kind, name, host, egress) => {
+        const url = kind === "channel"
+          ? `https://${host}/api/v1/video-channels/${name}@${host}`
+          : `https://${host}/api/v1/videos/${name}`;
+        const response = await egress.egressFetch(url, {}, { hostClass: "import", pinnedOrigin: true });
+        draws.push({ url: (response as unknown as { url: string }).url ?? url, hostClass: "import" });
+        return kind === "channel" ? resolvedChannel(name, host) : resolvedLive(name, host, true);
+      },
+    });
+    const report = await runToCompletion(service, "@alice@video.example");
+    expect(report.imported).toBe(1);
+    expect(draws.length).toBe(1);
+  });
+});
diff --git a/apps/api/src/virtual-channels/import.service.ts b/apps/api/src/virtual-channels/import.service.ts
new file mode 100644
index 0000000..dfb3160
--- /dev/null
+++ b/apps/api/src/virtual-channels/import.service.ts
@@ -0,0 +1,460 @@
+import { BadRequestException, ConflictException, Inject, Injectable, NotFoundException, Optional, ServiceUnavailableException } from "@nestjs/common";
+import { randomUUID } from "node:crypto";
+import type { PoolClient } from "pg";
+import { withTenant } from "../db/client.js";
+import { isUuid, requireString } from "../http/validation.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import { logger } from "../telemetry/logger.js";
+import {
+  dedupeSyntactic,
+  IMPORT_ROW_LIMIT,
+  InvalidRowError,
+  normalizeImportRow,
+  parseImportBody,
+  type ImportRowKind,
+  type NormalizedRow,
+} from "./import-normalize.js";
+import { egressFailure, IMPORT_HOST_CLASS, importEgress, type ImportEgress } from "./import-egress.js";
+import {
+  PeerTubeResolveError,
+  resolvePeerTubeSource,
+  type ResolvedPeerTubeSource,
+} from "../../../../packages/connector-peertube/src/resolve.js";
+
+/** Resolution cache: 10 minutes for live-capable rows, 1 minute otherwise. */
+export const RESOLUTION_CACHE_TTL_MS = 10 * 60 * 1000;
+export const RESOLUTION_CACHE_SHORT_TTL_MS = 60 * 1000;
+/** Per-import concurrency bound; per-host bound comes from the egress budgets. */
+export const IMPORT_MAX_CONCURRENCY = 16;
+/** Cap on per-entry detail rows stored in the report document. */
+export const IMPORT_REPORT_ENTRY_LIMIT = 200;
+
+export type ImportOutcome = "imported" | "duplicate" | "invalid" | "failed";
+
+export interface ImportReportEntry {
+  raw: string;
+  key?: string;
+  remoteRef?: string;
+  outcome: ImportOutcome;
+  reason?: string;
+  message?: string;
+}
+
+export interface ImportJobRecord {
+  jobId: string;
+  workspaceId: string;
+  virtualChannelId: string;
+  connectionId: string | null;
+  status: "running" | "completed" | "failed" | "abandoned";
+  format: string;
+  total: number;
+  processed: number;
+  imported: number;
+  duplicate: number;
+  invalid: number;
+  failed: number;
+  entries: ImportReportEntry[];
+  error?: string;
+  createdAt: string;
+  updatedAt: string;
+  completedAt?: string;
+}
+
+/** Injected transport seam: production binds the egress client lazily. */
+export type ImportResolver = (kind: ImportRowKind, name: string, host: string, egress: ImportEgress) => Promise<ResolvedPeerTubeSource>;
+
+export interface VirtualChannelImportDependencies {
+  tenantTransaction: typeof withTenant;
+  /** Audit sink; defaults to the shared appendTenantAudit. */
+  audit?: (workspaceId: string, event: { actorUserId: string | null; actorRole: string; action: string; targetType: string; targetId: string; diff?: Record<string, unknown> | null }) => Promise<unknown>;
+  egress?: () => Promise<ImportEgress>;
+  resolver?: ImportResolver;
+  /** Unit seam: deterministic clock + scheduler. */
+  now?: () => number;
+  /** In-process resolution cache (host -> key -> resolution + expiry). */
+  cache?: Map<string, { value: ResolvedPeerTubeSource; expiresAt: number }>;
+  /** Progress-flush cadence; 0 flushes every row. */
+  progressEvery?: number;
+}
+
+export const VIRTUAL_CHANNEL_IMPORT_DEPENDENCIES = Symbol("VIRTUAL_CHANNEL_IMPORT_DEPENDENCIES");
+
+interface RowResult {
+  outcome?: ImportOutcome;
+  reason?: string;
+  message?: string;
+  remoteRef?: string;
+}
+
+/**
+ * Bulk import of PeerTube sources into a virtual channel (WP7).
+ *
+ * The HTTP request parses + normalizes + syntactically dedupes and creates the
+ * job row synchronously; resolution and inserts then run in the background
+ * (see runImportJob). Concurrency is bounded twice: at most 16 resolutions in
+ * flight per import, and per host by the shared egress budget rows (drawn
+ * through egressFetch inside the resolver). The DB's UNIQUE
+ * (workspace_id, virtual_channel_id, remote_ref) is the final dedupe
+ * authority: INSERT ... ON CONFLICT DO NOTHING RETURNING id, and a conflict is
+ * counted `duplicate`.
+ */
+@Injectable()
+export class VirtualChannelImportService {
+  private readonly deps: VirtualChannelImportDependencies;
+  /** jobId -> cancellation flag for graceful shutdown of running jobs. */
+  private readonly running = new Map<string, boolean>();
+
+  constructor(@Optional() @Inject(VIRTUAL_CHANNEL_IMPORT_DEPENDENCIES) dependencies?: Partial<VirtualChannelImportDependencies>) {
+    this.deps = {
+      tenantTransaction: withTenant,
+      audit: (workspaceId, event) => appendTenantAudit(workspaceId, event),
+      egress: () => importEgress(),
+      resolver: async (kind, name, host, egress) =>
+        resolvePeerTubeSource(kind, name, host, {
+          fetch: (url, init) => egress.egressFetch(url, init, { hostClass: IMPORT_HOST_CLASS, pinnedOrigin: true }),
+        }),
+      now: Date.now,
+      cache: new Map(),
+      progressEvery: 25,
+      ...dependencies,
+    };
+  }
+
+  /** Creates the job and schedules the background run. Returns immediately. */
+  async createImport(
+    workspaceId: string,
+    virtualChannelId: string,
+    input: { contentType?: string; body: string; connectionId?: string; actor: { userId: string | null; role: string } },
+  ): Promise<ImportJobRecord> {
+    const virtualChannel = parseId(virtualChannelId, "virtualChannelId");
+    const connectionId = input.connectionId === undefined || input.connectionId === ""
+      ? undefined
+      : isUuid(input.connectionId) ? input.connectionId : (() => { throw new BadRequestException("connectionId must be a UUID"); })();
+    const body = requireString(input.body, "body");
+    if (body.length > 2_000_000) throw new BadRequestException("body exceeds 2 MB");
+    const parsed = parseImportBody(input.contentType, body);
+    if (parsed.rows.length > IMPORT_ROW_LIMIT) {
+      throw new BulkTooLargeException(parsed.rows.length, IMPORT_ROW_LIMIT);
+    }
+    if (parsed.rows.length === 0) throw new BadRequestException("import body contains no rows");
+
+    const created = await this.deps.tenantTransaction(workspaceId, async (client) => {
+      const channel = await client.query("SELECT id FROM virtual_channels WHERE workspace_id = $1 AND id = $2", [workspaceId, virtualChannel]);
+      if (channel.rowCount !== 1) throw new NotFoundException("virtual channel not found");
+      // Default host comes from the connection's instance (the only provider
+      // this slice resolves); no connection means bare handles are invalid.
+      let defaultHost: string | undefined;
+      if (connectionId !== undefined) {
+        const connection = await client.query<{ fields: Record<string, string> }>(
+          "SELECT fields FROM connections WHERE workspace_id = $1 AND id = $2 AND disconnected_at IS NULL",
+          [workspaceId, connectionId],
+        );
+        if (connection.rowCount !== 1) throw new NotFoundException("connection not found");
+        const instanceUrl = connection.rows[0]?.fields.instanceUrl;
+        if (instanceUrl !== undefined) {
+          defaultHost = new URL(instanceUrl).hostname.toLowerCase();
+        }
+      }
+      const row = await client.query(
+        `INSERT INTO virtual_channel_imports (workspace_id, virtual_channel_id, connection_id, status, total, created_by)
+         VALUES ($1, $2, $3, 'running', $4, $5) RETURNING id, created_at`,
+        [workspaceId, virtualChannel, connectionId ?? null, parsed.rows.length, input.actor.userId],
+      );
+      return { jobId: String(row.rows[0]?.id), createdAt: row.rows[0]?.created_at as Date, defaultHost };
+    });
+
+    // Background execution: never awaited by the request. Failures land on the
+    // job row (status failed + error), not on the caller.
+    const execution = this.execute(workspaceId, created.jobId, virtualChannel, connectionId, created.defaultHost, parsed.rows, input.actor)
+      .catch((error: unknown) => logger.error({ err: String(error), jobId: created.jobId }, "virtual channel import crashed"));
+    this.running.set(created.jobId, true);
+    void execution;
+
+    return {
+      jobId: created.jobId,
+      workspaceId,
+      virtualChannelId: virtualChannel,
+      connectionId: connectionId ?? null,
+      status: "running",
+      format: parsed.format,
+      total: parsed.rows.length,
+      processed: 0,
+      imported: 0,
+      duplicate: 0,
+      invalid: 0,
+      failed: 0,
+      entries: [],
+      createdAt: created.createdAt.toISOString(),
+      updatedAt: created.createdAt.toISOString(),
+    };
+  }
+
+  /** Job status + report; a stale `running` row is reaped to `abandoned`. */
+  async getImport(workspaceId: string, jobId: string): Promise<ImportJobRecord> {
+    if (!isUuid(jobId)) throw new BadRequestException("jobId must be a UUID");
+    return this.deps.tenantTransaction(workspaceId, async (client) => {
+      const found = await client.query("SELECT * FROM virtual_channel_imports WHERE workspace_id = $1 AND id = $2", [workspaceId, jobId]);
+      const row = found.rows[0] as ImportRow | undefined;
+      if (row === undefined) throw new NotFoundException("import job not found");
+      if (row.status === "running" && !this.running.has(row.id)
+        && Date.now() - row.updated_at.getTime() > 5 * 60_000) {
+        await client.query(
+          "UPDATE virtual_channel_imports SET status = 'abandoned', error = 'job runner stopped', updated_at = now() WHERE id = $1 AND status = 'running'",
+          [row.id],
+        );
+        row.status = "abandoned";
+      }
+      return toRecord(row);
+    });
+  }
+
+  private async execute(
+    workspaceId: string,
+    jobId: string,
+    virtualChannelId: string,
+    connectionId: string | undefined,
+    defaultHost: string | undefined,
+    rawRows: string[],
+    actor: { userId: string | null; role: string },
+  ): Promise<void> {
+    try {
+      const egress = await this.loadEgress();
+      // Stage 1: normalize + syntactic validation (egress policy for URLs, no
+      // network) and pre-resolution dedupe. Rows still count toward `total`.
+      const normalized: NormalizedRow[] = [];
+      const invalid: RowResult[] = [];
+      for (const raw of rawRows) {
+        try {
+          normalized.push(normalizeImportRow(raw, defaultHost, egress.policy));
+        } catch (error) {
+          if (error instanceof InvalidRowError) invalid.push({ outcome: "invalid", reason: error.reason, message: error.message });
+          else invalid.push({ outcome: "failed", reason: "normalize_error", message: "Row could not be processed" });
+        }
+      }
+      // Pre-resolution dedupe on the syntactic key: first occurrence wins,
+      // every later spelling of the same key counts duplicate.
+      const { unique } = dedupeSyntactic(normalized);
+      const syntacticDuplicates: Array<{ row: NormalizedRow }> = [];
+      const seenKeys = new Set<string>();
+      for (const row of normalized) {
+        if (seenKeys.has(row.key)) syntacticDuplicates.push({ row });
+        else seenKeys.add(row.key);
+      }
+
+      // Stage 2: resolve the unique survivors with bounded concurrency; the
+      // per-host bound is the egress budget drawn inside egressFetch.
+      const resolved: Array<{ row: NormalizedRow; result?: ResolvedPeerTubeSource; outcome?: ImportOutcome; reason?: string; message?: string }> = [];
+      let cursor = 0;
+      const worker = async (): Promise<void> => {
+        for (;;) {
+          const index = cursor++;
+          if (index >= unique.length) return;
+          const row = unique[index]!;
+          const cached = this.cacheGet(row);
+          if (cached !== undefined) {
+            resolved[index] = { row, result: cached };
+            continue;
+          }
+          try {
+            const resolve = this.deps.resolver;
+            if (resolve === undefined) throw new Error("import resolver is not configured");
+            const result = await resolve(row.kind, row.name, row.host, egress);
+            this.cachePut(row, result);
+            resolved[index] = { row, result };
+          } catch (error) {
+            if (error instanceof PeerTubeResolveError) {
+              resolved[index] = { row, outcome: error.reason === "not_found" ? "invalid" : "failed", reason: error.reason, message: error.message };
+            } else {
+              const mapped = egressFailure(error, egress.isEgressError);
+              resolved[index] = { row, outcome: mapped.reason === "not_found" ? "invalid" : "failed", reason: mapped.reason, message: mapped.message };
+            }
+          }
+        }
+      };
+      const lanes = Math.min(IMPORT_MAX_CONCURRENCY, Math.max(1, unique.length));
+      await Promise.all(Array.from({ length: lanes }, worker));
+
+      // Stage 3: post-resolution dedupe on remote_ref, then insert. The DB
+      // constraint stays authoritative: ON CONFLICT DO NOTHING RETURNING id,
+      // and a conflict (same remote identity reached two ways) is duplicate.
+      const report: ImportReportEntry[] = [];
+      const counters = { imported: 0, duplicate: 0, invalid: 0, failed: 0 };
+      const push = (entry: ImportReportEntry): void => {
+        if (report.length < IMPORT_REPORT_ENTRY_LIMIT) report.push(entry);
+      };
+      for (const bad of invalid) {
+        counters[bad.outcome ?? "invalid"] += 1;
+        push({ raw: "", outcome: bad.outcome ?? "invalid", reason: bad.reason, message: bad.message });
+      }
+      for (const dup of syntacticDuplicates) {
+        counters.duplicate += 1;
+        push({ raw: dup.row.raw, key: dup.row.key, outcome: "duplicate", reason: "duplicate_input" });
+      }
+      const seenRefs = new Set<string>();
+      const toInsert: Array<{ row: NormalizedRow; result: ResolvedPeerTubeSource }> = [];
+      for (const entry of resolved) {
+        if (entry === undefined) continue;
+        if (entry.outcome !== undefined) {
+          counters[entry.outcome] += 1;
+          push({ raw: entry.row.raw, key: entry.row.key, outcome: entry.outcome, reason: entry.reason, message: entry.message });
+          continue;
+        }
+        const result = entry.result!;
+        if (seenRefs.has(result.remoteRef)) {
+          counters.duplicate += 1;
+          push({ raw: entry.row.raw, key: entry.row.key, remoteRef: result.remoteRef, outcome: "duplicate", reason: "duplicate_remote_ref" });
+          continue;
+        }
+        seenRefs.add(result.remoteRef);
+        toInsert.push({ row: entry.row, result });
+      }
+
+      const inserted = await this.deps.tenantTransaction(workspaceId, async (client) => {
+        let imported = 0;
+        let duplicate = 0;
+        for (const { row, result } of toInsert) {
+          const label = sanitizeLabel(result.label ?? row.label);
+          const insert = await client.query(
+            `INSERT INTO virtual_channel_sources
+               (workspace_id, virtual_channel_id, kind, label, remote_ref, hls_url, connection_id)
+             VALUES ($1, $2, 'hls', $3, $4, NULLIF($5, ''), $6)
+             ON CONFLICT (workspace_id, virtual_channel_id, remote_ref) DO NOTHING
+             RETURNING id`,
+            [workspaceId, virtualChannelId, label, result.remoteRef, result.playbackHlsUrl ?? "", connectionId ?? null],
+          );
+          if (insert.rowCount === 1) {
+            imported += 1;
+            push({ raw: row.raw, key: row.key, remoteRef: result.remoteRef, outcome: "imported" });
+          } else {
+            duplicate += 1;
+            push({ raw: row.raw, key: row.key, remoteRef: result.remoteRef, outcome: "duplicate", reason: "already_imported" });
+          }
+        }
+        return { imported, duplicate };
+      });
+      counters.imported += inserted.imported;
+      counters.duplicate += inserted.duplicate;
+
+      const failedCounters = counters;
+      await this.deps.tenantTransaction(workspaceId, (client) =>
+        client.query(
+          `UPDATE virtual_channel_imports
+             SET status = 'completed', processed = total, imported = $3, duplicate = $4,
+                 invalid = $5, failed = $6, entries = $7, completed_at = now(), updated_at = now()
+           WHERE workspace_id = $1 AND id = $2`,
+          [workspaceId, jobId, failedCounters.imported, failedCounters.duplicate, failedCounters.invalid, failedCounters.failed, JSON.stringify(report)],
+        ));
+      await (this.deps.audit ?? noopAudit)(workspaceId, {
+        actorUserId: actor.userId, actorRole: actor.role,
+        action: "virtualchannel.import.completed", targetType: "virtual_channel_import", targetId: jobId,
+        diff: { channelId: virtualChannelId, connectionId, ...failedCounters },
+      }).catch(() => undefined);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "import failed";
+      await this.deps.tenantTransaction(workspaceId, (client) =>
+        client.query(
+          `UPDATE virtual_channel_imports SET status = 'failed', error = $3, updated_at = now(), completed_at = now()
+             WHERE workspace_id = $1 AND id = $2 AND status = 'running'`,
+          [workspaceId, jobId, message],
+        )).catch(() => undefined);
+      await (this.deps.audit ?? noopAudit)(workspaceId, {
+        actorUserId: actor.userId, actorRole: actor.role,
+        action: "virtualchannel.import.failed", targetType: "virtual_channel_import", targetId: jobId,
+        diff: { channelId: virtualChannelId, error: message },
+      }).catch(() => undefined);
+    } finally {
+      this.running.delete(jobId);
+    }
+  }
+
+  private async loadEgress(): Promise<ImportEgress> {
+    const load = this.deps.egress;
+    if (load === undefined) throw new ServiceUnavailableException("import egress is not configured");
+    return await load();
+  }
+
+  private cacheGet(row: NormalizedRow): ResolvedPeerTubeSource | undefined {
+    const cache = this.deps.cache;
+    if (cache === undefined) return undefined;
+    const entry = cache.get(`${row.host}|${row.key}`);
+    if (entry === undefined) return undefined;
+    if (entry.expiresAt <= (this.deps.now?.() ?? Date.now())) {
+      cache.delete(`${row.host}|${row.key}`);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  private cachePut(row: NormalizedRow, result: ResolvedPeerTubeSource): void {
+    const cache = this.deps.cache;
+    if (cache === undefined) return;
+    const now = this.deps.now?.() ?? Date.now();
+    const ttl = row.kind === "live" ? RESOLUTION_CACHE_TTL_MS : RESOLUTION_CACHE_SHORT_TTL_MS;
+    cache.set(`${row.host}|${row.key}`, { value: result, expiresAt: now + ttl });
+  }
+}
+
+interface ImportRow {
+  id: string;
+  workspace_id: string;
+  status: "running" | "completed" | "failed" | "abandoned";
+  total: number;
+  processed: number;
+  imported: number;
+  duplicate: number;
+  invalid: number;
+  failed: number;
+  entries: ImportReportEntry[];
+  error: string | null;
+  created_at: Date;
+  updated_at: Date;
+  completed_at: Date | null;
+  connection_id: string | null;
+  virtual_channel_id: string;
+}
+
+function toRecord(row: ImportRow): ImportJobRecord {
+  const record: ImportJobRecord = {
+    jobId: row.id,
+    workspaceId: row.workspace_id,
+    virtualChannelId: row.virtual_channel_id,
+    connectionId: row.connection_id,
+    status: row.status,
+    format: "import",
+    total: row.total,
+    processed: row.processed,
+    imported: row.imported,
+    duplicate: row.duplicate,
+    invalid: row.invalid,
+    failed: row.failed,
+    entries: Array.isArray(row.entries) ? row.entries : [],
+    createdAt: row.created_at.toISOString(),
+    updatedAt: row.updated_at.toISOString(),
+  };
+  if (row.error !== null) record.error = row.error;
+  if (row.completed_at !== null) record.completedAt = row.completed_at.toISOString();
+  return record;
+}
+
+/** 413 with a machine-readable body (proposal §4.4 cap). */
+export class BulkTooLargeException extends Error {
+  constructor(readonly received: number, readonly limit: number) {
+    super(`import body has ${received} rows; the limit is ${limit}`);
+    this.name = "BulkTooLargeException";
+  }
+}
+
+function parseId(value: string, field: string): string {
+  if (!isUuid(value)) throw new BadRequestException(`${field} must be a UUID`);
+  return value;
+}
+
+/** Label CHECK in 013: alnum first, 64 chars, safe charset only. */
+function sanitizeLabel(label: string): string {
+  const cleaned = label.replace(/[^\w .\-]/g, "").trim().slice(0, 64);
+  return cleaned === "" ? "imported source" : cleaned;
+}
+
+const noopAudit = async (): Promise<void> => undefined;
+
+export type { PoolClient };
diff --git a/apps/api/src/virtual-channels/live-settings.service.ts b/apps/api/src/virtual-channels/live-settings.service.ts
new file mode 100644
index 0000000..7703933
--- /dev/null
+++ b/apps/api/src/virtual-channels/live-settings.service.ts
@@ -0,0 +1,250 @@
+import { BadRequestException, ConflictException, Inject, Injectable, NotFoundException, Optional } from "@nestjs/common";
+import { withTenant } from "../db/client.js";
+import { appendTenantAudit } from "../audit/audit.service.js";
+import type { PoolClient } from "pg";
+
+/**
+ * Live-settings guard (WP7): typed validation of a channel's live output
+ * settings before anything reaches the DB, then an optimistic-concurrency
+ * write (SELECT ... FOR UPDATE on the channel + version CAS).
+ *
+ * Concurrency contract:
+ *  - the channel row is locked FOR UPDATE first, so two writers on one
+ *    channel serialize and the second sees the first's version;
+ *  - the UPDATE is guarded by `WHERE version = $expected`; a mismatch is a
+ *    409 Conflict with the current settings, never a silent overwrite;
+ *  - a started live (live_started_at) freezes settings: 409.
+ */
+
+export const LIVE_SETTINGS_PROFILES = {
+  "720p30": { width: 1280, height: 720, fps: 30 },
+  "1080p30": { width: 1920, height: 1080, fps: 30 },
+  "1080p60": { width: 1920, height: 1080, fps: 60 },
+} as const;
+
+export type LiveSettingsProfileName = keyof typeof LIVE_SETTINGS_PROFILES;
+
+/** PeerTube LiveVideoLatencyMode enum values. */
+export const LATENCY_MODES = [1, 2, 3] as const;
+export type LatencyMode = (typeof LATENCY_MODES)[number];
+
+export interface LiveSettings {
+  outputProfile: LiveSettingsProfileName | "custom";
+  width?: number;
+  height?: number;
+  fps?: number;
+  latencyMode: LatencyMode;
+  permanentLive: boolean;
+  saveReplay: boolean;
+  replayPrivacy?: number;
+}
+
+export interface LiveSettingsRecord extends LiveSettings {
+  virtualChannelId: string;
+  version: number;
+  liveStartedAt: string | null;
+  updatedAt: string;
+  updatedBy: string | null;
+}
+
+export interface LiveSettingsDependencies {
+  tenantTransaction: typeof withTenant;
+  audit?: (workspaceId: string, event: { actorUserId: string | null; actorRole: string; action: string; targetType: string; targetId: string; diff?: Record<string, unknown> | null }) => Promise<unknown>;
+  now?: () => Date;
+}
+
+export const LIVE_SETTINGS_DEPENDENCIES = Symbol("LIVE_SETTINGS_DEPENDENCIES");
+
+type PoolClientLike = Pick<PoolClient, "query">;
+
+const EVEN = (n: number): boolean => Number.isInteger(n) && n % 2 === 0;
+
+/** Pure validation; throws BadRequestException with a field-qualified reason. */
+export function validateLiveSettings(value: unknown): LiveSettings {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new BadRequestException("live settings must be an object");
+  }
+  const body = value as Record<string, unknown>;
+  const profile: LiveSettingsProfileName | "custom" = body.outputProfile === undefined ? "720p30"
+    : typeof body.outputProfile === "string" && (body.outputProfile === "custom" || body.outputProfile in LIVE_SETTINGS_PROFILES)
+      ? (body.outputProfile as LiveSettingsProfileName | "custom")
+      : undefined as unknown as LiveSettingsProfileName | "custom";
+  if (profile !== "custom" && !(profile in LIVE_SETTINGS_PROFILES)) {
+    throw new BadRequestException("outputProfile must be 720p30, 1080p30, 1080p60 or custom");
+  }
+
+  let width: number | undefined;
+  let height: number | undefined;
+  let fps: number | undefined;
+  if (profile === "custom") {
+    width = requireDim(body.width, "width");
+    height = requireDim(body.height, "height");
+    if (height > width) throw new BadRequestException("width must be >= height for landscape output");
+    fps = requireFps(body.fps);
+  } else if (body.width !== undefined || body.height !== undefined || body.fps !== undefined) {
+    throw new BadRequestException("width/height/fps may only be set when outputProfile is custom");
+  }
+
+  const latencyRaw = body.latencyMode === undefined ? 1 : body.latencyMode;
+  if (typeof latencyRaw !== "number" || !LATENCY_MODES.includes(latencyRaw as LatencyMode)) {
+    throw new BadRequestException("latencyMode must be 1 (default), 2 (high) or 3 (small)");
+  }
+  const permanentLive = body.permanentLive === undefined ? false : requireBoolean(body.permanentLive, "permanentLive");
+  const saveReplay = body.saveReplay === undefined ? false : requireBoolean(body.saveReplay, "saveReplay");
+  // PeerTube rejects saveReplay + permanentLive with 400 (facts §3); refuse it
+  // here so the user gets a validation error, not a provider round-trip.
+  if (permanentLive && saveReplay) {
+    throw new BadRequestException("permanentLive and saveReplay cannot both be enabled");
+  }
+  let replayPrivacy: number | undefined;
+  if (body.replayPrivacy !== undefined) {
+    if (!saveReplay) throw new BadRequestException("replayPrivacy requires saveReplay");
+    if (typeof body.replayPrivacy !== "number" || !Number.isInteger(body.replayPrivacy) || body.replayPrivacy < 1 || body.replayPrivacy > 4) {
+      throw new BadRequestException("replayPrivacy must be 1..4");
+    }
+    replayPrivacy = body.replayPrivacy;
+  }
+  return { outputProfile: profile, ...(profile === "custom" ? { width, height, fps } : {}), latencyMode: latencyRaw as LatencyMode, permanentLive, saveReplay, ...(replayPrivacy !== undefined ? { replayPrivacy } : {}) };
+}
+
+function requireDim(value: unknown, field: string): number {
+  if (typeof value !== "number" || !EVEN(value) || value < 16 || value > 7680) {
+    throw new BadRequestException(`${field} must be an even integer between 16 and 7680`);
+  }
+  return value;
+}
+
+function requireFps(value: unknown): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 1 || value > 120) {
+    throw new BadRequestException("fps must be an integer between 1 and 120");
+  }
+  return value;
+}
+
+function requireBoolean(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") throw new BadRequestException(`${field} must be a boolean`);
+  return value;
+}
+
+@Injectable()
+export class LiveSettingsService {
+  private readonly deps: Required<LiveSettingsDependencies>;
+
+  constructor(@Optional() @Inject(LIVE_SETTINGS_DEPENDENCIES) dependencies?: Partial<LiveSettingsDependencies>) {
+    this.deps = {
+      tenantTransaction: withTenant,
+      audit: (workspaceId, event) => appendTenantAudit(workspaceId, event),
+      now: () => new Date(),
+      ...dependencies,
+    };
+  }
+
+  /** Reads (and lazily creates) the channel's settings row. */
+  async get(workspaceId: string, virtualChannelId: string): Promise<LiveSettingsRecord> {
+    return this.deps.tenantTransaction(workspaceId, async (client) => {
+      const row = await ensureRow(client, workspaceId, virtualChannelId);
+      return toRecord(row);
+    });
+  }
+
+  /**
+   * Optimistic-concurrency save. `expectedVersion` is required and must match
+   * the row's current version; a mismatch (or a started live) is a 409 that
+   * carries the current record so the caller can rebase and retry.
+   */
+  async save(
+    workspaceId: string,
+    virtualChannelId: string,
+    expectedVersion: unknown,
+    settings: unknown,
+    actor: { userId: string | null; role: string },
+  ): Promise<LiveSettingsRecord> {
+    if (typeof expectedVersion !== "number" || !Number.isInteger(expectedVersion) || expectedVersion < 0) {
+      throw new BadRequestException("expectedVersion must be a non-negative integer");
+    }
+    const validated = validateLiveSettings(settings);
+    return this.deps.tenantTransaction(workspaceId, async (client) => {
+      // Serialize writers on the channel row; the version CAS then decides.
+      await client.query("SELECT id FROM virtual_channels WHERE workspace_id = $1 AND id = $2 FOR UPDATE", [workspaceId, virtualChannelId]);
+      const row = await ensureRow(client, workspaceId, virtualChannelId);
+      if (row.live_started_at !== null) {
+        throw new ConflictException({ message: "live settings are locked while a live is running", current: toRecord(row) });
+      }
+      if (row.version !== expectedVersion) {
+        throw new ConflictException({ message: "live settings were modified by someone else", current: toRecord(row) });
+      }
+      const updated = await client.query(
+        `UPDATE virtual_channel_live_settings
+           SET output_profile = $3, width = $4, height = $5, fps = $6,
+               latency_mode = $7, permanent_live = $8, save_replay = $9,
+               replay_settings = $10, version = version + 1, updated_by = $11, updated_at = now()
+         WHERE workspace_id = $1 AND virtual_channel_id = $2 AND version = $12
+         RETURNING *`,
+        [workspaceId, virtualChannelId, validated.outputProfile, validated.width ?? null, validated.height ?? null, validated.fps ?? null,
+          validated.latencyMode, validated.permanentLive, validated.saveReplay,
+          validated.replayPrivacy === undefined ? null : JSON.stringify({ privacy: validated.replayPrivacy }),
+          actor.userId, expectedVersion],
+      );
+      if (updated.rowCount !== 1) {
+        throw new ConflictException({ message: "live settings were modified by someone else", current: toRecord(row) });
+      }
+      const next = updated.rows[0] as LiveSettingsRow;
+      await this.deps.audit(workspaceId, {
+        actorUserId: actor.userId, actorRole: actor.role,
+        action: "virtualchannel.live_settings.updated", targetType: "virtual_channel", targetId: virtualChannelId,
+        diff: { version: next.version, outputProfile: next.output_profile, latencyMode: next.latency_mode, permanentLive: next.permanent_live, saveReplay: next.save_replay },
+      });
+      return toRecord(next);
+    });
+  }
+}
+
+interface LiveSettingsRow {
+  virtual_channel_id: string;
+  output_profile: LiveSettingsProfileName | "custom";
+  width: number | null;
+  height: number | null;
+  fps: number | null;
+  latency_mode: LatencyMode;
+  permanent_live: boolean;
+  save_replay: boolean;
+  replay_settings: { privacy?: number } | null;
+  live_started_at: Date | null;
+  version: number;
+  updated_by: string | null;
+  updated_at: Date;
+}
+
+/** Creates the settings row on first read (0-or-1 per channel, UNIQUE). */
+async function ensureRow(client: PoolClientLike, workspaceId: string, virtualChannelId: string): Promise<LiveSettingsRow> {
+  const existing = await client.query("SELECT * FROM virtual_channel_live_settings WHERE workspace_id = $1 AND virtual_channel_id = $2", [workspaceId, virtualChannelId]);
+  if (existing.rowCount === 1) return existing.rows[0] as LiveSettingsRow;
+  const channel = await client.query("SELECT id FROM virtual_channels WHERE workspace_id = $1 AND id = $2", [workspaceId, virtualChannelId]);
+  if (channel.rowCount !== 1) throw new NotFoundException("virtual channel not found");
+  const created = await client.query(
+    `INSERT INTO virtual_channel_live_settings (workspace_id, virtual_channel_id)
+     VALUES ($1, $2) ON CONFLICT (workspace_id, virtual_channel_id) DO NOTHING RETURNING *`,
+    [workspaceId, virtualChannelId],
+  );
+  if (created.rowCount === 1) return created.rows[0] as LiveSettingsRow;
+  const reread = await client.query("SELECT * FROM virtual_channel_live_settings WHERE workspace_id = $1 AND virtual_channel_id = $2", [workspaceId, virtualChannelId]);
+  if (reread.rowCount !== 1) throw new NotFoundException("virtual channel not found");
+  return reread.rows[0] as LiveSettingsRow;
+}
+
+function toRecord(row: LiveSettingsRow): LiveSettingsRecord {
+  const record: LiveSettingsRecord = {
+    virtualChannelId: row.virtual_channel_id,
+    outputProfile: row.output_profile,
+    latencyMode: row.latency_mode,
+    permanentLive: row.permanent_live,
+    saveReplay: row.save_replay,
+    version: Number(row.version),
+    liveStartedAt: row.live_started_at === null ? null : row.live_started_at.toISOString(),
+    updatedAt: row.updated_at.toISOString(),
+    updatedBy: row.updated_by,
+    ...(row.output_profile === "custom" ? { width: row.width ?? undefined, height: row.height ?? undefined, fps: row.fps ?? undefined } : {}),
+    ...(row.replay_settings?.privacy !== undefined ? { replayPrivacy: row.replay_settings.privacy } : {}),
+  };
+  return record;
+}
diff --git a/apps/api/src/virtual-channels/live-settings.test.ts b/apps/api/src/virtual-channels/live-settings.test.ts
new file mode 100644
index 0000000..abbf5cf
--- /dev/null
+++ b/apps/api/src/virtual-channels/live-settings.test.ts
@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+import {
+  ConflictException,
+  BadRequestException,
+} from "@nestjs/common";
+import {
+  LATENCY_MODES,
+  validateLiveSettings,
+} from "./live-settings.service.js";
+
+describe("live settings validation", () => {
+  it("applies defaults for an empty object", () => {
+    expect(validateLiveSettings({})).toEqual({
+      outputProfile: "720p30",
+      latencyMode: 1,
+      permanentLive: false,
+      saveReplay: false,
+    });
+  });
+
+  it("accepts every named profile and every latency mode", () => {
+    for (const profile of ["720p30", "1080p30", "1080p60"] as const) {
+      expect(validateLiveSettings({ outputProfile: profile }).outputProfile).toBe(profile);
+    }
+    for (const latency of LATENCY_MODES) {
+      expect(validateLiveSettings({ latencyMode: latency }).latencyMode).toBe(latency);
+    }
+  });
+
+  it("custom profile requires even dimensions and a sane fps", () => {
+    expect(validateLiveSettings({ outputProfile: "custom", width: 1920, height: 1080, fps: 60 }))
+      .toMatchObject({ width: 1920, height: 1080, fps: 60 });
+    expect(() => validateLiveSettings({ outputProfile: "custom", width: 1081, height: 1080, fps: 60 })).toThrow(BadRequestException);
+    expect(() => validateLiveSettings({ outputProfile: "custom", width: 1920, height: 15, fps: 60 })).toThrow(BadRequestException);
+    expect(() => validateLiveSettings({ outputProfile: "custom", width: 1920, height: 1080, fps: 0 })).toThrow(BadRequestException);
+    expect(() => validateLiveSettings({ outputProfile: "custom", width: 1920, height: 1080 })).toThrow(/fps/);
+  });
+
+  it("named profiles forbid explicit dimensions", () => {
+    expect(() => validateLiveSettings({ outputProfile: "720p30", width: 1280 })).toThrow(/custom/);
+  });
+
+  it("rejects permanentLive + saveReplay (PeerTube rejects the pair)", () => {
+    expect(() => validateLiveSettings({ permanentLive: true, saveReplay: true })).toThrow(BadRequestException);
+  });
+
+  it("latencyMode must be 1..3", () => {
+    expect(() => validateLiveSettings({ latencyMode: 0 })).toThrow(BadRequestException);
+    expect(() => validateLiveSettings({ latencyMode: 4 })).toThrow(BadRequestException);
+  });
+
+  it("replayPrivacy only with saveReplay, and only 1..4", () => {
+    expect(validateLiveSettings({ saveReplay: true, replayPrivacy: 3 })).toMatchObject({ saveReplay: true, replayPrivacy: 3 });
+    expect(() => validateLiveSettings({ replayPrivacy: 3 })).toThrow(/saveReplay/);
+    expect(() => validateLiveSettings({ saveReplay: true, replayPrivacy: 5 })).toThrow(BadRequestException);
+  });
+
+  it("rejects non-objects and unknown profiles", () => {
+    expect(() => validateLiveSettings(null)).toThrow(BadRequestException);
+    expect(() => validateLiveSettings([])).toThrow(BadRequestException);
+    expect(() => validateLiveSettings({ outputProfile: "4k120" })).toThrow(BadRequestException);
+  });
+
+  it("ConflictException is importable (CAS guard surface)", () => {
+    expect(ConflictException).toBeDefined();
+  });
+});
diff --git a/apps/api/src/virtual-channels/virtual-channels.controller.test.ts b/apps/api/src/virtual-channels/virtual-channels.controller.test.ts
new file mode 100644
index 0000000..38906bb
--- /dev/null
+++ b/apps/api/src/virtual-channels/virtual-channels.controller.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from "vitest";
+import type { Request } from "express";
+import { Readable } from "node:stream";
+import { BadRequestException } from "@nestjs/common";
+import { VirtualChannelsController } from "./virtual-channels.controller.js";
+import { BulkTooLargeException, VirtualChannelImportService, type ImportJobRecord } from "./import.service.js";
+import { LiveSettingsService } from "./live-settings.service.js";
+
+/**
+ * Controller-level: the body-shape seam. Nest registers only json/urlencoded
+ * parsers, so text/plain + text/csv arrive as an unconsumed stream that the
+ * controller must read itself; JSON arrays arrive already parsed and are
+ * re-serialized. Guard/route wiring is exercised in the live-DB suite.
+ */
+
+function fakeRequest(body?: string): Request & { session: { workspaceId: string; userId: string | null; role: string } } {
+  const stream = body === undefined ? new Readable({ read() { this.push(null); } }) : undefined;
+  return {
+    readable: stream !== undefined,
+    headers: { "content-type": body === undefined ? "text/plain" : "text/plain" },
+    session: { workspaceId: "ws-1", userId: null, role: "Owner" },
+    ...(stream === undefined ? {} : { [Symbol.asyncIterator]: stream[Symbol.asyncIterator].bind(stream) }),
+  } as unknown as Request & { session: { workspaceId: string; userId: string | null; role: string } };
+}
+
+function makeController(inputs: { bodies: string[]; created: ImportJobRecord }) {
+  const createImport = vi.fn(async (_ws: string, _id: string, input: { body: string }) => {
+    inputs.bodies.push(input.body);
+    return inputs.created;
+  });
+  const imports = { createImport, getImport: vi.fn() } as unknown as VirtualChannelImportService;
+  const settings = { get: vi.fn(), save: vi.fn() } as unknown as LiveSettingsService;
+  return { controller: new VirtualChannelsController(imports, settings), createImport };
+}
+
+const job: ImportJobRecord = {
+  jobId: "11111111-1111-4111-8111-111111111111", workspaceId: "ws-1",
+  virtualChannelId: "22222222-2222-4222-8222-222222222222", connectionId: null,
+  status: "running", format: "multiline", total: 1, processed: 0,
+  imported: 0, duplicate: 0, invalid: 0, failed: 0, entries: [],
+  createdAt: new Date(0).toISOString(), updatedAt: new Date(0).toISOString(),
+};
+
+describe("import controller body shapes", () => {
+  it("reads a text/plain body from the raw stream", async () => {
+    const { controller, createImport } = makeController({ bodies: [], created: job });
+    const request = fakeRequest();
+    // Simulate the unconsumed stream delivering the text.
+    const stream = Readable.from(["@alice@video.example\n@bob@video.example"]);
+    (request as unknown as { readable: boolean }).readable = true;
+    (request as unknown as Record<symbol, unknown>)[Symbol.asyncIterator] = stream[Symbol.asyncIterator].bind(stream);
+    const result = await controller.createImport(request as never, "22222222-2222-4222-8222-222222222222", undefined, undefined);
+    expect(result.job.jobId).toBe(job.jobId);
+    expect(createImport).toHaveBeenCalledOnce();
+    expect((createImport.mock.calls[0]?.[2] as { body: string }).body).toContain("@alice@video.example");
+  });
+
+  it("passes through an already-parsed JSON array re-serialized", async () => {
+    const { controller, createImport } = makeController({ bodies: [], created: job });
+    await controller.createImport(fakeRequest() as never, "22222222-2222-4222-8222-222222222222", undefined, ["@alice@video.example", { url: "https://v.example/c/alice" }]);
+    const passed = (createImport.mock.calls[0]?.[2] as { body: string }).body;
+    expect(JSON.parse(passed)).toHaveLength(2);
+  });
+
+  it("a parsed JSON object (not array) is a 400", async () => {
+    const { controller } = makeController({ bodies: [], created: job });
+    // express has consumed the stream and set req.body to the parsed object:
+    // readable is false and no string/array shape is present.
+    const request = { ...fakeRequest(), readable: false } as unknown as Parameters<typeof controller.createImport>[0];
+    await expect(controller.createImport(request, "22222222-2222-4222-8222-222222222222", undefined, { not: "an array" }))
+      .rejects.toBeInstanceOf(BadRequestException);
+  });
+
+  it("maps the 5000-row cap to HTTP 413", async () => {
+    const createImport = vi.fn(async () => { throw new BulkTooLargeException(5001, 5000); });
+    const imports = { createImport, getImport: vi.fn() } as unknown as VirtualChannelImportService;
+    const settings = { get: vi.fn(), save: vi.fn() } as unknown as LiveSettingsService;
+    const controller = new VirtualChannelsController(imports, settings);
+    const request = fakeRequest();
+    const stream = Readable.from(["x"]);
+    (request as unknown as { readable: boolean }).readable = true;
+    (request as unknown as Record<symbol, unknown>)[Symbol.asyncIterator] = stream[Symbol.asyncIterator].bind(stream);
+    await expect(controller.createImport(request as never, "22222222-2222-4222-8222-222222222222", undefined, undefined))
+      .rejects.toMatchObject({ status: 413 });
+  });
+});
diff --git a/apps/api/src/virtual-channels/virtual-channels.controller.ts b/apps/api/src/virtual-channels/virtual-channels.controller.ts
new file mode 100644
index 0000000..38536fe
--- /dev/null
+++ b/apps/api/src/virtual-channels/virtual-channels.controller.ts
@@ -0,0 +1,121 @@
+import { BadRequestException, Body, Controller, Get, HttpCode, Inject, Param, PayloadTooLargeException, Patch, Post, Query, Req, UseGuards } from "@nestjs/common";
+import type { Request } from "express";
+import { RbacGuard, RequirePermission, type AuthenticatedRequest } from "../rbac/rbac.guard.js";
+import { requireSession } from "../http/validation.js";
+import {
+  BulkTooLargeException,
+  VirtualChannelImportService,
+  type ImportJobRecord,
+} from "./import.service.js";
+import { LIVE_SETTINGS_DEPENDENCIES, LiveSettingsService, type LiveSettingsRecord } from "./live-settings.service.js";
+
+/** Raw-body import: URL / handle / multiline / CSV / JSON shapes all arrive as text. */
+@Controller("virtual-channels")
+@UseGuards(RbacGuard)
+export class VirtualChannelsController {
+  constructor(
+    @Inject(VirtualChannelImportService) private readonly imports: VirtualChannelImportService,
+    @Inject(LiveSettingsService) private readonly settings: LiveSettingsService,
+  ) {}
+
+  /**
+   * POST /virtual-channels/:id/import
+   * Body: text/plain (URL, handle, multiline, CSV) or application/json (array).
+   * Query: ?connectionId= optional default-instance connection.
+   * Returns 202 + the job record; poll GET .../import/:jobId for progress.
+   */
+  @Post(":id/import")
+  @RequirePermission("streamsource.manage")
+  @HttpCode(202)
+  async createImport(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+    @Query("connectionId") connectionId: string | undefined,
+    @Body() body: unknown,
+  ): Promise<{ job: ImportJobRecord }> {
+    const session = requireSession(request);
+    // Nest registers only json/urlencoded body parsers, so a text/csv or
+    // text/plain body arrives as an unconsumed stream: read it here. JSON
+    // bodies were already parsed into `body` (an array of rows) — re-serialized
+    // so the service's single parseImportBody path handles every shape.
+    let raw: string;
+    if (typeof body === "string") raw = body;
+    else if (Array.isArray(body)) raw = JSON.stringify(body);
+    else if (request.readable === true) raw = await readRawBody(request);
+    else throw new BadRequestException("import body must be text (URL, handle, CSV, multiline) or a JSON array");
+    try {
+      return { job: await this.imports.createImport(session.workspaceId, id, {
+        contentType: request.headers["content-type"],
+        body: raw,
+        ...(connectionId === undefined ? {} : { connectionId }),
+        actor: { userId: session.userId, role: session.role },
+      }) };
+    } catch (error) {
+      if (error instanceof BulkTooLargeException) throw new ImportTooLargeException(error);
+      throw error;
+    }
+  }
+
+  /** GET /virtual-channels/:id/import/:jobId — progress + report counts. */
+  @Get(":id/import/:jobId")
+  @RequirePermission("streamsource.manage")
+  async getImport(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+    @Param("jobId") jobId: string,
+  ): Promise<ImportJobRecord> {
+    return this.imports.getImport(requireSession(request).workspaceId, jobId);
+  }
+
+  /** GET /virtual-channels/:id/live-settings */
+  @Get(":id/live-settings")
+  @RequirePermission("virtualchannel.view")
+  async getSettings(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+  ): Promise<LiveSettingsRecord> {
+    return this.settings.get(requireSession(request).workspaceId, id);
+  }
+
+  /**
+   * PATCH /virtual-channels/:id/live-settings?expectedVersion=N
+   * Stale version or a started live => 409 with the current record.
+   */
+  @Patch(":id/live-settings")
+  @RequirePermission("virtualchannel.edit")
+  async saveSettings(
+    @Req() request: Request & AuthenticatedRequest,
+    @Param("id") id: string,
+    @Query("expectedVersion") expectedVersion: string | undefined,
+    @Body() body: unknown,
+  ): Promise<LiveSettingsRecord> {
+    const session = requireSession(request);
+    const version = expectedVersion === undefined ? NaN : Number(expectedVersion);
+    return this.settings.save(session.workspaceId, id, version, body, { userId: session.userId, role: session.role });
+  }
+}
+
+/**
+ * Consumes the request stream for text bodies (Nest's default parsers skip
+ * text/plain and text/csv, leaving the stream unread). Bounded to 2 MB — the
+ * same cap the service enforces on the parsed string.
+ */
+async function readRawBody(request: Request): Promise<string> {
+  if (request.readable !== true) throw new BadRequestException("import body must be text (URL, handle, CSV, multiline) or a JSON array");
+  const chunks: Buffer[] = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+    size += buffer.byteLength;
+    if (size > 2_000_000) throw new ImportTooLargeException({ received: size, limit: 2_000_000 } as BulkTooLargeException);
+    chunks.push(buffer);
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/** 413 with a machine-readable body (the 5000-row cap, proposal §4.4). */
+class ImportTooLargeException extends PayloadTooLargeException {
+  constructor(error: BulkTooLargeException) {
+    super({ message: error.message, received: error.received, limit: error.limit });
+  }
+}
diff --git a/apps/api/src/virtual-channels/virtual-channels.integration.test.ts b/apps/api/src/virtual-channels/virtual-channels.integration.test.ts
new file mode 100644
index 0000000..41de356
--- /dev/null
+++ b/apps/api/src/virtual-channels/virtual-channels.integration.test.ts
@@ -0,0 +1,209 @@
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { Pool, type PoolClient } from "pg";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { runMigrations } from "../db/migrate.js";
+import { channelRemoteRef, videoRemoteRef } from "../../../../packages/connector-peertube/src/resolve.js";
+
+/**
+ * Live-DB suite for WP7 (migration 023 + import persistence + live-settings
+ * guard). Follows the house pattern: owner pool for provisioning, app pool
+ * (sp_app) for tenant work; skips when DATABASE_URL is absent.
+ */
+const dbAvailable = process.env.DATABASE_URL !== undefined;
+const ownerPool = new Pool({ connectionString: process.env.SUPER_DATABASE_URL ?? process.env.DATABASE_URL });
+const appPool = new Pool({ connectionString: process.env.DATABASE_URL });
+
+const UUID_A = "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d";
+
+async function asTenant<T>(workspaceId: string | null, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+  const client = await appPool.connect();
+  try {
+    await client.query("BEGIN");
+    if (workspaceId !== null) await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+    const result = await fn(client);
+    await client.query("COMMIT");
+    return result;
+  } catch (error) {
+    await client.query("ROLLBACK").catch(() => undefined);
+    throw error;
+  } finally {
+    client.release();
+  }
+}
+
+async function seedWorkspace(name: string): Promise<string> {
+  const row = await ownerPool.query("INSERT INTO workspaces (name, slug) VALUES ($1, $2) RETURNING id", [name, `${name.toLowerCase()}-${randomUUID()}`]);
+  return String(row.rows[0]?.id);
+}
+
+async function seedChannel(workspaceId: string, slug: string): Promise<string> {
+  return asTenant(workspaceId, async (client) => {
+    const row = await client.query("INSERT INTO virtual_channels (workspace_id, slug, name) VALUES ($1, $2, $3) RETURNING id", [workspaceId, slug, slug]);
+    return String(row.rows[0]?.id);
+  });
+}
+
+async function insertImportedSource(workspaceId: string, channelId: string, remoteRef: string, hlsUrl: string | null): Promise<"imported" | "duplicate"> {
+  return asTenant(workspaceId, async (client) => {
+    const result = await client.query(
+      `INSERT INTO virtual_channel_sources (workspace_id, virtual_channel_id, kind, label, remote_ref, hls_url)
+       VALUES ($1, $2, 'hls', $3, $4, $5)
+       ON CONFLICT (workspace_id, virtual_channel_id, remote_ref) DO NOTHING
+       RETURNING id`,
+      [workspaceId, channelId, "imported source", remoteRef, hlsUrl],
+    );
+    return result.rowCount === 1 ? "imported" : "duplicate";
+  });
+}
+
+describe.skipIf(!dbAvailable)("virtual channel import (live DB)", () => {
+  let workspaceId: string;
+  let otherWorkspaceId: string;
+  let channelId: string;
+
+  beforeAll(async () => {
+    await runMigrations(process.env.MIGRATIONS_DIR ?? join(process.cwd(), "migrations"));
+    workspaceId = await seedWorkspace("VC import A");
+    otherWorkspaceId = await seedWorkspace("VC import B");
+    channelId = await seedChannel(workspaceId, "import-target");
+  });
+
+  afterAll(async () => {
+    if (workspaceId !== undefined) await ownerPool.query("DELETE FROM workspaces WHERE id = ANY($1)", [[workspaceId, otherWorkspaceId]]);
+    await appPool.end();
+    await ownerPool.end();
+  });
+
+  it("migration 023 landed its tables and policies", async () => {
+    const applied = await ownerPool.query("SELECT name FROM schema_migrations WHERE name LIKE '023%'");
+    expect(applied.rows.length).toBeGreaterThanOrEqual(1);
+    for (const table of ["virtual_channel_imports", "virtual_channel_live_settings"]) {
+      const flags = await ownerPool.query("SELECT relrowsecurity, relforcerowsecurity FROM pg_class WHERE oid = $1::regclass", [table]);
+      expect(flags.rows[0], table).toEqual({ relrowsecurity: true, relforcerowsecurity: true });
+      const grants = await ownerPool.query("SELECT has_table_privilege($1, $2, 'INSERT') AS ok", ["sp_app", table]);
+      expect(grants.rows[0]?.ok).toBe(true);
+    }
+  });
+
+  it("imports a source with a remote_ref and no HLS URL yet (023 widened CHECK)", async () => {
+    const outcome = await insertImportedSource(workspaceId, channelId, channelRemoteRef("alice", "video.example"), null);
+    expect(outcome).toBe("imported");
+    const row = await asTenant(workspaceId, (client) => client.query(
+      "SELECT kind, remote_ref, hls_url FROM virtual_channel_sources WHERE workspace_id = $1 AND virtual_channel_id = $2 AND remote_ref = $3",
+      [workspaceId, channelId, channelRemoteRef("alice", "video.example")],
+    ));
+    expect(row.rows[0]).toEqual({ kind: "hls", remote_ref: "channel:alice@video.example", hls_url: null });
+  });
+
+  it("the same remote_ref is a conflict (counted duplicate), a different one is not", async () => {
+    expect(await insertImportedSource(workspaceId, channelId, channelRemoteRef("alice", "video.example"), null)).toBe("duplicate");
+    expect(await insertImportedSource(workspaceId, channelId, videoRemoteRef(UUID_A, "video.example"), `https://video.example/static/streaming-playlists/hls/${UUID_A}/master.m3u8`)).toBe("imported");
+  });
+
+  it("013's playlist arm is unchanged: playlists still refuse remote_ref/hls_url", async () => {
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "INSERT INTO virtual_channel_sources (workspace_id, virtual_channel_id, kind, label, playlist_loop, remote_ref) VALUES ($1, $2, 'playlist', 'P', true, 'channel:x@y')",
+      [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+  });
+
+  it("workspace_id and channel ownership are immutable on both new tables", async () => {
+    // Seed one row per table first: the immutability triggers fire per row, so
+    // an UPDATE that matches nothing would trivially "succeed".
+    await asTenant(workspaceId, async (client) => {
+      await client.query(
+        `INSERT INTO virtual_channel_imports (workspace_id, virtual_channel_id, total)
+         VALUES ($1, $2, 1)
+         ON CONFLICT DO NOTHING`, [workspaceId, channelId]);
+      await client.query(
+        `INSERT INTO virtual_channel_live_settings (workspace_id, virtual_channel_id)
+         VALUES ($1, $2)
+         ON CONFLICT (workspace_id, virtual_channel_id) DO NOTHING`, [workspaceId, channelId]);
+    });
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_imports SET workspace_id = $2::uuid WHERE workspace_id = $1::uuid", [workspaceId, otherWorkspaceId],
+    ))).rejects.toThrow(/immutable|row-level security/);
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_live_settings SET virtual_channel_id = $2::uuid WHERE workspace_id = $1::uuid", [workspaceId, randomUUID()],
+    ))).rejects.toThrow(/immutable|row-level security/);
+  });
+
+  it("RLS: tenant B sees neither A's imports nor A's live settings", async () => {
+    await asTenant(workspaceId, async (client) => {
+      await client.query("INSERT INTO virtual_channel_imports (workspace_id, virtual_channel_id, total) VALUES ($1, $2, 1)", [workspaceId, channelId]);
+      await client.query(
+        "INSERT INTO virtual_channel_live_settings (workspace_id, virtual_channel_id) VALUES ($1, $2) ON CONFLICT (workspace_id, virtual_channel_id) DO NOTHING",
+        [workspaceId, channelId]);
+    });
+    for (const [sql, params] of [
+      ["SELECT count(*)::int AS n FROM virtual_channel_imports WHERE workspace_id = $1", [workspaceId]],
+      ["SELECT count(*)::int AS n FROM virtual_channel_live_settings WHERE workspace_id = $1", [workspaceId]],
+    ] as const) {
+      const seen = await asTenant(otherWorkspaceId, (client) => client.query(sql, [...params]));
+      expect(seen.rows[0]?.n).toBe(0);
+    }
+    // Cross-tenant writes are refused by WITH CHECK.
+    await expect(asTenant(otherWorkspaceId, (client) => client.query(
+      "INSERT INTO virtual_channel_imports (workspace_id, virtual_channel_id, total) VALUES ($1, $2, 1)", [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "42501" });
+    // No tenant context sees nothing at all.
+    expect((await asTenant(null, (client) => client.query("SELECT count(*)::int AS n FROM virtual_channel_imports"))).rows[0]?.n).toBe(0);
+  });
+
+  it("live settings: version CAS rejects a stale version and bumps exactly once per accepted write", async () => {
+    const initial = await asTenant(workspaceId, async (client) => {
+      const existing = await client.query("SELECT version FROM virtual_channel_live_settings WHERE workspace_id = $1 AND virtual_channel_id = $2", [workspaceId, channelId]);
+      if (existing.rowCount === 1) return Number(existing.rows[0]?.version);
+      await client.query("INSERT INTO virtual_channel_live_settings (workspace_id, virtual_channel_id) VALUES ($1, $2)", [workspaceId, channelId]);
+      return 0;
+    });
+    // Accepted write: version -> initial+1.
+    const updated = await asTenant(workspaceId, (client) => client.query(
+      `UPDATE virtual_channel_live_settings SET latency_mode = 3, version = version + 1
+         WHERE workspace_id = $1 AND virtual_channel_id = $2 AND version = $3 RETURNING version`,
+      [workspaceId, channelId, initial],
+    ));
+    expect(updated.rowCount).toBe(1);
+    expect(Number(updated.rows[0]?.version)).toBe(initial + 1);
+    // Stale write: matches nothing, changes nothing.
+    const stale = await asTenant(workspaceId, (client) => client.query(
+      `UPDATE virtual_channel_live_settings SET latency_mode = 1, version = version + 1
+         WHERE workspace_id = $1 AND virtual_channel_id = $2 AND version = $3 RETURNING version`,
+      [workspaceId, channelId, initial],
+    ));
+    expect(stale.rowCount).toBe(0);
+    expect(Number(stale.rows.length)).toBe(0);
+    // The version cannot be rewound by a direct write either.
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_live_settings SET version = 0 WHERE workspace_id = $1 AND virtual_channel_id = $2", [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+  });
+
+  it("live settings CHECKs mirror the validator (permanent+replay, latency, custom triple)", async () => {
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_live_settings SET permanent_live = true, save_replay = true WHERE workspace_id = $1 AND virtual_channel_id = $2",
+      [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_live_settings SET latency_mode = 4 WHERE workspace_id = $1 AND virtual_channel_id = $2", [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_live_settings SET output_profile = 'custom' WHERE workspace_id = $1 AND virtual_channel_id = $2", [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+    // A valid custom triple passes.
+    await asTenant(workspaceId, (client) => client.query(
+      "UPDATE virtual_channel_live_settings SET output_profile = 'custom', width = 1920, height = 1080, fps = 60 WHERE workspace_id = $1 AND virtual_channel_id = $2",
+      [workspaceId, channelId],
+    ));
+  });
+
+  it("import job rows enforce the caps (5000) and processed <= total", async () => {
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "INSERT INTO virtual_channel_imports (workspace_id, virtual_channel_id, total) VALUES ($1, $2, 5001)", [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+    await expect(asTenant(workspaceId, (client) => client.query(
+      "INSERT INTO virtual_channel_imports (workspace_id, virtual_channel_id, total, processed) VALUES ($1, $2, 1, 2)", [workspaceId, channelId],
+    ))).rejects.toMatchObject({ code: "23514" });
+  });
+});
diff --git a/apps/api/src/virtual-channels/virtual-channels.module.ts b/apps/api/src/virtual-channels/virtual-channels.module.ts
new file mode 100644
index 0000000..0b57def
--- /dev/null
+++ b/apps/api/src/virtual-channels/virtual-channels.module.ts
@@ -0,0 +1,18 @@
+import { Module } from "@nestjs/common";
+import { VirtualChannelsController } from "./virtual-channels.controller.js";
+import { VirtualChannelImportService } from "./import.service.js";
+import { LiveSettingsService } from "./live-settings.service.js";
+
+/**
+ * WP7 bulk source import + live-settings guard.
+ *
+ * Registration (one line, added by the app.module owner):
+ *   import { VirtualChannelsModule } from "./virtual-channels/virtual-channels.module.js";
+ *   imports: [..., VirtualChannelsModule]
+ */
+@Module({
+  controllers: [VirtualChannelsController],
+  providers: [VirtualChannelImportService, LiveSettingsService],
+  exports: [VirtualChannelImportService, LiveSettingsService],
+})
+export class VirtualChannelsModule {}
diff --git a/apps/api/tsconfig.json b/apps/api/tsconfig.json
new file mode 100644
index 0000000..d4f3651
--- /dev/null
+++ b/apps/api/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true,
+    "target": "ES2022",
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  },
+  "include": ["src"]
+}
diff --git a/apps/api/vitest.config.ts b/apps/api/vitest.config.ts
new file mode 100644
index 0000000..f090b64
--- /dev/null
+++ b/apps/api/vitest.config.ts
@@ -0,0 +1,10 @@
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // Integration suites migrate a scratch database in beforeAll; a fresh
+    // migration run alone can exceed the 10 s default hook budget.
+    hookTimeout: 120_000,
+    testTimeout: 60_000,
+  },
+});
diff --git a/apps/media-worker/.gitignore b/apps/media-worker/.gitignore
new file mode 100644
index 0000000..678a59a
--- /dev/null
+++ b/apps/media-worker/.gitignore
@@ -0,0 +1,2 @@
+# Packaged native helpers (scripts/build-helpers.sh output)
+/bin/
diff --git a/apps/media-worker/package.json b/apps/media-worker/package.json
new file mode 100644
index 0000000..bb2a689
--- /dev/null
+++ b/apps/media-worker/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/media-worker",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "tsx watch src/main.ts",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "build:helpers": "sh scripts/build-helpers.sh",
+    "smoke:cpu": "node --import tsx src/compositor/cpu-smoke.ts --seconds 30",
+    "soak": "node --import tsx src/compositor/soak.ts"
+  },
+  "dependencies": {
+    "pino": "^9.3.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "tsx": "^4.17.0"
+  }
+}
diff --git a/apps/media-worker/scripts/build-helpers.sh b/apps/media-worker/scripts/build-helpers.sh
new file mode 100755
index 0000000..4ae3c55
--- /dev/null
+++ b/apps/media-worker/scripts/build-helpers.sh
@@ -0,0 +1,24 @@
+#!/bin/sh
+# Deterministic release build of the native helpers (src/gate/rust: frame-gate, source-bus).
+#
+#   scripts/build-helpers.sh [OUT_DIR]      (default: apps/media-worker/bin)
+#
+# std only, no crates: `--offline --locked` needs no network and fails if Cargo.lock would change.
+# Reproducible for a given rustc: the crate path is remapped out of the binary, symbols are
+# stripped, and the build uses its own target dir (the development target/ is left alone).
+# OUT_DIR gets the two binaries plus SHA256SUMS; the worker finds them via MEDIA_HELPER_DIR
+# (src/gate/binary.ts). The image builds this in a pinned rust stage (infra/media-worker.Dockerfile).
+set -eu
+here=$(cd "$(dirname "$0")/.." && pwd)
+crate="$here/src/gate/rust"
+out=${1:-"$here/bin"}
+target=${CARGO_TARGET_DIR:-"$crate/target/package"}
+export CARGO_TARGET_DIR="$target"
+export RUSTFLAGS="--remap-path-prefix=$crate=/frame-gate -C strip=symbols -C debuginfo=0"
+cargo build --release --offline --locked --manifest-path "$crate/Cargo.toml"
+mkdir -p "$out"
+for bin in frame-gate source-bus; do
+  install -m 0755 "$target/release/$bin" "$out/$bin"
+done
+(cd "$out" && sha256sum frame-gate source-bus > SHA256SUMS && cat SHA256SUMS)
+rustc --version > "$out/RUSTC_VERSION"
diff --git a/apps/media-worker/scripts/nightly-soak.sh b/apps/media-worker/scripts/nightly-soak.sh
new file mode 100644
index 0000000..fc39974
--- /dev/null
+++ b/apps/media-worker/scripts/nightly-soak.sh
@@ -0,0 +1,12 @@
+#!/bin/sh
+# Reference-host nightly entry point. Eight hours; nonzero means a gate/leak failure.
+# Usage: sh scripts/nightly-soak.sh [JSONL_OUTPUT_PATH]
+set -eu
+worker_dir=$(cd "$(dirname "$0")/.." && pwd)
+repo_dir=$(cd "$worker_dir/../.." && pwd)
+out=${1:-"$repo_dir/runs/soak/$(date -u +%F).jsonl"}
+mkdir -p "$(dirname "$out")"
+cd "$worker_dir"
+sh scripts/build-helpers.sh
+export MEDIA_HELPER_DIR="$worker_dir/bin"
+exec node --import tsx src/compositor/soak.ts --hours 8 --profile 1080p30 --swap-every 30 --sample-every 10 --out "$out"
diff --git a/apps/media-worker/src/bus/control-signer.ts b/apps/media-worker/src/bus/control-signer.ts
new file mode 100644
index 0000000..493775a
--- /dev/null
+++ b/apps/media-worker/src/bus/control-signer.ts
@@ -0,0 +1,14 @@
+import type { KeyObject } from "node:crypto";
+import { signCommand, type CommandBody, type SignedCommand } from "./envelope";
+
+/** API-side stub: caller must commit desired state and re-authorize before signing. */
+export interface ControlCommandSigner {
+  signCommittedSnapshot(body: CommandBody): Promise<SignedCommand>;
+}
+
+export class Ed25519ControlSigner implements ControlCommandSigner {
+  constructor(private readonly kid: string, private readonly privateKey: KeyObject) {}
+  async signCommittedSnapshot(body: CommandBody): Promise<SignedCommand> {
+    return signCommand(body, this.kid, this.privateKey);
+  }
+}
diff --git a/apps/media-worker/src/bus/envelope.ts b/apps/media-worker/src/bus/envelope.ts
new file mode 100644
index 0000000..5f943be
--- /dev/null
+++ b/apps/media-worker/src/bus/envelope.ts
@@ -0,0 +1,61 @@
+import { sign, verify, type KeyObject } from "node:crypto";
+import { isDesiredChannel, snapshotHlsUrls, type DesiredChannel } from "../types";
+import { validateEndpointShape } from "../relay/endpoints";
+
+export interface CommandBody {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  commandId: string;
+  desiredVersion: number;
+  issuedAt: string;
+  expiresAt: string;
+  snapshot: DesiredChannel;
+}
+export interface SignedCommand { kid: string; body: CommandBody; signature: string }
+
+/** Fixed field order is the wire-format contract for both signing and verifying. */
+export function commandBytes(body: CommandBody): Buffer {
+  return Buffer.from(JSON.stringify({
+    workspaceId: body.workspaceId, channelId: body.channelId, workerId: body.workerId,
+    assignmentEpoch: body.assignmentEpoch, commandId: body.commandId,
+    desiredVersion: body.desiredVersion, issuedAt: body.issuedAt,
+    expiresAt: body.expiresAt, snapshot: body.snapshot,
+  }));
+}
+
+export function signCommand(body: CommandBody, kid: string, key: KeyObject): SignedCommand {
+  if (!isDesiredChannel(body.snapshot)) throw new Error("invalid desired snapshot");
+  validateSnapshotEndpoints(body.snapshot);
+  return { kid, body, signature: sign(null, commandBytes(body), key).toString("base64") };
+}
+
+function validateSnapshotEndpoints(snapshot: DesiredChannel): void {
+  for (const url of snapshotHlsUrls(snapshot)) validateEndpointShape(url, "hls");
+  if (snapshot.output) validateEndpointShape(snapshot.output.endpointUrl, "output");
+}
+
+export function verifyCommand(value: unknown, keys: ReadonlyMap<string, KeyObject>, workerId: string, now = Date.now()): SignedCommand {
+  if (typeof value !== "object" || value === null) throw new Error("invalid command");
+  const command = value as Partial<SignedCommand>;
+  const body = command.body;
+  if (typeof command.kid !== "string" || typeof command.signature !== "string" || !body ||
+      typeof body.workspaceId !== "string" || typeof body.channelId !== "string" ||
+      body.workerId !== workerId || typeof body.commandId !== "string" || body.commandId.length === 0 ||
+      !Number.isSafeInteger(body.assignmentEpoch) || (body.assignmentEpoch ?? -1) < 0 ||
+      !Number.isSafeInteger(body.desiredVersion) || (body.desiredVersion ?? -1) < 0 ||
+      typeof body.issuedAt !== "string" || typeof body.expiresAt !== "string" ||
+      !isDesiredChannel(body.snapshot)) throw new Error("invalid command fields");
+  const issued = Date.parse(body.issuedAt);
+  const expires = Date.parse(body.expiresAt);
+  if (!Number.isFinite(issued) || !Number.isFinite(expires) || issued > now + 30_000 || expires <= now || expires <= issued) throw new Error("expired command");
+  const snapshot = body.snapshot;
+  if (snapshot.workspaceId !== body.workspaceId || snapshot.channelId !== body.channelId ||
+      snapshot.workerId !== body.workerId || snapshot.assignmentEpoch !== body.assignmentEpoch ||
+      snapshot.desiredVersion !== body.desiredVersion) throw new Error("snapshot mismatch");
+  validateSnapshotEndpoints(snapshot);
+  const key = keys.get(command.kid);
+  if (!key || !verify(null, commandBytes(body as CommandBody), key, Buffer.from(command.signature, "base64"))) throw new Error("invalid signature");
+  return command as SignedCommand;
+}
diff --git a/apps/media-worker/src/bus/fence.ts b/apps/media-worker/src/bus/fence.ts
new file mode 100644
index 0000000..a2002c9
--- /dev/null
+++ b/apps/media-worker/src/bus/fence.ts
@@ -0,0 +1,68 @@
+import { closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { randomUUID } from "node:crypto";
+import type { CommandBody } from "./envelope";
+
+interface FenceEntry { assignmentEpoch: number; acceptedVersion: number; seen: Record<string, number> }
+type FenceData = Record<string, FenceEntry>;
+
+/** Local durable fence. Atomic rename plus fsync of file and directory precedes execute/ack. */
+export class DurableFence {
+  private data: FenceData;
+  constructor(private readonly path: string) {
+    mkdirSync(dirname(path), { recursive: true });
+    this.data = existsSync(path) ? this.read() : {};
+  }
+
+  private read(): FenceData {
+    const parsed: unknown = JSON.parse(readFileSync(this.path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("invalid fence file");
+    for (const entry of Object.values(parsed)) {
+      if (typeof entry !== "object" || entry === null) throw new Error("invalid fence entry");
+      const record = entry as Partial<FenceEntry>;
+      if (!Number.isSafeInteger(record.assignmentEpoch) || !Number.isSafeInteger(record.acceptedVersion) ||
+          (record.assignmentEpoch ?? -1) < 0 || (record.acceptedVersion ?? -1) < 0 ||
+          typeof record.seen !== "object" || record.seen === null || Array.isArray(record.seen) ||
+          Object.values(record.seen).some((expiry) => !Number.isFinite(expiry))) throw new Error("invalid fence entry");
+    }
+    return parsed as FenceData;
+  }
+
+  accepted(workspaceId: string, channelId: string): { assignmentEpoch: number; acceptedVersion: number } | null {
+    const entry = this.data[`${workspaceId}:${channelId}`];
+    return entry ? { assignmentEpoch: entry.assignmentEpoch, acceptedVersion: entry.acceptedVersion } : null;
+  }
+
+  accept(body: CommandBody, now = Date.now()): "accepted" | "replay" | "stale" {
+    const key = `${body.workspaceId}:${body.channelId}`;
+    const previous = this.data[key];
+    if (previous && body.assignmentEpoch < previous.assignmentEpoch) return "stale";
+    if (previous && body.assignmentEpoch === previous.assignmentEpoch && body.desiredVersion < previous.acceptedVersion) return "stale";
+    if (previous?.seen[body.commandId] !== undefined) return "replay";
+    const seen = previous ? { ...previous.seen } : {};
+    for (const [id, expiry] of Object.entries(seen)) if (expiry <= now) delete seen[id];
+    seen[body.commandId] = Date.parse(body.expiresAt);
+    const next: FenceData = { ...this.data, [key]: {
+      assignmentEpoch: body.assignmentEpoch,
+      acceptedVersion: previous?.assignmentEpoch === body.assignmentEpoch
+        ? Math.max(previous.acceptedVersion, body.desiredVersion) : body.desiredVersion,
+      seen,
+    } };
+    this.persist(next);
+    this.data = next;
+    return "accepted";
+  }
+
+  private persist(data: FenceData): void {
+    const temp = `${this.path}.${randomUUID()}.tmp`;
+    const fd = openSync(temp, "wx", 0o600);
+    try {
+      writeFileSync(fd, JSON.stringify(data));
+      fsyncSync(fd);
+    } catch (error) { unlinkSync(temp); throw error; }
+    finally { closeSync(fd); }
+    renameSync(temp, this.path);
+    const dir = openSync(dirname(this.path), "r");
+    try { fsyncSync(dir); } finally { closeSync(dir); }
+  }
+}
diff --git a/apps/media-worker/src/bus/redis.ts b/apps/media-worker/src/bus/redis.ts
new file mode 100644
index 0000000..1339b0b
--- /dev/null
+++ b/apps/media-worker/src/bus/redis.ts
@@ -0,0 +1,137 @@
+import net, { type Socket } from "node:net";
+import tls from "node:tls";
+import type { ObservedChannel } from "../types";
+
+type Reply = string | number | null | Reply[];
+function encode(parts: string[]): Buffer {
+  return Buffer.from(`*${parts.length}\r\n${parts.map((part) => `\$${Buffer.byteLength(part)}\r\n${part}\r\n`).join("")}`);
+}
+function parse(buffer: Buffer, offset = 0): { reply: Reply; end: number } | null {
+  if (offset >= buffer.length) return null;
+  const endLine = buffer.indexOf("\r\n", offset);
+  if (endLine < 0) return null;
+  const length = Number(buffer.subarray(offset + 1, endLine).toString());
+  const type = String.fromCharCode(buffer[offset] ?? 0);
+  let pos = endLine + 2;
+  if (type === "+" || type === ":" || type === "-") return { reply: type === ":" ? length : buffer.subarray(offset + 1, endLine).toString(), end: pos };
+  if (type === "$") {
+    if (length === -1) return { reply: null, end: pos };
+    if (!Number.isInteger(length) || length < 0 || length > 2_000_000) throw new Error("invalid Redis bulk length");
+    if (buffer.length < pos + length + 2) return null;
+    const reply = buffer.subarray(pos, pos + length).toString();
+    return { reply, end: pos + length + 2 };
+  }
+  if (type === "*") {
+    if (length === -1) return { reply: null, end: pos };
+    if (!Number.isInteger(length) || length < 0 || length > 100) throw new Error("invalid Redis array length");
+    const replies: Reply[] = [];
+    for (let i = 0; i < length; i += 1) {
+      const item = parse(buffer, pos);
+      if (!item) return null;
+      replies.push(item.reply);
+      pos = item.end;
+    }
+    return { reply: replies, end: pos };
+  }
+  throw new Error("invalid Redis reply");
+}
+
+class RedisConnection {
+  private socket: Socket;
+  private buffer = Buffer.alloc(0);
+  private pending: Array<{ resolve: (reply: Reply) => void; reject: (error: Error) => void }> = [];
+  onPush: ((reply: Reply) => void) | null = null;
+  private subscribing = false;
+
+  private constructor(socket: Socket) {
+    this.socket = socket;
+    socket.on("data", (chunk: Buffer) => {
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+      if (this.buffer.length > 2_000_000) { socket.destroy(new Error("Redis reply too large")); return; }
+      while (true) {
+        const prefix = this.buffer[0];
+        const parsed = parse(this.buffer);
+        if (!parsed) break;
+        this.buffer = this.buffer.subarray(parsed.end);
+        if (prefix === 45) {
+          if (this.subscribing) this.onPush?.(parsed.reply);
+          else this.pending.shift()?.reject(new Error(`Redis: ${String(parsed.reply)}`));
+          continue;
+        }
+        if (this.subscribing) this.onPush?.(parsed.reply);
+        else this.pending.shift()?.resolve(parsed.reply);
+      }
+    });
+    socket.on("error", (error) => { for (const item of this.pending.splice(0)) item.reject(error); });
+    socket.on("close", () => { for (const item of this.pending.splice(0)) item.reject(new Error("Redis disconnected")); });
+  }
+
+  static async connect(url: URL): Promise<RedisConnection> {
+    const port = Number(url.port || (url.protocol === "rediss:" ? 6380 : 6379));
+    const socket = url.protocol === "rediss:"
+      ? tls.connect({ host: url.hostname, port, servername: url.hostname, rejectUnauthorized: true })
+      : net.connect({ host: url.hostname, port });
+    await new Promise<void>((resolve, reject) => {
+      socket.once(url.protocol === "rediss:" ? "secureConnect" : "connect", () => resolve());
+      socket.once("error", reject);
+    });
+    const connection = new RedisConnection(socket);
+    if (url.password) await connection.send(["AUTH", decodeURIComponent(url.username || "default"), decodeURIComponent(url.password)]);
+    return connection;
+  }
+
+  send(parts: string[]): Promise<Reply> {
+    return new Promise((resolve, reject) => {
+      this.pending.push({ resolve, reject });
+      this.socket.write(encode(parts));
+    });
+  }
+  subscribe(channel: string, onMessage: (message: string) => void): Promise<void> {
+    this.subscribing = true;
+    return new Promise((resolve, reject) => {
+      this.onPush = (reply) => {
+        if (typeof reply === "string") reject(new Error("Redis subscription rejected"));
+        else if (Array.isArray(reply) && reply[0] === "subscribe" && reply[1] === channel) resolve();
+        else if (Array.isArray(reply) && reply[0] === "message" && reply[1] === channel && typeof reply[2] === "string") onMessage(reply[2]);
+      };
+      this.socket.write(encode(["SUBSCRIBE", channel]));
+    });
+  }
+  close(): void { this.socket.destroy(); }
+}
+
+export interface ObservedStore {
+  get(workspaceId: string, channelId: string): Promise<ObservedChannel | null>;
+  put(observed: ObservedChannel): Promise<void>;
+  heartbeat(workerId: string, channels: ObservedChannel[]): Promise<void>;
+}
+
+export class RedisBus implements ObservedStore {
+  private subscribers: RedisConnection[] = [];
+  private constructor(private readonly url: URL, private readonly client: RedisConnection) {}
+  static async connect(rawUrl: string): Promise<RedisBus> {
+    const url = new URL(rawUrl);
+    if (url.protocol !== "redis:" && url.protocol !== "rediss:") throw new Error("invalid Redis URL");
+    return new RedisBus(url, await RedisConnection.connect(url));
+  }
+  async get(workspaceId: string, channelId: string): Promise<ObservedChannel | null> {
+    const result = await this.client.send(["GET", `obs:${workspaceId}:${channelId}`]);
+    return typeof result === "string" ? JSON.parse(result) as ObservedChannel : null;
+  }
+  async put(observed: ObservedChannel): Promise<void> {
+    await this.client.send(["SET", `obs:${observed.workspaceId}:${observed.channelId}`, JSON.stringify(observed), "EX", "60"]);
+  }
+  async heartbeat(workerId: string, channels: ObservedChannel[]): Promise<void> {
+    await this.client.send(["SET", `hb:${workerId}`, JSON.stringify({ workerId, sentAt: new Date().toISOString(), channels: channels.map((c) => ({ workspaceId: c.workspaceId, channelId: c.channelId, assignmentEpoch: c.assignmentEpoch, realizedVersion: c.realizedVersion })) }), "EX", "15"]);
+    for (const channel of channels) await this.put(channel);
+  }
+  async subscribe(workerId: string, workspaces: string[], onCommand: (message: string) => void): Promise<void> {
+    // A worker uses one subscription per assigned workspace; all channels are signature checked.
+    for (const workspaceId of workspaces) {
+      const subscriber = await RedisConnection.connect(this.url);
+      await subscriber.subscribe(`cmd:${workspaceId}:${workerId}`, onCommand);
+      this.subscribers.push(subscriber);
+    }
+  }
+  close(): void { for (const subscriber of this.subscribers) subscriber.close(); this.client.close(); }
+}
diff --git a/apps/media-worker/src/compositor/command-builder.test.ts b/apps/media-worker/src/compositor/command-builder.test.ts
new file mode 100644
index 0000000..a6e06ea
--- /dev/null
+++ b/apps/media-worker/src/compositor/command-builder.test.ts
@@ -0,0 +1,203 @@
+/**
+ * MediaCommandBuilder: argv shape, typed-param rejection, and golden-frame
+ * hashes per layout (deterministic synthetic inputs: seeded noise over test
+ * patterns; framemd5 of the composited output, video + program audio).
+ *
+ * Hashes are pinned to the system FFmpeg (5.1.x here). UPDATE_GOLDEN=1 rewrites
+ * src/compositor/golden-frames.json after an intentional graph change or an
+ * FFmpeg upgrade.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import {
+  buildCompositorArgs, buildEncoderArgs, buildFilterGraph, buildIngestArgs, CommandBuildError, layoutRects, rectFromBasisPoints,
+  SYNTHETIC_PATTERNS, type Canvas, type CompositorPlan, type PxRect,
+} from "./command-builder";
+import type { SceneLayout } from "../production";
+import { makeAssets } from "./testing";
+
+const canvas: Canvas = { width: 320, height: 180, fps: 30 };
+const GOLDEN = join(__dirname, "golden-frames.json");
+
+function synthetic(i: number) {
+  return { video: { kind: "synthetic" as const, pattern: SYNTHETIC_PATTERNS[i % SYNTHETIC_PATTERNS.length]!, seed: 1000 + i }, audio: { kind: "synthetic" as const, toneHz: 220 + 110 * i } };
+}
+
+const CUSTOM: PxRect[] = [{ x: 0, y: 0, w: 160, h: 90 }, { x: 160, y: 0, w: 160, h: 90 }, { x: 80, y: 90, w: 160, h: 90 }];
+const CUSTOM_OVERLAP: PxRect[] = [{ x: 0, y: 0, w: 200, h: 112 }, { x: 120, y: 68, w: 200, h: 112 }];
+
+interface Case { name: string; layout: SceneLayout; rects: PxRect[]; empty?: number[]; overlays: "none" | "lower" | "chyron" | "both"; mix: Array<[number, number]>; master: number }
+
+const CASES: Case[] = [
+  { name: "single", layout: "single", rects: layoutRects("single", canvas), overlays: "none", mix: [[0, 0]], master: 0 },
+  { name: "pip", layout: "pip", rects: [{ x: 0, y: 0, w: 320, h: 180 }, rectFromBasisPoints({ x: 6000, y: 6000, w: 3500, h: 3500 }, canvas)], overlays: "lower", mix: [[0, 0], [1, -12]], master: -3 },
+  { name: "2x1", layout: "2x1", rects: layoutRects("2x1", canvas), overlays: "none", mix: [[0, -3], [1, -3]], master: 0 },
+  { name: "2x2", layout: "2x2", rects: layoutRects("2x2", canvas), empty: [3], overlays: "chyron", mix: [[0, 0]], master: -6 },
+  { name: "3x3", layout: "3x3", rects: layoutRects("3x3", canvas), empty: [4, 8], overlays: "both", mix: [[0, 0], [1, -6], [2, -24]], master: 0 },
+  { name: "4x4", layout: "4x4", rects: layoutRects("4x4", canvas), empty: [5, 10, 15], overlays: "none", mix: [], master: 0 },
+  { name: "custom", layout: "custom", rects: CUSTOM, overlays: "lower", mix: [[2, 0]], master: 0 },
+  { name: "custom-overlap", layout: "custom", rects: CUSTOM_OVERLAP, overlays: "both", mix: [[0, 0], [1, 0]], master: -9 },
+];
+
+function plan(c: Case, assets: string[]): CompositorPlan {
+  const tiles = c.rects.map((rect, i) => ({ source: c.empty?.includes(i) ? null : i % 4, rect, fit: (["contain", "cover", "crop"] as const)[i % 3]! }));
+  const overlays = [
+    ...(c.overlays === "lower" || c.overlays === "both" ? [{ kind: "image" as const, asset: 0, x: 12, y: 140 }] : []),
+    ...(c.overlays === "chyron" || c.overlays === "both" ? [{ kind: "chyron" as const, asset: 1, y: 164, speedPxPerSec: 120 }] : []),
+  ];
+  return {
+    sources: [0, 1, 2, 3].map(synthetic), assets,
+    graph: { canvas, layout: c.layout, tiles, overlays, audio: { inputs: c.mix.map(([source, gainDb]) => ({ source, gainDb })), masterGainDb: c.master } },
+    output: { kind: "framemd5", frames: 4 },
+  };
+}
+
+function hashes(p: CompositorPlan): string[] {
+  const r = spawnSync("ffmpeg", buildCompositorArgs(p), { encoding: "utf8", timeout: 60_000 });
+  assert.equal(r.status, 0, r.stderr);
+  // framemd5 lines: stream, dts, pts, duration, size, hash — keep stream/pts/size/hash.
+  return r.stdout.split("\n").filter((l) => l && !l.startsWith("#")).map((l) => l.split(",").map((x) => x.trim())).map((f) => `${f[0]}:${f[2]}:${f[4]}:${f[5]}`);
+}
+
+test("golden-frame hashes per layout (deterministic synthetic inputs)", { timeout: 300_000 }, () => {
+  const dir = mkdtempSync(join(tmpdir(), "golden-"));
+  try {
+    const assets = makeAssets(dir);
+    const got: Record<string, string[]> = {};
+    for (const c of CASES) {
+      const p = plan(c, assets);
+      const h = hashes(p);
+      assert.ok(h.some((l) => l.startsWith("0:")) && h.some((l) => l.startsWith("1:")), `${c.name}: video and audio frames`);
+      assert.deepEqual(hashes(p), h, `${c.name}: two runs hash identically`);
+      got[c.name] = h;
+    }
+    if (process.env.UPDATE_GOLDEN || !existsSync(GOLDEN)) {
+      writeFileSync(GOLDEN, `${JSON.stringify({ ffmpeg: ffmpegVersion(), canvas, frames: 4, layouts: got }, null, 2)}\n`);
+    }
+    const golden = JSON.parse(readFileSync(GOLDEN, "utf8")) as { ffmpeg: string; layouts: Record<string, string[]> };
+    for (const c of CASES) assert.deepEqual(got[c.name], golden.layouts[c.name], `${c.name} matches golden (pinned to ${golden.ffmpeg}; UPDATE_GOLDEN=1 after an intentional change)`);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function ffmpegVersion(): string {
+  return spawnSync("ffmpeg", ["-version"], { encoding: "utf8" }).stdout.split("\n")[0] ?? "unknown";
+}
+
+test("layout cells are even, cover the canvas, and xstack/overlay is chosen by geometry", () => {
+  for (const layout of ["2x1", "2x2", "3x3", "4x4"] as const) {
+    for (const c of [canvas, { width: 1920, height: 1080, fps: 30 }, { width: 1280, height: 720, fps: 30 }]) {
+      const rects = layoutRects(layout, c);
+      assert.equal(rects.reduce((a, r) => a + r.w * r.h, 0), c.width * c.height, `${layout} ${c.width}x${c.height} tiles cover the canvas`);
+      for (const r of rects) for (const v of [r.x, r.y, r.w, r.h]) assert.equal(v % 2, 0);
+    }
+  }
+  const idx = { video: [0, 1, 2, 3], audio: [null, null, null, null], assets: [] };
+  const base = { sources: [0, 1, 2, 3].map(synthetic), assets: [], output: { kind: "framemd5" as const, frames: 1 } };
+  const audio = { inputs: [], masterGainDb: 0 };
+  const grid = buildFilterGraph({ ...base, graph: { canvas, layout: "2x2", tiles: layoutRects("2x2", canvas).map((rect, i) => ({ source: i, rect, fit: "contain" as const })), overlays: [], audio } }, idx);
+  assert.match(grid, /xstack=inputs=4:layout=0_0\|160_0\|0_90\|160_90:fill=black/);
+  assert.match(grid, /anullsrc=r=48000:cl=stereo/);
+  const pip = buildFilterGraph({ ...base, graph: { canvas, layout: "pip", tiles: [{ source: 0, rect: { x: 0, y: 0, w: 320, h: 180 }, fit: "cover" }, { source: 1, rect: { x: 200, y: 100, w: 100, h: 56 }, fit: "contain" }], overlays: [], audio } }, idx);
+  assert.match(pip, /overlay=x=200:y=100/);
+  assert.doesNotMatch(pip, /xstack/);
+  // Overlapping custom rects: the base is the first tile padded (paced by a live input), not a lavfi color source.
+  const overlap = buildFilterGraph({ ...base, graph: { canvas, layout: "custom", tiles: CUSTOM_OVERLAP.map((rect, i) => ({ source: i, rect, fit: "cover" as const })), overlays: [], audio } }, idx);
+  assert.match(overlap, /\[t0\]pad=320:180:0:0:color=black\[bg\];\[bg\]\[t1\]overlay=x=120:y=68/);
+  assert.doesNotMatch(overlap, /color=c=black/);
+  const shared = buildFilterGraph({ ...base, graph: { canvas, layout: "2x1", tiles: layoutRects("2x1", canvas).map((rect) => ({ source: 0, rect, fit: "crop" as const })), overlays: [], audio } }, idx);
+  assert.match(shared, /\[0:v\]split=2\[s0_0\]\[s0_1\]/);
+});
+
+test("program mix follows §2.3: volume per input → amix → master gain, 3 dB steps only", () => {
+  const idx = { video: [0, 2, 4], audio: [1, 3, 5], assets: [] };
+  const p = (inputs: Array<{ source: number; gainDb: number }>, masterGainDb = 0): CompositorPlan => ({
+    sources: [0, 1, 2].map(synthetic), assets: [], output: { kind: "framemd5", frames: 1 },
+    graph: { canvas, layout: "single", tiles: [{ source: 0, rect: { x: 0, y: 0, w: 320, h: 180 }, fit: "contain" }], overlays: [], audio: { inputs, masterGainDb } },
+  });
+  const g = buildFilterGraph(p([{ source: 0, gainDb: -6 }, { source: 2, gainDb: 0 }], -3), idx);
+  assert.match(g, /\[1:a\]aformat=[^;]*,volume=-6dB\[m0\]/);
+  assert.match(g, /\[5:a\]aformat=[^;]*,volume=0dB\[m1\]/);
+  assert.match(g, /\[m0\]\[m1\]amix=inputs=2:duration=longest:dropout_transition=2:normalize=1,volume=-3dB/);
+  assert.doesNotMatch(buildFilterGraph(p([{ source: 0, gainDb: 0 }]), idx), /amix/);
+  for (const bad of [-1, -25, 3, 1.5]) assert.throws(() => buildCompositorArgs(p([{ source: 0, gainDb: bad }])), /gainDb/);
+  assert.throws(() => buildCompositorArgs(p([{ source: 0, gainDb: 0 }, { source: 0, gainDb: -3 }])), /repeats a source/);
+  assert.throws(() => buildCompositorArgs(p([{ source: 0, gainDb: 0 }], -2)), /masterGainDb/);
+});
+
+test("typed params only: hostile values never reach argv", () => {
+  const good: CompositorPlan = {
+    sources: [{ video: { kind: "rawPipe", fd: 4 }, audio: { kind: "rawPipe", fd: 5 } }],
+    assets: [`/scratch/assets/${"a".repeat(64)}.png`],
+    graph: { canvas, layout: "single", tiles: [{ source: 0, rect: { x: 0, y: 0, w: 320, h: 180 }, fit: "contain" }], overlays: [{ kind: "chyron", asset: 0, y: 160, speedPxPerSec: 100 }], audio: { inputs: [{ source: 0, gainDb: 0 }], masterGainDb: 0 } },
+    output: { kind: "gate", videoFd: 1, audioFd: 3 },
+  };
+  const args = buildCompositorArgs(good);
+  assert.ok(args.includes("pipe:4") && args.includes("pipe:5") && args.includes(`file:/scratch/assets/${"a".repeat(64)}.png`));
+  assert.deepEqual(args.slice(-1), ["pipe:3"]);
+  const hostileAssets = ["/scratch/../etc/passwd.png", "/scratch/x;rm.png", "relative/" + "a".repeat(64) + ".png", `/scratch/${"a".repeat(64)}.png'`, `/s/movie=${"a".repeat(58)}.png`, "/scratch/assets/notahash.png"];
+  for (const asset of hostileAssets) assert.throws(() => buildCompositorArgs({ ...good, assets: [asset] }), CommandBuildError, asset);
+  const g = good.graph;
+  assert.throws(() => buildCompositorArgs({ ...good, graph: { ...g, tiles: [{ ...g.tiles[0]!, rect: { x: 1, y: 0, w: 320, h: 180 } }] } }), /even/);
+  assert.throws(() => buildCompositorArgs({ ...good, graph: { ...g, tiles: [{ ...g.tiles[0]!, rect: { x: 0, y: 0, w: 322, h: 180 } }] } }), CommandBuildError);
+  assert.throws(() => buildCompositorArgs({ ...good, graph: { ...g, overlays: [{ kind: "chyron", asset: 0, y: 160, speedPxPerSec: 39 }] } }), /speedPxPerSec/);
+  assert.throws(() => buildCompositorArgs({ ...good, graph: { ...g, overlays: [{ kind: "image", asset: 1, x: 0, y: 0 }] } }), /asset/);
+  assert.throws(() => buildCompositorArgs({ ...good, sources: [{ video: { kind: "rawPipe", fd: 1.5 }, audio: null }] }), /fd/);
+  assert.throws(() => buildCompositorArgs({ ...good, graph: { ...g, canvas: { width: 321, height: 180, fps: 30 } } }), /even/);
+  assert.throws(() => buildCompositorArgs({ ...good, graph: { ...g, canvas: { width: 320, height: 180, fps: 7 } } }), /fps/);
+  // Nothing in argv is a shell: no metacharacters outside the filtergraph and the expression quotes.
+  for (const a of args) if (!a.includes("[")) assert.doesNotMatch(a, /[;&|`$<>]/, a);
+});
+
+test("ingest normalize and persistent encoder argv", () => {
+  const ingest = buildIngestArgs({ input: { kind: "mpegtsPipe" }, canvas: { width: 1920, height: 1080, fps: 30 }, audio: "source" });
+  assert.deepEqual(ingest.slice(ingest.indexOf("-f"), ingest.indexOf("-f") + 4), ["-f", "mpegts", "-i", "pipe:0"]);
+  assert.ok(ingest.includes("pipe:1") && ingest.includes("pipe:3"));
+  assert.ok(ingest.some((a) => a.startsWith("scale=1920:1080:force_original_aspect_ratio=decrease") && a.includes("fps=30")));
+  const silent = buildIngestArgs({ input: { kind: "mpegtsPipe" }, canvas, audio: "none" });
+  assert.ok(silent.includes("anullsrc=r=48000:cl=stereo") && silent.includes("1:a:0"));
+  const enc = buildEncoderArgs({ canvas: { width: 1920, height: 1080, fps: 30 }, videoBitrateKbps: 6000, audioBitrateKbps: 128, output: { kind: "flvPipe", fd: 4 } });
+  assert.deepEqual(enc.slice(-3), ["-f", "flv", "pipe:4"]);
+  assert.ok(enc.includes("pipe:0") && enc.includes("pipe:3") && enc.includes("6000k") && enc.includes("60"));
+  assert.throws(() => buildEncoderArgs({ canvas, videoBitrateKbps: 1e9, audioBitrateKbps: 128, output: { kind: "null" } }));
+});
+
+test("ingest ×N normalize stage end to end: MPEG-TS pipe (4:3, no audio) and synthetic sources fill their buses", { timeout: 60_000 }, async () => {
+  const { IngestProcess } = await import("./ingest");
+  const { ensureGateBinary, passthroughRedactor } = await import("./testing");
+  assert.ok(ensureGateBinary(), "native helpers (source bus) build");
+  // 4:3 MPEG-TS without audio on the ingest's stdin, as the egress relay would deliver it.
+  const ts = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=s=640x480:r=25:d=2", "-c:v", "mpeg2video", "-f", "mpegts", "-"], { maxBuffer: 64 << 20 });
+  assert.equal(ts.status, 0);
+  const dir = mkdtempSync(join(tmpdir(), "ingest-"));
+  const tsPath = join(dir, "in.ts");
+  writeFileSync(tsPath, ts.stdout);
+  const { openSync, closeSync } = await import("node:fs");
+  const fd = openSync(tsPath, "r");
+  const exits: string[] = [];
+  const pipeIngest = new IngestProcess("a", { input: { kind: "mpegtsPipe" }, canvas, audio: "none" }, fd, join(dir, "scratch"), passthroughRedactor, () => undefined, (_id, r) => exits.push(r));
+  const synth = new IngestProcess("b", { input: { kind: "synthetic", pattern: "smptehdbars", seed: 7, toneHz: 440 }, canvas, audio: "source" }, null, join(dir, "scratch"), passthroughRedactor, () => undefined, (_id, r) => exits.push(r));
+  try {
+    await pipeIngest.start();
+    closeSync(fd);
+    await synth.start();
+    await new Promise((r) => setTimeout(r, 1_500));
+    // 2 s of 25 fps input → 30 fps CFR on the canvas (decoded faster than real time).
+    const piped = await pipeIngest.bus.stats();
+    assert.ok(piped.pairs >= 50, `mpegts pairs ${piped.pairs}`);
+    assert.equal(piped.silenceFilled, 0, "anullsrc supplies audio for a silent source");
+    // -re synthetic: real-time pace.
+    const synthetic = await synth.bus.stats();
+    assert.ok(synthetic.pairs >= 30 && synthetic.pairs <= 60, `synthetic pairs ${synthetic.pairs}`);
+    assert.deepEqual(exits, []);
+  } finally {
+    await pipeIngest.stop();
+    await synth.stop();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/apps/media-worker/src/compositor/command-builder.ts b/apps/media-worker/src/compositor/command-builder.ts
new file mode 100644
index 0000000..e008ca5
--- /dev/null
+++ b/apps/media-worker/src/compositor/command-builder.ts
@@ -0,0 +1,486 @@
+/**
+ * MediaCommandBuilder (docs/design/streaming-architecture.md §1.4, §2.3, §4, §6 S2).
+ *
+ * Typed params in, argv out. Nothing here takes a free-form string: sources are
+ * fds or closed synthetic patterns, assets are validated scratch paths to PNGs
+ * named by content id, geometry is integers, gains are 3 dB steps. Every
+ * filtergraph token is produced from those values, so no operator text can
+ * reach a graph or argv (§4.3 "Injection").
+ */
+import { CHYRON_SPEED_MAX, CHYRON_SPEED_MIN, GAIN_DB_MAX, GAIN_DB_MIN, gainDb, type SceneLayout, type SlotFit } from "../production";
+import { assertGeometry, GATE_CHANNELS, GATE_SAMPLE_RATE, type FrameGeometry } from "../gate/protocol";
+
+export type Canvas = FrameGeometry;
+
+export interface PxRect { x: number; y: number; w: number; h: number }
+
+/** Closed set of deterministic test patterns (golden frames, spike, CPU smoke). */
+export type SyntheticPattern = "testsrc2" | "smptehdbars" | "mandelbrot" | "rgbtestsrc";
+export const SYNTHETIC_PATTERNS: readonly SyntheticPattern[] = ["testsrc2", "smptehdbars", "mandelbrot", "rgbtestsrc"];
+
+export type VideoInput = { kind: "rawPipe"; fd: number } | { kind: "synthetic"; pattern: SyntheticPattern; seed: number };
+export type AudioInput = { kind: "rawPipe"; fd: number } | { kind: "synthetic"; toneHz: number };
+
+export interface CompositorSource { video: VideoInput; audio: AudioInput | null }
+
+export interface TileSpec {
+  /** Index into `sources`; null renders black. */
+  source: number | null;
+  /** Pixel rect inside the canvas; computed by `layoutRects` for grid layouts. */
+  rect: PxRect;
+  fit: SlotFit;
+}
+
+export type OverlaySpec =
+  | { kind: "image"; asset: number; x: number; y: number }
+  | { kind: "chyron"; asset: number; y: number; speedPxPerSec: number };
+
+export interface MixInput { source: number; gainDb: number }
+
+export interface CompositorGraph {
+  canvas: Canvas;
+  layout: SceneLayout;
+  tiles: TileSpec[];
+  /** Drawn in order (lowest layer first). */
+  overlays: OverlaySpec[];
+  audio: { inputs: MixInput[]; masterGainDb: number };
+}
+
+export type CompositorOutput =
+  | { kind: "gate"; videoFd: 1; audioFd: 3 }
+  /** Golden-frame hashing: framemd5 of the first `frames` video frames (and the audio in that span) on stdout. */
+  | { kind: "framemd5"; frames: number };
+
+export interface CompositorPlan {
+  sources: CompositorSource[];
+  /** Absolute scratch paths of rendered overlay PNGs, by content id. */
+  assets: string[];
+  graph: CompositorGraph;
+  output: CompositorOutput;
+}
+
+export class CommandBuildError extends Error {
+  constructor(message: string) { super(message); this.name = "CommandBuildError"; }
+}
+function fail(message: string): never { throw new CommandBuildError(message); }
+
+function int(value: number, field: string, min: number, max: number): number {
+  if (!Number.isSafeInteger(value) || value < min || value > max) fail(`${field} must be an integer in ${min}..${max}`);
+  return value;
+}
+
+function fd(value: number, field: string): number { return int(value, field, 0, 1023); }
+
+/** Rendered assets live in the worker's scratch dir and are named by sha256 (§4.3). */
+const ASSET_PATH = /^\/(?:[A-Za-z0-9._-]+\/)*[0-9a-f]{64}\.png$/;
+function assetPath(path: string, field: string): string {
+  if (!ASSET_PATH.test(path) || path.split("/").includes("..")) fail(`${field} must be an absolute scratch path to <sha256>.png`);
+  return path;
+}
+
+function even(n: number): number { return Math.round(n / 2) * 2; }
+
+/** Even cell boundaries so every tile has even size and offset (yuv420p chroma alignment). */
+function boundaries(total: number, parts: number): number[] {
+  return Array.from({ length: parts + 1 }, (_, i) => (i === parts ? total : even((i * total) / parts)));
+}
+
+const GRID: Partial<Record<SceneLayout, [cols: number, rows: number]>> = { "2x1": [2, 1], "2x2": [2, 2], "3x3": [3, 3], "4x4": [4, 4] };
+
+/** Cell rects for grid layouts, in slot-index order (row-major). `single`/`pip` slot 0 is the full canvas. */
+export function layoutRects(layout: SceneLayout, canvas: Canvas): PxRect[] {
+  if (layout === "single" || layout === "pip") return [{ x: 0, y: 0, w: canvas.width, h: canvas.height }];
+  const grid = GRID[layout];
+  if (!grid) return [];
+  const xs = boundaries(canvas.width, grid[0]);
+  const ys = boundaries(canvas.height, grid[1]);
+  const rects: PxRect[] = [];
+  for (let r = 0; r < grid[1]; r += 1) {
+    for (let c = 0; c < grid[0]; c += 1) rects.push({ x: xs[c] ?? 0, y: ys[r] ?? 0, w: (xs[c + 1] ?? 0) - (xs[c] ?? 0), h: (ys[r + 1] ?? 0) - (ys[r] ?? 0) });
+  }
+  return rects;
+}
+
+/** Basis points (0..10000) of the canvas to an even pixel rect. */
+export function rectFromBasisPoints(r: { x: number; y: number; w: number; h: number }, canvas: Canvas): PxRect {
+  const x = even((r.x * canvas.width) / 10_000);
+  const y = even((r.y * canvas.height) / 10_000);
+  const w = Math.max(2, Math.min(canvas.width - x, even((r.w * canvas.width) / 10_000)));
+  const h = Math.max(2, Math.min(canvas.height - y, even((r.h * canvas.height) / 10_000)));
+  return { x, y, w, h };
+}
+
+function checkRect(r: PxRect, canvas: Canvas, field: string): void {
+  int(r.x, `${field}.x`, 0, canvas.width - 2);
+  int(r.y, `${field}.y`, 0, canvas.height - 2);
+  int(r.w, `${field}.w`, 2, canvas.width);
+  int(r.h, `${field}.h`, 2, canvas.height);
+  if (r.x % 2 || r.y % 2 || r.w % 2 || r.h % 2) fail(`${field} must be even-aligned`);
+  if (r.x + r.w > canvas.width || r.y + r.h > canvas.height) fail(`${field} must lie inside the canvas`);
+}
+
+function overlaps(a: PxRect, b: PxRect): boolean {
+  return a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
+}
+
+function tileFilter(fit: SlotFit, r: PxRect): string {
+  switch (fit) {
+    case "contain": return `scale=${r.w}:${r.h}:force_original_aspect_ratio=decrease:force_divisible_by=2,pad=${r.w}:${r.h}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1`;
+    case "cover": return `scale=${r.w}:${r.h}:force_original_aspect_ratio=increase:force_divisible_by=2,crop=${r.w}:${r.h},setsar=1`;
+    case "crop": return `crop=${r.w}:${r.h},setsar=1`;
+  }
+}
+
+function db(value: number): string { return `${value}dB`; }
+
+const AUDIO_FORMAT = `aformat=sample_fmts=s16:sample_rates=${GATE_SAMPLE_RATE}:channel_layouts=stereo`;
+
+/**
+ * The `-filter_complex` string. Input labels: video of source i is `[v{i}]`
+ * after the builder's `-i` ordering, audio `[a{i}]`, asset k `[o{k}]`.
+ */
+export function buildFilterGraph(plan: CompositorPlan, inputIndex: { video: number[]; audio: Array<number | null>; assets: number[] }): string {
+  const { graph } = plan;
+  const { canvas } = graph;
+  const chains: string[] = [];
+  const black = (w: number, h: number): string => `color=c=black:s=${w}x${h}:r=${canvas.fps}`;
+
+  // Video sources used by several tiles are split once.
+  const uses = new Map<number, number>();
+  for (const tile of graph.tiles) if (tile.source !== null) uses.set(tile.source, (uses.get(tile.source) ?? 0) + 1);
+  const taken = new Map<number, number>();
+  const videoPad = (source: number): string => {
+    const n = uses.get(source) ?? 0;
+    const input = `${inputIndex.video[source]}:v`;
+    if (n <= 1) return `[${input}]`;
+    if (!taken.has(source)) {
+      chains.push(`[${input}]split=${n}${Array.from({ length: n }, (_, i) => `[s${source}_${i}]`).join("")}`);
+      taken.set(source, 0);
+    }
+    const i = taken.get(source) ?? 0;
+    taken.set(source, i + 1);
+    return `[s${source}_${i}]`;
+  };
+
+  const tiles = graph.tiles.map((tile, i) => ({ tile, label: `t${i}` }));
+  const live = tiles.filter(({ tile }) => tile.source !== null);
+  for (const { tile, label } of live) chains.push(`${videoPad(tile.source ?? 0)}${tileFilter(tile.fit, tile.rect)}[${label}]`);
+
+  const W = canvas.width;
+  const H = canvas.height;
+  const stackable = graph.layout !== "pip" && live.every(({ tile }, i) => live.every((other, j) => i === j || !overlaps(tile.rect, other.tile.rect)));
+  if (live.length === 0) {
+    chains.push(`${black(W, H)}[base]`);
+  } else if (stackable && live.length >= 2) {
+    const layout = live.map(({ tile }) => `${tile.rect.x}_${tile.rect.y}`).join("|");
+    // xstack sizes its output to the tiles' bounding box; pad only when that is not the canvas.
+    const right = Math.max(...live.map(({ tile }) => tile.rect.x + tile.rect.w));
+    const bottom = Math.max(...live.map(({ tile }) => tile.rect.y + tile.rect.h));
+    const fit = right === W && bottom === H ? "" : `,pad=${W}:${H}:0:0:color=black`;
+    chains.push(`${live.map(({ label }) => `[${label}]`).join("")}xstack=inputs=${live.length}:layout=${layout}:fill=black${fit}[base]`);
+  } else if (stackable) {
+    const only = live[0]!;
+    const full = only.tile.rect.w === W && only.tile.rect.h === H;
+    chains.push(full ? `[${only.label}]null[base]` : `[${only.label}]pad=${W}:${H}:${only.tile.rect.x}:${only.tile.rect.y}:color=black[base]`);
+  } else {
+    // PIP and overlapping custom rects: overlay chain in slot order (later slots on top). The base
+    // is the first tile padded to the canvas, never a lavfi `color` source: an unpaced main input
+    // runs ahead of the live tiles, so framesync queues them (~10 frames of extra video latency,
+    // more than a swap's alignment margin) and keeps emitting frames after the inputs end.
+    const first = live[0]!;
+    const fullFirst = first.tile.rect.x === 0 && first.tile.rect.y === 0 && first.tile.rect.w === W && first.tile.rect.h === H;
+    let cur = first.label;
+    if (!fullFirst) {
+      chains.push(`[${first.label}]pad=${W}:${H}:${first.tile.rect.x}:${first.tile.rect.y}:color=black[bg]`);
+      cur = "bg";
+    }
+    live.slice(1).forEach(({ tile, label }, i) => {
+      const next = `c${i}`;
+      chains.push(`[${cur}][${label}]overlay=x=${tile.rect.x}:y=${tile.rect.y}:eof_action=repeat[${next}]`);
+      cur = next;
+    });
+    chains.push(`[${cur}]null[base]`);
+  }
+
+  let cur = "base";
+  graph.overlays.forEach((overlay, i) => {
+    const next = `ov${i}`;
+    const asset = `[${inputIndex.assets[overlay.asset]}:v]`;
+    if (overlay.kind === "image") {
+      // Default format (yuv420, alpha from the PNG): `format=auto` breaks the 1:1 main-frame
+      // mapping in FFmpeg 5.1 (~1 in 6 main frames duplicated and its neighbour dropped).
+      chains.push(`[${cur}]${asset}overlay=x=${overlay.x}:y=${overlay.y}:eof_action=repeat[${next}]`);
+    } else {
+      // §4.3 chyron: one wide pre-rendered strip scrolled right-to-left by an x-expression of t.
+      chains.push(`[${cur}]${asset}overlay=x='W-mod(t*${overlay.speedPxPerSec}\\,w+W)':y=${overlay.y}:eof_action=repeat[${next}]`);
+    }
+    cur = next;
+  });
+  chains.push(`[${cur}]format=yuv420p[vout]`);
+
+  // §2.3 program mix: volume per input → amix (dead sources fade out) → master gain.
+  const mix = graph.audio.inputs;
+  mix.forEach((m, i) => chains.push(`[${inputIndex.audio[m.source]}:a]${AUDIO_FORMAT},volume=${db(m.gainDb)}[m${i}]`));
+  const master = `volume=${db(graph.audio.masterGainDb)},${AUDIO_FORMAT}`;
+  if (mix.length === 0) chains.push(`anullsrc=r=${GATE_SAMPLE_RATE}:cl=stereo,${master}[aout]`);
+  else if (mix.length === 1) chains.push(`[m0]${master}[aout]`);
+  else chains.push(`${mix.map((_, i) => `[m${i}]`).join("")}amix=inputs=${mix.length}:duration=longest:dropout_transition=2:normalize=1,${master}[aout]`);
+  return chains.join(";");
+}
+
+function validatePlan(plan: CompositorPlan): void {
+  const { graph } = plan;
+  assertGeometry(graph.canvas);
+  if (plan.sources.length > 16) fail("at most 16 compositor sources");
+  plan.sources.forEach((s, i) => {
+    if (s.video.kind === "rawPipe") fd(s.video.fd, `sources[${i}].video.fd`);
+    else {
+      if (!SYNTHETIC_PATTERNS.includes(s.video.pattern)) fail(`sources[${i}].video.pattern`);
+      int(s.video.seed, `sources[${i}].video.seed`, 0, 1_000_000);
+    }
+    if (s.audio?.kind === "rawPipe") fd(s.audio.fd, `sources[${i}].audio.fd`);
+    else if (s.audio?.kind === "synthetic") int(s.audio.toneHz, `sources[${i}].audio.toneHz`, 20, 20_000);
+  });
+  plan.assets.forEach((a, i) => assetPath(a, `assets[${i}]`));
+  if (graph.tiles.length > 16) fail("at most 16 tiles");
+  graph.tiles.forEach((t, i) => {
+    if (t.source !== null) int(t.source, `tiles[${i}].source`, 0, plan.sources.length - 1);
+    checkRect(t.rect, graph.canvas, `tiles[${i}].rect`);
+    if (t.fit !== "contain" && t.fit !== "cover" && t.fit !== "crop") fail(`tiles[${i}].fit`);
+  });
+  if (graph.overlays.length > 64) fail("at most 64 overlays");
+  graph.overlays.forEach((o, i) => {
+    int(o.asset, `overlays[${i}].asset`, 0, plan.assets.length - 1);
+    int(o.y, `overlays[${i}].y`, 0, graph.canvas.height);
+    if (o.kind === "image") int(o.x, `overlays[${i}].x`, 0, graph.canvas.width);
+    else if (o.kind === "chyron") int(o.speedPxPerSec, `overlays[${i}].speedPxPerSec`, CHYRON_SPEED_MIN, CHYRON_SPEED_MAX);
+    else fail(`overlays[${i}].kind`);
+  });
+  const seen = new Set<number>();
+  graph.audio.inputs.forEach((m, i) => {
+    int(m.source, `audio.inputs[${i}].source`, 0, plan.sources.length - 1);
+    if (plan.sources[m.source]?.audio == null) fail(`audio.inputs[${i}] names a source without audio`);
+    if (seen.has(m.source)) fail(`audio.inputs[${i}] repeats a source`);
+    seen.add(m.source);
+    gainDb(m.gainDb, `audio.inputs[${i}].gainDb`);
+  });
+  if (graph.audio.masterGainDb < GAIN_DB_MIN || graph.audio.masterGainDb > GAIN_DB_MAX) fail("audio.masterGainDb out of range");
+  gainDb(graph.audio.masterGainDb, "audio.masterGainDb");
+  if (plan.output.kind === "framemd5") int(plan.output.frames, "output.frames", 1, 600);
+}
+
+const RAW_IN = ["-thread_queue_size", "64", "-probesize", "32", "-analyzeduration", "0"];
+
+function rawVideoInput(canvas: Canvas, fdNum: number): string[] {
+  return [...RAW_IN, "-f", "rawvideo", "-pix_fmt", "yuv420p", "-s", `${canvas.width}x${canvas.height}`, "-framerate", String(canvas.fps), "-i", `pipe:${fdNum}`];
+}
+
+function rawAudioInput(fdNum: number): string[] {
+  return [...RAW_IN, "-f", "s16le", "-ar", String(GATE_SAMPLE_RATE), "-ac", String(GATE_CHANNELS), "-i", `pipe:${fdNum}`];
+}
+
+function syntheticVideo(canvas: Canvas, pattern: SyntheticPattern, seed: number): string {
+  // Seeded temporal noise makes every source distinct and every frame different, deterministically.
+  return `${pattern}=s=${canvas.width}x${canvas.height}:r=${canvas.fps},noise=alls=12:allf=t+u:all_seed=${seed},format=yuv420p`;
+}
+
+/** Full compositor argv. The process reads N sources (+ assets) and writes the gate FIFOs on fds 1/3. */
+export function buildCompositorArgs(plan: CompositorPlan): string[] {
+  validatePlan(plan);
+  const { canvas } = plan.graph;
+  // Single-threaded filtering keeps golden frames deterministic and per-compositor CPU predictable.
+  // (Slice threads were measured in the S2a CPU smoke and did not change its bus drops.)
+  // eslint-disable-next-line no-restricted-syntax -- FFmpeg's -threads options, not the Threads provider
+  const args = ["-hide_banner", "-nostdin", "-loglevel", "error", "-threads", "1", "-filter_threads", "1", "-filter_complex_threads", "1"];
+  let next = 0;
+  const video: number[] = [];
+  const audio: Array<number | null> = [];
+  const synthetic = plan.output.kind === "framemd5";
+  for (const s of plan.sources) {
+    if (s.video.kind === "rawPipe") args.push(...rawVideoInput(canvas, s.video.fd));
+    else args.push("-f", "lavfi", "-i", syntheticVideo(canvas, s.video.pattern, s.video.seed));
+    video.push(next++);
+    if (s.audio === null) { audio.push(null); continue; }
+    if (s.audio.kind === "rawPipe") args.push(...rawAudioInput(s.audio.fd));
+    else args.push("-f", "lavfi", "-i", `sine=frequency=${s.audio.toneHz}:sample_rate=${GATE_SAMPLE_RATE}`);
+    audio.push(next++);
+  }
+  const assets: number[] = [];
+  for (const path of plan.assets) {
+    // One decoded frame, held by overlay's eof_action=repeat. A `-loop 1` image stream would be
+    // decoded every frame and framesync'd against the live main input, which jitters the main.
+    args.push("-framerate", String(canvas.fps), "-i", `file:${path}`);
+    assets.push(next++);
+  }
+  args.push("-filter_complex", buildFilterGraph(plan, { video, audio, assets }));
+  if (plan.output.kind === "gate") {
+    args.push("-map", "[vout]", "-f", "rawvideo", "-pix_fmt", "yuv420p", "-fps_mode", "passthrough", "-flush_packets", "1", "pipe:1",
+      "-map", "[aout]", "-f", "s16le", "-ar", String(GATE_SAMPLE_RATE), "-ac", String(GATE_CHANNELS), "-flush_packets", "1", "pipe:3");
+  } else {
+    void synthetic;
+    const seconds = (plan.output.frames / canvas.fps).toFixed(6);
+    args.push("-map", "[vout]", "-map", "[aout]", "-t", seconds, "-c:v", "rawvideo", "-c:a", "pcm_s16le", "-fflags", "+bitexact", "-flags:v", "+bitexact", "-flags:a", "+bitexact", "-f", "framemd5", "pipe:1");
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Ingest ×N normalize stage
+
+export type IngestInput =
+  /** Live MPEG-TS from the pinned egress relay on stdin (WP7). */
+  | { kind: "mpegtsPipe" }
+  /**
+   * Playlist source (§5.1): the asset feeder's concatenated MPEG-TS on stdin, read at native rate
+   * (`-re`; assets arrive far faster than real time). The feeder shifts each asset to where the
+   * previous one ended, so timestamps are monotonic and the normalize stage and the gate hide
+   * asset boundaries. Audio is optional (a silent asset gets the bus's silence fill).
+   */
+  | { kind: "playlistPipe" }
+  /** Deterministic test source, paced at native rate. */
+  | { kind: "synthetic"; pattern: SyntheticPattern; seed: number; toneHz: number };
+
+export interface IngestPlan {
+  input: IngestInput;
+  canvas: Canvas;
+  /** "none" when the source is known to have no audio track: silence is generated instead. */
+  audio: "source" | "none";
+}
+
+/**
+ * One process per source: decode → scale/pad to the canvas, CFR at the canvas
+ * fps, yuv420p; audio → 48 kHz s16le stereo. Video on fd 1, PCM on fd 3.
+ */
+export function buildIngestArgs(plan: IngestPlan): string[] {
+  const { canvas, input } = plan;
+  assertGeometry(canvas);
+  // Auto frame-threading scales with host CPU count and adds almost a second of decode
+  // latency on a 28-core host. Independently warming ingests then hold different amounts
+  // of history in the compositor inputs. Bound decode/filter latency and emit raw frames
+  // synchronously instead of frame-threading the rawvideo encoder as well.
+  // eslint-disable-next-line no-restricted-syntax -- FFmpeg options, not the Threads provider
+  const args = ["-hide_banner", "-nostdin", "-loglevel", "error", "-threads", "2", "-filter_threads", "1"];
+  if (input.kind === "mpegtsPipe") {
+    args.push("-fflags", "+genpts+discardcorrupt", "-f", "mpegts", "-i", "pipe:0");
+  } else if (input.kind === "playlistPipe") {
+    args.push("-re", "-fflags", "+genpts+discardcorrupt", "-f", "mpegts", "-i", "pipe:0");
+  } else {
+    if (!SYNTHETIC_PATTERNS.includes(input.pattern)) fail("ingest pattern");
+    int(input.seed, "ingest seed", 0, 1_000_000);
+    int(input.toneHz, "ingest toneHz", 20, 20_000);
+    args.push("-re", "-f", "lavfi", "-i", syntheticVideo(canvas, input.pattern, input.seed),
+      "-re", "-f", "lavfi", "-i", `sine=frequency=${input.toneHz}:sample_rate=${GATE_SAMPLE_RATE}`);
+  }
+  const audioIndex = input.kind === "synthetic" ? 1 : 0;
+  if (plan.audio === "none") args.push("-f", "lavfi", "-i", `anullsrc=r=${GATE_SAMPLE_RATE}:cl=stereo`);
+  const silenceIndex = input.kind === "synthetic" ? 2 : 1;
+  const sourceAudio = input.kind === "playlistPipe" ? `${audioIndex}:a:0?` : `${audioIndex}:a:0`;
+  const W = canvas.width;
+  const H = canvas.height;
+  args.push(
+    "-map", "0:v:0",
+    "-vf", `scale=${W}:${H}:force_original_aspect_ratio=decrease:force_divisible_by=2,pad=${W}:${H}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,fps=${canvas.fps},format=yuv420p`,
+    // eslint-disable-next-line no-restricted-syntax -- FFmpeg rawvideo thread option, not the Threads provider
+    "-c:v", "rawvideo", "-threads:v", "1", "-f", "rawvideo", "-pix_fmt", "yuv420p", "-flush_packets", "1", "pipe:1",
+    "-map", plan.audio === "none" ? `${silenceIndex}:a:0` : sourceAudio,
+    "-af", `aresample=${GATE_SAMPLE_RATE}:async=1000,${AUDIO_FORMAT}`,
+    "-f", "s16le", "-ar", String(GATE_SAMPLE_RATE), "-ac", String(GATE_CHANNELS), "-flush_packets", "1", "pipe:3",
+  );
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Persistent encoder
+
+export type EncoderOutput = { kind: "flvPipe"; fd: number } | { kind: "null" };
+
+/**
+ * Program preview tap (§2.1: "the program tap is the same mechanism applied to the gate output"):
+ * the encoder also emits what it encodes, downscaled to `size`, as raw yuv420p + s16le on two
+ * extra fds that a source-bus helper reads. Each tap output is a `tee` with `onfail=ignore` plus a
+ * `null` anchor slave: a dead tap reader closes only that slave ("continuing with 1/2 slaves"),
+ * never the encoder (with a single slave ffmpeg 5.1 fails the whole output, verified in S2b).
+ */
+export interface EncoderProgramTap { videoFd: number; audioFd: number; size: { width: number; height: number } }
+
+export interface EncoderPlan { canvas: Canvas; videoBitrateKbps: number; audioBitrateKbps: number; output: EncoderOutput; programTap?: EncoderProgramTap }
+
+/** Reads the gate on fds 0 (video) / 3 (audio). Started once per channel; scene changes never restart it. */
+export function buildEncoderArgs(plan: EncoderPlan): string[] {
+  const { canvas, programTap: tap } = plan;
+  assertGeometry(canvas);
+  const vb = int(plan.videoBitrateKbps, "videoBitrateKbps", 200, 50_000);
+  const ab = int(plan.audioBitrateKbps, "audioBitrateKbps", 32, 320);
+  const args = ["-hide_banner", "-nostdin", "-loglevel", "error", ...rawVideoInput(canvas, 0), ...rawAudioInput(3)];
+  if (tap) {
+    const w = int(tap.size.width, "programTap.width", 2, canvas.width);
+    const h = int(tap.size.height, "programTap.height", 2, canvas.height);
+    if (w % 2 || h % 2) fail("programTap size must be even");
+    args.push("-filter_complex", `[0:v]split=2[enc][tap];[tap]scale=${w}:${h}:flags=bilinear,format=yuv420p[tapv];[1:a]asplit=2[enca][tapa]`,
+      "-map", "[enc]", "-map", "[enca]");
+  } else {
+    args.push("-map", "0:v", "-map", "1:a");
+  }
+  args.push(
+    "-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency", "-pix_fmt", "yuv420p",
+    "-b:v", `${vb}k`, "-maxrate", `${vb}k`, "-bufsize", `${vb * 2}k`, "-g", String(canvas.fps * 2), "-keyint_min", String(canvas.fps * 2), "-sc_threshold", "0",
+    "-c:a", "aac", "-b:a", `${ab}k`, "-ar", String(GATE_SAMPLE_RATE));
+  if (plan.output.kind === "flvPipe") args.push("-f", "flv", `pipe:${fd(plan.output.fd, "output.fd")}`);
+  else args.push("-f", "null", "-");
+  if (tap) {
+    const v = fd(tap.videoFd, "programTap.videoFd");
+    const a = fd(tap.audioFd, "programTap.audioFd");
+    args.push("-map", "[tapv]", "-c:v", "rawvideo", "-f", "tee", `[f=rawvideo:onfail=ignore]pipe:${v}|[f=null]-`,
+      "-map", "[tapa]", "-c:a", "pcm_s16le", "-f", "tee", `[f=s16le:onfail=ignore]pipe:${a}|[f=null]-`);
+  }
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Playlist feeder (§5.1)
+
+/** Output timestamp offset: microseconds, rendered as seconds (bounded: ~1 year of continuous playout). */
+function tsOffset(offsetUs: number): string {
+  return (int(offsetUs, "offsetUs", 0, 365 * 86_400 * 1_000_000) / 1e6).toFixed(6);
+}
+
+/**
+ * Remux of one playlist asset (pre-normalized at upload, so never transcoded) from stdin to MPEG-TS
+ * on stdout, with its timestamps shifted to `offsetUs` (where the previous asset ended), so the
+ * concatenated stream is monotonic. FFmpeg 5.1's own MPEG-TS discontinuity correction does not
+ * work with `-re` (measured: 1.3–2 s stalls and bursts at every boundary). `-progress pipe:3`
+ * reports the asset's end (`out_time_us`, excluding the offset) for the next asset's offset.
+ * `initial_discontinuity` marks the continuity-counter restart as legitimate.
+ */
+export function buildPlaylistRemuxArgs(offsetUs: number): string[] {
+  return ["-hide_banner", "-nostdin", "-loglevel", "error", "-progress", "pipe:3", "-protocol_whitelist", "pipe", "-i", "pipe:0",
+    "-map", "0:v:0", "-map", "0:a:0?", "-c", "copy", "-output_ts_offset", tsOffset(offsetUs),
+    "-f", "mpegts", "-mpegts_flags", "+initial_discontinuity", "-muxdelay", "0", "pipe:1"];
+}
+
+/**
+ * Slate floor (§5.1): `seconds` of a still (the rendered slate PNG when there is one, else black)
+ * plus silence as MPEG-TS at `offsetUs`, fed when no asset can be played or a non-looping playlist
+ * has ended. Encoded faster than real time and paced by the playlist ingest like any asset.
+ */
+export function buildSlateArgs(plan: { canvas: Canvas; seconds: number; image: string | null; offsetUs: number }): string[] {
+  const { canvas } = plan;
+  assertGeometry(canvas);
+  const seconds = int(plan.seconds, "slate seconds", 1, 60);
+  const args = ["-hide_banner", "-nostdin", "-loglevel", "error", "-progress", "pipe:3"];
+  if (plan.image) args.push("-loop", "1", "-framerate", String(canvas.fps), "-i", `file:${assetPath(plan.image, "slate image")}`);
+  else args.push("-f", "lavfi", "-i", `color=c=black:s=${canvas.width}x${canvas.height}:r=${canvas.fps}`);
+  args.push("-f", "lavfi", "-i", `anullsrc=r=${GATE_SAMPLE_RATE}:cl=stereo`, "-t", String(seconds),
+    "-vf", `scale=${canvas.width}:${canvas.height}:force_original_aspect_ratio=decrease:force_divisible_by=2,pad=${canvas.width}:${canvas.height}:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1,format=yuv420p`,
+    "-c:v", "libx264", "-preset", "ultrafast", "-tune", "stillimage", "-g", String(canvas.fps), "-b:v", "500k",
+    "-c:a", "aac", "-b:a", "64k", "-output_ts_offset", tsOffset(plan.offsetUs),
+    "-f", "mpegts", "-mpegts_flags", "+initial_discontinuity", "-muxdelay", "0", "pipe:1");
+  return args;
+}
+
+export const MediaCommandBuilder = {
+  layoutRects, rectFromBasisPoints, buildFilterGraph,
+  compositor: buildCompositorArgs,
+  ingest: buildIngestArgs,
+  encoder: buildEncoderArgs,
+} as const;
diff --git a/apps/media-worker/src/compositor/compositor.ts b/apps/media-worker/src/compositor/compositor.ts
new file mode 100644
index 0000000..241113b
--- /dev/null
+++ b/apps/media-worker/src/compositor/compositor.ts
@@ -0,0 +1,95 @@
+import type { StdioOptions } from "node:child_process";
+import type { FrameGate } from "../gate/frame-gate";
+import { spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+import { buildCompositorArgs, type CompositorGraph, type CompositorSource } from "./command-builder";
+import type { BusSubscription, SourceBus } from "./source-bus";
+
+/** A scene ready to compose: buses in input order plus the typed graph (source indexes refer to `inputs`). */
+export interface ComposeRequest {
+  inputs: Array<{ bus: SourceBus; audio: boolean }>;
+  assets: string[];
+  graph: CompositorGraph;
+}
+
+const FIRST_INPUT_FD = 4;
+
+/**
+ * One compositor process (A or B of a swap). Reads its sources from bus
+ * subscription FIFOs inherited on fds 4.., writes the gate's slot FIFOs on fds 1 and 3.
+ * Its lifetime is bounded by the gate: when the gate retires the slot the FIFOs
+ * close and the process gets EPIPE; `stop()` also escalates to SIGKILL.
+ */
+export class CompositorInstance {
+  private proc: ManagedProcess | null = null;
+  /** One per input, in request order (valid after `start()`). */
+  subscriptions: BusSubscription[] = [];
+  /** Gate origin sent at attach (see protocol.attachLine). */
+  origin: number | undefined;
+  slotId = 0;
+
+  constructor(
+    private readonly gate: FrameGate,
+    private readonly request: ComposeRequest,
+    private readonly redactor: StderrRedactor,
+    private readonly onStderr: (message: string) => void,
+  ) {}
+
+  get pid(): number | undefined { return this.proc?.child.pid; }
+
+  /**
+   * Subscribes, spawns and attaches to the gate as the pending slot. `originFor`
+   * maps the fresh subscriptions to a gate origin. Resolve ≠ on air: use `gate.waitActive(slotId)`.
+   */
+  async start(originFor?: (subscriptions: BusSubscription[]) => number | undefined): Promise<void> {
+    const slot = this.gate.allocateSlot();
+    this.slotId = slot.id;
+    try {
+      for (const input of this.request.inputs) this.subscriptions.push(await input.bus.subscribe({ video: true, audio: input.audio }));
+    } catch (error) {
+      slot.fifos.releaseWriters();
+      slot.fifos.releaseHolders();
+      slot.fifos.unlink();
+      await this.stop();
+      throw error;
+    }
+    let next = FIRST_INPUT_FD;
+    const inputFds: number[] = [];
+    const sources: CompositorSource[] = this.subscriptions.map((sub) => {
+      if (sub.videoFd === null) throw new Error("compositor input without video");
+      inputFds.push(sub.videoFd);
+      const video = { kind: "rawPipe" as const, fd: next++ };
+      if (sub.audioFd === null) return { video, audio: null };
+      inputFds.push(sub.audioFd);
+      return { video, audio: { kind: "rawPipe" as const, fd: next++ } };
+    });
+    const args = buildCompositorArgs({ sources, assets: this.request.assets, graph: this.request.graph, output: { kind: "gate", videoFd: 1, audioFd: 3 } });
+    const stdio: StdioOptions = ["ignore", slot.fifos.videoFd, "pipe", slot.fifos.audioFd, ...inputFds];
+    let proc: ManagedProcess;
+    try {
+      proc = spawnManaged("ffmpeg", args, stdio, this.redactor, this.onStderr);
+    } finally {
+      slot.fifos.releaseWriters();
+      // The compositor holds the read ends now: when it exits, the bus sees EPIPE and drops it.
+      for (const sub of this.subscriptions) sub.releaseReaders();
+    }
+    this.proc = proc;
+    try {
+      await proc.started;
+      this.origin = originFor?.(this.subscriptions);
+      await this.gate.attach(slot, this.origin);
+    } catch (error) {
+      slot.fifos.releaseHolders();
+      slot.fifos.unlink();
+      await this.stop();
+      throw error;
+    }
+  }
+
+  async stop(): Promise<void> {
+    for (const sub of this.subscriptions) sub.unsubscribe();
+    await this.proc?.terminate();
+    this.proc = null;
+  }
+
+  kill(signal: NodeJS.Signals): void { this.proc?.kill(signal); }
+}
diff --git a/apps/media-worker/src/compositor/cpu-smoke.ts b/apps/media-worker/src/compositor/cpu-smoke.ts
new file mode 100644
index 0000000..3d991d6
--- /dev/null
+++ b/apps/media-worker/src/compositor/cpu-smoke.ts
@@ -0,0 +1,206 @@
+/**
+ * S2 CPU budget and sustained transport gate:
+ * 4 × 1080p30 H.264 MPEG-TS sources → ingest×4 (decode + normalize) → source-bus helpers →
+ * 2x2 compositor with a lower third and a chyron → Rust frame gate → x264
+ * veryfast 6 Mb/s persistent encoder (-f null). CPU per process from
+ * /proc/<pid>/stat over the measurement window, plus the worker (Node) itself.
+ *
+ *   node --import tsx src/compositor/cpu-smoke.ts [--seconds 30] [--swaps-every 0]
+ *        [--warmup-seconds 30] [--settle-max 45]
+ */
+import { closeSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ManagedProcess } from "../relay/ffmpeg";
+import { layoutRects, type Canvas, type CompositorGraph } from "./command-builder";
+import type { ComposeRequest } from "./compositor";
+import { IngestProcess } from "./ingest";
+import { ProgramChain } from "./program";
+import { encodeSourceClip, ensureGateBinary, makeAssets, passthroughRedactor, startPacer } from "./testing";
+
+const canvas: Canvas = { width: 1920, height: 1080, fps: 30 };
+const TICKS = 100; // USER_HZ
+
+function cpuTicks(pid: number | undefined): number {
+  if (pid === undefined) return 0;
+  try {
+    const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
+    const fields = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+    return Number(fields[11]) + Number(fields[12]); // utime + stime
+  } catch { return 0; }
+}
+
+/** Time spent runnable but not running (host contention), ns, from /proc/<pid>/schedstat (all threads). */
+function runDelayNs(pid: number | undefined): number {
+  if (pid === undefined) return 0;
+  try {
+    let total = 0;
+    for (const tid of readdirSync(`/proc/${pid}/task`)) total += Number(readFileSync(`/proc/${pid}/task/${tid}/schedstat`, "utf8").split(" ")[1] ?? 0);
+    return total;
+  } catch { return 0; }
+}
+
+function arg(name: string, fallback: number): number {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? Number(process.argv[i + 1]) : fallback;
+}
+
+async function main(): Promise<void> {
+  const seconds = arg("seconds", 30);
+  const swapEvery = arg("swaps-every", 0);
+  const minimumWarmup = arg("warmup-seconds", 30);
+  const settleCap = arg("settle-max", 45);
+  if (!Number.isFinite(seconds) || seconds <= 0 || !Number.isFinite(swapEvery) || swapEvery < 0
+    || !Number.isFinite(minimumWarmup) || minimumWarmup < 0 || !Number.isFinite(settleCap) || settleCap < Math.max(3, minimumWarmup)) {
+    throw new Error("invalid smoke duration, swap interval, or warmup/settle bounds");
+  }
+  if (!ensureGateBinary()) throw new Error("native helpers unavailable (cargo build failed)");
+  const dir = mkdtempSync(join(tmpdir(), "cpu-smoke-"));
+  const procs: ManagedProcess[] = [];
+  const ingests: IngestProcess[] = [];
+  let chain: ProgramChain | null = null;
+  try {
+    // A 1080p30 H.264 + AAC source clip (encoded once, before measuring).
+    const clip = join(dir, "src.ts");
+    encodeSourceClip(clip, canvas);
+    const assets = makeAssets(dir);
+
+    for (let i = 0; i < 4; i += 1) {
+      // Stand-in for the pinned egress relay: a paced remux of the clip into a FIFO the ingest reads.
+      const { readFd, proc: pacer } = await startPacer(clip, dir, `src${i}`);
+      procs.push(pacer);
+      const ingest = new IngestProcess(`s${i}`, { input: { kind: "mpegtsPipe" }, canvas, audio: "source" }, readFd, join(dir, "gate"), passthroughRedactor,
+        (m) => process.stderr.write(m), (id, r) => process.stderr.write(`${id} ${r}\n`));
+      await ingest.start();
+      closeSync(readFd);
+      ingests.push(ingest);
+    }
+
+    const graph = (i: number): CompositorGraph => ({
+      canvas, layout: "2x2",
+      tiles: layoutRects("2x2", canvas).map((rect, t) => ({ source: (t + i) % 4, rect, fit: "contain" as const })),
+      overlays: [{ kind: "image", asset: 0, x: 96, y: 900 }, { kind: "chyron", asset: 1, y: 1040, speedPxPerSec: 120 }],
+      audio: { inputs: [{ source: 0, gainDb: 0 }, { source: 1, gainDb: -6 }], masterGainDb: 0 },
+    });
+    const request = (i: number): ComposeRequest => ({ inputs: ingests.map((ing, k) => ({ bus: ing.bus, audio: k < 2 })), assets, graph: graph(i) });
+    const fatal: string[] = [];
+    chain = new ProgramChain({ canvas, scratchDir: join(dir, "gate"), videoBitrateKbps: 6000, output: { kind: "null" },
+      redactor: passthroughRedactor, onStderr: (m) => process.stderr.write(m), onFatal: (r) => fatal.push(r) });
+    const tStart = Date.now();
+    await chain.start(request(0));
+    const warmupEnd = Date.now() + minimumWarmup * 1000;
+    // Warm-up: the first seconds are a startup transient on a loaded host (4 ingests bursting to
+    // catch up with their sources, compositor and x264 warming up), during which the compositor's
+    // bus queues stand near the backlog limit and the gate repeats. Measure the steady state: wait
+    // until every subscriber queue is within its configured backlog + replay history
+    // and neither bus drops nor gate fills increase for 3 consecutive seconds. Allow at least
+    // 30 s for demux/decoder queues and x264 to warm, at most 45 s by default. Startup loss
+    // stays visible separately; the sustained window begins only after this declared warmup.
+    // A queue can remain nonempty at native rate: it reflects fixed pipeline/replay delay,
+    // not overload. Absence of drops/fills at bounded depth is the steady-state criterion.
+    const backlogLimit = Math.min(...ingests.map((ingest) => ingest.bus.maxBacklogFrames + ingest.bus.historyFrames));
+    let calm = 0;
+    const initialGate = await chain.stats();
+    let lastFills = initialGate.vrep + initialGate.asil;
+    let lastDrops = (await Promise.all(ingests.map((ingest) => ingest.bus.stats()))).reduce((total, bus) => total + bus.subscriberDrops, 0);
+    const settleTrace: Array<[number, number, number]> = [];
+    for (let s = 0; s < settleCap && (calm < 3 || Date.now() < warmupEnd); s += 1) {
+      await new Promise((r) => setTimeout(r, 1_000));
+      const buses = await Promise.all(ingests.map((i) => i.bus.stats()));
+      const q = Math.max(0, ...buses.flatMap((bus) => bus.subscribers.map((sub) => sub.queued)));
+      const drops = buses.reduce((total, bus) => total + bus.subscriberDrops, 0);
+      const gate = await chain.stats();
+      const fills = gate.vrep + gate.asil;
+      settleTrace.push([q, fills - lastFills, drops - lastDrops]);
+      calm = q <= backlogLimit && fills === lastFills && drops === lastDrops ? calm + 1 : 0;
+      lastFills = fills;
+      lastDrops = drops;
+    }
+    const settleS = (Date.now() - tStart) / 1000;
+    const startupDrops = (await Promise.all(ingests.map((i) => i.bus.stats()))).reduce((a, b) => a + b.subscriberDrops, 0);
+
+    const pids = {
+      ingest: ingests.map((i) => i.pid),
+      compositor: () => chain?.activeCompositor?.pid,
+      gate: chain.gate.pid,
+      encoder: chain.encoderPid,
+    };
+    const busPids = ingests.map((i) => i.bus.pid);
+    const snap = async () => {
+      const buses = await Promise.all(ingests.map((i) => i.bus.stats()));
+      return {
+        ingest: pids.ingest.map(cpuTicks).reduce((a, b) => a + b, 0),
+        compositor: cpuTicks(pids.compositor()),
+        gate: cpuTicks(pids.gate),
+        encoder: cpuTicks(pids.encoder),
+        buses: busPids.map(cpuTicks).reduce((a, b) => a + b, 0),
+        worker: process.cpuUsage(),
+        busDrops: buses.reduce((a, b) => a + b.subscriberDrops, 0),
+        busPairs: buses.map((b) => b.pairs),
+        busStats: buses,
+        delay: { compositor: runDelayNs(pids.compositor()), encoder: runDelayNs(pids.encoder), gate: runDelayNs(pids.gate) },
+      };
+    };
+    await chain.gate.resetPeaks();
+    const g0 = await chain.stats();
+    const s0 = await snap();
+    const t0 = Date.now();
+    let swaps = 0;
+    // Deepest subscriber queue seen per second (frames waiting in a source-bus helper for a consumer).
+    const queueMax: number[] = [];
+    while (Date.now() - t0 < seconds * 1000) {
+      await new Promise((r) => setTimeout(r, swapEvery > 0 ? swapEvery * 1000 : 1000));
+      if (swapEvery > 0) { await chain.swap(request(++swaps)); }
+      const depths = (await Promise.all(ingests.map((i) => i.bus.stats()))).flatMap((b) => b.subscribers.map((s) => s.queued));
+      queueMax.push(Math.max(0, ...depths));
+    }
+    const s1 = await snap();
+    const g1 = await chain.stats();
+    const wall = (Date.now() - t0) / 1000;
+    const pct = (ticks: number): number => Number(((ticks / TICKS / wall) * 100).toFixed(1));
+    const workerUs = (s1.worker.user + s1.worker.system) - (s0.worker.user + s0.worker.system);
+    const result = {
+      host: { cpus: (await import("node:os")).cpus().length, model: (await import("node:os")).cpus()[0]?.model, loadavg: (await import("node:os")).loadavg() },
+      wallS: wall, swaps,
+      // Seconds from chain start to steady state, the per-second [max queue, gate repeats] trace, and drops before the window.
+      settleS, minimumWarmupS: minimumWarmup, settled: calm >= 3 && Date.now() >= warmupEnd, settleTrace, startupDrops,
+      startupGate: { ticks: g0.ticks, vrep: g0.vrep, asil: g0.asil, outDrops: g0.outDrops },
+      pctOfOneCore: {
+        ingestX4: pct(s1.ingest - s0.ingest),
+        compositor: swapEvery > 0 ? null : pct(s1.compositor - s0.compositor),
+        gate: pct(s1.gate - s0.gate),
+        encoderX264: pct(s1.encoder - s0.encoder),
+        sourceBusX4: pct(s1.buses - s0.buses),
+        workerNode: Number(((workerUs / 1e6 / wall) * 100).toFixed(1)),
+      },
+      // Pairs the buses dropped for a subscriber that fell behind, inside the window (a compositor not keeping up).
+      busDropsInWindow: s1.busDrops - s0.busDrops,
+      busQueueMaxPerSecond: queueMax,
+      // Host contention: ms per second of wall time each process (all threads) sat runnable but not scheduled.
+      runDelayMsPerS: {
+        compositor: Number(((s1.delay.compositor - s0.delay.compositor) / 1e6 / wall).toFixed(1)),
+        encoder: Number(((s1.delay.encoder - s0.delay.encoder) / 1e6 / wall).toFixed(1)),
+        gate: Number(((s1.delay.gate - s0.delay.gate) / 1e6 / wall).toFixed(1)),
+      },
+      // Source pairs each bus produced inside the window (≈ 30 × wallS for a paced 30 fps source).
+      busPairsInWindow: s1.busPairs.map((n, k) => n - (s0.busPairs[k] ?? 0)),
+      gate: { ticks: g1.ticks - g0.ticks, vrep: g1.vrep - g0.vrep, asil: g1.asil - g0.asil, lateOverFrame: g1.lateOverFrame, lateMaxUs: g1.lateMaxUs, outDrops: g1.outDrops - g0.outDrops },
+      buses: s1.busStats,
+      fatal,
+    };
+    const p = result.pctOfOneCore;
+    process.stdout.write(`${JSON.stringify({ ...result, totalCores: Number((((p.ingestX4 + (p.compositor ?? 0) + p.gate + p.encoderX264 + p.sourceBusX4 + p.workerNode) / 100)).toFixed(2)) })}\n`);
+    if (!result.settled || result.busDropsInWindow !== 0 || result.gate.vrep !== 0 || result.gate.asil !== 0 || result.gate.outDrops !== 0 || fatal.length > 0
+      || result.busPairsInWindow.some((pairs) => pairs < canvas.fps * wall * 0.98)) {
+      throw new Error("cpu-smoke failed: require settled 4×1080p30, zero bus drops, zero gate fills/output drops, and no fatal exit");
+    }
+  } finally {
+    await chain?.stop();
+    for (const i of ingests) await i.stop();
+    for (const p of procs) await p.terminate(500);
+    rmSync(dir, { recursive: true, force: true });
+  }
+  process.exit(0);
+}
+
+if (require.main === module) void main().catch((error: unknown) => { process.stderr.write(`${String(error)}\n`); process.exit(1); });
diff --git a/apps/media-worker/src/compositor/golden-frames.json b/apps/media-worker/src/compositor/golden-frames.json
new file mode 100644
index 0000000..2d5f31a
--- /dev/null
+++ b/apps/media-worker/src/compositor/golden-frames.json
@@ -0,0 +1,115 @@
+{
+  "ffmpeg": "ffmpeg version 5.1.9-0+deb12u1 Copyright (c) 2000-2026 the FFmpeg developers",
+  "canvas": {
+    "width": 320,
+    "height": 180,
+    "fps": 30
+  },
+  "frames": 4,
+  "layouts": {
+    "single": [
+      "0:0:86400:473ec55d56d6cd3f85b31ef5f0b615b2",
+      "1:0:4096:f858b65fe890efbc0ac6cf1e085a37d2",
+      "1:1024:4096:e3ef895bb0e533a4a8a89d5a6ed843f6",
+      "0:1:86400:80e9688e53079ff4623b78115e2b6b1c",
+      "1:2048:4096:8da1b5054e4f15590b674af0c5239537",
+      "1:3072:4096:18a3a0028363827191cd4d8885bc2b11",
+      "0:2:86400:f2b6d37903c429f8ad6c4416056a8538",
+      "1:4096:4096:aecafa4e5f0f3626cc00a9849cbcc3fa",
+      "0:3:86400:5113494af070e29d7c5c6cbbbaa7a721",
+      "1:5120:4096:749e60b205100820f0f493a79c17ee46",
+      "1:6144:1024:f465c566bd65b8743119b970d5b9734e"
+    ],
+    "pip": [
+      "0:0:86400:ff2365f77b17a7437246001c3282af88",
+      "1:0:4096:fd773b1ed90b3793d331bebf439d85a7",
+      "1:1024:4096:e1a1133f44e0c84ae28eca0ac57333c9",
+      "0:1:86400:9a238c82abca419758f64d31f3f5080e",
+      "1:2048:4096:c7f8ec938afbe515acf2cc21ee07b398",
+      "1:3072:4096:c99fc35fb2f9fb03c18e8ff04b5300a5",
+      "0:2:86400:ef78085de2d4d6f6e20e266e40e7a07d",
+      "1:4096:4096:62bc5a8e144fb37ec4e5a48fa0a3179a",
+      "0:3:86400:956a390b4024b79289063d54abde9c07",
+      "1:5120:4096:20dd40a44d6167e3d20631d72cca7021",
+      "1:6144:1024:4aebc7614678f7837d5c2c42c7ae5049"
+    ],
+    "2x1": [
+      "0:0:86400:124ceb28ce6fb2adda306ebab85c020e",
+      "1:0:4096:779110ff86bde4abc0c312c254c6a07b",
+      "1:1024:4096:58bf6a6a073a28c148162edbfb1cb2f0",
+      "0:1:86400:2a815118db500f1fe35af785761546d3",
+      "1:2048:4096:b47c4007c2bd03d67892ed6c4d2e0ad2",
+      "1:3072:4096:4c1fa084e7e962bdfccc6445944fe6bd",
+      "0:2:86400:fb62f8882a43ace4e0a50f611ba5b011",
+      "1:4096:4096:96331541b14dd07c95116914832e2646",
+      "0:3:86400:3d22dd326e76b9ace9b605e67568c5c9",
+      "1:5120:4096:8d09c0dd1dd3d94d2296b8b96a887d0f",
+      "1:6144:1024:456a74bc6828cb74630049d3c3ede52b"
+    ],
+    "2x2": [
+      "0:0:86400:c1a86085e98caf0c6ddca6eecd76f996",
+      "1:0:4096:f2e48ac5003bebe6980227d7984f03ee",
+      "1:1024:4096:c42c6c8bd7e38a04da330614958e8ec7",
+      "0:1:86400:eacfcee60a815e7098d9f2678ef3a2b8",
+      "1:2048:4096:07d15edac8583afe4f0c37062f8e2e95",
+      "1:3072:4096:2eeb48f1b0671b51871cca079144b9a0",
+      "0:2:86400:a69202dd6be84938c0669cfb1b1aea91",
+      "1:4096:4096:86b18ee36947048c70bacd00707025d0",
+      "0:3:86400:339a15c6489b3af66d4cbe4311179d0f",
+      "1:5120:4096:e10e40ebb313c090b2679d523299c4f4",
+      "1:6144:1024:2f3a2ef3cc8c5f0206828e53fe002d1b"
+    ],
+    "3x3": [
+      "0:0:86400:dfffffffbc45583776628ba9e07d2ac7",
+      "1:0:4096:95afee33956e36002cb7bc4174d41fb8",
+      "1:1024:4096:4cc1e8ca719bd34775c4bc5f0f1d1149",
+      "0:1:86400:495bf533902abce01a4c6213275d4a8a",
+      "1:2048:4096:39a06315fe075c8d02500f7b69f9d0b1",
+      "1:3072:4096:28a2f2f96cbb5947d1ad1bf6f0f656d3",
+      "0:2:86400:2b721e57614c93bc1a50f486317d3a69",
+      "1:4096:4096:f80381b7c6e59ac4ed8cf350cdf675ae",
+      "0:3:86400:8e738a80e6b6a24d2c97f0a4a819e8b4",
+      "1:5120:4096:47905d32edded2c3b98653ac97c9b92e",
+      "1:6144:1024:7cdba1f0765decdaa01239f8d415ce83"
+    ],
+    "4x4": [
+      "0:0:86400:9b5bc219325405095ad5c3ed5acc1ea1",
+      "1:0:4096:620f0b67a91f7f74151bc5be745b7110",
+      "1:1024:4096:620f0b67a91f7f74151bc5be745b7110",
+      "0:1:86400:f96bf1c80e7dfac31e8e612139c0ad40",
+      "1:2048:4096:620f0b67a91f7f74151bc5be745b7110",
+      "1:3072:4096:620f0b67a91f7f74151bc5be745b7110",
+      "0:2:86400:0b6280a6f2b063114eb892b8fa2ef406",
+      "1:4096:4096:620f0b67a91f7f74151bc5be745b7110",
+      "0:3:86400:73f848d7c873b09ef45467fe2a8b5785",
+      "1:5120:4096:620f0b67a91f7f74151bc5be745b7110",
+      "1:6144:1024:0f343b0931126a20f133d67c2b018a3b"
+    ],
+    "custom": [
+      "0:0:86400:7151990b9ab56564d8f6f1ab63edd9ee",
+      "1:0:4096:8904df5033d62a7340b98e03dea71359",
+      "1:1024:4096:9fa5c863b67d9831fa7bc93cbe868e4e",
+      "0:1:86400:ccfdc3ae531e8d495aa67e2989dd8e72",
+      "1:2048:4096:5602eff96d58dd2c18365237b01aeac5",
+      "1:3072:4096:d6702b18d7e15f6ead23e77cdb3b7be0",
+      "0:2:86400:9725c1c13fccbc094cad0c2ef683fbab",
+      "1:4096:4096:3090fcea0f7513e35c03b80a199925be",
+      "0:3:86400:019eb04e7297c7bae18d86f47ebbfee7",
+      "1:5120:4096:3bbc5f09a7275706e87668d3ccd96793",
+      "1:6144:1024:2642090512e9f3b93a215ba0497dcbd8"
+    ],
+    "custom-overlap": [
+      "0:0:86400:5c78229f51b9307615a1f9e442efe391",
+      "1:0:4096:2cc5270f68b8a25c1909d435272422b4",
+      "1:1024:4096:3c83cd930cd96b9da3e3f29ce369adf9",
+      "0:1:86400:0cd6d909f4b84e42f6ac6360f1bda3f6",
+      "1:2048:4096:f6e469bc77eaa6d1042c70e91450b4ab",
+      "1:3072:4096:f5e8ee7c276f02215053e8143e65861d",
+      "0:2:86400:fdff300a63db4e8bb5d9d7fea498ea59",
+      "1:4096:4096:d9af646ccccb557d6a065868cf2fa667",
+      "0:3:86400:aeaecd38cc4cbd0f900e8a1cec209962",
+      "1:5120:4096:f22c40c3beb84a93a61e834d0daad01a",
+      "1:6144:1024:e93ffc6d18f786a744a9b1ac241ec306"
+    ]
+  }
+}
diff --git a/apps/media-worker/src/compositor/ingest.ts b/apps/media-worker/src/compositor/ingest.ts
new file mode 100644
index 0000000..3116212
--- /dev/null
+++ b/apps/media-worker/src/compositor/ingest.ts
@@ -0,0 +1,59 @@
+import { spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+import { buildIngestArgs, type IngestPlan } from "./command-builder";
+import { SourceBus } from "./source-bus";
+
+/**
+ * Ingest ×N normalize stage: one ffmpeg per source decodes and normalizes to
+ * the canvas (raw yuv420p on fd 1, s16le 48 kHz stereo on fd 3) straight into
+ * its source bus's FIFOs. Compositors and preview taps subscribe to buses; they
+ * never touch the remote, and the raw frames never pass through the worker.
+ */
+export class IngestProcess {
+  readonly bus: SourceBus;
+  private proc: ManagedProcess | null = null;
+  private stopping = false;
+
+  constructor(
+    readonly sourceId: string,
+    private readonly plan: IngestPlan,
+    /** MPEG-TS fd: the WP7 pinned relay (`mpegtsPipe`) or the playlist feeder (`playlistPipe`); null for synthetic. */
+    private readonly stdinFd: number | null,
+    scratchDir: string,
+    private readonly redactor: StderrRedactor,
+    private readonly onStderr: (message: string) => void,
+    private readonly onExit: (sourceId: string, reason: string) => void,
+  ) {
+    // Native fan-out can retain a bounded half-second of live backlog in addition to
+    // replay history. With FIFO resizing denied on shared hosts, the replay/input delay
+    // otherwise leaves too little room for short decoder/filter scheduling bursts.
+    this.bus = new SourceBus({ geometry: plan.canvas, scratchDir, redactor, onStderr,
+      maxBacklogFrames: Math.max(4, Math.ceil(plan.canvas.fps / 2)),
+      onExit: (reason) => { if (!this.stopping) onExit(sourceId, reason); } });
+  }
+
+  get pid(): number | undefined { return this.proc?.child.pid; }
+
+  async start(): Promise<void> {
+    if ((this.plan.input.kind !== "synthetic") !== (this.stdinFd !== null)) throw new Error("ingest input and fd disagree");
+    this.stopping = false;
+    const out = await this.bus.start();
+    try {
+      const proc = spawnManaged("ffmpeg", buildIngestArgs(this.plan), [this.stdinFd ?? "ignore", out.videoFd, "pipe", out.audioFd], this.redactor, this.onStderr);
+      this.proc = proc;
+      void proc.exited.then(({ code, signal }) => { if (!this.stopping) this.onExit(this.sourceId, `ingest exited code=${code} signal=${signal}`); });
+      await proc.started;
+    } catch (error) {
+      await this.stop();
+      throw error;
+    } finally {
+      this.bus.releaseIngestWriters();
+    }
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    await this.proc?.terminate();
+    this.proc = null;
+    await this.bus.stop();
+  }
+}
diff --git a/apps/media-worker/src/compositor/playlist-feeder.test.ts b/apps/media-worker/src/compositor/playlist-feeder.test.ts
new file mode 100644
index 0000000..37ec521
--- /dev/null
+++ b/apps/media-worker/src/compositor/playlist-feeder.test.ts
@@ -0,0 +1,160 @@
+/**
+ * Playlist feeder (streaming-architecture.md §5.1): argv goldens, and real
+ * ffmpeg runs of feeder → `playlistPipe` ingest → source bus, checking that
+ * asset boundaries keep the bus at frame rate with A/V paired, that a broken
+ * asset is skipped, that the slate floor covers an unplayable or ended list,
+ * and that `update()` adopts a new list at the next asset boundary.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createReadStream, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Readable } from "node:stream";
+import test from "node:test";
+import { buildIngestArgs, buildPlaylistRemuxArgs, buildSlateArgs } from "./command-builder";
+import { IngestProcess } from "./ingest";
+import { PlaylistFeeder, type FeederEvent } from "./playlist-feeder";
+import { ensureGateBinary, passthroughRedactor } from "./testing";
+
+const canvas = { width: 320, height: 180, fps: 30 };
+
+test("playlist argv: copy-only remux from stdin at a monotonic offset, paced ingest, slate floor", () => {
+  assert.deepEqual(buildPlaylistRemuxArgs(2_020_133), ["-hide_banner", "-nostdin", "-loglevel", "error", "-progress", "pipe:3", "-protocol_whitelist", "pipe", "-i", "pipe:0",
+    "-map", "0:v:0", "-map", "0:a:0?", "-c", "copy", "-output_ts_offset", "2.020133",
+    "-f", "mpegts", "-mpegts_flags", "+initial_discontinuity", "-muxdelay", "0", "pipe:1"]);
+  assert.throws(() => buildPlaylistRemuxArgs(-1));
+  assert.throws(() => buildPlaylistRemuxArgs(1.5));
+  const ingest = buildIngestArgs({ input: { kind: "playlistPipe" }, canvas, audio: "source" });
+  assert.deepEqual(ingest.slice(ingest.indexOf("-re"), ingest.indexOf("-re") + 8), ["-re", "-fflags", "+genpts+discardcorrupt", "-f", "mpegts", "-i", "pipe:0", "-map"]);
+  assert.ok(ingest.includes("0:a:0?"), "a silent asset cannot fail the ingest");
+  const slate = buildSlateArgs({ canvas, seconds: 5, image: null, offsetUs: 0 });
+  assert.ok(slate.includes("color=c=black:s=320x180:r=30") && slate.includes("anullsrc=r=48000:cl=stereo") && slate.at(-1) === "pipe:1");
+  const png = `/scratch/${"a".repeat(64)}.png`;
+  assert.ok(buildSlateArgs({ canvas, seconds: 5, image: png, offsetUs: 7_000_000 }).includes(`file:${png}`));
+  assert.ok(buildSlateArgs({ canvas, seconds: 5, image: null, offsetUs: 7_000_000 }).includes("7.000000"));
+  assert.throws(() => buildSlateArgs({ canvas, seconds: 5, image: "/etc/passwd", offsetUs: 0 }));
+  assert.throws(() => buildSlateArgs({ canvas, seconds: 0, image: null, offsetUs: 0 }));
+  const all = [...buildPlaylistRemuxArgs(0), ...ingest, ...slate].join(" ");
+  assert.ok(!/https?:|concat|movie=|tcp:|udp:/.test(all), "pipes and lavfi only");
+});
+
+function clip(dir: string, name: string, seconds: number, hz: number): string {
+  const path = join(dir, name);
+  const r = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", `testsrc2=s=320x180:r=30:d=${seconds}`, "-f", "lavfi", "-i", `sine=frequency=${hz}:d=${seconds}`,
+    "-c:v", "libx264", "-preset", "ultrafast", "-g", "30", "-c:a", "aac", "-movflags", "+faststart", path]);
+  assert.equal(r.status, 0);
+  return path;
+}
+
+async function run(t: { skip(msg: string): void }, assetIds: string[], loop: boolean, files: Map<string, string>, seconds: number,
+  during?: (feeder: PlaylistFeeder) => void): Promise<{ events: FeederEvent[]; samples: number[]; stats: { pairs: number; silenceFilled: number }; feeder: PlaylistFeeder; exits: string[] } | null> {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return null; }
+  const dir = mkdtempSync(join(tmpdir(), "feeder-"));
+  const events: FeederEvent[] = [];
+  const exits: string[] = [];
+  const feeder = new PlaylistFeeder("src", { assetIds, loop }, {
+    assets: { async open(id) { const path = files.get(id); if (!path) throw new Error("no such asset"); return id === "broken" ? Readable.from([Buffer.from("not media")]) : createReadStream(path); } },
+    canvas, scratchDir: dir, redactor: passthroughRedactor, onStderr: () => undefined, onEvent: (e) => events.push(e), slateSeconds: 2,
+  });
+  const ingest = new IngestProcess("src", { input: { kind: "playlistPipe" }, canvas, audio: "source" }, feeder.start(), dir, passthroughRedactor, () => undefined, (_id, r) => exits.push(r));
+  const samples: number[] = [];
+  try {
+    await ingest.start();
+    feeder.releaseReader();
+    // Measure playback once FFmpeg has probed the TS input and delivered a pair.
+    // Process startup is bounded separately, rather than consuming the playback window.
+    const startupDeadline = Date.now() + 10_000;
+    while ((await ingest.bus.stats()).pairs === 0) {
+      assert.ok(Date.now() < startupDeadline, "playlist ingest produced its first A/V pair within 10 s");
+      await new Promise((r) => setTimeout(r, 100));
+    }
+    const t0 = Date.now();
+    while (Date.now() - t0 < seconds * 1000) {
+      await new Promise((r) => setTimeout(r, 250));
+      samples.push((await ingest.bus.stats()).pairs);
+      if (during && samples.length === 4) during(feeder);
+    }
+    const stats = await ingest.bus.stats();
+    return { events, samples, stats, feeder, exits };
+  } finally {
+    await feeder.stop();
+    await ingest.stop();
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** Longest stretch (in 250 ms samples) without a new pair once the stream is up. */
+function longestStall(samples: number[]): number {
+  let worst = 0;
+  let run = 0;
+  const first = samples.findIndex((n) => n > 0);
+  for (let i = Math.max(1, first + 1); i < samples.length; i += 1) {
+    run = samples[i] === samples[i - 1] ? run + 1 : 0;
+    worst = Math.max(worst, run);
+  }
+  return worst;
+}
+
+test("feeder: asset boundaries stay at frame rate with A/V paired; a broken asset is skipped; the list loops", { timeout: 120_000 }, async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "feeder-clips-"));
+  try {
+    const files = new Map([["a", clip(dir, "a.mp4", 2, 300)], ["b", clip(dir, "b.mp4", 1, 600)], ["broken", join(dir, "broken")]]);
+    writeFileSync(join(dir, "broken"), "x");
+    const r = await run(t, ["a", "broken", "b"], true, files, 7);
+    if (!r) return;
+    const played = r.events.filter((e): e is Extract<FeederEvent, { type: "asset" }> => e.type === "asset").map((e) => e.assetId);
+    assert.deepEqual(played.slice(0, 4), ["a", "broken", "b", "a"], "in order, looping");
+    assert.ok(r.events.some((e) => e.type === "asset-failed" && e.assetId === "broken"));
+    assert.ok(!r.events.some((e) => e.type === "slate"), "one bad asset does not drop to the slate");
+    assert.equal(r.stats.silenceFilled, 0, "audio continuous across boundaries");
+    assert.ok(longestStall(r.samples) <= 1, `no stall at boundaries (samples ${r.samples.join(",")})`);
+    const up = r.samples.findIndex((n) => n > 0);
+    const rate = ((r.samples.at(-1) ?? 0) - (r.samples[up] ?? 0)) / ((r.samples.length - 1 - up) * 0.25);
+    assert.ok(rate > 26 && rate < 36, `paced at the frame rate (${rate.toFixed(1)} pairs/s)`);
+    assert.deepEqual(r.exits, []);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("feeder: nothing playable → slate floor (the bus keeps running); a finished non-looping list → slate", { timeout: 120_000 }, async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "feeder-clips-"));
+  try {
+    writeFileSync(join(dir, "broken"), "x");
+    const dead = await run(t, ["broken"], true, new Map([["broken", join(dir, "broken")]]), 4);
+    if (!dead) return;
+    assert.ok(dead.events.some((e) => e.type === "slate" && e.reason === "unavailable"));
+    assert.ok(dead.stats.pairs >= 60, `slate keeps the source alive (${dead.stats.pairs} pairs)`);
+    const once = await run(t, ["a"], false, new Map([["a", clip(dir, "a.mp4", 1, 300)]]), 4);
+    assert.ok(once?.events.some((e) => e.type === "slate" && e.reason === "ended"));
+    assert.equal(once?.feeder.ended, true);
+    assert.ok(longestStall(once?.samples ?? []) <= 1, "the slate follows the last asset without a stall");
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("feeder: update() adopts a new list after the asset being fed (desired-state v2, no restart)", { timeout: 120_000 }, async (t) => {
+  const dir = mkdtempSync(join(tmpdir(), "feeder-clips-"));
+  try {
+    const files = new Map([["a", clip(dir, "a.mp4", 2, 300)], ["b", clip(dir, "b.mp4", 1, 600)], ["c", clip(dir, "c.mp4", 1, 900)]]);
+    // 1 s in, [a, b] becomes [c, a]. The feeder hands assets to the ingest ahead of playback (FIFO and
+    // demuxer buffers: tens of ms at production bitrates, several of these tiny clips), so "the asset
+    // being fed" is the boundary: after it, playback follows the new list from the position after it.
+    let adoptedAfter: string | null = null;
+    const r = await run(t, ["a", "b"], true, files, 12, (feeder) => {
+      adoptedAfter = feeder.nowPlaying;
+      feeder.update({ assetIds: ["c", "a"], loop: true });
+    });
+    if (!r) return;
+    const order = r.events.filter((e) => e.type === "asset" || e.type === "adopted").map((e) => (e.type === "asset" ? e.assetId : "|"));
+    const cut = order.indexOf("|");
+    assert.ok(cut > 0, `adopted (events ${order.join(",")})`);
+    const before = order.slice(0, cut);
+    const after = order.slice(cut + 1);
+    assert.deepEqual(before, ["a", "b", "a", "b", "a", "b"].slice(0, before.length), "the old list until the update");
+    assert.ok(after.length >= 2, `the new list plays (${order.join(",")})`);
+    // Position after the asset being fed: after "a" (index 1 in [c, a]) comes "c"; after "b" (gone) the list restarts at "c".
+    assert.equal(after[0], "c", `after ${String(adoptedAfter)} the new list continues at c (${order.join(",")})`);
+    assert.deepEqual(after.slice(0, 4), ["c", "a", "c", "a"].slice(0, Math.min(4, after.length)));
+    assert.ok(longestStall(r.samples) <= 1, `no stall when a prepared asset is replaced (samples ${r.samples.join(",")})`);
+    assert.deepEqual(r.exits, []);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/apps/media-worker/src/compositor/playlist-feeder.ts b/apps/media-worker/src/compositor/playlist-feeder.ts
new file mode 100644
index 0000000..4e19ede
--- /dev/null
+++ b/apps/media-worker/src/compositor/playlist-feeder.ts
@@ -0,0 +1,250 @@
+/**
+ * Playlist feeder (streaming-architecture.md §5.1): a `kind: "playlist"` source
+ * becomes a continuous input like any other. The feeder walks the ordered asset
+ * list, opens each asset (a presigned GET through the ingest egress relay),
+ * remuxes it to MPEG-TS (pre-normalized at upload: copy only, never a
+ * transcode) and pipes the remuxes one after another into a FIFO that one
+ * `playlistPipe` ingest reads at native rate. FFmpeg reads only pipes (WP9);
+ * no concat protocol.
+ *
+ * - Timestamps: each remux is shifted to where the previous asset ended (its
+ *   `-progress` end time), so the concatenated stream is monotonic. FFmpeg
+ *   5.1's own discontinuity correction stalls `-re` for 1–2 s per boundary.
+ * - Boundaries: two overlapped stages. Asset i+1's remux starts as soon as
+ *   asset i's remux has exited (its end time is then known), while asset i is
+ *   still being fed from its capture buffer (~4 MiB ahead, several seconds), so
+ *   the next asset's bytes are waiting when the current one ends: no gap.
+ * - Failure: an asset that cannot be opened or remuxed is skipped. When a whole
+ *   pass of the list fails (or the list is empty), the slate floor plays for a
+ *   few seconds and the list is retried.
+ * - End: `loop: false` plays the list once, then the slate for good.
+ * - Desired-state v2: `update()` adopts a new asset list without a restart. The
+ *   asset on air finishes; playback continues after it in the new list (or at
+ *   the new list's start when it is no longer there). An already prepared next
+ *   asset that is no longer next is discarded.
+ */
+import { closeSync, constants, openSync, rmSync } from "node:fs";
+import { Socket } from "node:net";
+import { PassThrough, type Readable } from "node:stream";
+import { makeFifo, openBlockingReader } from "../gate/fifo";
+import { spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+import { buildPlaylistRemuxArgs, buildSlateArgs, type Canvas } from "./command-builder";
+
+/** Opens one playlist asset's bytes (WP7: presigned GET through the pinned ingest egress relay). */
+export interface PlaylistAssetSource { open(assetId: string): Promise<Readable> }
+
+export interface PlaylistSpec { assetIds: string[]; loop: boolean }
+
+export type FeederEvent =
+  | { type: "asset"; assetId: string; index: number }
+  | { type: "asset-failed"; assetId: string; reason: string }
+  | { type: "slate"; reason: "unavailable" | "ended" }
+  | { type: "adopted"; assetIds: number };
+
+export interface PlaylistFeederDeps {
+  assets: PlaylistAssetSource;
+  canvas: Canvas;
+  scratchDir: string;
+  redactor: StderrRedactor;
+  onStderr(message: string): void;
+  onEvent?(event: FeederEvent): void;
+  /** Rendered slate PNG (S4, overlay renderer); null = black. */
+  slateImage?: string | null;
+  slateSeconds?: number;
+}
+
+/** Bytes of produced MPEG-TS held ahead of the FIFO per producer (~5 s at 6 Mb/s). */
+const CAPTURE_BYTES = 4 << 20;
+
+/** One remux (or slate) run: its captured output and, once it exits, its end time. */
+interface Job {
+  proc: ManagedProcess;
+  output: Readable;
+  /** Resolves when the producer exits: success, and the end time it reported (µs, excluding the offset). */
+  done: Promise<{ ok: boolean; endUs: number; reason: string }>;
+  input: Readable | null;
+  cancelled: boolean;
+}
+
+let nextFeeder = 1;
+
+export class PlaylistFeeder {
+  private spec: PlaylistSpec;
+  private out: Socket | null = null;
+  private reader: { fd: number; releaseHolder(): void } | null = null;
+  private stopping = false;
+  private running: Promise<void> = Promise.resolve();
+  private current: { assetId: string; index: number } | null = null;
+  private nextIndex = 0;
+  /** Bumped by `update()`: a job prepared under an older list is discarded. */
+  private generation = 0;
+  private readonly jobs = new Set<Job>();
+  private abortFeed: (() => void) | null = null;
+  /** Assets started, assets failed, slate chunks fed. */
+  readonly stats = { assets: 0, failures: 0, slates: 0 };
+  ended = false;
+
+  constructor(readonly sourceId: string, spec: PlaylistSpec, private readonly deps: PlaylistFeederDeps) {
+    this.spec = { assetIds: [...spec.assetIds], loop: spec.loop };
+  }
+
+  get nowPlaying(): string | null { return this.current?.assetId ?? null; }
+
+  /**
+   * Creates the FIFO and starts feeding. Returns the blocking read end for the ingest's stdin;
+   * call `releaseReader()` once the ingest has it.
+   */
+  start(): number {
+    const path = makeFifo(this.deps.scratchDir, `playlist-${nextFeeder++}.fifo`);
+    const reader = openBlockingReader(path);
+    this.reader = reader;
+    const out = new Socket({ fd: openSync(path, constants.O_WRONLY | constants.O_NONBLOCK), readable: false, writable: true });
+    out.on("error", () => { if (!this.stopping) void this.stop(); }); // the ingest is gone; IngestProcess reports its exit
+    this.out = out;
+    reader.releaseHolder();
+    rmSync(path, { force: true });
+    this.running = this.run().catch((error: unknown) => this.deps.onStderr(`playlist feeder ${this.sourceId}: ${String(error)}`));
+    return reader.fd;
+  }
+
+  releaseReader(): void {
+    if (this.reader) { closeSync(this.reader.fd); this.reader = null; }
+  }
+
+  /** Desired-state v2: adopt a new list at the next asset boundary (no restart, no mid-asset cut). */
+  update(spec: PlaylistSpec): void {
+    this.spec = { assetIds: [...spec.assetIds], loop: spec.loop };
+    const at = this.current ? this.spec.assetIds.indexOf(this.current.assetId) : -1;
+    this.nextIndex = at >= 0 ? at + 1 : 0;
+    this.ended = false;
+    this.generation += 1;
+    this.deps.onEvent?.({ type: "adopted", assetIds: this.spec.assetIds.length });
+  }
+
+  private peekNext(): { assetId: string; index: number } | null {
+    const ids = this.spec.assetIds;
+    if (ids.length === 0) return null;
+    let index = this.nextIndex;
+    if (index >= ids.length) {
+      if (!this.spec.loop) return null;
+      index = 0;
+    }
+    return { assetId: ids[index]!, index };
+  }
+
+  /** Spawns a remux of `asset` (or the slate) at `offsetUs`, capturing its output from the start. */
+  private produce(asset: { assetId: string; index: number } | null, offsetUs: number): Job {
+    const args = asset ? buildPlaylistRemuxArgs(offsetUs)
+      : buildSlateArgs({ canvas: this.deps.canvas, seconds: this.deps.slateSeconds ?? 5, image: this.deps.slateImage ?? null, offsetUs });
+    const proc = spawnManaged("ffmpeg", args, [asset ? "pipe" : "ignore", "pipe", "pipe", "pipe"], this.deps.redactor, this.deps.onStderr);
+    // A producer may exit before its turn (a broken asset at once, a small one that fits in the
+    // buffers), and Node then resumes its unconsumed stdout itself, dropping data and 'end'. The
+    // capture keeps both until fed; backpressure holds a large asset's remux CAPTURE_BYTES ahead.
+    const output = new PassThrough({ highWaterMark: CAPTURE_BYTES });
+    const stdout = proc.child.stdout as Readable | null;
+    if (stdout) stdout.pipe(output);
+    else output.end();
+    let progress = "";
+    (proc.child.stdio[3] as Readable | null)?.on("data", (chunk: Buffer) => { progress = (progress + chunk.toString("latin1")).slice(-4096); });
+    let failed: string | null = null;
+    const done = proc.exited.then(({ code }) => {
+      const endUs = Number([...progress.matchAll(/out_time_us=(\d+)/g)].at(-1)?.[1] ?? 0);
+      return { ok: failed === null && code === 0 && endUs > 0, endUs, reason: failed ?? `producer exited code=${code} end=${endUs}us` };
+    });
+    const job: Job = { proc, output, input: null, done, cancelled: false };
+    if (asset) {
+      proc.child.stdin?.on("error", () => undefined); // EPIPE when the remux rejects its input
+      void this.deps.assets.open(asset.assetId).then((input) => {
+        if (job.cancelled || this.stopping || proc.child.exitCode !== null || proc.child.signalCode !== null) { input.destroy(); return; }
+        job.input = input;
+        input.on("error", (error: Error) => { failed = `asset read failed: ${error.name}`; proc.kill("SIGKILL"); });
+        if (proc.child.stdin) input.pipe(proc.child.stdin);
+      }, (error: unknown) => {
+        failed = `asset open failed: ${error instanceof Error ? error.name : "error"}`;
+        proc.kill("SIGKILL");
+      });
+    }
+    this.jobs.add(job);
+    void done.then(() => this.jobs.delete(job));
+    return job;
+  }
+
+  private discard(job: Job): void {
+    job.cancelled = true;
+    job.input?.destroy();
+    job.output.destroy();
+    job.proc.kill("SIGKILL");
+  }
+
+  /** Pipes a job's captured output into the FIFO; resolves once all of it has been handed over. */
+  private async feed(job: Job): Promise<void> {
+    const out = this.out;
+    if (!out) return;
+    job.output.pipe(out, { end: false });
+    // Until the producer's last byte ('end'). On stop the FIFO socket is destroyed, which unpipes
+    // and pauses the capture, so 'end' would never come: stop() aborts the wait instead.
+    await new Promise<void>((resolve) => {
+      this.abortFeed = resolve;
+      job.output.once("end", resolve);
+      job.output.once("error", () => resolve());
+    });
+    this.abortFeed = null;
+    job.output.unpipe(out);
+  }
+
+  private async run(): Promise<void> {
+    let offsetUs = 0;
+    let failedInARow = 0;
+    let slateNext = false;
+    let feeding: Promise<void> = Promise.resolve();
+    while (!this.stopping) {
+      const generation = this.generation;
+      const next = slateNext ? null : this.peekNext();
+      slateNext = false;
+      // Prepared while the previous job is still being fed (its producer has exited: offsetUs is final).
+      const job = this.produce(next, offsetUs);
+      await feeding;
+      if (this.stopping) { this.discard(job); break; }
+      if (generation !== this.generation) { this.discard(job); continue; } // re-plan under the new list
+      if (next) {
+        this.nextIndex = next.index + 1;
+        this.current = next;
+        this.stats.assets += 1;
+        this.deps.onEvent?.({ type: "asset", assetId: next.assetId, index: next.index });
+      } else {
+        this.current = null;
+        this.ended = this.spec.assetIds.length > 0 && !this.spec.loop && this.nextIndex >= this.spec.assetIds.length;
+        this.stats.slates += 1;
+        this.deps.onEvent?.({ type: "slate", reason: this.ended ? "ended" : "unavailable" });
+      }
+      feeding = this.feed(job);
+      const result = await job.done;
+      if (result.ok) {
+        offsetUs += result.endUs;
+        failedInARow = 0;
+        continue;
+      }
+      if (!next) continue; // a failed slate is retried (offset unchanged)
+      this.stats.failures += 1;
+      failedInARow += 1;
+      this.deps.onEvent?.({ type: "asset-failed", assetId: next.assetId, reason: result.reason });
+      if (failedInARow >= Math.max(1, this.spec.assetIds.length)) {
+        failedInARow = 0;
+        slateNext = true;
+      }
+    }
+  }
+
+  async stop(): Promise<void> {
+    if (this.stopping) { await this.running; return; }
+    this.stopping = true;
+    const jobs = [...this.jobs];
+    for (const job of jobs) this.discard(job);
+    this.abortFeed?.();
+    this.out?.destroy();
+    this.out = null;
+    this.releaseReader();
+    await this.running;
+    await Promise.all(jobs.map((job) => job.done));
+  }
+}
diff --git a/apps/media-worker/src/compositor/production-job.ts b/apps/media-worker/src/compositor/production-job.ts
new file mode 100644
index 0000000..b44b5c5
--- /dev/null
+++ b/apps/media-worker/src/compositor/production-job.ts
@@ -0,0 +1,181 @@
+import { createHash } from "node:crypto";
+import type { GateImpl } from "../gate/frame-gate";
+import { snapshotHlsUrls, OUTPUT_PROFILES, type DesiredChannel } from "../types";
+import { validateEndpointShape, type EndpointValidator } from "../relay/endpoints";
+import type { StderrRedactor, VaultHandleBroker } from "../relay/ffmpeg";
+import type { Canvas, EncoderOutput, IngestInput } from "./command-builder";
+import type { ComposeRequest } from "./compositor";
+import { ManifestPreviewPublisher, type PreviewManifestStore, type PreviewObjectStore } from "../preview/contract";
+import type { HlsRendition } from "../preview/argv";
+import { PreviewTaps } from "../preview/taps";
+import { IngestProcess } from "./ingest";
+import { PlaylistFeeder, type PlaylistAssetSource } from "./playlist-feeder";
+import { ProgramChain } from "./program";
+import type { SourceBus } from "./source-bus";
+import { planScene, programScene } from "./scene-plan";
+
+/** WP7 egress for a production snapshot: one pinned MPEG-TS fd per HLS source, plus the push fd. */
+export interface ProductionEgress {
+  prepare(config: DesiredChannel, validator: EndpointValidator, vault: VaultHandleBroker): Promise<{
+    sources: Map<string, { input: IngestInput; fd: number | null }>;
+    output: EncoderOutput;
+    close(): Promise<void>;
+  }>;
+}
+
+/** Overlay PNGs by content id, fetched through assignment-scoped presigned GETs (§4.3) into scratch. */
+export interface AssetStore { localPath(assetId: string): Promise<string> }
+
+export interface ProductionJobDeps {
+  validator: EndpointValidator;
+  egress: ProductionEgress;
+  vault: VaultHandleBroker;
+  assets: AssetStore;
+  redactor: StderrRedactor;
+  onStderr(message: string): void;
+  onExit(reason: string): void;
+  scratchDir: string;
+  gateImpl?: GateImpl;
+  /** Playlist sources (§5.1). Without it, playlist sources render black and are reported in `lastSkipped`. */
+  playlists?: PlaylistAssetSource;
+  /** Preview taps (§2.1) publish through the API's manifest contract. Without it, no taps run. */
+  preview?: { objects: PreviewObjectStore; manifests: PreviewManifestStore };
+}
+
+/**
+ * What may change by swap. Anything else (the set of sources, an HLS URL, output, profile, mode)
+ * restarts the channel. A playlist's asset list and loop flag are not part of it: the feeder
+ * adopts them in place (desired-state v2: an edited playlist never interrupts the program).
+ */
+function pathKey(c: DesiredChannel): string {
+  const sources = c.production?.sources.map((src) => (src.kind === "hls" ? { id: src.id, kind: src.kind, url: src.url } : { id: src.id, kind: src.kind })) ?? null;
+  return createHash("sha256").update(JSON.stringify({ profile: c.profile, mode: c.mode, output: c.output, sources, source: c.source })).digest("hex");
+}
+
+/**
+ * Supervisor RelayJob for a desired-state v2 snapshot. `start()` brings up
+ * ingest×N (HLS through the egress relay, playlists through the asset feeder)
+ * → gate → encoder, puts the program scene on air, and starts the preview taps.
+ * `reconfigure()` is the meaning of an accepted RUNNING snapshot while already
+ * RUNNING: a TAKE, layout, overlay or gain change is an A/B compositor swap,
+ * playlist edits are adopted by their feeders, and it resolves only once the
+ * new compositor is on air at a frame boundary.
+ */
+export class ProductionJob {
+  private ingests = new Map<string, IngestProcess>();
+  private feeders = new Map<string, PlaylistFeeder>();
+  private chain: ProgramChain | null = null;
+  private taps: PreviewTaps | null = null;
+  private closeEgress: (() => Promise<void>) | null = null;
+  private key = "";
+  private canvas: Canvas | null = null;
+  lastSkipped: string[] = [];
+
+  constructor(private readonly deps: ProductionJobDeps) {}
+
+  get program(): ProgramChain | null { return this.chain; }
+  get previews(): PreviewTaps | null { return this.taps; }
+  feeder(sourceId: string): PlaylistFeeder | undefined { return this.feeders.get(sourceId); }
+  /** The source's bus (its ingest's fan-out), for stats. */
+  sourceBus(sourceId: string): SourceBus | undefined { return this.ingests.get(sourceId)?.bus; }
+
+  async start(config: DesiredChannel): Promise<void> {
+    const spec = config.production;
+    if (!spec || !config.output) throw new Error("production job needs a production snapshot with an output");
+    for (const url of snapshotHlsUrls(config)) validateEndpointShape(url, "hls");
+    validateEndpointShape(config.output.endpointUrl, "output");
+    const profile = OUTPUT_PROFILES[config.profile];
+    const canvas: Canvas = { width: profile.width, height: profile.height, fps: profile.fps };
+    this.canvas = canvas;
+    const egress = await this.deps.egress.prepare(config, this.deps.validator, this.deps.vault);
+    this.closeEgress = egress.close;
+    const lost = (id: string, reason: string): void => this.deps.onExit(`source ${id}: ${reason}`);
+    try {
+      for (const [sourceId, { input, fd }] of egress.sources) {
+        const ingest = new IngestProcess(sourceId, { input, canvas, audio: "source" }, fd, this.deps.scratchDir, this.deps.redactor, this.deps.onStderr, lost);
+        this.ingests.set(sourceId, ingest);
+        await ingest.start();
+      }
+      const playlists = this.deps.playlists;
+      for (const src of spec.sources) {
+        if (src.kind !== "playlist" || !playlists) continue;
+        const feeder = new PlaylistFeeder(src.id, { assetIds: src.assetIds, loop: src.loop }, {
+          assets: playlists, canvas, scratchDir: this.deps.scratchDir, redactor: this.deps.redactor, onStderr: this.deps.onStderr,
+          onEvent: (e) => { if (e.type === "asset-failed" || e.type === "slate") this.deps.onStderr(`playlist ${src.id}: ${e.type}${"reason" in e ? ` ${e.reason}` : ""}`); },
+        });
+        this.feeders.set(src.id, feeder);
+        const fd = feeder.start();
+        const ingest = new IngestProcess(src.id, { input: { kind: "playlistPipe" }, canvas, audio: "source" }, fd, this.deps.scratchDir, this.deps.redactor, this.deps.onStderr, lost);
+        this.ingests.set(src.id, ingest);
+        try { await ingest.start(); } finally { feeder.releaseReader(); }
+      }
+      this.chain = new ProgramChain({
+        canvas, scratchDir: this.deps.scratchDir, videoBitrateKbps: Number.parseInt(profile.videoBitrate, 10),
+        output: egress.output, redactor: this.deps.redactor, onStderr: this.deps.onStderr,
+        onFatal: (reason) => this.deps.onExit(reason), gateImpl: this.deps.gateImpl, programTap: this.deps.preview !== undefined,
+      });
+      await this.chain.start(await this.compose(config));
+      this.key = pathKey(config);
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
+    await this.startPreviews(config);
+  }
+
+  /**
+   * Preview taps never gate the program: a tap that cannot start is reported and the channel runs on.
+   * The program tap's renditions are always on (§2.2: the PGM tile is always live); source renditions
+   * start on demand (`previews.demand()`).
+   */
+  private async startPreviews(config: DesiredChannel): Promise<void> {
+    const preview = this.deps.preview;
+    if (!preview || !this.chain?.programBus) return;
+    const taps = new PreviewTaps({
+      publisher: new ManifestPreviewPublisher({ workspaceId: config.workspaceId, channelId: config.channelId }, preview.objects, preview.manifests),
+      scratchDir: this.deps.scratchDir, redactor: this.deps.redactor, onStderr: this.deps.onStderr,
+      onError: (tap, reason) => this.deps.onStderr(`preview ${tap}: ${reason}`),
+    });
+    this.taps = taps;
+    const add = async (tap: string, bus: SourceBus, alwaysOn: HlsRendition[]): Promise<void> => {
+      try { await taps.add(tap, bus, { alwaysOn }); } catch (error) { this.deps.onStderr(`preview ${tap}: ${String(error)}`); }
+    };
+    await add("program", this.chain.programBus, ["video", "audio"]);
+    for (const [sourceId, ingest] of this.ingests) await add(sourceId, ingest.bus, []);
+  }
+
+  /** false = this change cannot be a swap (sources/output/profile changed): the supervisor restarts. */
+  async reconfigure(config: DesiredChannel): Promise<boolean> {
+    if (!this.chain || !config.production || pathKey(config) !== this.key) return false;
+    for (const src of config.production.sources) {
+      if (src.kind === "playlist") this.feeders.get(src.id)?.update({ assetIds: src.assetIds, loop: src.loop });
+    }
+    await this.chain.swap(await this.compose(config));
+    return true;
+  }
+  private async compose(config: DesiredChannel): Promise<ComposeRequest> {
+    if (!config.production || !this.canvas) throw new Error("no production spec");
+    const plan = planScene(config.production, programScene(config.production), this.canvas, (id) => this.ingests.has(id));
+    this.lastSkipped = plan.skipped;
+    const inputs = plan.sourceIds.map((id, i) => {
+      const ingest = this.ingests.get(id);
+      if (!ingest) throw new Error("planned source has no ingest");
+      return { bus: ingest.bus, audio: plan.audio[i] ?? false };
+    });
+    const assets = await Promise.all(plan.assetIds.map((id) => this.deps.assets.localPath(id)));
+    return { inputs, assets, graph: plan.graph };
+  }
+
+  async stop(): Promise<void> {
+    await this.taps?.stop();
+    this.taps = null;
+    await this.chain?.stop();
+    this.chain = null;
+    for (const feeder of this.feeders.values()) await feeder.stop();
+    this.feeders.clear();
+    for (const ingest of this.ingests.values()) await ingest.stop();
+    this.ingests.clear();
+    await this.closeEgress?.();
+    this.closeEgress = null;
+  }
+}
diff --git a/apps/media-worker/src/compositor/program.ts b/apps/media-worker/src/compositor/program.ts
new file mode 100644
index 0000000..5549b04
--- /dev/null
+++ b/apps/media-worker/src/compositor/program.ts
@@ -0,0 +1,194 @@
+import { CompositorLagError, FrameGate, type GateImpl } from "../gate/frame-gate";
+import type { GateEvent, GateStats } from "../gate/protocol";
+import { spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+import { programTapGeometry } from "../preview/argv";
+import { buildEncoderArgs, type Canvas, type EncoderOutput, type EncoderProgramTap } from "./command-builder";
+import { CompositorInstance, type ComposeRequest } from "./compositor";
+import { SourceBus, type BusSubscription } from "./source-bus";
+
+export interface ProgramChainOptions {
+  canvas: Canvas;
+  scratchDir: string;
+  videoBitrateKbps: number;
+  /**
+   * flvPipe: the push relay's inherited fd (WP9/WP13); null: x264 into `-f null` (CPU smoke);
+   * external: no encoder is spawned, the caller has opened the gate's encoder FIFOs (verifying sinks).
+   */
+  output: EncoderOutput | { kind: "external" };
+  redactor: StderrRedactor;
+  onStderr(message: string): void;
+  /** Encoder or gate died: the RTMP session is gone and the supervisor must restart the channel. */
+  onFatal(reason: string): void;
+  /** The on-air compositor died (gate is repeating its last frame); the chain respawns it. */
+  onCompositorLost?(reason: string): void;
+  gateImpl?: GateImpl;
+  /** Swap must go on air within this long, or B is abandoned and A stays (default 10 s). */
+  swapTimeoutMs?: number;
+  /**
+   * Program preview tap (§2.1): the encoder also emits a 360p copy of what it encodes into
+   * `programBus`, which preview taps subscribe to. Needs an encoder (not `external`).
+   */
+  programTap?: boolean;
+}
+
+/** Child fd of the push relay's pipe in the encoder (flvPipe), and of the program tap outputs after it. */
+const ENCODER_OUTPUT_FD = 4;
+
+const LAG_RETRIES = 2;
+
+/**
+ * The persistent part of a channel's program path (§1.4): frame gate + encoder,
+ * started once, plus the A/B compositor swap. `swap()` starts B for the new
+ * scene, waits until the gate splices it in at a frame boundary, then stops A.
+ * The encoder and its push session are never restarted by a swap.
+ */
+export class ProgramChain {
+  readonly gate: FrameGate;
+  /** The program tap's bus (360p of the encoder input), when `programTap` is set. */
+  readonly programBus: SourceBus | null;
+  private encoder: ManagedProcess | null = null;
+  private active: CompositorInstance | null = null;
+  private activeRequest: ComposeRequest | null = null;
+  private queue: Promise<unknown> = Promise.resolve();
+  private stopping = false;
+  swaps = 0;
+  /** Swap-in compositors replaced after a gate `LAG` report. */
+  lagRetries = 0;
+
+  constructor(private readonly options: ProgramChainOptions) {
+    // The Node reference gate has neither A/V pair lockstep nor origin alignment (s2a-report §5.3):
+    // swaps through it can step backwards and skew A/V. Spike/contract comparison only (gate/spike.ts, gate.test.ts).
+    if (options.gateImpl === "node") throw new Error("the Node reference gate is spike-only; a program chain needs the Rust gate");
+    this.gate = new FrameGate({
+      geometry: options.canvas, scratchDir: options.scratchDir, impl: options.gateImpl ?? "rust",
+      redactor: options.redactor, onStderr: options.onStderr,
+      onEvent: (event) => this.onGateEvent(event),
+      onExit: (reason) => { if (!this.stopping) options.onFatal(reason); },
+    });
+    if (options.programTap && options.output.kind === "external") throw new Error("the program tap needs an encoder");
+    this.programBus = options.programTap ? new SourceBus({
+      geometry: programTapGeometry(options.canvas), scratchDir: options.scratchDir, redactor: options.redactor, onStderr: options.onStderr,
+      // Losing the tap bus loses previews, never the program: the encoder's tee drops that slave.
+      onExit: (reason) => options.onStderr(`program tap bus: ${reason}`),
+    }) : null;
+  }
+
+  get activeCompositor(): CompositorInstance | null { return this.active; }
+  get encoderPid(): number | undefined { return this.encoder?.child.pid; }
+
+  async start(first: ComposeRequest): Promise<void> {
+    const { canvas, output } = this.options;
+    if (output.kind === "external") {
+      await this.gate.start();
+      await this.swap(first);
+      return;
+    }
+    const inputs = this.gate.encoderInputs();
+    const stdio: Array<number | "pipe" | "ignore"> = [inputs.videoFd, "ignore", "pipe", inputs.audioFd];
+    // The push relay's fd is inherited as child fd 4, whatever its number in the worker.
+    let encoderOutput: EncoderOutput = output;
+    if (output.kind === "flvPipe") { stdio.push(output.fd); encoderOutput = { kind: "flvPipe", fd: ENCODER_OUTPUT_FD }; }
+    let programTap: EncoderProgramTap | undefined;
+    if (this.programBus) {
+      const tap = await this.programBus.start();
+      const first = stdio.length;
+      stdio.push(tap.videoFd, tap.audioFd);
+      programTap = { videoFd: first, audioFd: first + 1, size: programTapGeometry(canvas) };
+    }
+    let encoder: ManagedProcess;
+    try {
+      encoder = spawnManaged("ffmpeg", buildEncoderArgs({ canvas, videoBitrateKbps: this.options.videoBitrateKbps, audioBitrateKbps: 128, output: encoderOutput, programTap }),
+        stdio, this.options.redactor, this.options.onStderr);
+    } finally {
+      this.programBus?.releaseIngestWriters();
+    }
+    this.encoder = encoder;
+    void encoder.exited.then(({ code, signal }) => { if (!this.stopping) this.options.onFatal(`encoder exited code=${code} signal=${signal}`); });
+    await encoder.started;
+    await this.gate.start();
+    await this.swap(first);
+  }
+
+  /** Serialized A/B swap. Resolves with the gate tick at which the new compositor went on air. */
+  swap(request: ComposeRequest): Promise<number> {
+    const run = this.queue.catch(() => undefined).then(() => this.swapNow(request));
+    this.queue = run;
+    return run;
+  }
+
+  /**
+   * A B the gate reports as lagging (still behind A's on-air source position, typically a spawn
+   * starved of CPU while draining its startup backlog) is replaced by a fresh one; A stays on air.
+   */
+  private async swapNow(request: ComposeRequest): Promise<number> {
+    for (let attempt = 0; ; attempt += 1) {
+      try {
+        return await this.swapOnce(request);
+      } catch (error) {
+        if (!(error instanceof CompositorLagError) || attempt >= LAG_RETRIES) throw error;
+        this.lagRetries += 1;
+      }
+    }
+  }
+
+  private async swapOnce(request: ComposeRequest): Promise<number> {
+    const next = new CompositorInstance(this.gate, request, this.options.redactor, this.options.onStderr);
+    const current = this.active;
+    await next.start((subs) => (current ? this.originAfter(current, subs) : 0));
+    let tick: number;
+    try {
+      tick = await this.gate.waitActive(next.slotId, this.options.swapTimeoutMs ?? 10_000);
+    } catch (error) {
+      try { this.gate.detach(next.slotId); } catch { /* gate gone */ }
+      await next.stop();
+      throw error;
+    }
+    const old = this.active;
+    this.active = next;
+    this.activeRequest = request;
+    this.swaps += 1;
+    if (old) void old.stop();
+    return tick;
+  }
+
+  /**
+   * Origin of B relative to on-air A, in A's numbering: through a bus both use
+   * (exact: pair counters, minus pairs A had lost to backlog when B subscribed), else by wall clock.
+   * Pairs B loses after attach only make B *ahead*: a forward skip, never backwards.
+   */
+  private originAfter(a: CompositorInstance, subs: BusSubscription[]): number | undefined {
+    if (a.origin === undefined) return undefined;
+    for (const sb of subs) {
+      const sa = a.subscriptions.find((x) => x.bus === sb.bus);
+      if (sa) return a.origin + sb.startPair - sa.startPair - (sb.droppedBefore(sa) ?? sa.dropped);
+    }
+    const sa = a.subscriptions[0];
+    const sb = subs[0];
+    if (!sa || !sb) return undefined;
+    return a.origin + Math.round((Number(sb.startedAt - sa.startedAt) / 1e9) * this.options.canvas.fps);
+  }
+
+  private onGateEvent(event: GateEvent): void {
+    if (event.type !== "EOF" || this.stopping || !this.active || event.id !== this.active.slotId || !this.activeRequest) return;
+    // The on-air compositor died (crash, kill -9). The gate is already holding
+    // the last frame + silence, so the encoder never notices; respawn the scene.
+    const lost = this.active;
+    this.active = null;
+    void lost.stop();
+    this.options.onCompositorLost?.(`compositor ${event.id} ended on air`);
+    void this.swap(this.activeRequest).catch((error: unknown) => this.options.onCompositorLost?.(`respawn failed: ${String(error)}`));
+  }
+
+  stats(): Promise<GateStats> { return this.gate.stats(); }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    await this.queue.catch(() => undefined);
+    await this.active?.stop();
+    this.active = null;
+    await this.gate.stop();
+    await this.encoder?.terminate();
+    this.encoder = null;
+    await this.programBus?.stop();
+  }
+}
diff --git a/apps/media-worker/src/compositor/scene-plan.test.ts b/apps/media-worker/src/compositor/scene-plan.test.ts
new file mode 100644
index 0000000..ab32324
--- /dev/null
+++ b/apps/media-worker/src/compositor/scene-plan.test.ts
@@ -0,0 +1,68 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { parseProductionSpec } from "../production";
+import { buildCompositorArgs } from "./command-builder";
+import { planScene, programScene } from "./scene-plan";
+
+const id = (n: number) => `00000000-0000-4000-8000-${String(n).padStart(12, "0")}`;
+const sha = (c: string) => c.repeat(64);
+
+const spec = parseProductionSpec({
+  sources: [
+    { id: id(1), label: "Cam A", kind: "hls", url: "https://a.example/live.m3u8" },
+    { id: id(2), label: "Cam B", kind: "hls", url: "https://b.example/live.m3u8" },
+    { id: id(3), label: "Loop", kind: "playlist", assetIds: [id(9)], loop: true },
+  ],
+  scenes: [
+    { id: id(10), label: "Grid", layout: "2x2", slots: [
+      { index: 0, sourceId: id(1), rect: null, fit: "cover", audioMode: "primary", gainDb: 0 },
+      { index: 1, sourceId: id(2), rect: null, fit: "contain", audioMode: "on", gainDb: -6 },
+      { index: 2, sourceId: id(3), rect: null, fit: "contain", audioMode: "on", gainDb: 0 },
+      { index: 3, sourceId: id(1), rect: null, fit: "crop", audioMode: "on", gainDb: -12 },
+    ] },
+    { id: id(11), label: "PIP", layout: "pip", slots: [
+      { index: 0, sourceId: id(2), rect: null, fit: "cover", audioMode: "primary", gainDb: -3 },
+      { index: 1, sourceId: id(1), rect: { x: 6500, y: 6500, w: 3000, h: 3000 }, fit: "contain", audioMode: "off", gainDb: 0 },
+    ] },
+  ],
+  buses: { preview: id(11), program: id(10) },
+  overlays: [
+    { id: id(20), sceneId: id(10), kind: "chyron", enabled: true, layer: 2, position: { x: 0, y: 9000 }, revisionId: id(30), assetId: sha("c"), chyron: { speedPxPerSec: 120, stripWidthPx: 4000 }, clock: null },
+    { id: id(21), sceneId: id(10), kind: "lower_third", enabled: true, layer: 1, position: { x: 500, y: 7500 }, revisionId: id(31), assetId: sha("a"), chyron: null, clock: null },
+    { id: id(22), sceneId: id(10), kind: "logo", enabled: false, layer: 3, position: { x: 9000, y: 500 }, revisionId: id(32), assetId: sha("b"), chyron: null, clock: null },
+    { id: id(23), sceneId: id(10), kind: "clock", enabled: true, layer: 4, position: { x: 9000, y: 500 }, revisionId: null, assetId: null, chyron: null, clock: { format: "HH:MM" } },
+    { id: id(24), sceneId: id(11), kind: "lower_third", enabled: true, layer: 0, position: { x: 0, y: 0 }, revisionId: id(33), assetId: sha("d"), chyron: null, clock: null },
+  ],
+  transition: { type: "cut" },
+  audio: { masterGainDb: -3 },
+});
+const canvas = { width: 1920, height: 1080, fps: 30 };
+const hls = (sourceId: string) => spec.sources.find((s) => s.id === sourceId)?.kind === "hls";
+
+test("program scene → typed graph: grid cells, shared source, playlist black, one mix input per source", () => {
+  const plan = planScene(spec, programScene(spec), canvas, hls);
+  assert.deepEqual(plan.sourceIds, [id(1), id(2)]);
+  assert.deepEqual(plan.audio, [true, true]);
+  assert.deepEqual(plan.graph.tiles.map((t) => t.source), [0, 1, null, 0]);
+  assert.deepEqual(plan.graph.tiles[3]?.rect, { x: 960, y: 540, w: 960, h: 540 });
+  // Cam A is primary at 0 dB and "on" at -12 dB in slot 3: one input at the louder gain.
+  assert.deepEqual(plan.graph.audio, { inputs: [{ source: 0, gainDb: 0 }, { source: 1, gainDb: -6 }], masterGainDb: -3 });
+  // Layer order (lower third under chyron); disabled logo and S2a-unsupported clock skipped.
+  assert.deepEqual(plan.assetIds, [sha("a"), sha("c")]);
+  assert.deepEqual(plan.graph.overlays, [{ kind: "image", asset: 0, x: 96, y: 810 }, { kind: "chyron", asset: 1, y: 972, speedPxPerSec: 120 }]);
+  assert.equal(plan.skipped.length, 2);
+  const args = buildCompositorArgs({
+    sources: plan.sourceIds.map((_, i) => ({ video: { kind: "rawPipe" as const, fd: 4 + 2 * i }, audio: { kind: "rawPipe" as const, fd: 5 + 2 * i } })),
+    assets: plan.assetIds.map((a) => `/scratch/assets/${a}.png`), graph: plan.graph, output: { kind: "gate", videoFd: 1, audioFd: 3 },
+  });
+  assert.ok(!args.join(" ").includes("Cam A"), "labels never reach argv");
+  assert.ok(!args.join(" ").includes("example"), "source URLs never reach the compositor");
+});
+
+test("PIP scene: inset rect from basis points, audio off slot not mixed", () => {
+  const plan = planScene(spec, spec.scenes[1]!, canvas, hls);
+  assert.deepEqual(plan.sourceIds, [id(2), id(1)]);
+  assert.deepEqual(plan.audio, [true, false]);
+  assert.deepEqual(plan.graph.tiles[1]?.rect, { x: 1248, y: 702, w: 576, h: 324 });
+  assert.deepEqual(plan.graph.audio.inputs, [{ source: 0, gainDb: -3 }]);
+});
diff --git a/apps/media-worker/src/compositor/scene-plan.ts b/apps/media-worker/src/compositor/scene-plan.ts
new file mode 100644
index 0000000..e7eb851
--- /dev/null
+++ b/apps/media-worker/src/compositor/scene-plan.ts
@@ -0,0 +1,81 @@
+import type { ProductionOverlay, ProductionScene, ProductionSpec } from "../production";
+import { layoutRects, rectFromBasisPoints, type Canvas, type CompositorGraph, type MixInput, type OverlaySpec, type TileSpec } from "./command-builder";
+
+/** Desired-state v2 scene → typed compositor graph over a list of source ids (input order). */
+export interface ScenePlan {
+  sourceIds: string[];
+  /** Same order as sourceIds: whether the compositor needs that source's audio. */
+  audio: boolean[];
+  assetIds: string[];
+  graph: CompositorGraph;
+  /** Things in the snapshot this slice renders as black/skips, for the observed reason. */
+  skipped: string[];
+}
+
+export function programScene(spec: ProductionSpec): ProductionScene {
+  const scene = spec.scenes.find((s) => s.id === spec.buses.program);
+  if (!scene) throw new Error("program bus names no scene");
+  return scene;
+}
+
+/**
+ * `available(sourceId)` says whether the worker has an ingest for that source:
+ * S2a ingests HLS sources only; playlist sources (S2b feeder) render black.
+ * Overlay order: `layer` ascending, snapshot order within a layer.
+ */
+export function planScene(spec: ProductionSpec, scene: ProductionScene, canvas: Canvas, available: (sourceId: string) => boolean): ScenePlan {
+  const skipped: string[] = [];
+  const sourceIds: string[] = [];
+  const indexOf = (id: string): number => {
+    let i = sourceIds.indexOf(id);
+    if (i < 0) { sourceIds.push(id); i = sourceIds.length - 1; }
+    return i;
+  };
+  const grid = layoutRects(scene.layout, canvas);
+  const slots = [...scene.slots].sort((a, b) => a.index - b.index);
+  const tiles: TileSpec[] = [];
+  const gains = new Map<number, number>();
+  for (const slot of slots) {
+    const rect = slot.rect ? rectFromBasisPoints(slot.rect, canvas) : grid[slot.index];
+    if (!rect) continue;
+    let source: number | null = null;
+    if (slot.sourceId !== null) {
+      if (available(slot.sourceId)) source = indexOf(slot.sourceId);
+      else skipped.push(`slot ${slot.index}: source ${slot.sourceId} has no ingest in this worker build`);
+    }
+    tiles.push({ source, rect, fit: slot.fit });
+    if (source !== null && slot.audioMode !== "off") gains.set(source, Math.max(gains.get(source) ?? -Infinity, slot.gainDb));
+  }
+  const audio = sourceIds.map((_, i) => gains.has(i));
+  const mix: MixInput[] = [...gains.entries()].sort((a, b) => a[0] - b[0]).map(([source, gainDb]) => ({ source, gainDb }));
+
+  const assetIds: string[] = [];
+  const overlays: OverlaySpec[] = [];
+  const ordered = spec.overlays
+    .map((o, i) => ({ o, i }))
+    .filter(({ o }) => o.sceneId === scene.id && o.enabled)
+    .sort((a, b) => a.o.layer - b.o.layer || a.i - b.i)
+    .map(({ o }) => o);
+  for (const o of ordered) {
+    const spec = overlaySpec(o, canvas, (assetId) => {
+      let i = assetIds.indexOf(assetId);
+      if (i < 0) { assetIds.push(assetId); i = assetIds.length - 1; }
+      return i;
+    });
+    if (spec) overlays.push(spec);
+    else skipped.push(`overlay ${o.id}: ${o.kind} is not composited in S2a`);
+  }
+  return {
+    sourceIds, audio, assetIds, skipped,
+    graph: { canvas, layout: scene.layout, tiles, overlays, audio: { inputs: mix, masterGainDb: spec.audio.masterGainDb } },
+  };
+}
+
+function overlaySpec(o: ProductionOverlay, canvas: Canvas, asset: (id: string) => number): OverlaySpec | null {
+  if (o.assetId === null) return null; // clock: server-generated drawtext is a later slice
+  const x = Math.min(canvas.width, Math.round((o.position.x * canvas.width) / 10_000));
+  const y = Math.min(canvas.height, Math.round((o.position.y * canvas.height) / 10_000));
+  if (o.kind === "chyron" && o.chyron) return { kind: "chyron", asset: asset(o.assetId), y, speedPxPerSec: o.chyron.speedPxPerSec };
+  if (o.kind === "lower_third" || o.kind === "logo") return { kind: "image", asset: asset(o.assetId), x, y };
+  return null;
+}
diff --git a/apps/media-worker/src/compositor/soak.ts b/apps/media-worker/src/compositor/soak.ts
new file mode 100644
index 0000000..a5b91c3
--- /dev/null
+++ b/apps/media-worker/src/compositor/soak.ts
@@ -0,0 +1,275 @@
+/**
+ * S2 soak (streaming-architecture.md §6 S2: "the ≥8 h soak is wired into the
+ * nightly run, not blocking merge"). Drives the production path for hours and
+ * fails on drift or leaks:
+ *
+ *   ProductionJob (4 paced 1080p30 MPEG-TS sources standing in for the WP7
+ *   relay + one looping playlist source through the asset feeder) → source-bus
+ *   helpers → A/B compositors → Rust gate → x264 (-f null) + program tap, with
+ *   preview taps (program LL-HLS always on, one source rendition kept demanded)
+ *   publishing into an in-memory manifest store, and a scripted scene / overlay
+ *   / gain swap every `--swap-every` s through `reconfigure()` (the RUNNING
+ *   snapshot path the supervisor uses).
+ *
+ * Every `--sample-every` s one JSON line goes to `--out`: gate continuity
+ * counters, bus drops, swap latency, feeder and preview counters, and RSS + open
+ * fds per process. The last line is the summary; the exit code is 0 only if:
+ *   - no process of the chain exited on its own and every swap went on air;
+ *   - after the settle window: bus drops ≤ --max-bus-drops (default 0) and gate
+ *     repeat/silence fills ≤ 1 per 1 000 ticks;
+ *   - from the end of the first hour (or the first quarter of a shorter run) to
+ *     the end: no process grows RSS by more than 15 % (+16 MiB) and fd counts
+ *     move by at most 8.
+ *
+ *   node --import tsx src/compositor/soak.ts [--hours 8] [--profile 1080p30|720p30]
+ *        [--swap-every 30] [--sample-every 10] [--max-bus-drops 0] [--out soak.jsonl]
+ *
+ * Nightly: `pnpm --filter @tactical-media-broadcast-hub/media-worker soak -- --hours 8 --out
+ * runs/soak/$(date +%F).jsonl` on the reference host (see runs/wp4/s2b-report.md).
+ */
+import { appendFileSync, closeSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { createReadStream } from "node:fs";
+import { tmpdir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { parseProductionSpec, type ProductionSpec } from "../production";
+import type { PreviewContentType } from "../preview/contract";
+import type { ManagedProcess } from "../relay/ffmpeg";
+import { OUTPUT_PROFILES, type DesiredChannel, type OutputPreset } from "../types";
+import { ProductionJob } from "./production-job";
+import { encodeSourceClip, ensureGateBinary, makeAssets, passthroughRedactor, startPacer } from "./testing";
+
+function opt(name: string, fallback: string): string {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? (process.argv[i + 1] ?? fallback) : fallback;
+}
+
+const id = (n: number): string => `00000000-0000-4000-8000-${String(n).padStart(12, "0")}`;
+const WS = "8f0c5a8e-3b1d-4c3e-9a5b-0c1d2e3f4a5b";
+const CH = "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d";
+const PLAYLIST = id(5);
+
+/** Swap i of the script: layouts over the 4 live sources and the playlist, overlays on/off, gains in 3 dB steps. */
+function scene(i: number, assetIds: [string, string]): ProductionSpec {
+  const layouts = ["2x2", "pip", "single", "3x3", "2x1"] as const;
+  const layout = layouts[i % layouts.length]!;
+  const order = [id(1), id(2), id(3), id(4), PLAYLIST];
+  const rot = (k: number): string => order[(k + i) % order.length]!;
+  const count = { "2x2": 4, pip: 2, single: 1, "3x3": 5, "2x1": 2 }[layout];
+  const slots = Array.from({ length: count }, (_, k) => ({
+    index: k, sourceId: rot(k),
+    rect: layout === "pip" && k === 1 ? { x: 6500, y: 6500, w: 3000, h: 3000 } : null,
+    fit: (["cover", "contain", "crop"] as const)[(i + k) % 3]!,
+    audioMode: k === 0 ? "primary" as const : (k === 1 ? "on" as const : "off" as const),
+    gainDb: -3 * ((i + k) % 9),
+  }));
+  return parseProductionSpec({
+    sources: [
+      ...[1, 2, 3, 4].map((n) => ({ id: id(n), label: `Cam ${n}`, kind: "hls", url: `https://cam${n}.example/live.m3u8` })),
+      { id: PLAYLIST, label: "Loop", kind: "playlist", assetIds: [id(40), id(41), id(42)], loop: true },
+    ],
+    scenes: [{ id: id(10), label: "Program", layout, slots }, { id: id(11), label: "Preview", layout: "single", slots: [] }],
+    buses: { preview: id(11), program: id(10) },
+    overlays: [
+      { id: id(20), sceneId: id(10), kind: "lower_third", enabled: i % 3 !== 0, layer: 1, position: { x: 500, y: 8000 }, revisionId: id(30), assetId: assetIds[0], chyron: null, clock: null },
+      { id: id(21), sceneId: id(10), kind: "chyron", enabled: i % 2 === 0, layer: 2, position: { x: 0, y: 9400 }, revisionId: id(31), assetId: assetIds[1], chyron: { speedPxPerSec: 40 + ((i * 20) % 360), stripWidthPx: 600 }, clock: null },
+    ],
+    transition: { type: "cut" },
+    audio: { masterGainDb: -3 * (i % 3) },
+  });
+}
+
+/** VmRSS (KiB) and open fds of a process. */
+function procStat(pid: number | undefined): { rssKiB: number; fds: number } | null {
+  if (pid === undefined) return null;
+  try {
+    const rss = /VmRSS:\s+(\d+)/.exec(readFileSync(`/proc/${pid}/status`, "utf8"))?.[1];
+    return { rssKiB: Number(rss ?? 0), fds: readdirSync(`/proc/${pid}/fd`).length };
+  } catch { return null; }
+}
+
+function pids(name: string): number[] {
+  const r = spawnSync("pgrep", ["-f", name], { encoding: "utf8" });
+  return r.stdout.split("\n").filter(Boolean).map(Number);
+}
+
+async function main(): Promise<void> {
+  const hours = Number(opt("hours", "8"));
+  const profile = opt("profile", "1080p30") as OutputPreset;
+  const swapEvery = Number(opt("swap-every", "30"));
+  const sampleEvery = Number(opt("sample-every", "10"));
+  const maxBusDrops = Number(opt("max-bus-drops", "0"));
+  const out = opt("out", join(process.cwd(), `soak-${new Date().toISOString().replace(/[:.]/g, "-")}.jsonl`));
+  if (!(hours > 0) || !Number.isFinite(hours) || !OUTPUT_PROFILES[profile]) throw new Error("--hours must be > 0 and --profile one of 720p30|1080p30|1080p60");
+  if (!(swapEvery > 0) || !Number.isFinite(swapEvery) || !(sampleEvery > 0) || !Number.isFinite(sampleEvery) || !Number.isSafeInteger(maxBusDrops) || maxBusDrops < 0) throw new Error("swap/sample intervals must be positive and max-bus-drops a non-negative integer");
+  if (!ensureGateBinary()) throw new Error("native helpers unavailable (cargo build failed)");
+  const { width, height, fps } = OUTPUT_PROFILES[profile];
+  const canvas = { width, height, fps };
+  const dir = mkdtempSync(join(tmpdir(), "soak-"));
+  let job: ProductionJob | null = null;
+  let exitCode = 2;
+  try {
+    writeFileSync(out, "");
+    const log = (record: object): void => appendFileSync(out, `${JSON.stringify(record)}\n`);
+
+    // Fixtures, prepared before the clock starts.
+    const clip = join(dir, "src.ts");
+    encodeSourceClip(clip, canvas);
+    const clips = new Map<string, string>();
+    for (const [n, hz] of [[40, 300], [41, 600], [42, 900]] as const) {
+      const path = join(dir, `asset-${n}.mp4`);
+      const r = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", `testsrc2=s=${width}x${height}:r=${fps}:d=6`, "-f", "lavfi", "-i", `sine=frequency=${hz}:d=6`,
+        "-c:v", "libx264", "-preset", "veryfast", "-b:v", "4000k", "-g", String(fps), "-c:a", "aac", "-movflags", "+faststart", path]);
+      if (r.status !== 0) throw new Error("playlist asset encode failed");
+      clips.set(id(n), path);
+    }
+    const assets = makeAssets(dir);
+    const assetIds = assets.map((p) => basename(p, ".png")) as [string, string];
+    const pacers: ManagedProcess[] = [];
+    const pacerFds: number[] = [];
+    const exits: string[] = [];
+    const published = { count: 0, bytes: 0 };
+    const manifests = new Map<string, number>();
+
+    job = new ProductionJob({
+      validator: { async validate() { throw new Error("not used: synthetic egress"); } },
+      vault: { async deliverPushTarget() { throw new Error("not used: null output"); } },
+      egress: {
+        async prepare(config) {
+          const sources = new Map<string, { input: { kind: "mpegtsPipe" }; fd: number }>();
+          for (const src of config.production?.sources ?? []) {
+            if (src.kind !== "hls") continue;
+            const pacer = await startPacer(clip, dir, `pacer-${src.id.slice(-2)}`);
+            pacers.push(pacer.proc);
+            pacerFds.push(pacer.readFd);
+            sources.set(src.id, { input: { kind: "mpegtsPipe" }, fd: pacer.readFd });
+          }
+          return { sources, output: { kind: "null" as const }, async close() { for (const p of pacers) await p.terminate(500); for (const fd of pacerFds.splice(0)) closeSync(fd); } };
+        },
+      },
+      assets: { async localPath(assetId) { const p = assets.find((a) => basename(a, ".png") === assetId); if (!p) throw new Error("unknown overlay asset"); return p; } },
+      playlists: { async open(assetId) { const p = clips.get(assetId); if (!p) throw new Error("unknown asset"); return createReadStream(p); } },
+      preview: {
+        objects: { async putContent(body: Buffer, contentType: PreviewContentType) { published.count += 1; published.bytes += body.length; return { key: `sha256/${"0".repeat(64)}.${contentType === "image/jpeg" ? "jpg" : "bin"}` }; } },
+        manifests: { async set(key: string) { manifests.set(key, (manifests.get(key) ?? 0) + 1); } },
+      },
+      redactor: passthroughRedactor, onStderr: () => undefined,
+      onExit: (reason) => exits.push(reason),
+      scratchDir: join(dir, "scratch"),
+    });
+    const config = (version: number, i: number): DesiredChannel => ({
+      workspaceId: WS, channelId: CH, workerId: "soak", assignmentEpoch: 1, desiredVersion: version, desiredStatus: "RUNNING",
+      source: null, output: { endpointUrl: "rtmp://push.example/live", credentialHandleId: "keyref-soak" }, profile, mode: "normalize",
+      production: scene(i, assetIds),
+    });
+
+    const t0 = Date.now();
+    await job.start(config(1, 0));
+    const runningJob = job;
+    const chain = runningJob.program!;
+    await runningJob.previews?.demand(id(1), "video").catch(() => undefined);
+
+    const settleMs = Math.min(60_000, (hours * 3_600_000) / 10);
+    const endAt = t0 + hours * 3_600_000;
+    const swapLatency: number[] = [];
+    let swaps = 0;
+    let swapFailures = 0;
+    let nextSwap = Date.now() + swapEvery * 1000;
+    let nextSample = Date.now() + sampleEvery * 1000;
+    let settled: { ticks: number; fills: number; busDrops: number } | null = null;
+    const samples: Array<{ t: number; procs: Record<string, { rssKiB: number; fds: number } | null> }> = [];
+    const busDrops = async (): Promise<number> => {
+      let total = 0;
+      for (const sid of [id(1), id(2), id(3), id(4), PLAYLIST]) {
+        const bus = runningJob.sourceBus(sid);
+        if (bus) total += (await bus.stats()).subscriberDrops;
+      }
+      return total;
+    };
+
+    while (Date.now() < endAt && exits.length === 0) {
+      const now = Date.now();
+      if (now >= nextSwap) {
+        nextSwap += swapEvery * 1000;
+        const started = Date.now();
+        try {
+          await runningJob.reconfigure(config(swaps + 2, swaps + 1));
+          swaps += 1;
+          swapLatency.push(Date.now() - started);
+        } catch (error) {
+          swapFailures += 1;
+          log({ type: "swap-failed", t: (Date.now() - t0) / 1000, error: String(error) });
+        }
+      }
+      if (now >= nextSample) {
+        nextSample += sampleEvery * 1000;
+        const gate = await chain.stats();
+        const drops = await busDrops();
+        if (!settled && now - t0 >= settleMs) settled = { ticks: gate.ticks, fills: gate.vrep + gate.asil, busDrops: drops };
+        const procs: Record<string, { rssKiB: number; fds: number } | null> = {
+          worker: { rssKiB: Math.round(process.memoryUsage().rss / 1024), fds: readdirSync("/proc/self/fd").length },
+          gate: procStat(chain.gate.pid),
+          encoder: procStat(chain.encoderPid),
+          compositor: procStat(chain.activeCompositor?.pid),
+          programBus: procStat(chain.programBus?.pid ?? undefined),
+        };
+        pids(join(dir, "scratch", "bus-")).forEach((pid, k) => { procs[`bus${k}`] = procStat(pid); });
+        samples.push({ t: now - t0, procs });
+        const sorted = [...swapLatency].sort((a, b) => a - b);
+        log({
+          type: "sample", t: (now - t0) / 1000, ticks: gate.ticks, vrep: gate.vrep, asil: gate.asil, outDrops: gate.outDrops, lagged: gate.lagged,
+          lateOverFrame: gate.lateOverFrame, busDrops: drops, swaps, swapFailures, lagRetries: chain.lagRetries,
+          swapMs: { p50: sorted[Math.floor(sorted.length / 2)] ?? null, max: sorted.at(-1) ?? null },
+          feeder: runningJob.feeder(PLAYLIST)?.stats, previews: { ...published, manifests: manifests.size }, procs,
+        });
+        // Keep the demanded source rendition alive (a viewer watching that tile).
+        await runningJob.previews?.demand(id(1), "video").catch(() => undefined);
+      }
+      await new Promise((r) => setTimeout(r, 250));
+    }
+
+    // Verdict.
+    const gate = await chain.stats();
+    const drops = await busDrops();
+    const failures: string[] = [];
+    if (!settled) failures.push("no settled sample collected");
+    if (gate.outDrops !== 0) failures.push(`encoder output drops: ${gate.outDrops}`);
+    if (exits.length) failures.push(`chain exited: ${exits.join("; ")}`);
+    if (swapFailures) failures.push(`${swapFailures} swaps never went on air`);
+    if (settled) {
+      const ticks = gate.ticks - settled.ticks;
+      const fills = gate.vrep + gate.asil - settled.fills;
+      if (drops - settled.busDrops > maxBusDrops) failures.push(`bus drops after settle: ${drops - settled.busDrops}`);
+      if (fills > Math.ceil(ticks / 1000)) failures.push(`gate fills after settle: ${fills} over ${ticks} ticks`);
+    }
+    const baseAt = Math.min(3_600_000, (hours * 3_600_000) / 4);
+    const base = samples.find((s) => s.t >= baseAt);
+    const last = samples.at(-1);
+    const growth: Record<string, { rssPct: number; fds: number }> = {};
+    if (base && last && last !== base) {
+      for (const [name, b] of Object.entries(base.procs)) {
+        const l = last.procs[name];
+        if (!b || !l) continue;
+        // Compositors are replaced by swaps; their size is not a leak signal.
+        if (name === "compositor") continue;
+        growth[name] = { rssPct: Number((((l.rssKiB - b.rssKiB) / b.rssKiB) * 100).toFixed(1)), fds: l.fds - b.fds };
+        if (l.rssKiB > b.rssKiB * 1.15 + 16 * 1024) failures.push(`${name} RSS ${b.rssKiB} → ${l.rssKiB} KiB`);
+        if (Math.abs(l.fds - b.fds) > 8) failures.push(`${name} fds ${b.fds} → ${l.fds}`);
+      }
+    }
+    const summary = {
+      type: "summary", hours: (Date.now() - t0) / 3_600_000, profile, swaps, swapFailures, lagRetries: chain.lagRetries,
+      gate: { ticks: gate.ticks, vrep: gate.vrep, asil: gate.asil, outDrops: gate.outDrops, lagged: gate.lagged }, busDrops: drops, settled,
+      growth, previews: published, feeder: runningJob.feeder(PLAYLIST)?.stats, pass: failures.length === 0, failures,
+    };
+    log(summary);
+    process.stdout.write(`${JSON.stringify(summary)}\n`);
+    exitCode = failures.length === 0 ? 0 : 1;
+  } finally {
+    await job?.stop();
+    rmSync(dir, { recursive: true, force: true });
+  }
+  process.exitCode = exitCode;
+}
+
+if (require.main === module) void main().catch((error: unknown) => { process.stderr.write(`${String(error)}\n`); process.exit(2); });
diff --git a/apps/media-worker/src/compositor/source-bus.test.ts b/apps/media-worker/src/compositor/source-bus.test.ts
new file mode 100644
index 0000000..3553d68
--- /dev/null
+++ b/apps/media-worker/src/compositor/source-bus.test.ts
@@ -0,0 +1,153 @@
+/**
+ * Source bus helper (src/gate/rust/src/bin/source-bus.rs) through its Node
+ * manager: the S2a bus semantics on the new out-of-process path. Frames are
+ * tagged (first byte = pair index) so delivery can be checked exactly.
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { Socket } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { audioFrameBytes, videoFrameBytes } from "../gate/protocol";
+import { ProgramChain } from "./program";
+import { SourceBus, type BusSubscription } from "./source-bus";
+import { ensureGateBinary, passthroughRedactor } from "./testing";
+
+const g = { width: 64, height: 36, fps: 30 };
+const V = videoFrameBytes(g);
+const A = audioFrameBytes(g);
+
+const frame = (bytes: number, tag: number): Buffer => Buffer.alloc(bytes, tag & 0xff);
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function until(cond: () => boolean | Promise<boolean>, ms: number, what: string): Promise<void> {
+  const t0 = Date.now();
+  while (!(await cond())) {
+    if (Date.now() - t0 > ms) throw new Error(`timeout: ${what}`);
+    await sleep(20);
+  }
+}
+
+type Harness = { bus: SourceBus; video: Socket; audio: Socket; dir: string; close(): Promise<void> };
+
+/** Writes pair i as an ingest does (interleaved): a burst of one stream would be trimmed as skew. */
+async function pair(h: Harness, i: number, audio = true): Promise<void> {
+  await Promise.all([
+    new Promise<void>((r) => h.video.write(frame(V, i), () => r())),
+    audio ? new Promise<void>((r) => h.audio.write(frame(A, i), () => r())) : Promise.resolve(),
+  ]);
+}
+
+async function harness(): Promise<Harness> {
+  const dir = mkdtempSync(join(tmpdir(), "bus-"));
+  const bus = new SourceBus({ geometry: g, scratchDir: dir, redactor: passthroughRedactor, onStderr: () => undefined });
+  const fds = await bus.start();
+  bus.adoptIngestWriters();
+  const video = new Socket({ fd: fds.videoFd, readable: false, writable: true });
+  const audio = new Socket({ fd: fds.audioFd, readable: false, writable: true });
+  return { bus, video, audio, dir, async close() { video.destroy(); audio.destroy(); await bus.stop(); rmSync(dir, { recursive: true, force: true }); } };
+}
+
+/** Reads a subscriber's stream into whole frames (first byte of each). */
+function collect(fd: number | null, bytes: number): { tags: number[]; socket: Socket } {
+  assert.ok(fd !== null);
+  const tags: number[] = [];
+  let pending = Buffer.alloc(0);
+  const socket = new Socket({ fd, readable: true, writable: false });
+  socket.on("data", (chunk: Buffer) => {
+    pending = Buffer.concat([pending, chunk]);
+    while (pending.length >= bytes) { tags.push(pending[0]!); pending = pending.subarray(bytes); }
+  });
+  return { tags, socket };
+}
+
+test("history replay, start pair and A/V pairs delivered frame-exact", { timeout: 60_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const h = await harness();
+  try {
+    for (let i = 0; i < 20; i += 1) await pair(h, i);
+    await until(async () => (await h.bus.stats()).pairs === 20, 5_000, "20 pairs");
+    const sub = await h.bus.subscribe({ video: true, audio: true });
+    assert.equal(sub.startPair, 20 - h.bus.historyFrames, "starts at the oldest replayed pair");
+    const v = collect(sub.videoFd, V);
+    const a = collect(sub.audioFd, A);
+    sub.adoptReaders();
+    for (let i = 20; i < 25; i += 1) await pair(h, i);
+    await until(() => v.tags.length >= 17 && a.tags.length >= 17, 5_000, "replay + live");
+    const expected = Array.from({ length: 17 }, (_, k) => 8 + k);
+    assert.deepEqual(v.tags.slice(0, 17), expected, "video: history then live, no gap");
+    assert.deepEqual(a.tags.slice(0, 17), expected, "audio pairs with video");
+    const stats = await h.bus.stats();
+    assert.equal(stats.subscriberDrops, 0);
+    assert.equal(stats.subscribers.length, 1);
+    v.socket.destroy(); a.socket.destroy();
+    // The reader is gone: the helper drops the subscriber on EPIPE.
+    await pair(h, 25).catch(() => undefined);
+    await until(async () => (await h.bus.stats()).subscribers.length === 0, 5_000, "closed subscriber removed");
+  } finally { await h.close(); }
+});
+
+test("stride subscribers get the newest pair then every n-th; audio-only and silence fill", { timeout: 60_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const h = await harness();
+  try {
+    for (let i = 0; i < 10; i += 1) await pair(h, i);
+    await until(async () => (await h.bus.stats()).pairs === 10, 5_000, "10 pairs");
+    const thumb = await h.bus.subscribe({ video: true, audio: false, stride: 5 });
+    assert.equal(thumb.audioFd, null);
+    assert.equal(thumb.startPair, 9, "the newest pair first");
+    const ears = await h.bus.subscribe({ video: false, audio: true });
+    const tv = collect(thumb.videoFd, V);
+    const ea = collect(ears.audioFd, A);
+    thumb.adoptReaders(); ears.adoptReaders();
+    for (let i = 10; i < 21; i += 1) await pair(h, i);
+    // The audio-only subscriber replays the 10 pairs of history there are, then 11 live ones.
+    await until(() => tv.tags.length >= 3 && ea.tags.length >= 10 + 11, 5_000, "strided + audio");
+    assert.deepEqual(tv.tags.slice(0, 3), [9, 14, 19]);
+    assert.deepEqual(ea.tags.slice(-3), [18, 19, 20]);
+    // Video without audio: once video runs maxSkew ahead, pairs carry silence.
+    for (let i = 21; i < 21 + h.bus.maxSkewFrames + 5; i += 1) await pair(h, i, false);
+    await until(async () => (await h.bus.stats()).silenceFilled >= 5, 5_000, "silence fill");
+    await until(() => ea.tags.at(-1) === 0, 5_000, "silence reaches the audio subscriber");
+    tv.socket.destroy(); ea.socket.destroy();
+  } finally { await h.close(); }
+});
+
+test("a stalled subscriber loses whole pairs past its backlog; peers' drop counts are snapshotted at subscribe", { timeout: 60_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const h = await harness();
+  let stalled: BusSubscription | null = null;
+  try {
+    stalled = await h.bus.subscribe({ video: true, audio: true });
+    // Never read: each 1 MiB pipe fills (audio first: 163 frames here), then the helper queue does.
+    const limit = h.bus.maxBacklogFrames + h.bus.historyFrames;
+    const youngLimit = limit + g.fps;
+    const produced = Math.ceil((1 << 20) / A) + youngLimit + 20;
+    for (let i = 0; i < produced; i += 1) await pair(h, i);
+    await until(async () => (await h.bus.stats()).pairs === produced, 10_000, "entire burst consumed");
+    await until(async () => (await h.bus.stats()).subscriberDrops > 0, 10_000, "drops while young");
+    const young = await h.bus.stats();
+    const queued = young.subscribers[0]?.queued ?? 0;
+    assert.ok(queued > limit && queued <= youngLimit + 1, `a young subscriber queues up to ~1 s more than the limit (${queued} queued, limit ${limit})`);
+    const youngDrops = young.subscriberDrops;
+    await sleep(2_100); // young period over: the normal limit applies, and the queue is still above it
+    for (let i = 0; i < 10; i += 1) await pair(h, i);
+    await until(async () => (await h.bus.stats()).subscriberDrops >= youngDrops + 10, 5_000, "every new pair dropped");
+    await until(() => stalled?.dropped === (youngDrops + 10), 5_000, "DROP events reach the subscription");
+    const peer = await h.bus.subscribe({ video: true, audio: false });
+    assert.equal(peer.droppedBefore(stalled), youngDrops + 10, "exact at the peer's start pair");
+    await pair(h, 1);
+    await until(() => (stalled?.dropped ?? 0) > youngDrops + 10, 5_000, "live count moves on");
+    assert.equal(peer.droppedBefore(stalled), youngDrops + 10, "the snapshot does not");
+    peer.unsubscribe();
+  } finally {
+    stalled?.unsubscribe();
+    await h.close();
+  }
+});
+
+test("program chains refuse the Node reference gate (no pair lockstep, no origin alignment)", () => {
+  assert.throws(() => new ProgramChain({ canvas: g, scratchDir: join(tmpdir(), "never"), videoBitrateKbps: 500, output: { kind: "external" }, gateImpl: "node",
+    redactor: passthroughRedactor, onStderr: () => undefined, onFatal: () => undefined }), /spike-only/);
+});
diff --git a/apps/media-worker/src/compositor/source-bus.ts b/apps/media-worker/src/compositor/source-bus.ts
new file mode 100644
index 0000000..4440a75
--- /dev/null
+++ b/apps/media-worker/src/compositor/source-bus.ts
@@ -0,0 +1,274 @@
+import { closeSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { resolveHelperBinary } from "../gate/binary";
+import { createFifoPair, makeFifoPair, openBlockingReader, type FifoPair } from "../gate/fifo";
+import { assertGeometry, type FrameGeometry } from "../gate/protocol";
+import { spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+
+/**
+ * Per-source fan-out between one ingest and every consumer of the source's raw
+ * frames: the compositors that use it (two during an A/B swap) and its preview
+ * taps.
+ *
+ * The bytes never pass through Node. A `source-bus` helper process
+ * (src/gate/rust/src/bin/source-bus.rs) reads the ingest's FIFOs and writes
+ * each subscriber's FIFOs; this class is its process manager and speaks its
+ * control lines. (S2a moved the frames on the worker's event loop: at
+ * 4 × 1080p30 that left no headroom and the buses dropped ~7.5 % of source
+ * pairs; runs/wp4/s2b-report.md item 1.)
+ *
+ * Semantics are unchanged from S2a: frames are delivered as A/V *pairs*, a
+ * subscriber more than `maxBacklogFrames + historyFrames` behind loses whole
+ * pairs, and the last `historyFrames` pairs are replayed to a new subscriber so
+ * the gate can splice a swap-in compositor at the on-air one's next source frame.
+ */
+export interface SourceBusOptions {
+  geometry: FrameGeometry;
+  scratchDir: string;
+  redactor: StderrRedactor;
+  onStderr(message: string): void;
+  /** The helper died (not on `stop()`): the source is gone. */
+  onExit?(reason: string): void;
+  maxSkewFrames?: number;
+  maxBacklogFrames?: number;
+  historyFrames?: number;
+}
+
+export interface SubscribeOptions {
+  video: boolean;
+  audio: boolean;
+  /** Take every `stride`-th pair only (thumbnails). Default 1. */
+  stride?: number;
+}
+
+/** A subscription: the pair index it starts at, and the pairs it has lost to backlog since. */
+export interface BusSubscription {
+  readonly bus: SourceBus;
+  readonly id: number;
+  readonly startPair: number;
+  readonly startedAt: bigint;
+  readonly dropped: number;
+  /** Blocking read ends for the consumer's stdio (null when not subscribed to that stream). */
+  readonly videoFd: number | null;
+  readonly audioFd: number | null;
+  /** Pairs `other` had lost when this subscription started (exact, unlike its live `dropped`). */
+  droppedBefore(other: BusSubscription): number | undefined;
+  /** Close the worker's copies of the read ends (after spawning the consumer). */
+  releaseReaders(): void;
+  /** The caller takes ownership of the read ends (an in-process consumer that closes them itself). */
+  adoptReaders(): void;
+  unsubscribe(): void;
+}
+
+export interface SourceBusStats {
+  pairs: number; silenceFilled: number; audioTrimmed: number; subscriberDrops: number; allocs: number;
+  input: { videoWaiting: number; audioWaiting: number; videoEof: boolean; audioEof: boolean };
+  /** Per subscriber: pairs dropped to backlog, and frames queued in the helper right now. */
+  subscribers: Array<{ id: number; dropped: number; queued: number }>;
+}
+
+interface Waiter { match(line: string[]): boolean; resolve(line: string[]): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }
+
+let nextBus = 1;
+
+export class SourceBus {
+  private proc: ManagedProcess | null = null;
+  private readonly busId = nextBus++;
+  private nextSub = 1;
+  private lineBuf = "";
+  private waiters: Waiter[] = [];
+  private readonly drops = new Map<number, number>();
+  private stopping = false;
+  private exited = false;
+  private ingest: FifoPair | null = null;
+  readonly maxSkewFrames: number;
+  readonly maxBacklogFrames: number;
+  readonly historyFrames: number;
+  /** Set when the helper reports the ingest closed both streams. */
+  ended = false;
+
+  constructor(private readonly options: SourceBusOptions) {
+    assertGeometry(options.geometry);
+    this.maxSkewFrames = options.maxSkewFrames ?? 15;
+    this.maxBacklogFrames = options.maxBacklogFrames ?? 4;
+    this.historyFrames = options.historyFrames ?? 12;
+    mkdirSync(options.scratchDir, { recursive: true, mode: 0o700 });
+  }
+
+  get geometry(): FrameGeometry { return this.options.geometry; }
+  get pid(): number | undefined { return this.proc?.child.pid; }
+
+  /**
+   * Starts the helper on fresh ingest FIFOs. The returned fds are blocking write ends for the
+   * producer's stdio (ingest: video on fd 1, PCM on fd 3); call `releaseIngestWriters()` once
+   * the producer has them. Until a producer writes, the bus simply has no pairs.
+   */
+  async start(): Promise<{ videoFd: number; audioFd: number }> {
+    const g = this.options.geometry;
+    const fifos = createFifoPair(this.options.scratchDir, this.busId, "bus");
+    this.ingest = fifos;
+    const argv = [String(g.width), String(g.height), String(g.fps), String(this.maxSkewFrames), String(this.maxBacklogFrames), String(this.historyFrames),
+      fifos.videoPath, fifos.audioPath];
+    const proc = spawnManaged(resolveHelperBinary("source-bus"), argv, ["pipe", "pipe", "pipe"], this.options.redactor, this.options.onStderr);
+    this.proc = proc;
+    proc.child.stdout?.setEncoding("utf8");
+    proc.child.stdout?.on("data", (chunk: string) => this.onData(chunk));
+    // EPIPE on a control line to a helper that just died: its exit is reported below, never as a crash.
+    proc.child.stdin?.on("error", () => undefined);
+    void proc.exited.then(({ code, signal }) => {
+      this.exited = true;
+      const reason = `source bus exited code=${code} signal=${signal}`;
+      for (const w of this.waiters.splice(0)) { clearTimeout(w.timer); w.reject(new Error(reason)); }
+      if (!this.stopping) this.options.onExit?.(reason);
+    });
+    const ready = this.waitFor((l) => l[0] === "READY", 10_000);
+    try {
+      await proc.started;
+      await ready;
+    } catch (error) {
+      ready.catch(() => undefined);
+      fifos.releaseHolders();
+      fifos.releaseWriters();
+      fifos.unlink();
+      throw error;
+    } finally {
+      // The helper holds the read ends now; from here only the producer keeps the FIFOs open.
+      fifos.releaseHolders();
+      fifos.unlink();
+    }
+    return { videoFd: fifos.videoFd, audioFd: fifos.audioFd };
+  }
+
+  /** Close the worker's copies of the ingest write ends (after spawning the producer). */
+  releaseIngestWriters(): void { this.ingest?.releaseWriters(); }
+
+  /** The caller takes ownership of the ingest write ends (an in-process producer that closes them itself). */
+  adoptIngestWriters(): void { this.ingest = null; }
+
+  private onData(chunk: string): void {
+    this.lineBuf += chunk;
+    let nl = this.lineBuf.indexOf("\n");
+    while (nl >= 0) {
+      const line = this.lineBuf.slice(0, nl).trim().split(/\s+/);
+      this.lineBuf = this.lineBuf.slice(nl + 1);
+      nl = this.lineBuf.indexOf("\n");
+      if (line[0] === "DROP") this.drops.set(Number(line[1]), Number(line[2]));
+      if (line[0] === "EOF") this.ended = true;
+      const i = this.waiters.findIndex((w) => w.match(line));
+      if (i >= 0) {
+        const [w] = this.waiters.splice(i, 1);
+        if (w) { clearTimeout(w.timer); w.resolve(line); }
+      }
+    }
+  }
+
+  private waitFor(match: (line: string[]) => boolean, timeoutMs: number): Promise<string[]> {
+    return new Promise<string[]>((resolve, reject) => {
+      const waiter: Waiter = {
+        match, resolve, reject,
+        timer: setTimeout(() => { this.waiters = this.waiters.filter((w) => w !== waiter); reject(new Error("source bus reply timeout")); }, timeoutMs),
+      };
+      this.waiters.push(waiter);
+    });
+  }
+
+  private send(line: string): void {
+    const stdin = this.proc?.child.stdin;
+    if (this.exited || !stdin || stdin.destroyed) throw new Error("source bus is not running");
+    stdin.write(line);
+  }
+
+  /** Sends a control line and waits for its reply; a failed send never leaves a waiter behind. */
+  private request(line: string, match: (l: string[]) => boolean, timeoutMs: number): Promise<string[]> {
+    const reply = this.waitFor(match, timeoutMs);
+    try {
+      this.send(line);
+    } catch (error) {
+      reply.catch(() => undefined);
+      const waiter = this.waiters.at(-1);
+      if (waiter) { clearTimeout(waiter.timer); this.waiters.pop(); }
+      throw error;
+    }
+    return reply;
+  }
+
+  /**
+   * New consumer. Delivery starts with the replayed history (a strided subscriber gets only the
+   * newest pair), then live pairs; `startPair` is the first pair's index. Spawn the consumer with
+   * `videoFd`/`audioFd`, then `releaseReaders()`.
+   */
+  async subscribe(opts: SubscribeOptions): Promise<BusSubscription> {
+    if (!opts.video && !opts.audio) throw new Error("subscription needs video or audio");
+    const stride = opts.stride ?? 1;
+    if (!Number.isSafeInteger(stride) || stride < 1 || stride > 3600) throw new Error("stride out of range");
+    const id = this.nextSub++;
+    const paths = makeFifoPair(this.options.scratchDir, id, `sub-${this.busId}`);
+    // The consumer (ffmpeg) needs *blocking* read ends; a temporary writer keeps each open() from
+    // blocking and is released once the helper has opened its non-blocking write end.
+    const video = opts.video ? openBlockingReader(paths.videoPath) : null;
+    const audio = opts.audio ? openBlockingReader(paths.audioPath) : null;
+    const unlink = (): void => { rmSync(paths.videoPath, { force: true }); rmSync(paths.audioPath, { force: true }); };
+    let line: string[];
+    try {
+      line = await this.request(`SUB ${id} ${video ? paths.videoPath : "-"} ${audio ? paths.audioPath : "-"} ${stride}\n`,
+        (l) => (l[0] === "SUBSCRIBED" || l[0] === "ERROR") && Number(l[1]) === id, 5_000);
+      if (line[0] !== "SUBSCRIBED") throw new Error("source bus could not open subscriber fifos");
+    } catch (error) {
+      for (const r of [video, audio]) if (r) { r.releaseHolder(); closeSync(r.fd); }
+      throw error;
+    } finally {
+      video?.releaseHolder();
+      audio?.releaseHolder();
+      unlink();
+    }
+    const peers = new Map<number, number>();
+    if (line[3] && line[3] !== "-") {
+      for (const entry of line[3].split(",")) {
+        const [peer, dropped] = entry.split(":").map(Number);
+        if (peer !== undefined && dropped !== undefined) peers.set(peer, dropped);
+      }
+    }
+    const drops = this.drops;
+    let readersOpen = true;
+    const subscription: BusSubscription = {
+      bus: this, id, startPair: Number(line[2]), startedAt: process.hrtime.bigint(),
+      get dropped() { return drops.get(id) ?? 0; },
+      videoFd: video?.fd ?? null, audioFd: audio?.fd ?? null,
+      droppedBefore: (other) => (other.bus === this ? peers.get(other.id) : undefined),
+      releaseReaders() { if (readersOpen) { readersOpen = false; for (const r of [video, audio]) if (r) closeSync(r.fd); } },
+      adoptReaders() { readersOpen = false; },
+      unsubscribe: () => {
+        subscription.releaseReaders();
+        drops.delete(id);
+        try { this.send(`UNSUB ${id}\n`); } catch { /* helper gone */ }
+      },
+    };
+    return subscription;
+  }
+
+  async stats(): Promise<SourceBusStats> {
+    const line = await this.request("STATS\n", (l) => l[0] === "STATS", 5_000);
+    const kv = new Map(line.slice(1).map((p) => p.split("=") as [string, string]));
+    const n = (k: string): number => Number(kv.get(k) ?? 0);
+    return { pairs: n("pairs"), silenceFilled: n("silence_filled"), audioTrimmed: n("audio_trimmed"), subscriberDrops: n("subscriber_drops"), allocs: n("allocs"),
+      input: { videoWaiting: n("video_waiting"), audioWaiting: n("audio_waiting"), videoEof: n("video_eof") !== 0, audioEof: n("audio_eof") !== 0 },
+      subscribers: (kv.get("subs") ?? "-").split(",").filter((e) => e !== "-").map((e) => {
+        const [id, dropped, queued] = e.split(":").map(Number);
+        return { id: id ?? 0, dropped: dropped ?? 0, queued: queued ?? 0 };
+      }) };
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    const proc = this.proc;
+    this.ingest?.releaseWriters();
+    if (!proc) return;
+    try { this.send("QUIT\n"); } catch { /* already gone */ }
+    const timer = setTimeout(() => proc.kill("SIGKILL"), 2_000);
+    await proc.exited;
+    clearTimeout(timer);
+    this.proc = null;
+    rmSync(join(this.options.scratchDir, `bus-${this.busId}.v.fifo`), { force: true });
+    rmSync(join(this.options.scratchDir, `bus-${this.busId}.a.fifo`), { force: true });
+  }
+}
diff --git a/apps/media-worker/src/compositor/testing.ts b/apps/media-worker/src/compositor/testing.ts
new file mode 100644
index 0000000..79530a0
--- /dev/null
+++ b/apps/media-worker/src/compositor/testing.ts
@@ -0,0 +1,211 @@
+/**
+ * Test/spike fixtures for the compositor chain (not used in production paths).
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { closeSync, copyFileSync, openSync, readFileSync } from "node:fs";
+import { Socket } from "node:net";
+import { join } from "node:path";
+import { SCENE_LAYOUTS, type SceneLayout } from "../production";
+import { ensureHelperBinaries } from "../gate/binary";
+import { layoutRects, type Canvas, type CompositorGraph, type OverlaySpec, type PxRect } from "./command-builder";
+import type { FrameGate } from "../gate/frame-gate";
+import type { ComposeRequest } from "./compositor";
+import { audioFrameBytes, videoFrameBytes, type FrameGeometry } from "../gate/protocol";
+import type { SinkReport } from "../gate/sink";
+import { spawnManaged, type ManagedProcess } from "../relay/ffmpeg";
+import { SourceBus } from "./source-bus";
+
+export const passthroughRedactor = { redact: (s: string): string => s };
+
+/**
+ * Luma of source frame n: a frame counter that survives scaling. Solid frames
+ * scale to (almost) the same value; swscale can round ±1 at some ratios
+ * (4x4 tiles), so the counter moves in steps of 4 and the sink rounds.
+ */
+export function counterLuma(n: number): number { return 20 + 4 * (n % 50); }
+
+/**
+ * A live source paced by the wall clock that writes into a bus's ingest FIFOs
+ * (the bytes an ingest process would write): solid frames whose luma is the
+ * frame counter, and a 1500 Hz sine that holds a whole number of periods per
+ * frame at 24/25/30/60 fps — any splice that is not on a frame boundary, and
+ * any inserted silence, shows up at the sink.
+ */
+export class CounterSource {
+  readonly bus: SourceBus;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private n = 0;
+  private readonly frames: Buffer[];
+  private readonly pcm: Buffer;
+  private out: { video: Socket; audio: Socket } | null = null;
+
+  constructor(private readonly g: FrameGeometry, scratchDir: string, amplitude = 4000) {
+    this.bus = new SourceBus({ geometry: g, scratchDir, redactor: passthroughRedactor, onStderr: (m) => process.stderr.write(m) });
+    const luma = g.width * g.height;
+    this.frames = Array.from({ length: 50 }, (_, i) => {
+      const f = Buffer.alloc(videoFrameBytes(g), 128);
+      f.fill(counterLuma(i), 0, luma);
+      return f;
+    });
+    const samples = audioFrameBytes(g) / 4;
+    this.pcm = Buffer.alloc(audioFrameBytes(g));
+    for (let s = 0; s < samples; s += 1) {
+      const v = Math.round(amplitude * Math.sin((2 * Math.PI * 1500 * s) / 48_000));
+      this.pcm.writeInt16LE(v, s * 4);
+      this.pcm.writeInt16LE(v, s * 4 + 2);
+    }
+  }
+
+  get framesSent(): number { return this.n; }
+
+  async start(): Promise<void> {
+    const fds = await this.bus.start();
+    this.bus.adoptIngestWriters();
+    const open = (fd: number): Socket => new Socket({ fd, readable: false, writable: true }).on("error", () => undefined);
+    const out = { video: open(fds.videoFd), audio: open(fds.audioFd) };
+    this.out = out;
+    const t0 = process.hrtime.bigint();
+    const period = 1_000_000_000n / BigInt(this.g.fps);
+    const step = (): void => {
+      const now = process.hrtime.bigint();
+      while (t0 + BigInt(this.n) * period <= now) {
+        out.video.write(this.frames[this.n % 50]!);
+        out.audio.write(this.pcm);
+        this.n += 1;
+      }
+      const wait = Number((t0 + BigInt(this.n) * period - process.hrtime.bigint()) / 1_000_000n);
+      this.timer = setTimeout(step, Math.max(0, wait));
+    };
+    step();
+  }
+
+  async stop(): Promise<void> {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.out?.video.destroy();
+    this.out?.audio.destroy();
+    this.out = null;
+    await this.bus.stop();
+  }
+}
+
+/** The verifying null encoder (src/gate/sink-cli.ts) as its own process, reading the gate's encoder FIFOs. */
+export class SinkProcess {
+  private proc: ManagedProcess | null = null;
+  private out = "";
+
+  async start(gate: FrameGate, g: FrameGeometry): Promise<void> {
+    const cwd = join(__dirname, "../..");
+    const proc = spawnManaged(process.execPath, ["--import", "tsx", join(__dirname, "../gate/sink-cli.ts"),
+      gate.encoderFifos.videoPath, gate.encoderFifos.audioPath, String(g.width), String(g.height), String(g.fps)],
+    ["pipe", "pipe", "pipe"], passthroughRedactor, (m) => process.stderr.write(m), cwd);
+    this.proc = proc;
+    proc.child.stdout?.setEncoding("utf8");
+    proc.child.stdout?.on("data", (c: string) => { this.out += c; });
+    const t0 = Date.now();
+    while (!this.out.includes("OPEN\n")) {
+      if (Date.now() - t0 > 15_000) throw new Error("sink did not open");
+      await new Promise((r) => setTimeout(r, 10));
+    }
+  }
+
+  async report(firstActiveTick: number): Promise<SinkReport & { silentAfterFirstActive: number }> {
+    const proc = this.proc;
+    if (!proc) throw new Error("sink not started");
+    proc.child.stdin?.write(`REPORT ${firstActiveTick}\n`);
+    await proc.exited;
+    const line = this.out.split("\n").find((l) => l.startsWith("{"));
+    if (!line) throw new Error("sink produced no report");
+    return JSON.parse(line) as SinkReport & { silentAfterFirstActive: number };
+  }
+
+  /** Also close the sink when a gate assertion fails before REPORT is requested. */
+  async stop(): Promise<void> {
+    await this.proc?.terminate(500);
+    this.proc = null;
+  }
+}
+
+/** H.264 + AAC MPEG-TS clip at the canvas size (encoded once, before measuring): the stand-in for a live HLS source. */
+export function encodeSourceClip(path: string, canvas: Canvas, seconds = 12): void {
+  const r = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", "-f", "lavfi", "-i", `testsrc2=s=${canvas.width}x${canvas.height}:r=${canvas.fps}:d=${seconds}`,
+    "-f", "lavfi", "-i", `sine=frequency=500:sample_rate=48000:d=${seconds}`,
+    "-c:v", "libx264", "-preset", "veryfast", "-b:v", "6000k", "-g", String(2 * canvas.fps), "-c:a", "aac", "-b:a", "128k", "-f", "mpegts", path]);
+  if (r.status !== 0) throw new Error("source clip encode failed");
+}
+
+/**
+ * Stand-in for the pinned egress relay (WP7): a paced, looping remux of `clip` into a FIFO.
+ * Returns the read end for an `mpegtsPipe` ingest's stdin (close it after spawning the ingest).
+ */
+export async function startPacer(clip: string, dir: string, name: string): Promise<{ readFd: number; proc: ManagedProcess }> {
+  const fifo = join(dir, `${name}.fifo`);
+  spawnSync("mkfifo", [fifo]);
+  const readFd = openSync(fifo, "r+");
+  const writeFd = openSync(fifo, "w");
+  const proc = spawnManaged("ffmpeg", ["-hide_banner", "-loglevel", "error", "-re", "-stream_loop", "-1", "-i", clip, "-c", "copy", "-f", "mpegts", "pipe:1"],
+    ["ignore", writeFd, "pipe"], passthroughRedactor, () => undefined);
+  await proc.started;
+  closeSync(writeFd);
+  return { readFd, proc };
+}
+
+export const ZERO_GAP_CANVAS: Canvas = { width: 320, height: 180, fps: 30 };
+const canvas = ZERO_GAP_CANVAS;
+
+/** Both native helpers (frame gate + source bus), built offline if missing or stale (src/gate/binary.ts). */
+export function ensureGateBinary(): boolean { return ensureHelperBinaries(); }
+
+export function makeAssets(dir: string): string[] {
+  const out: string[] = [];
+  for (const src of ["color=c=red@0.6:s=160x24", "testsrc2=s=600x16"]) {
+    const tmp = join(dir, `tmp-${out.length}.png`);
+    const r = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-y", "-f", "lavfi", "-i", `${src},format=rgba`, "-frames:v", "1", "-fflags", "+bitexact", "-flags", "+bitexact", tmp]);
+    assert.equal(r.status, 0, "asset render");
+    const path = join(dir, `${createHash("sha256").update(readFileSync(tmp)).digest("hex")}.png`);
+    copyFileSync(tmp, path);
+    out.push(path);
+  }
+  return out;
+}
+
+const CUSTOM: PxRect[] = [{ x: 0, y: 0, w: 160, h: 90 }, { x: 160, y: 90, w: 160, h: 90 }, { x: 100, y: 40, w: 120, h: 68 }];
+
+/** Swap i: cycles layouts × overlay sets × gains. Slot 0 always shows source 0 at the top-left (the counter pixel). */
+export function scriptedGraph(i: number): CompositorGraph {
+  const layouts = SCENE_LAYOUTS;
+  const layout: SceneLayout = layouts[i % layouts.length]!;
+  const rects = layout === "pip" ? [{ x: 0, y: 0, w: 320, h: 180 }, { x: 200, y: 100, w: 100, h: 56 }]
+    : layout === "custom" ? CUSTOM : layoutRects(layout, canvas);
+  const tiles = rects.map((rect, t) => ({ source: t === 0 ? 0 : (t % 5 === 4 ? null : t % 4), rect, fit: (["contain", "cover", "crop"] as const)[(i + t) % 3]! }));
+  if (tiles[0]) tiles[0].fit = "cover"; // cover/crop keep the counter pixel (0,0) on picture, contain letterboxes it
+  const overlays: OverlaySpec[] = [];
+  if (i % 3 !== 0) overlays.push({ kind: "image", asset: 0, x: 10, y: 130 });
+  if (i % 2 === 0) overlays.push({ kind: "chyron", asset: 1, y: 160, speedPxPerSec: 40 + ((i * 20) % 360) });
+  const gain = -3 * (i % 9);
+  const audible = [...new Set(tiles.map((t) => t.source).filter((s): s is number => s !== null))].slice(0, 1 + (i % 3));
+  return { canvas, layout, tiles, overlays, audio: { inputs: audible.map((source, k) => ({ source, gainDb: k === 0 ? gain : -6 })), masterGainDb: -3 * (i % 3) } };
+}
+
+
+/**
+ * Compose request over only the sources the graph uses (renumbered), as
+ * `planScene` does in production: ffmpeg never reads an input that is not wired
+ * into the filtergraph, so an unused bus subscription would just stall.
+ */
+export function composeOver(buses: SourceBus[], assets: string[], graph: CompositorGraph): ComposeRequest {
+  const used = [...new Set(graph.tiles.map((t) => t.source).concat(graph.audio.inputs.map((m) => m.source)).filter((s): s is number => s !== null))].sort((a, b) => a - b);
+  const index = (s: number): number => used.indexOf(s);
+  const audible = new Set(graph.audio.inputs.map((m) => m.source));
+  return {
+    inputs: used.map((s) => ({ bus: buses[s]!, audio: audible.has(s) })),
+    assets,
+    graph: {
+      ...graph,
+      tiles: graph.tiles.map((t) => ({ ...t, source: t.source === null ? null : index(t.source) })),
+      audio: { ...graph.audio, inputs: graph.audio.inputs.map((m) => ({ ...m, source: index(m.source) })) },
+    },
+  };
+}
diff --git a/apps/media-worker/src/compositor/wp12-hardening.test.ts b/apps/media-worker/src/compositor/wp12-hardening.test.ts
new file mode 100644
index 0000000..06e61a3
--- /dev/null
+++ b/apps/media-worker/src/compositor/wp12-hardening.test.ts
@@ -0,0 +1,492 @@
+/**
+ * WP12 hardening tests (flash slice) — apps/media-worker/src/compositor only.
+ *
+ * Two layers of the §4.3 "Injection" defense are exercised here:
+ *
+ * 1. Graph-builder injection at the type/argv layer. Hostile payloads
+ *    (`movie=`, `amovie=`, `filename=`, protocol prefixes, shell
+ *    metacharacters, newline/graph-chaining) are injected into every
+ *    string-typed input surface of the compositor plan. Either the typed
+ *    validators reject the plan (CommandBuildError) or the produced argv is
+ *    proven inert: the payload never appears, not even escaped.
+ *
+ * 2. Crop-mode full matrix: contain/cover/crop × every scene layout —
+ *    per-tile scale/pad/crop chains asserted from the generated filtergraph
+ *    and argv only (no ffmpeg execution).
+ *
+ * Vitest suite: `node_modules/.bin/vitest` of a sibling workspace app resolves
+ * this file (the media-worker devDependencies install only tsx/node:test);
+ * see the run note at the bottom of this file.
+ */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  buildCompositorArgs,
+  buildFilterGraph,
+  CommandBuildError,
+  layoutRects,
+  rectFromBasisPoints,
+  SYNTHETIC_PATTERNS,
+  type Canvas,
+  type CompositorPlan,
+  type OverlaySpec,
+} from "./command-builder";
+
+const canvas: Canvas = { width: 320, height: 180, fps: 30 };
+const W = canvas.width;
+const H = canvas.height;
+
+function synthetic(i: number) {
+  return {
+    video: { kind: "synthetic" as const, pattern: SYNTHETIC_PATTERNS[i % SYNTHETIC_PATTERNS.length]!, seed: 1000 + i },
+    audio: { kind: "synthetic" as const, toneHz: 220 + 110 * i },
+  };
+}
+
+const sha = (c: string) => c.repeat(64);
+/** Valid absolute scratch asset paths (what `assetPath` accepts). */
+const ASSET_A = `/scratch/assets/${sha("a")}.png`;
+const ASSET_B = `/scratch/assets/${sha("b")}.png`;
+
+/** Minimal valid plan: one live full-frame tile, one image overlay, silent mix. */
+function basePlan(): CompositorPlan {
+  return {
+    sources: [synthetic(0)],
+    assets: [ASSET_A],
+    graph: {
+      canvas,
+      layout: "single",
+      tiles: [{ source: 0, rect: { x: 0, y: 0, w: W, h: H }, fit: "contain" }],
+      overlays: [{ kind: "image", asset: 0, x: 8, y: 8 }],
+      audio: { inputs: [], masterGainDb: 0 },
+    },
+    output: { kind: "gate", videoFd: 1, audioFd: 3 },
+  };
+}
+
+/** Input-index map that buildFilterGraph expects for a one-source/one-asset plan. */
+const IDX1 = { video: [0], audio: [1], assets: [2] };
+
+function graphOf(plan: CompositorPlan): string {
+  return buildFilterGraph(plan, IDX1);
+}
+
+function argvOf(plan: CompositorPlan): string[] {
+  return buildCompositorArgs(plan);
+}
+
+/**
+ * A payload is inert when it is absent from every argv element — including the
+ * escaped forms a filtergraph string could need (`\;`, `\'`, `\\\,` …): the
+ * builder either drops or rejects it, it never transcodes it into a graph.
+ */
+function expectInert(plan: CompositorPlan, payload: string): void {
+  const argv = argvOf(plan);
+  const escaped = payload.replace(/([[\];,'\\])/g, "\\$1");
+  for (const arg of argv) {
+    assert.ok(!(arg).includes(payload));
+    assert.ok(!(arg).includes(escaped));
+  }
+  assert.ok(!(argv.join(" ")).includes(escaped));
+}
+
+/** Every mutation must either throw CommandBuildError or leave the payload out of argv. */
+function expectRejectedOrInert(mutate: (plan: CompositorPlan) => CompositorPlan, payload: string): void {
+  const plan = mutate(basePlan());
+  try {
+    argvOf(plan);
+  } catch (error) {
+    assert.ok((error) instanceof CommandBuildError);
+    return;
+  }
+  expectInert(plan, payload);
+}
+
+// ---------------------------------------------------------------------------
+// 1. Graph-builder injection: every string-typed input surface
+// ---------------------------------------------------------------------------
+
+/** [wb] WP12 payload classes, each must be rejected or proven inert. */
+const PAYLOADS: Array<[string, string]> = [
+  ["lavfi movie/amovie", "movie=evil.mp4"],
+  ["lavfi amovie", "amovie=evil.mp3"],
+  ["lavfi filename", "filename=/etc/passwd"],
+  ["lavfi chained filter", "color=c=black:s=320x180,drawtext=text=pwned"],
+  ["file protocol", "file:/etc/passwd"],
+  ["http url", "http://evil.example/x.mp4"],
+  ["https url", "https://evil.example/x.m3u8"],
+  ["pipe protocol", "pipe:0"],
+  ["subfile protocol", "subfile,,start=0,end=0,,:/etc/passwd"],
+  ["concat protocol", "concat:/etc/passwd|/etc/shadow"],
+  ["data protocol", "data:text/plain,pwned"],
+  ["hls protocol", "hls+http://evil.example/x.m3u8"],
+  ["rtsp url", "rtsp://evil.example:8554/live"],
+  ["shell separator", ";rm -rf /"],
+  ["shell pipe", "|tee /tmp/pwned"],
+  ["shell command substitution", "$(id -u)"],
+  ["shell backtick substitution", "`id -u`"],
+  ["shell redirect", ">/tmp/pwned"],
+  ["shell and-chain", "&&rm -rf /"],
+  ["shell or-chain", "||rm -rf /"],
+  ["graph pad link", "[0:v]null[sink]"],
+  ["graph output pad", "[vout]"],
+  ["graph chain separator", "null;nullsink"],
+  ["filter option comma", "scale=1:1,scale=2:2"],
+  ["filter option equals", "rate=999"],
+  ["quoted value", "'$(id -u)'"],
+  ["newline chaining", "a\nb"],
+  ["crlf chaining", "a\r\nb"],
+  ["newline + filter", "\nmovie=evil.mp4"],
+  ["tab separator", "\tmovie=evil.mp4"],
+  ["unicode line separator", "a\u2028b"],
+  ["control char", "a\x01b"],
+  ["backslash escape", "\\;movie=evil.mp4"],
+];
+
+/** One maximal payload spanning every class at once. */
+const KITCHEN_SINK = "movie=x|amovie=y|filename=z;[0:v]null[v];$(id)|`id`|\nhttp://e/x|file:/e";
+
+describe("WP12 injection: overlay asset paths (plan.assets[i])", () => {
+  const withAsset = (path: string): CompositorPlan => ({ ...basePlan(), assets: [path] });
+
+  for (const [_name, payload] of PAYLOADS) {
+    it(`rejects or neutralizes: ${_name}`, () => {
+    // Raw path form…
+    expectRejectedOrInert(withAsset(payload), payload);
+    // …and smuggled inside an otherwise-valid-looking scratch path shape.
+    const smuggle = `/scratch/assets/${payload.replace(/[/\s]/g, "-")}-${sha("p")}.png`;
+    expectRejectedOrInert(withAsset(smuggle), payload);
+  });
+
+  it("rejects traversal and traversal-lookalikes and non-scratch shapes", () => {
+    for (const path of [
+      "/scratch/../etc/passwd.png",
+      `/scratch/assets/../${sha("a")}.png`,
+      `/scratch/assets/${sha("a")}.png/../../${sha("b")}.png`,
+      `relative/${sha("a")}.png`,
+      `${sha("a")}.png`,
+      `/scratch/assets/${sha("a")}.PNG`,
+      `/scratch/assets/${sha("a").slice(0, 63)}.png`,
+      `/scratch/assets/${sha("a")} extra.png`,
+      "",
+    ]) {
+      assert.throws(() => argvOf(withAsset(path)), path, CommandBuildError);
+    }
+  });
+
+  it("rejects every protocol prefix as an asset path", () => {
+    for (const prefix of ["file:", "http:", "https:", "pipe:", "fd:", "concat:", "subfile,", "data:", "hls+", "rtsp:", "movie=", "amovie=", "filename="]) {
+      assert.throws(() => argvOf(withAsset(`${prefix}${sha("a")}.png`)), prefix, CommandBuildError);
+    }
+  });
+
+  it("rejects shell and graph metacharacters anywhere in an asset path", () => {
+    for (const ch of [";", "&", "|", "<", ">", "`", "$", "(", ")", "'", '"', "\\", "[", "]", ",", "\n", "\r", "\t", " ", "=", ":"]) {
+      const path = `/scratch/assets/x${ch}${sha("a").slice(0, 60)}.png`;
+      assert.throws(() => argvOf(withAsset(path)), CommandBuildError);
+    }
+  });
+
+  it("argv carries valid assets only as closed file:<sha>.png inputs", () => {
+    const argv = argvOf(basePlan());
+    assert.ok((argv).includes(`file:${ASSET_A}`));
+    const fileArgs = argv.filter((a) => a.startsWith("file:"));
+    assert.deepStrictEqual(fileArgs, [`file:${ASSET_A}`]);
+  });
+});
+
+describe("WP12 injection: overlay geometry and asset indexes (typed, no string surface)", () => {
+  const withOverlay = (o: OverlaySpec): CompositorPlan => ({ ...basePlan(), graph: { ...basePlan().graph, overlays: [o] } });
+
+  it("rejects an overlay naming a nonexistent asset index", () => {
+    assert.throws(() => argvOf(withOverlay({ kind: "image", asset: 9, x: 0, y: 0 })), /asset/);
+    assert.throws(() => argvOf(withOverlay({ kind: "image", asset: -1, x: 0, y: 0 })), /asset/);
+    assert.throws(() => argvOf(withOverlay({ kind: "chyron", asset: 2, y: 0, speedPxPerSec: 120 })), /asset/);
+  });
+
+  it("chyron x-expression is built only from a bounded integer speed — payloads cannot ride the expression", () => {
+    const plan = basePlan();
+    plan.graph.overlays = [{ kind: "chyron", asset: 0, y: 160, speedPxPerSec: 120 }];
+    const graph = graphOf(plan);
+    assert.ok(!/overlay=x='W-mod/.test(graph));
+    assert.ok(!(graph).includes("movie="));
+    // Out-of-band speeds are rejected before any expression string is built.
+    for (const speed of [0, 39, 401, 1e9, -120, 12.5, Number.NaN]) {
+      const bad: CompositorPlan = { ...plan, graph: { ...plan.graph, overlays: [{ kind: "chyron", asset: 0, y: 160, speedPxPerSec: speed }] } };
+      assert.throws(() => argvOf(bad), String(speed), CommandBuildError);
+    }
+  });
+
+  it("overlay geometry is integer-bounded; hostile numbers are type errors, not payload carriers", () => {
+    for (const x of [-1, W + 2, 0.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+      assert.throws(() => argvOf(withOverlay({ kind: "image", asset: 0, x, y: 8 })), String(x), CommandBuildError);
+    }
+    for (const y of [-2, H + 4, 0.5, Number.NaN]) {
+      assert.throws(() => argvOf(withOverlay({ kind: "chyron", asset: 0, y, speedPxPerSec: 120 })), String(y), CommandBuildError);
+    }
+  });
+});
+
+describe("WP12 injection: labels and source ids never reach the graph or argv", () => {
+  it("hostile labels on a desired-state snapshot leave no trace in compositor argv", async () => {
+    const { parseProductionSpec } = await import("../production");
+    const { planScene, programScene } = await import("./scene-plan");
+    const id = (n: number) => `00000000-0000-4000-8000-${String(n).padStart(12, "0")}`;
+    const payloads = [
+      "movie=evil.mp4",
+      "amovie=evil.mp3",
+      "filename=/etc/passwd",
+      "; rm -rf /",
+      "$(id -u)",
+      "`id`",
+      "[0:v]null[sink]",
+      "http://evil.example/x.m3u8",
+      "file:/etc/passwd",
+      "a\nmovie=evil.mp4",
+      "pipe:0",
+      KITCHEN_SINK,
+    ];
+    // parseProductionSpec must reject all of these as labels (strict allowlist).
+    for (const label of payloads) {
+      assert.throws(() => parseProductionSpec(labelSpec(id, label)));
+    }
+    // A spec with clean labels plans/compiles; ids, labels and URLs stay out of argv.
+    const spec = parseProductionSpec(labelSpec(id, "Cam A"));
+    const plan = planScene(spec, programScene(spec), canvas, (sourceId) => sourceId === id(1));
+    const argv = argvOf({
+      sources: plan.sourceIds.map((_, i) => ({ video: { kind: "rawPipe" as const, fd: 4 + 2 * i }, audio: null })),
+      assets: plan.assetIds.map((a) => `/scratch/assets/${a}.png`),
+      graph: plan.graph,
+      output: { kind: "gate", videoFd: 1, audioFd: 3 },
+    });
+    const joined = argv.join(" ");
+    for (const payload of payloads) {
+      assert.ok(!(joined).includes(payload));
+      assert.ok(!(joined).includes(payload.replace(/([[\];,'\\])/g, "\\$1")));
+    }
+    assert.ok(!(joined).includes("Cam"));
+    assert.ok(!(joined).includes("example"));
+  });
+
+  it("source ids are never argv material: synthetic plans reference patterns and integers only", () => {
+    const argv = argvOf(basePlan());
+    const patternArg = argv.find((a) => a.includes(`testsrc2=s=${W}x${H}`));
+    assert.notStrictEqual(patternArg, undefined);
+    assert.ok(!/[;|`$]|\bmovie=|\bamovie=|\bfilename=/.test(patternArg));
+    // Input references are structured (`<index>:v`, `<index>:a`) — never id strings.
+    assert.ok(new RegExp(/\[0:v\]/).test(graphOf(basePlan())));
+  });
+});
+
+describe("WP12 injection: filtergraph token provenance (labels, splits, pads)", () => {
+  it("graph labels are builder-owned; a payload cannot introduce new pad labels", () => {
+    const plan = basePlan();
+    plan.graph.tiles.push({ source: 0, rect: rectFromBasisPoints({ x: 6000, y: 6000, w: 3500, h: 3500 }, canvas), fit: "contain" });
+    const graph = graphOf(plan);
+    // split outputs and tile labels follow the fixed grammar [s<src>_<n>] / [t<i>] / [ov<i>] / [base] / [vout] / [aout]
+    assert.ok(new RegExp(/\[0:v\]split=2\[s0_0\]\[s0_1\]/).test(graph));
+    assert.ok(new RegExp(/\[s0_1\]scale=96:96/).test(graph));
+    assert.ok(new RegExp(/\[t1\]overlay=x=192:y=108/).test(graph));
+    const labels = graph.match(/\[[a-z0-9_:]+\]/g) ?? [];
+    assert.ok((labels.length) > (0));
+    assert.strictEqual(labels.every((m) => /^(?:\d+:v|\d+:a|s\d+_\d+|t\d+|ov\d+|c\d+|m\d+|bg|base|vout|aout)$/.test(m.slice(1, -1))), true);
+    assert.ok(!(graph).includes("[v]"));
+    assert.ok(!(graph).includes("[sink]"));
+  });
+
+  it("the full filtergraph never contains a payload in raw or escaped form", () => {
+    const plan = basePlan();
+    plan.graph.tiles.push({ source: 0, rect: rectFromBasisPoints({ x: 6000, y: 6000, w: 3500, h: 3500 }, canvas), fit: "cover" });
+    plan.graph.overlays = [
+      { kind: "image", asset: 0, x: 8, y: 8 },
+      { kind: "chyron", asset: 0, y: 160, speedPxPerSec: 200 },
+    ];
+    plan.graph.audio = { inputs: [{ source: 0, gainDb: -6 }], masterGainDb: -3 };
+    const graph = graphOf(plan);
+    for (const [, payload] of PAYLOADS) {
+      assert.ok(!(graph).includes(payload));
+      assert.ok(!(graph).includes(payload.replace(/([\[\];,'\\])/g, "\\$1")));
+    }
+    assert.ok(!(graph).includes(KITCHEN_SINK));
+  });
+
+  it("kitchen-sink payload stays inert end to end (argv layer)", () => {
+    const argv = argvOf(basePlan());
+    const joined = argv.join(" ");
+    assert.ok(!(joined).includes(KITCHEN_SINK));
+    assert.ok(!(joined).includes("movie="));
+    assert.ok(!(joined).includes("amovie="));
+    assert.ok(!(joined).includes("filename="));
+    assert.ok(!(joined).includes("$(id"));
+    assert.ok(!(joined).includes("`id`"));
+  });
+
+  it("single quotes appear only as the chyron x-expression quoting around the builder-owned expression", () => {
+    const single = (plan: CompositorPlan): CompositorPlan => {
+      plan.graph.overlays = [{ kind: "chyron", asset: 0, y: 160, speedPxPerSec: 80 }];
+      return plan;
+    };
+    const graph = graphOf(single(basePlan()));
+    const quoted = graph.match(/'[^']*'/g) ?? [];
+    assert.deepStrictEqual(quoted, ["W-mod(t*80\\,w+W)"]);
+    // No quote-escape sequences exist anywhere in the graph.
+    assert.ok(!(graph).includes("\\'"));
+    assert.ok(!(graph).includes("''"));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// 2. Crop-mode full matrix: contain/cover/crop × layouts
+// ---------------------------------------------------------------------------
+
+/**
+ * `tileFilter` chains per fit (from command-builder.ts):
+ *   contain → scale(w,h:force_original_aspect_ratio=decrease:force_divisible_by=2) → pad(w,h,centered,black) → setsar=1
+ *   cover   → scale(w,h:force_original_aspect_ratio=increase:force_divisible_by=2) → crop(w,h) → setsar=1
+ *   crop    → crop(w,h) → setsar=1
+ */
+const FIT_CHAIN: Record<"contain" | "cover" | "crop", (w: number, h: number) => RegExp> = {
+  contain: (w, h) => new RegExp(`^scale=${w}:${h}:force_original_aspect_ratio=decrease:force_divisible_by=2,pad=${w}:${h}:\\(ow-iw\)/2:\\(oh-ih\)/2:color=black,setsar=1$`),
+  cover: (w, h) => new RegExp(`^scale=${w}:${h}:force_original_aspect_ratio=increase:force_divisible_by=2,crop=${w}:${h},setsar=1$`),
+  crop: (w, h) => new RegExp(`^crop=${w}:${h},setsar=1$`),
+};
+
+interface MatrixCase {
+  name: string;
+  layout: "single" | "pip" | "2x1" | "2x2" | "3x3" | "4x4" | "custom";
+  rects: PxRect[];
+  /** Slot indexes rendered black (source=null) — excluded from the live-tile assertions. */
+  empty?: number[];
+}
+
+const MATRIX: MatrixCase[] = [
+  { name: "single", layout: "single", rects: layoutRects("single", canvas) },
+  { name: "pip", layout: "pip", rects: [{ x: 0, y: 0, w: 320, h: 180 }, rectFromBasisPoints({ x: 6000, y: 6000, w: 3500, h: 3500 }, canvas)] },
+  { name: "2x1", layout: "2x1", rects: layoutRects("2x1", canvas) },
+  { name: "2x2", layout: "2x2", rects: layoutRects("2x2", canvas), empty: [3] },
+  { name: "3x3", layout: "3x3", rects: layoutRects("3x3", canvas), empty: [4, 8] },
+  { name: "4x4", layout: "4x4", rects: layoutRects("4x4", canvas), empty: [5, 10, 15] },
+  { name: "custom (non-overlapping, xstack)", layout: "custom", rects: [{ x: 0, y: 0, w: 160, h: 90 }, { x: 160, y: 90, w: 160, h: 90 }] },
+  { name: "custom (overlapping, overlay chain)", layout: "custom", rects: [{ x: 0, y: 0, w: 200, h: 112 }, { x: 120, y: 68, w: 200, h: 112 }] },
+];
+
+/** Every layout × every fit, via buildCompositorArgs (the production entry point). */
+function matrixPlan(c: MatrixCase, fit: "contain" | "cover" | "crop"): CompositorPlan {
+  const plan = basePlan();
+  plan.sources = [0, 1, 2, 3].map(synthetic);
+  plan.graph.layout = c.layout;
+  plan.graph.tiles = c.rects.map((rect, i) => ({ source: c.empty?.includes(i) ? null : i % 4, rect, fit }));
+  plan.graph.overlays = [];
+  plan.graph.audio = { inputs: [], masterGainDb: 0 };
+  plan.assets = [];
+  return plan;
+}
+
+describe("WP12 crop-mode matrix: contain/cover/crop × single/pip/two_up/split grids/custom", () => {
+  it("layout cell rects are even-aligned and tile the canvas exactly", () => {
+    for (const layout of ["2x1", "2x2", "3x3", "4x4"] as const) {
+      const rects = layoutRects(layout, canvas);
+      assert.strictEqual(rects.reduce((a, r) => a + r.w * r.h, 0), W * H);
+      for (const r of rects) for (const v of [r.x, r.y, r.w, r.h]) assert.strictEqual(v % 2, 0);
+    }
+  });
+
+  for (const { c, fit } of MATRIX.flatMap((c) => (["contain", "cover", "crop"] as const).map((fit) => ({ c, fit })))) {
+      const plan = matrixPlan(c, fit);
+      const argv = argvOf(plan);
+      const graph = argv[argv.indexOf("-filter_complex") + 1]!;
+
+      const live = c.rects.filter((_, i) => !c.empty?.includes(i));
+      live.forEach((rect, i) => {
+        const chain = new RegExp(`\\[t${i}\\]`.replace("[", "\\[") + `\\]`); // placeholder, replaced below
+        void chain;
+        const tileChain = new RegExp(`\\[s?\\d*(?::v)?\\][^;]*\\[t${i}\\]`);
+        const match = graph.match(tileChain);
+        assert.notStrictEqual(match, null);
+        assert.strictEqual(FIT_CHAIN[fit](rect.w, rect.h).test(match![0].slice(match![0].indexOf("]") + 1)), true);
+        // Geometry is exactly the layout cell: no source- or fit-dependent drift.
+        assert.ok((graph).includes(`[t${i}]`));
+      });
+
+      // The assembly stage per layout family:
+      if (c.layout === "pip" || c.name.includes("overlapping")) {
+        // PIP and overlapping customs are overlay chains; xstack must not appear.
+        assert.ok(!(graph).includes("xstack"));
+        assert.ok(new RegExp(/overlay=x=\d+:y=\d+:eof_action=repeat/).test(graph));
+      } else if (live.length >= 2) {
+        const layout = live.map((r) => `${r.x}_${r.y}`).join("|");
+        assert.ok(graph.includes(`xstack=inputs=${live.length}:layout=${layout.replace(/([|_])/g, "\\$1")}:fill=black`));
+      } else {
+        assert.ok(!(graph).includes("xstack"));
+      }
+    },
+  );
+
+  it("argv structure per matrix row: -i ordering, -filter_complex once, gate outputs on pipe:1/pipe:3", () => {
+    for (const c of MATRIX) {
+      for (const fit of ["contain", "cover", "crop"] as const) {
+        const argv = argvOf(matrixPlan(c, fit));
+        assert.strictEqual((argv.filter((a) => a === "-filter_complex")).length, 1);
+        assert.strictEqual((argv.filter((a) => a === "-i")).length, c.rects.filter((_, i) => !c.empty?.includes(i)).length || 1);
+        assert.ok(!/[&<>]/.test(argv[argv.indexOf("-filter_complex") + 1]));
+        assert.ok(!/[;&|`$<>]/.test(argv[argv.indexOf("-filter_complex") + 1]));
+        assert.strictEqual(argv.at(-1), "pipe:3");
+        assert.ok((argv).includes("pipe:1"));
+      }
+    }
+  });
+
+  it("split_horizontal/split_vertical equivalents (2x1 / custom row-split) keep per-half fit chains", () => {
+    // Horizontal split = 2x1 grid: left/right halves, each independently cropped.
+    const row = matrixPlan({ name: "2x1", layout: "2x1", rects: layoutRects("2x1", canvas) }, "crop");
+    const rowGraph = argvOf(row)[argvOf(row).indexOf("-filter_complex") + 1]!;
+    assert.ok(new RegExp(/\[t0\]$/m).test(rowGraph));
+    assert.ok((rowGraph).includes("crop=160:180,setsar=1[t0]"));
+    assert.ok((rowGraph).includes("crop=160:180,setsar=1[t1]"));
+    // Vertical split = a custom top/bottom split: same halves stacked, xstack fills black.
+    const col = matrixPlan({ name: "custom vsplit", layout: "custom", rects: [{ x: 0, y: 0, w: 320, h: 90 }, { x: 0, y: 90, w: 320, h: 90 }] }, "cover");
+    const colGraph = argvOf(col)[argvOf(col).indexOf("-filter_complex") + 1]!;
+    assert.ok((colGraph).includes("scale=320:90:force_original_aspect_ratio=increase:force_divisible_by=2,crop=320:90,setsar=1[t0]"));
+    assert.ok((colGraph).includes("scale=320:90:force_original_aspect_ratio=increase:force_divisible_by=2,crop=320:90,setsar=1[t1]"));
+    assert.ok(new RegExp(/xstack=inputs=2:layout=0_0\|0_90:fill=black/).test(colGraph));
+  });
+
+  it("mixed fits inside one layout keep each tile's own chain (cover base + contain PIP inset)", () => {
+    const plan = matrixPlan({ name: "pip", layout: "pip", rects: [{ x: 0, y: 0, w: 320, h: 180 }, rectFromBasisPoints({ x: 6000, y: 6000, w: 3500, h: 3500 }, canvas)] }, "cover");
+    plan.graph.tiles[1]!.fit = "contain";
+    const graph = argvOf(plan)[argvOf(plan).indexOf("-filter_complex") + 1]!;
+    assert.ok((graph).includes("scale=320:180:force_original_aspect_ratio=increase:force_divisible_by=2,crop=320:180,setsar=1[t0]"));
+    assert.ok((graph).includes("scale=96:96:force_original_aspect_ratio=decrease:force_divisible_by=2,pad=96:96:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1[t1]"));
+    assert.ok(new RegExp(/overlay=x=192:y=108:eof_action=repeat/).test(graph));
+  });
+
+  it("contain letterboxes black and never crops; crop never pads; cover never letterboxes", () => {
+    const rect = { x: 0, y: 0, w: 160, h: 180 };
+    const graph = (fit: "contain" | "cover" | "crop") => graphOf({ ...basePlan(), graph: { ...basePlan().graph, tiles: [{ source: 0, rect, fit }] } });
+    const contain = graph("contain");
+    assert.ok((contain).includes("pad=160:180:(ow-iw)/2:(oh-ih)/2:color=black"));
+    assert.ok(!(contain).includes(`crop=${rect.w}:${rect.h}`));
+    const cover = graph("cover");
+    assert.ok((cover).includes(`crop=${rect.w}:${rect.h},setsar=1`));
+    assert.ok(!(cover).includes("pad="));
+    const cropOnly = graph("crop");
+    assert.ok((cropOnly).includes(`crop=${rect.w}:${rect.h},setsar=1`));
+    assert.ok(!(cropOnly).includes("scale="));
+    assert.ok(!(cropOnly).includes("pad="));
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Run note
+// ---------------------------------------------------------------------------
+
+// This suite runs under the repo's vitest 2.1.9 (installed with the api app;
+// the media-worker package itself has no vitest dependency):
+//
+//   cd apps/api && ./node_modules/.bin/vitest run \
+//     --root ../media-worker src/compositor/wp12-hardening.test.ts
+//
+// The media-worker `npm test` glob (node --test) also picks this file up as a
+// bare `describe/it` import failure — it is authored for vitest only, per the
+// WP12 deliverable.
diff --git a/apps/media-worker/src/compositor/zero-gap.test.ts b/apps/media-worker/src/compositor/zero-gap.test.ts
new file mode 100644
index 0000000..293c378
--- /dev/null
+++ b/apps/media-worker/src/compositor/zero-gap.test.ts
@@ -0,0 +1,116 @@
+/**
+ * S2 gate: zero gap at the encoder input across 1 000 scripted scene, overlay
+ * and gain swaps (streaming-architecture.md §6 S2), plus kill -9 of the
+ * compositor mid-swap leaving the encoder input up.
+ *
+ * Real compositor ffmpeg processes built by MediaCommandBuilder, the Rust frame
+ * gate, and a verifying null encoder in its own process. Sources are
+ * CounterSources (luma = frame counter, phase-locked 1500 Hz sine).
+ * The regular suite runs 50 swaps. The standalone acceptance gate runs
+ * ZERO_GAP_SWAPS=1000, keeping the extended media workload separate from other live-process tests.
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import type { ComposeRequest } from "./compositor";
+import { ProgramChain } from "./program";
+import { composeOver, CounterSource, ensureGateBinary, makeAssets, passthroughRedactor, scriptedGraph, SinkProcess, ZERO_GAP_CANVAS as canvas } from "./testing";
+
+const SWAPS = Number(process.env.ZERO_GAP_SWAPS ?? 50);
+
+test("zero gap at the encoder input across scripted scene/overlay/gain swaps", { timeout: 1_800_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("frame-gate binary unavailable (cargo build failed)"); return; }
+  const scratch = mkdtempSync(join(tmpdir(), "zero-gap-"));
+  const assets = makeAssets(scratch);
+  const sources = Array.from({ length: 4 }, () => new CounterSource(canvas, scratch));
+  for (const s of sources) await s.start();
+  const lost: string[] = [];
+  const chain = new ProgramChain({ canvas, scratchDir: scratch, videoBitrateKbps: 1000, output: { kind: "external" },
+    redactor: passthroughRedactor, onStderr: () => undefined, onFatal: (r) => lost.push(`fatal ${r}`), onCompositorLost: (r) => lost.push(r) });
+  const sink = new SinkProcess();
+  await sink.start(chain.gate, canvas);
+  const request = (i: number): ComposeRequest => composeOver(sources.map((s) => s.bus), assets, scriptedGraph(i));
+  try {
+    await chain.start(request(0));
+    const first = await chain.stats();
+    const firstTick = first.ticks;
+    const swapTicks: number[] = [];
+    for (let i = 1; i <= SWAPS; i += 1) swapTicks.push(await chain.swap(request(i)));
+    // Let the last compositor run, then read the counters.
+    await new Promise((r) => setTimeout(r, 500));
+    const stats = await chain.stats();
+    // Report before teardown: stopping the chain makes the gate hold its last frame.
+    const report = await sink.report(firstTick);
+    await chain.stop();
+
+    assert.equal(chain.swaps, SWAPS + 1);
+    assert.equal(stats.swaps, SWAPS + 1);
+    assert.deepEqual(lost.filter((l) => !l.startsWith("fatal frame gate exited")), [], "no compositor lost on air");
+    assert.ok(swapTicks.every((tick, k) => k === 0 || tick > (swapTicks[k - 1] ?? 0)), "swap ticks strictly increase");
+    // Encoder-side continuity: every tick delivered exactly one video and one audio frame.
+    assert.ok(Math.abs(report.videoFrames - report.audioFrames) <= 1, "video/audio lockstep at the encoder input");
+    assert.ok(report.videoFrames >= stats.ticks - 2, "encoder received every tick");
+    assert.equal(stats.outDrops, 0, "gate never dropped toward the encoder");
+    // Every delivered frame advances by exactly one, including across every swap.
+    assert.deepEqual(Object.keys(report.tagDeltas), ["1"], `frame counter all +1 (deltas ${JSON.stringify(report.tagDeltas)}, gate lagged=${stats.lagged} behindMax=${stats.behindMax} drops=${stats.drops} vrep=${stats.vrep})`);
+    // PCM continuity: no inserted silence after the first compositor and no step larger than the sine allows.
+    const bound = Math.ceil(report.maxPcmAbs * Math.sin((2 * Math.PI * 1500) / 48_000)) + 4;
+    assert.ok(report.maxPcmStep <= bound, `PCM step ${report.maxPcmStep} <= ${bound}`);
+    const fills = stats.vrep + stats.asil;
+    // On an overloaded host a fill can come from the gate itself not being scheduled; it must stay rare.
+    assert.ok(fills <= Math.ceil(stats.ticks / 1000), `repeat/silence fills ${fills} over ${stats.ticks} ticks`);
+    t.diagnostic(JSON.stringify({ swaps: SWAPS, lagRetries: chain.lagRetries, lagged: stats.lagged, behindMax: stats.behindMax, ticks: stats.ticks, vrep: stats.vrep, asil: stats.asil, lateMaxUs: stats.lateMaxUs, lateOverFrame: stats.lateOverFrame,
+      tagDeltas: report.tagDeltas, maxPcmStep: report.maxPcmStep, bound, maxGapMs: report.maxGapMs }));
+  } finally {
+    await sink.stop();
+    for (const s of sources) await s.stop();
+    await chain.stop();
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
+
+test("kill -9 of the compositor mid-swap leaves the encoder input up", { timeout: 120_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("frame-gate binary unavailable"); return; }
+  const scratch = mkdtempSync(join(tmpdir(), "kill9-"));
+  const assets = makeAssets(scratch);
+  const sources = Array.from({ length: 4 }, () => new CounterSource(canvas, scratch));
+  for (const s of sources) await s.start();
+  const lost: string[] = [];
+  const fatal: string[] = [];
+  const chain = new ProgramChain({ canvas, scratchDir: scratch, videoBitrateKbps: 1000, output: { kind: "external" },
+    redactor: passthroughRedactor, onStderr: () => undefined, onFatal: (r) => fatal.push(r), onCompositorLost: (r) => lost.push(r) });
+  const sink = new SinkProcess();
+  await sink.start(chain.gate, canvas);
+  const request = (i: number): ComposeRequest => composeOver(sources.map((s) => s.bus), assets, { ...scriptedGraph(i), audio: { inputs: [{ source: 0, gainDb: 0 }], masterGainDb: 0 } });
+  try {
+    await chain.start(request(0));
+    const firstTick = (await chain.stats()).ticks;
+    // Mid-swap: B is starting while A is SIGKILLed.
+    const a = chain.activeCompositor;
+    const swapping = chain.swap(request(1));
+    a?.kill("SIGKILL");
+    await swapping;
+    // On air: SIGKILL the active one; the chain respawns it behind the gate.
+    chain.activeCompositor?.kill("SIGKILL");
+    await new Promise((r) => setTimeout(r, 2_000));
+    await chain.swap(request(2));
+    const before = await chain.stats();
+    await new Promise((r) => setTimeout(r, 1_000));
+    const after = await chain.stats();
+    const report = await sink.report(firstTick);
+    await chain.stop();
+    assert.deepEqual(fatal.filter((f) => !f.startsWith("frame gate exited")), [], "gate and encoder input never went down");
+    assert.ok(lost.length >= 1, "the on-air kill was detected");
+    assert.ok(after.ticks - before.ticks >= canvas.fps * 0.8, "gate kept ticking");
+    assert.ok(Math.abs(report.videoFrames - report.audioFrames) <= 1);
+    assert.ok(report.videoFrames >= after.ticks - 2, "encoder input never starved");
+    t.diagnostic(JSON.stringify({ lost, vrep: after.vrep, asil: after.asil, ticks: after.ticks }));
+  } finally {
+    await sink.stop();
+    for (const s of sources) await s.stop();
+    await chain.stop();
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
diff --git a/apps/media-worker/src/gate/binary.ts b/apps/media-worker/src/gate/binary.ts
new file mode 100644
index 0000000..0372432
--- /dev/null
+++ b/apps/media-worker/src/gate/binary.ts
@@ -0,0 +1,85 @@
+/**
+ * Native helper binaries (src/gate/rust, std only): `frame-gate` (the channel's
+ * clock master) and `source-bus` (per-source raw frame fan-out).
+ *
+ * Resolution order, first hit wins:
+ *  1. `MEDIA_FRAME_GATE_BIN` / `MEDIA_SOURCE_BUS_BIN`: an explicit path per binary;
+ *  2. `MEDIA_HELPER_DIR/<name>`: the packaged directory (the image builds the crate
+ *     with `scripts/build-helpers.sh` and sets this; see runs/wp4/s2b-report.md item 5);
+ *  3. the crate's `target/release/<name>` (development checkouts and tests).
+ *
+ * Nothing builds at runtime in production. `ensureHelperBinaries()` is for tests
+ * and the spike/smoke scripts: it builds the crate offline when a binary is
+ * missing or older than its sources.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+export type HelperBinary = "frame-gate" | "source-bus";
+
+const ENV: Record<HelperBinary, string> = { "frame-gate": "MEDIA_FRAME_GATE_BIN", "source-bus": "MEDIA_SOURCE_BUS_BIN" };
+
+/** The crate directory, from `src/gate` (tsx) or `dist/gate` (compiled). */
+export function helperCrateDir(): string {
+  const local = resolve(__dirname, "rust");
+  return existsSync(join(local, "Cargo.toml")) ? local : resolve(__dirname, "../../src/gate/rust");
+}
+
+function candidates(name: HelperBinary): string[] {
+  return [
+    process.env[ENV[name]],
+    process.env.MEDIA_HELPER_DIR ? join(process.env.MEDIA_HELPER_DIR, name) : undefined,
+    join(helperCrateDir(), "target/release", name),
+  ].filter((path): path is string => typeof path === "string" && path.length > 0);
+}
+
+export function resolveHelperBinary(name: HelperBinary): string {
+  const found = candidates(name).find((path) => existsSync(path));
+  if (!found) throw new Error(`${name} binary not found: set ${ENV[name]} or MEDIA_HELPER_DIR, or run scripts/build-helpers.sh`);
+  return found;
+}
+
+function newestSource(crate: string): number {
+  const files = ["Cargo.toml", "Cargo.lock"].map((f) => join(crate, f));
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.name.endsWith(".rs")) files.push(path);
+    }
+  };
+  walk(join(crate, "src"));
+  return Math.max(...files.filter((f) => existsSync(f)).map((f) => statSync(f).mtimeMs));
+}
+
+/** Development binaries that are missing or older than the crate sources. Env/packaged binaries are taken as given. */
+export function staleHelpers(): HelperBinary[] {
+  const crate = helperCrateDir();
+  if (!existsSync(join(crate, "Cargo.toml"))) return [];
+  const newest = newestSource(crate);
+  return (Object.keys(ENV) as HelperBinary[]).filter((name) => {
+    if (process.env[ENV[name]] || process.env.MEDIA_HELPER_DIR) return false;
+    const path = join(crate, "target/release", name);
+    return !existsSync(path) || statSync(path).mtimeMs < newest;
+  });
+}
+
+/**
+ * Tests/scripts: build the crate if a development binary is missing or stale.
+ * `--offline --locked`: no network, and the (dependency-free) lockfile must not change.
+ * Concurrent callers are serialized by cargo's own build-directory lock.
+ */
+export function ensureHelperBinaries(): boolean {
+  if (staleHelpers().length > 0) {
+    const built = spawnSync("cargo", ["build", "--release", "--offline", "--locked", "--manifest-path", join(helperCrateDir(), "Cargo.toml")], { stdio: "ignore" });
+    if (built.status !== 0) return false;
+  }
+  try {
+    resolveHelperBinary("frame-gate");
+    resolveHelperBinary("source-bus");
+    return true;
+  } catch {
+    return false;
+  }
+}
diff --git a/apps/media-worker/src/gate/buffers.ts b/apps/media-worker/src/gate/buffers.ts
new file mode 100644
index 0000000..32e7981
--- /dev/null
+++ b/apps/media-worker/src/gate/buffers.ts
@@ -0,0 +1,29 @@
+/**
+ * Preallocated, refcounted frame buffers. Raw 1080p frames are 3 MB; allocating
+ * one per frame is ~93 MB/s of external memory per stream and drives GC, so the
+ * gate and the source bus recycle buffers once every in-flight write is done.
+ */
+export class BufferPool {
+  private readonly free: Buffer[] = [];
+  private readonly refs = new Map<Buffer, number>();
+  /** Buffers allocated after construction; stays 0 in steady state. */
+  allocs = 0;
+  constructor(readonly size: number, prealloc: number) {
+    for (let i = 0; i < prealloc; i += 1) this.free.push(Buffer.alloc(size));
+  }
+  /** The caller owns one reference; `release()` it when done. */
+  get(): Buffer {
+    let buf = this.free.pop();
+    if (!buf) { this.allocs += 1; buf = Buffer.alloc(this.size); }
+    this.refs.set(buf, 1);
+    return buf;
+  }
+  retain(buf: Buffer): void { this.refs.set(buf, (this.refs.get(buf) ?? 0) + 1); }
+  release(buf: Buffer): void {
+    const n = (this.refs.get(buf) ?? 0) - 1;
+    if (n > 0) { this.refs.set(buf, n); return; }
+    if (n < 0) return; // not pool-owned or already free
+    this.refs.delete(buf);
+    this.free.push(buf);
+  }
+}
diff --git a/apps/media-worker/src/gate/fifo.ts b/apps/media-worker/src/gate/fifo.ts
new file mode 100644
index 0000000..15c3307
--- /dev/null
+++ b/apps/media-worker/src/gate/fifo.ts
@@ -0,0 +1,79 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, constants, openSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { mediaEnv } from "../relay/ffmpeg";
+
+export interface FifoPair {
+  videoPath: string;
+  audioPath: string;
+  /**
+   * O_WRONLY write ends for the producer's stdio. A temporary non-blocking read
+   * end keeps each FIFO open (no ENXIO, no blocking open) until the gate has
+   * attached. After both releases only the producer writes and only the gate
+   * reads: producer death is an EOF at the gate, and a gate-side close is an
+   * EPIPE at the producer (a retired compositor cannot hang on a full pipe).
+   */
+  videoFd: number;
+  audioFd: number;
+  /** Close the worker's copies of the write ends (after spawning the producer). */
+  releaseWriters(): void;
+  /** Close the temporary read ends (after the gate has opened its own). */
+  releaseHolders(): void;
+  unlink(): void;
+}
+
+const SCRATCH = /^\/[A-Za-z0-9._/-]+$/;
+
+/** mkfifo(1) via argv (Node has no mkfifo binding). */
+const PREFIX = /^[a-z][a-z0-9-]{0,31}$/;
+
+/** Creates `<prefix>-<id>.{v,a}.fifo`; `prefix` names the owner (`gate`, `bus`, `sub-3`). Paths are scratch dir + prefix + numeric id only. */
+export function makeFifoPair(scratchDir: string, id: number, prefix: string): { videoPath: string; audioPath: string } {
+  if (!SCRATCH.test(scratchDir) || scratchDir.includes("..") || !Number.isSafeInteger(id) || id < 0 || !PREFIX.test(prefix)) throw new Error("unsafe fifo location");
+  const videoPath = join(scratchDir, `${prefix}-${id}.v.fifo`);
+  const audioPath = join(scratchDir, `${prefix}-${id}.a.fifo`);
+  const made = spawnSync("mkfifo", ["-m", "600", videoPath, audioPath], { shell: false, env: mediaEnv(), stdio: "ignore" });
+  if (made.status !== 0) throw new Error("mkfifo failed");
+  return { videoPath, audioPath };
+}
+
+const NAME = /^[a-z][a-z0-9-]{0,47}\.fifo$/;
+
+/** One FIFO `<scratchDir>/<name>` (name: lowercase, digits, '-', ending `.fifo`). */
+export function makeFifo(scratchDir: string, name: string): string {
+  if (!SCRATCH.test(scratchDir) || scratchDir.includes("..") || !NAME.test(name)) throw new Error("unsafe fifo location");
+  const path = join(scratchDir, name);
+  const made = spawnSync("mkfifo", ["-m", "600", path], { shell: false, env: mediaEnv(), stdio: "ignore" });
+  if (made.status !== 0) throw new Error("mkfifo failed");
+  return path;
+}
+
+export function createFifoPair(scratchDir: string, id: number, prefix = "gate"): FifoPair {
+  const { videoPath, audioPath } = makeFifoPair(scratchDir, id, prefix);
+  const holders = [openSync(videoPath, constants.O_RDONLY | constants.O_NONBLOCK), openSync(audioPath, constants.O_RDONLY | constants.O_NONBLOCK)];
+  const videoFd = openSync(videoPath, constants.O_WRONLY);
+  const audioFd = openSync(audioPath, constants.O_WRONLY);
+  let writers = true;
+  let held = true;
+  return {
+    videoPath, audioPath, videoFd, audioFd,
+    releaseWriters() { if (writers) { writers = false; closeSync(videoFd); closeSync(audioFd); } },
+    releaseHolders() { if (held) { held = false; for (const fd of holders) closeSync(fd); } },
+    unlink() { rmSync(videoPath, { force: true }); rmSync(audioPath, { force: true }); },
+  };
+}
+
+/**
+ * A *blocking* read end for a consumer's stdio (ffmpeg must not get O_NONBLOCK).
+ * A plain O_RDONLY open blocks until a writer exists, so a temporary writer is
+ * opened first (itself made possible by a temporary non-blocking reader).
+ * Call `releaseHolder()` once the real writer has opened the FIFO.
+ */
+export function openBlockingReader(path: string): { fd: number; releaseHolder(): void } {
+  const probe = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+  const holder = openSync(path, constants.O_WRONLY);
+  const fd = openSync(path, constants.O_RDONLY);
+  closeSync(probe);
+  let held = true;
+  return { fd, releaseHolder() { if (held) { held = false; closeSync(holder); } } };
+}
diff --git a/apps/media-worker/src/gate/frame-gate.ts b/apps/media-worker/src/gate/frame-gate.ts
new file mode 100644
index 0000000..603e150
--- /dev/null
+++ b/apps/media-worker/src/gate/frame-gate.ts
@@ -0,0 +1,244 @@
+import { spawnSync } from "node:child_process";
+import { closeSync, constants, mkdirSync, openSync, rmSync } from "node:fs";
+import { Socket } from "node:net";
+import { join, resolve } from "node:path";
+import { mediaEnv, spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+import { resolveHelperBinary } from "./binary";
+import { createFifoPair, openBlockingReader, type FifoPair } from "./fifo";
+import { assertGeometry, attachLine, parseGateEvent, type FrameGeometry, type GateEvent, type GateStats } from "./protocol";
+
+/**
+ * `rust` is the production gate (spike decision). `node` is the
+ * reference implementation of the pipe contract, kept for the spike comparison and the contract
+ * test only: it lacks A/V pair lockstep and origin alignment, and ProgramChain refuses it.
+ */
+export type GateImpl = "rust" | "node";
+
+export interface FrameGateOptions {
+  geometry: FrameGeometry;
+  scratchDir: string;
+  redactor: StderrRedactor;
+  onStderr(message: string): void;
+  /** Unsolicited events (ACTIVE, RETIRED, EOF, STALL...) and gate exit. */
+  onEvent?(event: GateEvent): void;
+  onExit?(reason: string): void;
+  impl?: GateImpl;
+  /** Frames buffered per compositor stream (default 16). */
+  ringFrames?: number;
+  /**
+   * Frames a pending compositor must buffer before going on air with no aligned predecessor
+   * (default 12, 400 ms at 30 fps). This sets the on-air delay margin, which every later swap
+   * preserves: a swap-in compositor can splice forward only while its pipeline latency stays inside
+   * it. 8 frames was not enough for a CPU-starved spawn on an oversubscribed host (s2a-report: alignment).
+   */
+  warmFrames?: number;
+  /** Rust gate: write with plain copies instead of vmsplice (spike comparison only). */
+  copyWrites?: boolean;
+}
+
+export interface GateSlot { id: number; fifos: FifoPair }
+
+/**
+ * The gate's output FIFOs. The reader (the persistent encoder via
+ * `encoderInputs()`, or a test sink via `openReaders()`) opens them before
+ * `start()`, so the gate's write-side open never blocks.
+ */
+export interface EncoderFifos { videoPath: string; audioPath: string }
+
+export function resolveGateCommand(impl: GateImpl): { command: string; args: string[]; cwd?: string } {
+  if (impl === "rust") return { command: resolveHelperBinary("frame-gate"), args: [] };
+  if (__filename.endsWith(".js")) return { command: process.execPath, args: [resolve(__dirname, "node-gate.js")] };
+  return { command: process.execPath, args: ["--import", "tsx", resolve(__dirname, "node-gate.ts")], cwd: resolve(__dirname, "../..") };
+}
+
+interface Waiter { match(event: GateEvent): boolean; resolve(event: GateEvent): void; reject(error: Error): void; timer: ReturnType<typeof setTimeout> }
+
+export class CompositorLagError extends Error {
+  constructor(readonly slotId: number, readonly behind: number) {
+    super(`compositor ${slotId} stayed ${behind} frames behind the on-air source position`);
+    this.name = "CompositorLagError";
+  }
+}
+
+/** Process manager for one channel's frame gate. */
+export class FrameGate {
+  private proc: ManagedProcess | null = null;
+  private nextId = 1;
+  private waiters: Waiter[] = [];
+  private lineBuf = "";
+  private stopping = false;
+  readonly encoderFifos: EncoderFifos;
+  readonly ringFrames: number;
+  readonly warmFrames: number;
+
+  constructor(private readonly options: FrameGateOptions) {
+    assertGeometry(options.geometry);
+    this.ringFrames = options.ringFrames ?? 16;
+    this.warmFrames = options.warmFrames ?? 12;
+    mkdirSync(options.scratchDir, { recursive: true, mode: 0o700 });
+    this.encoderFifos = { videoPath: join(options.scratchDir, "encoder.v.fifo"), audioPath: join(options.scratchDir, "encoder.a.fifo") };
+    for (const path of [this.encoderFifos.videoPath, this.encoderFifos.audioPath]) rmSync(path, { force: true });
+    const made = spawnSync("mkfifo", ["-m", "600", this.encoderFifos.videoPath, this.encoderFifos.audioPath], { shell: false, env: mediaEnv(), stdio: "ignore" });
+    if (made.status !== 0) throw new Error("mkfifo failed");
+  }
+
+  private holders: Array<() => void> = [];
+  private inputFds: number[] = [];
+
+  /**
+   * Blocking read ends for the persistent encoder's stdio (video on fd 0, audio
+   * on fd 3: `-i pipe:0`, `-i pipe:3`). Spawn the encoder, then `start()`; the
+   * worker's copies are closed once the gate is up, so the encoder sees EOF
+   * only if the gate itself dies.
+   */
+  encoderInputs(): { videoFd: number; audioFd: number } {
+    const video = openBlockingReader(this.encoderFifos.videoPath);
+    const audio = openBlockingReader(this.encoderFifos.audioPath);
+    this.holders.push(video.releaseHolder, audio.releaseHolder);
+    this.inputFds.push(video.fd, audio.fd);
+    return { videoFd: video.fd, audioFd: audio.fd };
+  }
+
+  /** Null-encoder side for tests and the spike: non-blocking read ends of the encoder FIFOs. */
+  openReaders(): { video: Socket; audio: Socket } {
+    const open = (path: string) => new Socket({ fd: openSync(path, constants.O_RDONLY | constants.O_NONBLOCK), readable: true, writable: false });
+    return { video: open(this.encoderFifos.videoPath), audio: open(this.encoderFifos.audioPath) };
+  }
+
+  get pid(): number | undefined { return this.proc?.child.pid; }
+
+  async start(): Promise<void> {
+    const { command, args, cwd } = resolveGateCommand(this.options.impl ?? "rust");
+    const g = this.options.geometry;
+    const argv = [...args, String(g.width), String(g.height), String(g.fps), String(this.ringFrames), String(this.warmFrames),
+      this.encoderFifos.videoPath, this.encoderFifos.audioPath, ...(this.options.copyWrites ? ["copy"] : [])];
+    const proc = spawnManaged(command, argv, ["pipe", "pipe", "pipe"], this.options.redactor, this.options.onStderr, cwd);
+    this.proc = proc;
+    proc.child.stdout?.setEncoding("utf8");
+    proc.child.stdout?.on("data", (chunk: string) => this.onData(chunk));
+    // EPIPE on a control line to a gate that just died: its exit is reported below, never as a crash.
+    proc.child.stdin?.on("error", () => undefined);
+    void proc.exited.then(({ code, signal }) => {
+      const reason = `frame gate exited code=${code} signal=${signal}`;
+      for (const w of this.waiters.splice(0)) { clearTimeout(w.timer); w.reject(new Error(reason)); }
+      if (!this.stopping) this.options.onExit?.(reason);
+    });
+    const ready = this.waitFor((e) => e.type === "READY", 10_000);
+    try {
+      await proc.started;
+      await ready;
+    } catch (error) {
+      ready.catch(() => undefined);
+      throw error;
+    } finally {
+      for (const release of this.holders.splice(0)) release();
+      for (const fd of this.inputFds.splice(0)) closeSync(fd);
+    }
+  }
+
+  private onData(chunk: string): void {
+    this.lineBuf += chunk;
+    let nl = this.lineBuf.indexOf("\n");
+    while (nl >= 0) {
+      const event = parseGateEvent(this.lineBuf.slice(0, nl));
+      this.lineBuf = this.lineBuf.slice(nl + 1);
+      nl = this.lineBuf.indexOf("\n");
+      if (!event) continue;
+      const i = this.waiters.findIndex((w) => w.match(event));
+      if (i >= 0) {
+        const [w] = this.waiters.splice(i, 1);
+        if (w) { clearTimeout(w.timer); w.resolve(event); }
+      }
+      this.options.onEvent?.(event);
+    }
+  }
+
+  waitFor(match: (event: GateEvent) => boolean, timeoutMs: number): Promise<GateEvent> {
+    return new Promise<GateEvent>((resolvePromise, reject) => {
+      const waiter: Waiter = {
+        match, resolve: resolvePromise, reject,
+        timer: setTimeout(() => {
+          this.waiters = this.waiters.filter((w) => w !== waiter);
+          reject(new Error("frame gate event timeout"));
+        }, timeoutMs),
+      };
+      this.waiters.push(waiter);
+    });
+  }
+
+  private send(line: string): void {
+    const stdin = this.proc?.child.stdin;
+    if (!stdin || stdin.destroyed) throw new Error("frame gate is not running");
+    stdin.write(line);
+  }
+
+  /** Sends a control line and waits for its reply; a failed send never leaves a waiter behind. */
+  private request(line: string, match: (event: GateEvent) => boolean, timeoutMs: number): Promise<GateEvent> {
+    const reply = this.waitFor(match, timeoutMs);
+    try {
+      this.send(line);
+    } catch (error) {
+      reply.catch(() => undefined);
+      const waiter = this.waiters.at(-1);
+      if (waiter) { clearTimeout(waiter.timer); this.waiters.pop(); }
+      throw error;
+    }
+    return reply;
+  }
+
+  /** FIFOs for the next compositor: spawn it with `fifos.videoFd`/`fifos.audioFd`, then `attach()`. */
+  allocateSlot(): GateSlot {
+    const id = this.nextId;
+    this.nextId += 1;
+    return { id, fifos: createFifoPair(this.options.scratchDir, id) };
+  }
+
+  /** Hands the slot to the gate as the pending compositor; resolves once both FIFOs are open. */
+  async attach(slot: GateSlot, origin?: number): Promise<void> {
+    slot.fifos.releaseWriters();
+    try {
+      const event = await this.request(attachLine(slot.id, slot.fifos.videoPath, slot.fifos.audioPath, origin),
+        (e) => (e.type === "ATTACHED" || e.type === "ERROR") && e.id === slot.id, 5_000);
+      if (event.type === "ERROR") throw new Error("frame gate could not open compositor fifos");
+    } finally {
+      slot.fifos.releaseHolders();
+      slot.fifos.unlink();
+    }
+  }
+
+  /**
+   * Resolves with the tick at which the slot went on air. Rejects with `CompositorLagError` when
+   * the gate reports the slot cannot reach the on-air source position (it never splices backwards).
+   */
+  async waitActive(id: number, timeoutMs: number): Promise<number> {
+    const event = await this.waitFor((e) => (e.type === "ACTIVE" || e.type === "EOF" || e.type === "DROPPED" || e.type === "LAG") && "id" in e && e.id === id, timeoutMs);
+    if (event.type === "LAG") throw new CompositorLagError(id, event.behind);
+    if (event.type !== "ACTIVE") throw new Error(`compositor ${id} ended before going on air`);
+    return event.tick;
+  }
+
+  detach(id: number): void { this.send(`DETACH ${id}\n`); }
+
+  async stats(): Promise<GateStats> {
+    const event = await this.request("STATS\n", (e) => e.type === "STATS", 5_000);
+    if (event.type !== "STATS") throw new Error("unexpected gate reply");
+    return event.stats;
+  }
+
+  /** Zero the peak counters (late/write maxima), e.g. after encoder warm-up. */
+  async resetPeaks(): Promise<void> {
+    await this.request("RESET\n", (e) => e.type === "RESET", 5_000);
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    const proc = this.proc;
+    if (!proc) return;
+    try { this.send("QUIT\n"); } catch { /* already gone */ }
+    const timer = setTimeout(() => proc.kill("SIGKILL"), 2_000);
+    await proc.exited;
+    clearTimeout(timer);
+    this.proc = null;
+    for (const path of [this.encoderFifos.videoPath, this.encoderFifos.audioPath]) rmSync(path, { force: true });
+  }
+}
diff --git a/apps/media-worker/src/gate/gate.test.ts b/apps/media-worker/src/gate/gate.test.ts
new file mode 100644
index 0000000..f7df362
--- /dev/null
+++ b/apps/media-worker/src/gate/gate.test.ts
@@ -0,0 +1,144 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { ensureGateBinary, passthroughRedactor, SinkProcess } from "../compositor/testing";
+import { FrameGate, type GateImpl } from "./frame-gate";
+import { assertGeometry, attachLine, audioFrameBytes, parseGateEvent, videoFrameBytes } from "./protocol";
+import { startProducer } from "./spike";
+import { spawnManaged } from "../relay/ffmpeg";
+
+test("pipe contract: frame sizes, geometry and control-line safety", () => {
+  assert.equal(videoFrameBytes({ width: 1920, height: 1080, fps: 30 }), 3_110_400);
+  assert.equal(audioFrameBytes({ width: 1920, height: 1080, fps: 30 }), 6_400);
+  assert.equal(audioFrameBytes({ width: 1920, height: 1080, fps: 60 }), 3_200);
+  for (const g of [{ width: 1921, height: 1080, fps: 30 }, { width: 1920, height: 1080, fps: 7 }, { width: 0, height: 2, fps: 30 }]) assert.throws(() => assertGeometry(g));
+  assert.equal(attachLine(3, "/tmp/x/gate-3.v.fifo", "/tmp/x/gate-3.a.fifo", 42), "ATTACH 3 /tmp/x/gate-3.v.fifo /tmp/x/gate-3.a.fifo 42\n");
+  for (const bad of ["/tmp/a b", "/tmp/../etc", "relative", "/tmp/x\nQUIT", "/tmp/x;y"]) assert.throws(() => attachLine(1, bad, "/tmp/ok"), bad);
+  assert.throws(() => attachLine(1, "/tmp/a", "/tmp/b", 1.5));
+  assert.deepEqual(parseGateEvent("ACTIVE 4 120"), { type: "ACTIVE", id: 4, tick: 120 });
+  const stats = parseGateEvent("STATS ticks=10 vrep=1 asil=2 active=4:2/2 unknown=9");
+  assert.ok(stats?.type === "STATS" && stats.stats.ticks === 10 && stats.stats.vrep === 1 && stats.stats.active === "4:2/2");
+  assert.equal(parseGateEvent("BOGUS"), null);
+});
+
+/** Same contract, both implementations: boot black, swap producers at frame boundaries, survive a dead producer. */
+for (const impl of ["rust", "node"] as GateImpl[]) {
+  test(`${impl} gate: swaps are frame-continuous and a dead producer never starves the encoder`, { timeout: 120_000 }, async (t) => {
+    if (impl === "rust" && !ensureGateBinary()) { t.skip("frame-gate binary unavailable"); return; }
+    const g = { width: 320, height: 180, fps: 30 };
+    const scratch = mkdtempSync(join(tmpdir(), `gate-${impl}-`));
+    const fatal: string[] = [];
+    const gate = new FrameGate({ geometry: g, scratchDir: scratch, impl, redactor: passthroughRedactor, onStderr: () => undefined, onExit: (r) => fatal.push(r) });
+    const sink = new SinkProcess();
+    await sink.start(gate, g);
+    await gate.start();
+    const producers = [];
+    try {
+      let current = await startProducer(gate, g, 20);
+      producers.push(current.proc);
+      const first = await gate.waitActive(current.id, 10_000);
+      for (let i = 1; i <= 10; i += 1) {
+        const next = await startProducer(gate, g, 20 + i);
+        producers.push(next.proc);
+        await gate.waitActive(next.id, 10_000);
+        void current.proc.terminate();
+        current = next;
+      }
+      const beforeKill = await gate.stats();
+      current.proc.kill("SIGKILL");
+      await new Promise((r) => setTimeout(r, 700));
+      const afterKill = await gate.stats();
+      const report = await sink.report(first);
+      assert.deepEqual(fatal, []);
+      assert.equal(beforeKill.swaps, 11);
+      assert.equal(beforeKill.vrep + beforeKill.asil, 0, "no repeat/silence while producers were live");
+      assert.ok(afterKill.ticks - beforeKill.ticks >= 15, "gate kept ticking after the producer died");
+      assert.ok(Math.abs(report.videoFrames - report.audioFrames) <= 1);
+      // Generation tags 20..30 appear in order, each once (after the boot black frames, tag 16).
+      const tags = report.tagChanges.map(([, tag]) => tag).filter((tag) => tag !== 16);
+      assert.deepEqual(tags, Array.from({ length: 11 }, (_, i) => 20 + i));
+      const bound = Math.ceil(report.maxPcmAbs * Math.sin((2 * Math.PI * 1500) / 48_000)) + 4;
+      assert.ok(report.maxPcmStep <= bound, `PCM step ${report.maxPcmStep} <= ${bound}`);
+    } finally {
+      await sink.stop();
+      await gate.stop();
+      for (const p of producers) await p.terminate(500);
+      rmSync(scratch, { recursive: true, force: true });
+    }
+  });
+}
+
+test("Rust holds an ahead compositor until A reaches its source position instead of skipping frames", { timeout: 60_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const g = { width: 320, height: 180, fps: 30 };
+  const scratch = mkdtempSync(join(tmpdir(), "gate-ahead-"));
+  const gate = new FrameGate({ geometry: g, scratchDir: scratch, redactor: passthroughRedactor, onStderr: () => undefined });
+  const sink = new SinkProcess();
+  const producers = [];
+  try {
+    await sink.start(gate, g);
+    await gate.start();
+    const a = await startProducer(gate, g, 20, 0, true);
+    producers.push(a.proc);
+    const first = await gate.waitActive(a.id, 10_000);
+    const before = await gate.stats();
+    const origin = before.ticks + 2 * g.fps;
+    const b = await startProducer(gate, g, 21, origin, true);
+    producers.push(b.proc);
+    const promoted = await gate.waitActive(b.id, 10_000);
+    // A's source sequence cannot exceed elapsed gate ticks. B must wait until
+    // the output reaches its origin even if it has already filled its rings.
+    assert.ok(promoted >= origin, `B promoted at tick ${promoted} before source position ${origin}`);
+    const stats = await gate.stats();
+    assert.equal(stats.vrep + stats.asil, 0, "A keeps supplying the encoder while B waits");
+    const report = await sink.report(first);
+    assert.deepEqual(report.tagChanges.map(([, tag]) => tag).filter((tag) => tag !== 16), [20, 21]);
+  } finally {
+    await sink.stop();
+    await gate.stop();
+    for (const proc of producers) await proc.terminate(500);
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
+
+test("Rust resumes a producer at native rate after a joint A/V stall", { timeout: 60_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const g = { width: 64, height: 36, fps: 30 };
+  const scratch = mkdtempSync(join(tmpdir(), "gate-resume-"));
+  const gate = new FrameGate({ geometry: g, scratchDir: scratch, redactor: passthroughRedactor, onStderr: () => undefined });
+  const sink = new SinkProcess();
+  let producer: ReturnType<typeof spawnManaged> | null = null;
+  try {
+    await sink.start(gate, g);
+    await gate.start();
+    const slot = gate.allocateSlot();
+    // setInterval deliberately resumes at native rate without replaying paused ticks.
+    producer = spawnManaged(process.execPath, ["-e", `const fs=require('node:fs'); const v=Buffer.alloc(${videoFrameBytes(g)},20),a=Buffer.alloc(${audioFrameBytes(g)}); setInterval(()=>{fs.writeSync(1,v);fs.writeSync(3,a)},33);`],
+      ["ignore", slot.fifos.videoFd, "pipe", slot.fifos.audioFd], passthroughRedactor, () => undefined);
+    slot.fifos.releaseWriters();
+    await producer.started;
+    await gate.attach(slot, 0);
+    const first = await gate.waitActive(slot.id, 10_000);
+    const initial = await gate.stats();
+    producer.kill("SIGSTOP");
+    await new Promise((r) => setTimeout(r, 1_000));
+    const stalled = await gate.stats();
+    assert.ok(stalled.vrep > initial.vrep && stalled.asil > initial.asil, "pause exhausted both warm rings");
+    producer.kill("SIGCONT");
+    await new Promise((r) => setTimeout(r, 2_000));
+    const resumed = await gate.stats();
+    await new Promise((r) => setTimeout(r, 1_000));
+    const steady = await gate.stats();
+    assert.equal(steady.vrep - resumed.vrep, 0, "video recovered instead of discarding every future frame");
+    assert.equal(steady.asil - resumed.asil, 0, "PCM recovered in lockstep");
+    await sink.report(first);
+  } finally {
+    producer?.kill("SIGCONT");
+    await sink.stop();
+    await gate.stop();
+    await producer?.terminate(500);
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
diff --git a/apps/media-worker/src/gate/node-gate.ts b/apps/media-worker/src/gate/node-gate.ts
new file mode 100644
index 0000000..dff44f3
--- /dev/null
+++ b/apps/media-worker/src/gate/node-gate.ts
@@ -0,0 +1,255 @@
+/**
+ * Node reference implementation of the frame gate (same pipe contract as the
+ * Rust helper; see src/gate/protocol.ts). Built for the §1.4 spike: preallocated
+ * frame rings, `net.Socket` `onread` into one reused buffer, refcounted output
+ * buffers so a frame is never mutated while a write is in flight.
+ *
+ * Run as its own process: `node node-gate.js <w> <h> <fps> <ring> <warm> <encVideoFifo> <encAudioFifo>`.
+ */
+import { constants, openSync } from "node:fs";
+import { Socket } from "node:net";
+import { PerformanceObserver } from "node:perf_hooks";
+import { BufferPool } from "./buffers";
+import { assertGeometry, audioFrameBytes, videoFrameBytes } from "./protocol";
+
+const READ_CHUNK = 1 << 20;
+/* Node cannot grow a FIFO past 64 KiB (no F_SETPIPE_SZ), so reads stay event-driven per chunk. */
+
+class Ring {
+  private readonly frames: Buffer[] = [];
+  head = 0;
+  count = 0;
+  fill = 0;
+  constructor(private readonly cap: number, private readonly size: number, private readonly pool: BufferPool) {
+    for (let i = 0; i <= cap; i += 1) this.frames.push(pool.get());
+  }
+  full(): boolean { return this.count >= this.cap; }
+  /** Copies `src` into the ring; returns bytes consumed (stops when full unless dropping). */
+  push(src: Buffer, start: number, end: number, dropWhenFull: boolean): { used: number; dropped: number } {
+    let at = start;
+    let dropped = 0;
+    while (at < end) {
+      if (this.full()) {
+        if (!dropWhenFull) break;
+        this.dropOldest();
+        dropped += 1;
+      }
+      const slot = this.frames[(this.head + this.count) % this.frames.length]!;
+      const n = Math.min(end - at, this.size - this.fill);
+      src.copy(slot, this.fill, at, at + n);
+      at += n;
+      this.fill += n;
+      if (this.fill === this.size) { this.fill = 0; this.count += 1; }
+    }
+    return { used: at - start, dropped };
+  }
+  dropOldest(): void {
+    if (this.count === 0) return;
+    this.head = (this.head + 1) % this.frames.length;
+    this.count -= 1;
+  }
+  /** Hands the oldest frame to the caller and refills the slot from the pool. */
+  take(): Buffer {
+    const frame = this.frames[this.head]!;
+    this.frames[this.head] = this.pool.get();
+    this.head = (this.head + 1) % this.frames.length;
+    this.count -= 1;
+    return frame;
+  }
+  dispose(): void { for (const f of this.frames) this.pool.release(f); }
+}
+
+class InStream {
+  readonly ring: Ring;
+  eof = false;
+  paused = false;
+  private readonly socket: Socket;
+  /** Bytes read past a full active ring, held until the next tick frees a slot. */
+  private carry: { buf: Buffer; start: number } | null = null;
+  constructor(path: string, cap: number, size: number, pool: BufferPool, private readonly gate: { dropping(s: InStream): boolean; drops: number }) {
+    this.ring = new Ring(cap, size, pool);
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const chunk = Buffer.alloc(READ_CHUNK);
+    this.socket = new Socket({
+      fd, readable: true, writable: false,
+      onread: {
+        buffer: chunk,
+        callback: (nread: number, buf: Buffer): boolean => {
+          const r = this.ring.push(buf, 0, nread, this.gate.dropping(this));
+          this.gate.drops += r.dropped;
+          if (r.used < nread) {
+            // Active ring full: keep the remainder in a side copy and apply backpressure.
+            this.carry = { buf: Buffer.from(buf.subarray(r.used, nread)), start: 0 };
+            this.paused = true;
+            return false;
+          }
+          return true;
+        },
+      },
+    });
+    this.socket.on("end", () => { this.eof = true; });
+    this.socket.on("error", () => { this.eof = true; });
+    this.socket.on("close", () => { this.eof = true; });
+  }
+  maybeResume(dropping: boolean): void {
+    if (!this.paused) return;
+    if (this.carry) {
+      const r = this.ring.push(this.carry.buf, this.carry.start, this.carry.buf.length, dropping);
+      this.carry.start += r.used;
+      if (this.carry.start < this.carry.buf.length) return;
+      this.carry = null;
+    }
+    this.paused = false;
+    this.socket.resume();
+  }
+  close(): void {
+    this.socket.destroy();
+    this.ring.dispose();
+  }
+}
+
+interface Slot { id: number; video: InStream; audio: InStream }
+
+function main(): void {
+  const [w, h, f, r, k] = process.argv.slice(2, 7).map(Number);
+  const [encVideoPath, encAudioPath] = process.argv.slice(7, 9);
+  if (encVideoPath === undefined || encAudioPath === undefined) throw new Error("encoder fifo paths required");
+  const geometry = { width: w ?? 0, height: h ?? 0, fps: f ?? 0 };
+  assertGeometry(geometry);
+  const ringFrames = r ?? 0;
+  const warm = k ?? 0;
+  if (!(ringFrames > 0 && warm > 0 && warm <= ringFrames)) throw new Error("ring/warm invalid");
+  const vBytes = videoFrameBytes(geometry);
+  const aBytes = audioFrameBytes(geometry);
+  const vPool = new BufferPool(vBytes, (ringFrames + 1) * 2 + 8);
+  const aPool = new BufferPool(aBytes, (ringFrames + 1) * 2 + 8);
+
+  // Non-blocking open fails fast (ENXIO) unless the encoder already holds the read ends, like the Rust gate.
+  const encVideo = new Socket({ fd: openSync(encVideoPath, constants.O_WRONLY | constants.O_NONBLOCK), readable: false, writable: true });
+  const encAudio = new Socket({ fd: openSync(encAudioPath, constants.O_WRONLY | constants.O_NONBLOCK), readable: false, writable: true });
+  for (const s of [encVideo, encAudio]) s.on("error", () => { process.stderr.write("frame-gate: encoder input closed\n"); process.exit(3); });
+
+  let last = vPool.get();
+  last.fill(16, 0, geometry.width * geometry.height);
+  last.fill(128, geometry.width * geometry.height);
+  const silence = Buffer.alloc(aBytes);
+
+  let active: Slot | null = null;
+  let pending: Slot | null = null;
+  const stats = { ticks: 0, idle: 0, vrep: 0, asil: 0, drops: 0, swaps: 0, lateMaxUs: 0, lateOverFrame: 0, writeMaxUs: 0, stallRun: 0, gcMaxUs: 0, backlogMax: 0, lateOver2ms: 0, lateOver5ms: 0 };
+  const gate = { dropping: (s: InStream) => pending !== null && (s === pending.video || s === pending.audio), get drops() { return stats.drops; }, set drops(v: number) { stats.drops = v; } };
+
+  new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) stats.gcMaxUs = Math.max(stats.gcMaxUs, Math.round(entry.duration * 1000));
+  }).observe({ entryTypes: ["gc"] });
+
+  const emit = (line: string): void => { process.stdout.write(`${line}\n`); };
+  const ended = (s: Slot): boolean => (s.video.eof && s.video.ring.count === 0) || (s.audio.eof && s.audio.ring.count === 0);
+  const closeSlot = (s: Slot): void => { s.video.close(); s.audio.close(); };
+
+  const start = process.hrtime.bigint();
+  const cpuStart = process.cpuUsage();
+  const periodNs = 1_000_000_000n / BigInt(geometry.fps);
+  const dueAt = (n: number): bigint => start + (BigInt(n) * 1_000_000_000n) / BigInt(geometry.fps);
+
+  const tick = (): void => {
+    let now = process.hrtime.bigint();
+    while (now >= dueAt(stats.ticks)) {
+      const late = Number((now - dueAt(stats.ticks)) / 1000n);
+      stats.lateMaxUs = Math.max(stats.lateMaxUs, late);
+      if (BigInt(late) * 1000n > periodNs) stats.lateOverFrame += 1;
+      if (late > 2_000) stats.lateOver2ms += 1;
+      if (late > 5_000) stats.lateOver5ms += 1;
+
+      if (pending && ended(pending)) { emit(`EOF ${pending.id}`); closeSlot(pending); pending = null; }
+      if (pending && pending.video.ring.count >= warm && pending.audio.ring.count >= warm) {
+        const p: Slot = pending;
+        pending = null;
+        while (p.video.ring.count > warm) p.video.ring.dropOldest();
+        while (p.audio.ring.count > warm) p.audio.ring.dropOldest();
+        const old = active;
+        active = p;
+        stats.swaps += 1;
+        stats.stallRun = 0;
+        emit(`ACTIVE ${p.id} ${stats.ticks}`);
+        if (old) { closeSlot(old); emit(`RETIRED ${old.id}`); }
+      }
+
+      let audio: Buffer = silence;
+      let audioOwned = false;
+      if (active) {
+        if (active.video.ring.count > 0) {
+          vPool.release(last);
+          last = active.video.ring.take();
+          stats.stallRun = 0;
+        } else {
+          stats.vrep += 1;
+          stats.stallRun += 1;
+          if (stats.stallRun === geometry.fps) emit(`STALL ${active.id} ${stats.ticks}`);
+        }
+        if (active.audio.ring.count > 0) { audio = active.audio.ring.take(); audioOwned = true; } else stats.asil += 1;
+        active.video.maybeResume(false);
+        active.audio.maybeResume(false);
+        if (ended(active)) { emit(`EOF ${active.id}`); closeSlot(active); active = null; }
+      } else stats.idle += 1;
+
+      const w0 = process.hrtime.bigint();
+      const frame = last;
+      vPool.retain(frame);
+      encAudio.write(audio, () => { if (audioOwned) aPool.release(audio); });
+      encVideo.write(frame, () => vPool.release(frame));
+      stats.writeMaxUs = Math.max(stats.writeMaxUs, Number((process.hrtime.bigint() - w0) / 1000n));
+      stats.backlogMax = Math.max(stats.backlogMax, encVideo.writableLength);
+      stats.ticks += 1;
+      now = process.hrtime.bigint();
+    }
+    const waitMs = Number((dueAt(stats.ticks) - process.hrtime.bigint()) / 1_000_000n);
+    setTimeout(tick, Math.max(0, waitMs));
+  };
+
+  let lineBuf = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("end", () => process.exit(0));
+  process.stdin.on("data", (chunk: string) => {
+    lineBuf += chunk;
+    let nl = lineBuf.indexOf("\n");
+    while (nl >= 0) {
+      const parts = lineBuf.slice(0, nl).trim().split(/\s+/);
+      lineBuf = lineBuf.slice(nl + 1);
+      nl = lineBuf.indexOf("\n");
+      const [cmd, a, b, c] = parts;
+      if (cmd === "ATTACH" && a !== undefined && b !== undefined && c !== undefined) {
+        const id = Number(a);
+        try {
+          const slot: Slot = { id, video: new InStream(b, ringFrames, vBytes, vPool, gate), audio: new InStream(c, ringFrames, aBytes, aPool, gate) };
+          if (pending) { closeSlot(pending); emit(`DROPPED ${pending.id}`); }
+          pending = slot;
+          emit(`ATTACHED ${id}`);
+        } catch { emit(`ERROR ${id} open`); }
+      } else if (cmd === "DETACH" && a !== undefined) {
+        const id = Number(a);
+        if (pending?.id === id) { closeSlot(pending); pending = null; emit(`DETACHED ${id}`); }
+        else if (active?.id === id) { closeSlot(active); active = null; emit(`DETACHED ${id}`); }
+      } else if (cmd === "STATS") {
+        const cpu = process.cpuUsage(cpuStart);
+        const ring = (s: Slot | null): string => (s ? `${s.id}:${s.video.ring.count}/${s.audio.ring.count}` : "-");
+        emit(`STATS ticks=${stats.ticks} idle=${stats.idle} vrep=${stats.vrep} asil=${stats.asil} drops=${stats.drops} swaps=${stats.swaps} late_max_us=${stats.lateMaxUs} late_over_frame=${stats.lateOverFrame} write_max_us=${stats.writeMaxUs} cpu_us=${cpu.user + cpu.system} wall_us=${Number((process.hrtime.bigint() - start) / 1000n)} active=${ring(active)} pending=${ring(pending)} gc_max_us=${stats.gcMaxUs} allocs=${vPool.allocs + aPool.allocs} backlog_max=${stats.backlogMax} late_over_2ms=${stats.lateOver2ms} late_over_5ms=${stats.lateOver5ms}`);
+      } else if (cmd === "RESET") {
+        stats.lateMaxUs = 0; stats.lateOverFrame = 0; stats.writeMaxUs = 0; stats.gcMaxUs = 0; stats.backlogMax = 0; stats.lateOver2ms = 0; stats.lateOver5ms = 0;
+        emit("RESET");
+      } else if (cmd === "QUIT") process.exit(0);
+      else if (cmd !== "" && cmd !== undefined) emit("ERROR 0 command");
+    }
+  });
+
+  emit(`READY ${vBytes} ${aBytes} ${ringFrames} ${warm}`);
+  tick();
+}
+
+if (require.main === module) {
+  try { main(); } catch (error: unknown) {
+    process.stderr.write(`frame-gate: ${error instanceof Error ? error.message : "startup failed"}\n`);
+    process.exit(2);
+  }
+}
+
diff --git a/apps/media-worker/src/gate/protocol.ts b/apps/media-worker/src/gate/protocol.ts
new file mode 100644
index 0000000..7ec417a
--- /dev/null
+++ b/apps/media-worker/src/gate/protocol.ts
@@ -0,0 +1,111 @@
+/**
+ * Frame-gate pipe contract (docs/design/streaming-architecture.md §1.4).
+ *
+ * Two implementations speak it: the Rust helper (src/gate/rust, the production
+ * choice, see runs/wp4/s2a-report.md) and the Node reference gate
+ * (src/gate/node-gate.ts, kept for spike/contract comparison only; ProgramChain refuses it).
+ *
+ * argv  <width> <height> <fps> <ringFrames> <warmFrames> <encoderVideoFifo> <encoderAudioFifo> [copy]
+ * fd 0  control lines:  ATTACH <id> <videoFifo> <audioFifo> [origin] | DETACH <id> | STATS | RESET (peak counters) | QUIT
+ * fd 1  event lines:    READY <videoBytes> <audioBytes> <ring> <warm> | ATTACHED <id>
+ *                       | ACTIVE <id> <tick> [<depthA> <behind> <have> <age>]  (Rust: A's buffered depth, B's backward step, B's depth, ticks B warmed)
+ *                       | RETIRED <id> | DROPPED <id> | DETACHED <id> | EOF <id> | STALL <id> <tick>
+ *                       | STATS k=v... | ERROR <id> <what>
+ *                       | LAG <id> <behind>  (Rust: pending slot still behind A's on-air source position after 3 s;
+ *                         the gate never splices backwards, the worker replaces the compositor)
+ *                       | GAP <v|a> <id> <tick> <ticksSinceActive> <lateUs>  (diagnostic: a repeat/silence fill, first 200)
+ * encoder FIFOs (opened for writing by path; the open is the rendezvous with the encoder):
+ *       video = rawvideo yuv420p, fixed frame size; audio = s16le 48 kHz stereo, fixed bytes per frame
+ * compositor FIFOs (ATTACH): same formats, read non-blocking into frame rings. Video frame i and audio
+ *       frame i of one compositor are one source pair: the Rust gate drops and skips both streams in lockstep.
+ *
+ * Exactly one video frame and one audio frame are written per tick.
+ */
+
+export const GATE_SAMPLE_RATE = 48_000;
+export const GATE_CHANNELS = 2;
+const BYTES_PER_SAMPLE = 2 * GATE_CHANNELS;
+
+export interface FrameGeometry { width: number; height: number; fps: number }
+
+export function videoFrameBytes(g: FrameGeometry): number { return (g.width * g.height * 3) / 2; }
+
+export function audioFrameBytes(g: FrameGeometry): number { return (GATE_SAMPLE_RATE / g.fps) * BYTES_PER_SAMPLE; }
+
+export function assertGeometry(g: FrameGeometry): void {
+  if (!Number.isSafeInteger(g.width) || !Number.isSafeInteger(g.height) || g.width < 2 || g.height < 2 || g.width % 2 !== 0 || g.height % 2 !== 0 || g.width > 7680 || g.height > 4320) {
+    throw new Error("frame geometry must be even and at most 7680x4320");
+  }
+  if (!Number.isSafeInteger(g.fps) || g.fps < 1 || g.fps > 120 || GATE_SAMPLE_RATE % g.fps !== 0) throw new Error("fps must divide 48000");
+}
+
+export interface GateStats {
+  ticks: number; idle: number; vrep: number; asil: number; drops: number; swaps: number;
+  lateMaxUs: number; lateOverFrame: number; writeMaxUs: number; cpuUs: number; wallUs: number;
+  active: string; pending: string;
+  /** Node gate only: longest GC pause, pool allocations after warm-up, peak encoder write backlog. */
+  gcMaxUs: number; allocs: number; backlogMax: number;
+  /** Frames dropped because the encoder stopped reading (backlog > 2 s). */
+  outDrops: number;
+  lateOver2ms: number; lateOver5ms: number;
+  /** Pending compositors reported `LAG` (still behind A's on-air source position after 3 s), and the largest gap seen. */
+  lagged: number; behindMax: number;
+}
+
+export type GateEvent =
+  | { type: "READY"; videoBytes: number; audioBytes: number }
+  | { type: "RESET" }
+  | { type: "GAP"; stream: "v" | "a"; id: number; tick: number; sinceActive: number; lateUs: number }
+  | { type: "ATTACHED" | "RETIRED" | "DROPPED" | "DETACHED" | "EOF"; id: number }
+  | { type: "ACTIVE" | "STALL"; id: number; tick: number }
+  | { type: "LAG"; id: number; behind: number }
+  | { type: "STATS"; stats: GateStats }
+  | { type: "ERROR"; id: number; what: string };
+
+const STAT_KEYS: Record<string, keyof GateStats> = {
+  ticks: "ticks", idle: "idle", vrep: "vrep", asil: "asil", drops: "drops", swaps: "swaps",
+  late_max_us: "lateMaxUs", late_over_frame: "lateOverFrame", write_max_us: "writeMaxUs",
+  cpu_us: "cpuUs", wall_us: "wallUs", active: "active", pending: "pending",
+  gc_max_us: "gcMaxUs", allocs: "allocs", backlog_max: "backlogMax", out_drops: "outDrops", late_over_2ms: "lateOver2ms", late_over_5ms: "lateOver5ms", lagged: "lagged", behind_max: "behindMax",
+};
+
+export function parseGateEvent(line: string): GateEvent | null {
+  const [type, ...rest] = line.trim().split(/\s+/);
+  const n = (i: number): number => Number(rest[i]);
+  switch (type) {
+    case "READY": return { type, videoBytes: n(0), audioBytes: n(1) };
+    case "RESET": return { type };
+    case "GAP": return { type, stream: rest[0] === "a" ? "a" : "v", id: n(1), tick: n(2), sinceActive: n(3), lateUs: n(4) };
+    case "ATTACHED": case "RETIRED": case "DROPPED": case "DETACHED": case "EOF": return { type, id: n(0) };
+    case "ACTIVE": case "STALL": return { type, id: n(0), tick: n(1) };
+    case "LAG": return { type, id: n(0), behind: n(1) };
+    case "ERROR": return { type, id: n(0), what: rest[1] ?? "" };
+    case "STATS": {
+      const stats: GateStats = { ticks: 0, idle: 0, vrep: 0, asil: 0, drops: 0, swaps: 0, lateMaxUs: 0, lateOverFrame: 0, writeMaxUs: 0, cpuUs: 0, wallUs: 0, active: "-", pending: "-", gcMaxUs: 0, allocs: 0, backlogMax: 0, outDrops: 0, lateOver2ms: 0, lateOver5ms: 0, lagged: 0, behindMax: 0 };
+      for (const pair of rest) {
+        const [k, v] = pair.split("=");
+        const key = k === undefined ? undefined : STAT_KEYS[k];
+        if (key === undefined || v === undefined) continue;
+        if (key === "active" || key === "pending") stats[key] = v;
+        else stats[key] = Number(v);
+      }
+      return { type, stats };
+    }
+    default: return null;
+  }
+}
+
+/** FIFO paths are generated by the worker (scratch dir + numeric id); nothing else may reach a control line. */
+const SAFE_PATH = /^\/[A-Za-z0-9._/-]+$/;
+
+/**
+ * `origin`: source frame index of the compositor's first output frame, in a
+ * numbering shared by consecutive compositors of one chain. The Rust gate uses
+ * it to splice B in at A's next source frame (no backwards step or forward skip at a swap).
+ */
+export function attachLine(id: number, videoFifo: string, audioFifo: string, origin?: number): string {
+  if (!Number.isSafeInteger(id) || id < 0 || id > 0xffffffff) throw new Error("gate slot id out of range");
+  for (const path of [videoFifo, audioFifo]) if (!SAFE_PATH.test(path) || path.includes("..")) throw new Error("unsafe gate fifo path");
+  if (origin !== undefined && !Number.isSafeInteger(origin)) throw new Error("gate origin must be an integer");
+  return `ATTACH ${id} ${videoFifo} ${audioFifo}${origin === undefined ? "" : ` ${origin}`}\n`;
+}
diff --git a/apps/media-worker/src/gate/rust/.gitignore b/apps/media-worker/src/gate/rust/.gitignore
new file mode 100644
index 0000000..2f7896d
--- /dev/null
+++ b/apps/media-worker/src/gate/rust/.gitignore
@@ -0,0 +1 @@
+target/
diff --git a/apps/media-worker/src/gate/rust/Cargo.lock b/apps/media-worker/src/gate/rust/Cargo.lock
new file mode 100644
index 0000000..d473dd7
--- /dev/null
+++ b/apps/media-worker/src/gate/rust/Cargo.lock
@@ -0,0 +1,7 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "frame-gate"
+version = "0.1.0"
diff --git a/apps/media-worker/src/gate/rust/Cargo.toml b/apps/media-worker/src/gate/rust/Cargo.toml
new file mode 100644
index 0000000..88c0a9a
--- /dev/null
+++ b/apps/media-worker/src/gate/rust/Cargo.toml
@@ -0,0 +1,15 @@
+[package]
+name = "frame-gate"
+version = "0.1.0"
+edition = "2021"
+description = "Clock-master frame gate between swappable compositors and a persistent encoder (streaming-architecture.md §1.4)"
+publish = false
+
+# std only: no crates, so the build works offline and the binary has no supply chain.
+[dependencies]
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1
+panic = "abort"
diff --git a/apps/media-worker/src/gate/rust/src/bin/source-bus.rs b/apps/media-worker/src/gate/rust/src/bin/source-bus.rs
new file mode 100644
index 0000000..03fb282
--- /dev/null
+++ b/apps/media-worker/src/gate/rust/src/bin/source-bus.rs
@@ -0,0 +1,503 @@
+//! Source bus (docs/design/streaming-architecture.md §1.4; runs/wp4/s2b-report.md item 1).
+//!
+//! One process per source, between the source's ingest and every consumer of
+//! its raw frames: the A/B compositors of a swap and the preview taps. The
+//! Node worker used to move these frames itself (S2a); at 4 × 1080p30 that is
+//! ~750 MB/s through 64 KiB chunks on one event loop, with no headroom left to
+//! absorb a burst, and the buses dropped ~7.5 % of source pairs. This helper
+//! moves the bytes; the worker keeps only the control lines.
+//!
+//! Semantics are those of the S2a Node bus (src/compositor/source-bus.ts):
+//!
+//! * raw yuv420p and s16le are re-framed into fixed-size frames and delivered
+//!   as *pairs* (video n + audio n), so a subscriber that joins mid-stream
+//!   starts at a frame boundary with A/V aligned;
+//! * a source without audio (or whose audio stalls) gets silence once video
+//!   runs `maxSkew` frames ahead; audio that runs ahead of video is trimmed;
+//! * a subscriber more than `maxBacklog + history` frames behind loses whole
+//!   pairs, never partial frames (a young subscriber, still starting up, may
+//!   queue one more second of frames for its first two seconds);
+//! * the last `history` pairs are replayed to a new subscriber, and its first
+//!   pair's index is reported, so the gate can splice a swap-in compositor at
+//!   exactly the on-air compositor's next source frame.
+//!
+//! A subscriber may take every `stride`-th pair only (JPEG thumbnails), and may
+//! take video or audio only (`-`).
+//!
+//! fds: 0 control lines, 1 event lines, 2 diagnostics. std only.
+//! argv: <width> <height> <fps> <maxSkew> <maxBacklog> <history> <ingestVideoFifo> <ingestAudioFifo>
+//!
+//! control: SUB <id> <videoFifo|-> <audioFifo|-> [stride] | UNSUB <id> | STATS | QUIT
+//! events:  READY <videoBytes> <audioBytes>
+//!          | SUBSCRIBED <id> <startPair> <otherId>:<dropped>,...|-   (pairs the other subscribers had
+//!            dropped at the same instant: the worker's origin arithmetic needs both together)
+//!          | UNSUBSCRIBED <id> | CLOSED <id> (the reader went away) | DROP <id> <total>
+//!          | EOF (the ingest closed both streams) | STATS k=v... | ERROR <id> <what>
+
+use std::collections::VecDeque;
+use std::fs::{File, OpenOptions};
+use std::io::{self, ErrorKind, Read, Write};
+use std::os::unix::fs::OpenOptionsExt;
+use std::os::unix::io::{AsRawFd, FromRawFd};
+use std::rc::Rc;
+use std::time::{Duration, Instant};
+
+#[repr(C)]
+struct PollFd {
+    fd: i32,
+    events: i16,
+    revents: i16,
+}
+
+extern "C" {
+    fn poll(fds: *mut PollFd, nfds: u64, timeout: i32) -> i32;
+    fn fcntl(fd: i32, cmd: i32, ...) -> i32;
+}
+
+const POLLIN: i16 = 0x1;
+const POLLOUT: i16 = 0x4;
+const O_NONBLOCK: i32 = 0o4000;
+const F_GETFL: i32 = 3;
+const F_SETFL: i32 = 4;
+const F_SETPIPE_SZ: i32 = 1031;
+const F_GETPIPE_SZ: i32 = 1032;
+const PIPE_BYTES: i32 = 1 << 20;
+const SAMPLE_RATE: usize = 48_000;
+const AUDIO_BYTES_PER_SAMPLE: usize = 4; // s16le stereo
+const MAX_READS_PER_PUMP: usize = 64;
+/// Pipes are serviced in bulk at most this often (as in the gate): waking per
+/// 32 KiB chunk costs far more than moving 1 MiB per wake. 1 MiB / 2 ms =
+/// 500 MB/s per pipe, above 1080p60 raw (186 MB/s).
+const PUMP_INTERVAL: Duration = Duration::from_micros(2_000);
+const YOUNG: Duration = Duration::from_secs(2);
+
+type Frame = Rc<Vec<u8>>;
+
+fn set_nonblocking(fd: i32) {
+    unsafe {
+        let flags = fcntl(fd, F_GETFL);
+        if flags >= 0 {
+            fcntl(fd, F_SETFL, flags | O_NONBLOCK);
+        }
+    }
+}
+
+fn emit(line: &str) {
+    let mut out = io::stdout().lock();
+    let _ = out.write_all(line.as_bytes());
+    let _ = out.write_all(b"\n");
+    let _ = out.flush();
+}
+
+fn arg(args: &[String], i: usize, name: &str, min: usize) -> usize {
+    match args.get(i).and_then(|v| v.parse::<usize>().ok()) {
+        Some(v) if v >= min => v,
+        _ => {
+            eprintln!("source-bus: invalid {}", name);
+            std::process::exit(2);
+        }
+    }
+}
+
+/// Recycled frame buffers: a frame returns here when its last reference
+/// (history, a subscriber queue) lets go, so steady state never allocates.
+struct Pool {
+    free: Vec<Vec<u8>>,
+    size: usize,
+    keep: usize,
+    allocs: u64,
+}
+
+impl Pool {
+    fn get(&mut self) -> Vec<u8> {
+        match self.free.pop() {
+            Some(b) => b,
+            None => {
+                self.allocs += 1;
+                vec![0u8; self.size]
+            }
+        }
+    }
+    fn put(&mut self, frame: Frame) {
+        if let Ok(buf) = Rc::try_unwrap(frame) {
+            if self.free.len() < self.keep {
+                self.free.push(buf);
+            }
+        }
+    }
+}
+
+/// One ingest stream, re-framed into fixed-size frames.
+struct Input {
+    file: File,
+    pipe_bytes: usize,
+    cur: Vec<u8>,
+    fill: usize,
+    eof: bool,
+}
+
+impl Input {
+    fn open(path: &str, pool: &mut Pool) -> Input {
+        match OpenOptions::new().read(true).custom_flags(O_NONBLOCK).open(path) {
+            Ok(file) => {
+                unsafe { fcntl(file.as_raw_fd(), F_SETPIPE_SZ, PIPE_BYTES) };
+                let pipe_bytes = unsafe { fcntl(file.as_raw_fd(), F_GETPIPE_SZ) }.max(0) as usize;
+                Input { file, pipe_bytes, cur: pool.get(), fill: 0, eof: false }
+            }
+            Err(_) => {
+                eprintln!("source-bus: cannot open ingest fifo");
+                std::process::exit(2);
+            }
+        }
+    }
+
+    /// Reads what the pipe holds; complete frames go to `out`.
+    fn pump(&mut self, pool: &mut Pool, out: &mut VecDeque<Frame>) {
+        for _ in 0..MAX_READS_PER_PUMP {
+            if self.eof {
+                break;
+            }
+            let fill = self.fill;
+            match self.file.read(&mut self.cur[fill..]) {
+                Ok(0) => self.eof = true,
+                Ok(n) => {
+                    self.fill += n;
+                    if self.fill == pool.size {
+                        let next = pool.get();
+                        out.push_back(Rc::new(std::mem::replace(&mut self.cur, next)));
+                        self.fill = 0;
+                    }
+                }
+                Err(e) if e.kind() == ErrorKind::WouldBlock => break,
+                Err(e) if e.kind() == ErrorKind::Interrupted => continue,
+                Err(_) => self.eof = true,
+            }
+        }
+    }
+}
+
+/// One consumer stream: queued frame references, written non-blocking in order.
+struct Out {
+    file: File,
+    pipe_bytes: usize,
+    queue: VecDeque<(Frame, usize)>,
+}
+
+impl Out {
+    fn open(path: &str) -> io::Result<Out> {
+        let file = OpenOptions::new().write(true).custom_flags(O_NONBLOCK).open(path)?;
+        unsafe { fcntl(file.as_raw_fd(), F_SETPIPE_SZ, PIPE_BYTES) };
+        let pipe_bytes = unsafe { fcntl(file.as_raw_fd(), F_GETPIPE_SZ) }.max(0) as usize;
+        Ok(Out { file, pipe_bytes, queue: VecDeque::new() })
+    }
+
+    /// false = the reader is gone.
+    fn flush(&mut self, pool: &mut Pool) -> bool {
+        while let Some((frame, off)) = self.queue.front_mut() {
+            match self.file.write(&frame[*off..]) {
+                Ok(n) => {
+                    *off += n;
+                    if *off == frame.len() {
+                        let (frame, _) = self.queue.pop_front().unwrap();
+                        pool.put(frame);
+                    }
+                }
+                Err(e) if e.kind() == ErrorKind::WouldBlock => return true,
+                Err(e) if e.kind() == ErrorKind::Interrupted => continue,
+                Err(_) => return false,
+            }
+        }
+        true
+    }
+
+    fn dispose(self, pool: &mut Pool) {
+        for (frame, _) in self.queue {
+            pool.put(frame);
+        }
+    }
+}
+
+struct Subscriber {
+    id: u32,
+    video: Option<Out>,
+    audio: Option<Out>,
+    stride: u64,
+    start_pair: u64,
+    young_until: Instant,
+    dropped: u64,
+}
+
+impl Subscriber {
+    fn queued(&self) -> usize {
+        let v = self.video.as_ref().map_or(0, |o| o.queue.len());
+        let a = self.audio.as_ref().map_or(0, |o| o.queue.len());
+        v.max(a)
+    }
+}
+
+struct Bus {
+    vpool: Pool,
+    apool: Pool,
+    vq: VecDeque<Frame>,
+    aq: VecDeque<Frame>,
+    silence: Frame,
+    history: VecDeque<(Frame, Option<Frame>)>,
+    subs: Vec<Subscriber>,
+    max_skew: usize,
+    limit: usize,
+    young_limit: usize,
+    history_frames: usize,
+    pairs: u64,
+    silence_filled: u64,
+    audio_trimmed: u64,
+    subscriber_drops: u64,
+}
+
+impl Bus {
+    /// Pairs first, then applies the skew rules to what is left over. A pump reads many frames of
+    /// each stream at once, so trimming before pairing would discard audio its video is about to
+    /// claim (the S2a Node bus drained after every single frame, where the order did not matter).
+    fn drain(&mut self) {
+        while !self.vq.is_empty() && !self.aq.is_empty() {
+            let video = self.vq.pop_front().unwrap();
+            let audio = self.aq.pop_front();
+            self.deliver(video, audio);
+        }
+        // Audio more than `max_skew` frames ahead of video: trim the oldest.
+        while self.aq.len() > self.max_skew {
+            let f = self.aq.pop_front().unwrap();
+            self.apool.put(f);
+            self.audio_trimmed += 1;
+        }
+        // Video more than `max_skew` frames ahead of audio (none, or stalled): pair with silence.
+        while self.vq.len() > self.max_skew {
+            let video = self.vq.pop_front().unwrap();
+            self.silence_filled += 1;
+            self.deliver(video, None);
+        }
+    }
+
+    fn deliver(&mut self, video: Frame, audio: Option<Frame>) {
+        let index = self.pairs;
+        self.pairs += 1;
+        let now = Instant::now();
+        for i in 0..self.subs.len() {
+            if (index - self.subs[i].start_pair) % self.subs[i].stride != 0 {
+                continue;
+            }
+            let sub = &mut self.subs[i];
+            let limit = if now < sub.young_until { self.young_limit } else { self.limit };
+            if sub.queued() > limit {
+                sub.dropped += 1;
+                self.subscriber_drops += 1;
+                emit(&format!("DROP {} {}", sub.id, sub.dropped));
+                continue;
+            }
+            Self::enqueue(&mut self.subs[i], &video, audio.as_ref(), &self.silence);
+        }
+        self.history.push_back((video, audio));
+        while self.history.len() > self.history_frames {
+            let (v, a) = self.history.pop_front().unwrap();
+            self.vpool.put(v);
+            if let Some(a) = a {
+                self.apool.put(a);
+            }
+        }
+    }
+
+    fn enqueue(sub: &mut Subscriber, video: &Frame, audio: Option<&Frame>, silence: &Frame) {
+        if let Some(v) = sub.video.as_mut() {
+            v.queue.push_back((Rc::clone(video), 0));
+        }
+        if let Some(a) = sub.audio.as_mut() {
+            a.queue.push_back((Rc::clone(audio.unwrap_or(silence)), 0));
+        }
+    }
+
+    /// Replays the history (a strided subscriber gets only the newest pair) and reports where it starts.
+    fn subscribe(&mut self, id: u32, video: Option<Out>, audio: Option<Out>, stride: u64) -> u64 {
+        let replay = if stride > 1 { self.history.len().min(1) } else { self.history.len() };
+        let start_pair = self.pairs - replay as u64;
+        let mut sub = Subscriber { id, video, audio, stride, start_pair, young_until: Instant::now() + YOUNG, dropped: 0 };
+        for (v, a) in self.history.iter().skip(self.history.len() - replay) {
+            Self::enqueue(&mut sub, v, a.as_ref(), &self.silence);
+        }
+        self.subs.push(sub);
+        start_pair
+    }
+
+    fn remove(&mut self, id: u32) -> bool {
+        match self.subs.iter().position(|s| s.id == id) {
+            Some(i) => {
+                let sub = self.subs.swap_remove(i);
+                if let Some(v) = sub.video {
+                    v.dispose(&mut self.vpool);
+                }
+                if let Some(a) = sub.audio {
+                    a.dispose(&mut self.apool);
+                }
+                true
+            }
+            None => false,
+        }
+    }
+
+    fn flush(&mut self) {
+        let mut gone: Vec<u32> = Vec::new();
+        for sub in self.subs.iter_mut() {
+            let v_ok = sub.video.as_mut().map_or(true, |o| o.flush(&mut self.vpool));
+            let a_ok = sub.audio.as_mut().map_or(true, |o| o.flush(&mut self.apool));
+            if !v_ok || !a_ok {
+                gone.push(sub.id);
+            }
+        }
+        for id in gone {
+            self.remove(id);
+            emit(&format!("CLOSED {}", id));
+        }
+    }
+}
+
+fn open_out(path: &str) -> Result<Option<Out>, ()> {
+    if path == "-" {
+        return Ok(None);
+    }
+    if !path.starts_with('/') || path.contains("..") {
+        return Err(());
+    }
+    Out::open(path).map(Some).map_err(|_| ())
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let width = arg(&args, 1, "width", 2);
+    let height = arg(&args, 2, "height", 2);
+    let fps = arg(&args, 3, "fps", 1);
+    let max_skew = arg(&args, 4, "maxSkew", 1);
+    let max_backlog = arg(&args, 5, "maxBacklog", 1);
+    let history = arg(&args, 6, "history", 0);
+    if width % 2 != 0 || height % 2 != 0 || SAMPLE_RATE % fps != 0 {
+        eprintln!("source-bus: geometry must be even and fps must divide 48000");
+        std::process::exit(2);
+    }
+    let video_bytes = width * height * 3 / 2;
+    let audio_bytes = SAMPLE_RATE / fps * AUDIO_BYTES_PER_SAMPLE;
+    let mut vpool = Pool { free: Vec::new(), size: video_bytes, keep: 0, allocs: 0 };
+    let mut apool = Pool { free: Vec::new(), size: audio_bytes, keep: 0, allocs: 0 };
+    let mut vin = Input::open(args.get(7).map(String::as_str).unwrap_or(""), &mut vpool);
+    let mut ain = Input::open(args.get(8).map(String::as_str).unwrap_or(""), &mut apool);
+    let limit = max_backlog + history;
+    // A young subscriber (process still starting) may queue one more second. Frames are shared
+    // references, so this costs memory only while that subscriber is actually stalled:
+    // at most (limit + fps) frames, 143 MB at 1080p30.
+    let young_limit = limit + fps;
+    // Recycled buffers for history + one backlog; anything beyond is freed when released.
+    vpool.keep = history + limit + 8;
+    apool.keep = 4 * (history + limit + 8) + 4 * fps;
+    let silence: Frame = Rc::new(vec![0u8; audio_bytes]);
+    let mut bus = Bus {
+        vpool, apool, vq: VecDeque::new(), aq: VecDeque::new(), silence, history: VecDeque::new(), subs: Vec::new(),
+        max_skew, limit, young_limit, history_frames: history, pairs: 0, silence_filled: 0, audio_trimmed: 0, subscriber_drops: 0,
+    };
+
+    set_nonblocking(0);
+    let mut control = unsafe { File::from_raw_fd(0) };
+    let mut line_buf: Vec<u8> = Vec::with_capacity(4096);
+    let mut read_buf = [0u8; 4096];
+    let mut last_pump = Instant::now() - PUMP_INTERVAL;
+    let mut eof_sent = false;
+    emit(&format!("READY {} {}", video_bytes, audio_bytes));
+
+    loop {
+        let now = Instant::now();
+        // A shared uid may exceed pipe-user-pages-soft: F_SETPIPE_SZ then fails and new
+        // pipes hold only 8 KiB. Batching those for 2 ms caps raw transport at ~4 MB/s.
+        // Batch only when every video pipe has two pump intervals of headroom.
+        let bulk_min = video_bytes * fps / 250;
+        let bulk = vin.pipe_bytes >= bulk_min && bus.subs.iter().all(|s| s.video.as_ref().map_or(true, |v| v.pipe_bytes >= bulk_min));
+        let pump_due = last_pump + if bulk { PUMP_INTERVAL } else { Duration::ZERO };
+        let mut fds: Vec<PollFd> = Vec::with_capacity(3 + 2 * bus.subs.len());
+        fds.push(PollFd { fd: 0, events: POLLIN, revents: 0 });
+        let timeout_ms = if now >= pump_due {
+            fds.push(PollFd { fd: if vin.eof { -1 } else { vin.file.as_raw_fd() }, events: POLLIN, revents: 0 });
+            fds.push(PollFd { fd: if ain.eof { -1 } else { ain.file.as_raw_fd() }, events: POLLIN, revents: 0 });
+            for sub in &bus.subs {
+                for out in [sub.video.as_ref(), sub.audio.as_ref()].into_iter().flatten() {
+                    fds.push(PollFd { fd: if out.queue.is_empty() { -1 } else { out.file.as_raw_fd() }, events: POLLOUT, revents: 0 });
+                }
+            }
+            1000
+        } else {
+            (pump_due.saturating_duration_since(now).as_micros() as i32 + 999) / 1000
+        };
+        unsafe { poll(fds.as_mut_ptr(), fds.len() as u64, timeout_ms) };
+
+        if fds.len() > 1 && fds[1..].iter().any(|f| f.revents != 0) {
+            last_pump = Instant::now();
+            vin.pump(&mut bus.vpool, &mut bus.vq);
+            ain.pump(&mut bus.apool, &mut bus.aq);
+            bus.drain();
+            bus.flush();
+            if vin.eof && ain.eof && !eof_sent {
+                eof_sent = true;
+                emit("EOF");
+            }
+        }
+
+        if fds[0].revents != 0 {
+            loop {
+                match control.read(&mut read_buf) {
+                    Ok(0) => std::process::exit(0), // parent gone
+                    Ok(n) => line_buf.extend_from_slice(&read_buf[..n]),
+                    Err(e) if e.kind() == ErrorKind::WouldBlock => break,
+                    Err(e) if e.kind() == ErrorKind::Interrupted => continue,
+                    Err(_) => std::process::exit(0),
+                }
+            }
+            while let Some(pos) = line_buf.iter().position(|&b| b == b'\n') {
+                let line: Vec<u8> = line_buf.drain(..=pos).collect();
+                let text = String::from_utf8_lossy(&line[..line.len() - 1]).into_owned();
+                let parts: Vec<&str> = text.split_whitespace().collect();
+                match parts.as_slice() {
+                    ["SUB", id, vpath, apath, rest @ ..] if rest.len() <= 1 => {
+                        let stride = rest.first().map_or(Some(1), |s| s.parse::<u64>().ok().filter(|&s| s >= 1));
+                        match (id.parse::<u32>(), stride) {
+                            (Ok(id), Some(stride)) if !bus.subs.iter().any(|s| s.id == id) && (*vpath != "-" || *apath != "-") => {
+                                match (open_out(vpath), open_out(apath)) {
+                                    (Ok(video), Ok(audio)) => {
+                                        let others: Vec<String> = bus.subs.iter().map(|s| format!("{}:{}", s.id, s.dropped)).collect();
+                                        let start = bus.subscribe(id, video, audio, stride);
+                                        let others = if others.is_empty() { "-".to_string() } else { others.join(",") };
+                                        emit(&format!("SUBSCRIBED {} {} {}", id, start, others));
+                                        bus.flush();
+                                    }
+                                    _ => emit(&format!("ERROR {} open", id)),
+                                }
+                            }
+                            (Ok(id), _) => emit(&format!("ERROR {} subscribe", id)),
+                            _ => emit("ERROR 0 id"),
+                        }
+                    }
+                    ["UNSUB", id] => {
+                        let id = id.parse::<u32>().unwrap_or(u32::MAX);
+                        if bus.remove(id) {
+                            emit(&format!("UNSUBSCRIBED {}", id));
+                        }
+                    }
+                    ["STATS"] => {
+                        let subs: Vec<String> = bus.subs.iter().map(|s| format!("{}:{}:{}", s.id, s.dropped, s.queued())).collect();
+                        emit(&format!(
+                            "STATS pairs={} silence_filled={} audio_trimmed={} subscriber_drops={} allocs={} video_waiting={} audio_waiting={} video_eof={} audio_eof={} subs={}",
+                            bus.pairs, bus.silence_filled, bus.audio_trimmed, bus.subscriber_drops, bus.vpool.allocs + bus.apool.allocs,
+                            bus.vq.len(), bus.aq.len(), vin.eof as u8, ain.eof as u8,
+                            if subs.is_empty() { "-".to_string() } else { subs.join(",") }
+                        ));
+                    }
+                    ["QUIT"] => std::process::exit(0),
+                    [] => {}
+                    _ => emit("ERROR 0 command"),
+                }
+            }
+        }
+    }
+}
diff --git a/apps/media-worker/src/gate/rust/src/main.rs b/apps/media-worker/src/gate/rust/src/main.rs
new file mode 100644
index 0000000..35aee66
--- /dev/null
+++ b/apps/media-worker/src/gate/rust/src/main.rs
@@ -0,0 +1,749 @@
+//! Frame gate (docs/design/streaming-architecture.md §1.4).
+//!
+//! The gate is the clock master between swappable compositor processes and one
+//! persistent encoder. It emits exactly one raw video frame and one PCM frame
+//! per tick of the output frame rate, whatever the compositors do:
+//!
+//! * the active compositor's next frame when it has one;
+//! * otherwise the last video frame again plus silence (a stall never starves
+//!   the encoder, so a dead or SIGKILLed compositor never takes RTMP down);
+//! * a pending compositor is promoted at a tick boundary once it has buffered
+//!   `warm` frames of both video and audio, and the old one is closed.
+//!
+//! Raw yuv420p and s16le have fixed bytes per frame, so there is no demuxing and
+//! no timestamp parsing: frames are counted. The pipe contract is shared with
+//! the Node implementation (src/gate/node-gate.ts) and documented in
+//! src/gate/protocol.ts.
+//!
+//! fds: 0 control lines, 1 event lines, 2 diagnostics.
+//! argv: <width> <height> <fps> <ringFrames> <warmFrames> <encoderVideoFifo> <encoderAudioFifo> [copy]
+//!
+//! Single thread, one poll loop. Every pipe is non-blocking and each encoder
+//! output has its own queue, so the tick clock never waits on the encoder and
+//! a consumer that reads its inputs in any order (ffmpeg probing one input
+//! before opening the next) cannot deadlock against the gate.
+
+use std::collections::VecDeque;
+use std::fs::{File, OpenOptions};
+use std::io::{self, ErrorKind, Read, Write};
+use std::os::unix::fs::OpenOptionsExt;
+use std::os::unix::io::{AsRawFd, FromRawFd};
+use std::time::{Duration, Instant};
+
+#[repr(C)]
+struct PollFd {
+    fd: i32,
+    events: i16,
+    revents: i16,
+}
+
+#[repr(C)]
+struct IoVec {
+    base: *const u8,
+    len: usize,
+}
+
+#[repr(C)]
+struct TimeVal {
+    sec: i64,
+    usec: i64,
+}
+
+#[repr(C)]
+struct RUsage {
+    utime: TimeVal,
+    stime: TimeVal,
+    rest: [i64; 14],
+}
+
+extern "C" {
+    fn poll(fds: *mut PollFd, nfds: u64, timeout: i32) -> i32;
+    fn fcntl(fd: i32, cmd: i32, ...) -> i32;
+    fn getrusage(who: i32, usage: *mut RUsage) -> i32;
+    fn vmsplice(fd: i32, iov: *const IoVec, nr_segs: u64, flags: u32) -> isize;
+    fn write(fd: i32, buf: *const u8, count: usize) -> isize;
+}
+
+const POLLIN: i16 = 0x1;
+const POLLOUT: i16 = 0x4;
+const O_NONBLOCK: i32 = 0o4000;
+const F_GETFL: i32 = 3;
+const F_SETFL: i32 = 4;
+const F_SETPIPE_SZ: i32 = 1031;
+const F_GETPIPE_SZ: i32 = 1032;
+const SPLICE_F_NONBLOCK: u32 = 0x02;
+const PIPE_BYTES: i32 = 1 << 20;
+const SAMPLE_RATE: usize = 48_000;
+const AUDIO_BYTES_PER_SAMPLE: usize = 4; // s16le stereo
+const MAX_READS_PER_WAKE: usize = 64;
+/// Compositor pipes are drained at most this often. Producers write in 32 KiB
+/// chunks; waking per chunk costs far more CPU than draining a 1 MiB pipe in
+/// bulk. 1 MiB / 2 ms = 500 MB/s per stream, above 1080p60 raw (186 MB/s).
+const PUMP_INTERVAL: Duration = Duration::from_micros(2_000);
+
+fn set_nonblocking(fd: i32) {
+    unsafe {
+        let flags = fcntl(fd, F_GETFL);
+        if flags >= 0 {
+            fcntl(fd, F_SETFL, flags | O_NONBLOCK);
+        }
+    }
+}
+
+fn cpu_us() -> u64 {
+    let mut usage = RUsage { utime: TimeVal { sec: 0, usec: 0 }, stime: TimeVal { sec: 0, usec: 0 }, rest: [0; 14] };
+    unsafe { getrusage(0, &mut usage) };
+    (usage.utime.sec * 1_000_000 + usage.utime.usec + usage.stime.sec * 1_000_000 + usage.stime.usec) as u64
+}
+
+/// Refcounted, preallocated frame buffers addressed by index.
+///
+/// vmsplice hands buffer *pages* to the encoder pipe, so a buffer whose write
+/// has finished may still be referenced by up to one pipe's worth (1 MiB) of
+/// unread data. Released buffers therefore sit in quarantine until a later
+/// frame has been fully written: a whole later frame (>= 1 MiB at the sizes
+/// that matter) cannot be in the pipe together with any older page.
+struct Pool {
+    bufs: Vec<Vec<u8>>,
+    refs: Vec<u32>,
+    free: Vec<usize>,
+    quarantine: Vec<(usize, u64)>,
+    size: usize,
+    allocs: u64,
+}
+
+impl Pool {
+    fn new(size: usize, prealloc: usize) -> Pool {
+        Pool { bufs: (0..prealloc).map(|_| vec![0u8; size]).collect(), refs: vec![0; prealloc], free: (0..prealloc).rev().collect(), quarantine: Vec::new(), size, allocs: 0 }
+    }
+    fn get(&mut self) -> usize {
+        let idx = match self.free.pop() {
+            Some(i) => i,
+            None => {
+                self.bufs.push(vec![0u8; self.size]);
+                self.refs.push(0);
+                self.allocs += 1;
+                self.bufs.len() - 1
+            }
+        };
+        self.refs[idx] = 1;
+        idx
+    }
+    fn retain(&mut self, idx: usize) {
+        self.refs[idx] += 1;
+    }
+    /// `written` = frames fully written so far; the buffer is reusable once a later one completes.
+    fn release(&mut self, idx: usize, written: u64) {
+        self.refs[idx] -= 1;
+        if self.refs[idx] == 0 {
+            self.quarantine.push((idx, written));
+        }
+    }
+    fn on_frame_written(&mut self, written: u64) {
+        let mut i = 0;
+        while i < self.quarantine.len() {
+            if self.quarantine[i].1 < written {
+                let (idx, _) = self.quarantine.swap_remove(i);
+                self.free.push(idx);
+            } else {
+                i += 1;
+            }
+        }
+    }
+}
+
+/// Fixed-size frame ring of pool buffers. One extra slot holds the partial frame being read.
+struct Ring {
+    slots: Vec<usize>,
+    head: usize,
+    count: usize,
+    fill: usize,
+    cap: usize,
+    /// Frames that have left the ring (taken, dropped or skipped): the source position of the head frame.
+    removed: u64,
+    /// Frames already counted in `removed` that have not arrived yet: discarded on arrival.
+    skip: u64,
+}
+
+impl Ring {
+    fn new(cap: usize, pool: &mut Pool) -> Ring {
+        Ring { slots: (0..=cap).map(|_| pool.get()).collect(), head: 0, count: 0, fill: 0, cap, removed: 0, skip: 0 }
+    }
+    fn full(&self) -> bool {
+        self.count >= self.cap
+    }
+    fn write_idx(&self) -> usize {
+        self.slots[(self.head + self.count) % self.slots.len()]
+    }
+    fn advance(&mut self, n: usize, size: usize) {
+        self.fill += n;
+        if self.fill == size {
+            self.fill = 0;
+            if self.skip > 0 {
+                self.skip -= 1; // the slot is overwritten by the next frame
+            } else {
+                self.count += 1;
+            }
+        }
+    }
+    /// Drops the oldest frame, or the next one to arrive when the ring is empty.
+    fn skip_one(&mut self) {
+        if self.count > 0 {
+            self.drop_oldest();
+        } else {
+            self.skip += 1;
+            self.removed += 1;
+        }
+    }
+    fn drop_oldest(&mut self) {
+        // The partial frame sits at head+count, which this leaves in place.
+        if self.count > 0 {
+            self.head = (self.head + 1) % self.slots.len();
+            self.count -= 1;
+            self.removed += 1;
+        }
+    }
+    /// Hands the oldest frame's buffer to the caller (who owns its reference) and refills the slot.
+    fn take(&mut self, pool: &mut Pool) -> usize {
+        let idx = self.slots[self.head];
+        self.slots[self.head] = pool.get();
+        self.head = (self.head + 1) % self.slots.len();
+        self.count -= 1;
+        self.removed += 1;
+        idx
+    }
+    fn dispose(&mut self, pool: &mut Pool, written: u64) {
+        for &idx in &self.slots {
+            pool.release(idx, written);
+        }
+        self.slots.clear();
+    }
+}
+
+struct Stream {
+    file: File,
+    pipe_bytes: usize,
+    ring: Ring,
+    eof: bool,
+}
+
+impl Stream {
+    fn open(path: &str, cap: usize, pool: &mut Pool) -> io::Result<Stream> {
+        let file = OpenOptions::new().read(true).custom_flags(O_NONBLOCK).open(path)?;
+        unsafe { fcntl(file.as_raw_fd(), F_SETPIPE_SZ, PIPE_BYTES) };
+        let pipe_bytes = unsafe { fcntl(file.as_raw_fd(), F_GETPIPE_SZ) }.max(0) as usize;
+        Ok(Stream { file, pipe_bytes, ring: Ring::new(cap, pool), eof: false })
+    }
+
+    /// Reads until the pipe is empty or the ring is full (the compositor then sees backpressure).
+    fn pump(&mut self, pool: &mut Pool) {
+        for _ in 0..MAX_READS_PER_WAKE {
+            if self.eof || self.ring.full() {
+                break;
+            }
+            let idx = self.ring.write_idx();
+            let fill = self.ring.fill;
+            match self.file.read(&mut pool.bufs[idx][fill..]) {
+                Ok(0) => self.eof = true,
+                Ok(n) => self.ring.advance(n, pool.size),
+                Err(e) if e.kind() == ErrorKind::WouldBlock => break,
+                Err(e) if e.kind() == ErrorKind::Interrupted => continue,
+                Err(_) => self.eof = true,
+            }
+        }
+    }
+}
+
+struct Slot {
+    id: u32,
+    video: Stream,
+    audio: Stream,
+    /// Source frame index (in the worker's per-chain numbering) of this compositor's first
+    /// output frame. With origins on both sides, a swap splices B at A's next source frame.
+    origin: Option<i64>,
+    /// Tick at which this pending slot first produced a frame (promotion timeout).
+    warm_since: Option<u64>,
+    /// `LAG` already reported for this pending slot.
+    lagged: bool,
+}
+
+impl Slot {
+    fn head_seq(&self) -> Option<i64> {
+        self.origin.map(|o| o + self.video.ring.removed as i64)
+    }
+    /// Video frame i and audio frame i of a compositor are one source pair, so every drop or skip
+    /// applies to both streams and the ring heads always hold the same pair index.
+    ///
+    /// Pending slot: keeps complete pairs at A's next position. Only whole pairs are dropped; a stream
+    /// that runs ahead of the other (compositor audio usually leads video) waits in its pipe
+    /// until its partner frames arrive, instead of discarding frames the pairing still needs.
+    fn pump_pending(&mut self, vpool: &mut Pool, apool: &mut Pool, target: Option<i64>) -> u64 {
+        let mut dropped = 0;
+        for _ in 0..4 {
+            self.video.pump(vpool);
+            self.audio.pump(apool);
+            let mut freed = false;
+            while (self.video.ring.full() || self.audio.ring.full()) && self.video.ring.count > 0 && self.audio.ring.count > 0
+                && target.zip(self.head_seq()).map_or(true, |(t, head)| head < t) {
+                self.video.ring.drop_oldest();
+                self.audio.ring.drop_oldest();
+                dropped += 1;
+                freed = true;
+            }
+            if !freed {
+                break;
+            }
+        }
+        dropped
+    }
+    fn ended(&self) -> bool {
+        (self.video.eof && self.video.ring.count == 0) || (self.audio.eof && self.audio.ring.count == 0)
+    }
+    fn close(mut self, vpool: &mut Pool, apool: &mut Pool, written: u64) {
+        self.video.ring.dispose(vpool, written);
+        self.audio.ring.dispose(apool, written);
+    }
+}
+
+/// One encoder output: queued buffer references, written non-blocking in order.
+struct Out {
+    fd: i32,
+    queue: VecDeque<(usize, usize)>,
+    zero_copy: bool,
+    written_frames: u64,
+}
+
+enum Flush {
+    Ok,
+    Closed,
+}
+
+impl Out {
+    fn flush(&mut self, pool: &mut Pool) -> Flush {
+        while let Some(&(idx, off)) = self.queue.front() {
+            let buf = &pool.bufs[idx][off..];
+            let n = if self.zero_copy {
+                let iov = IoVec { base: buf.as_ptr(), len: buf.len() };
+                unsafe { vmsplice(self.fd, &iov, 1, SPLICE_F_NONBLOCK) }
+            } else {
+                unsafe { write(self.fd, buf.as_ptr(), buf.len()) }
+            };
+            if n < 0 {
+                let err = io::Error::last_os_error();
+                match err.kind() {
+                    ErrorKind::WouldBlock => return Flush::Ok,
+                    ErrorKind::Interrupted => continue,
+                    _ => return Flush::Closed,
+                }
+            }
+            let n = n as usize;
+            if n == buf.len() {
+                self.queue.pop_front();
+                self.written_frames += 1;
+                pool.release(idx, self.written_frames - 1);
+                pool.on_frame_written(self.written_frames);
+            } else {
+                self.queue.front_mut().unwrap().1 += n;
+            }
+        }
+        Flush::Ok
+    }
+}
+
+#[derive(Default)]
+struct Stats {
+    ticks: u64,
+    idle: u64,
+    vrep: u64,
+    asil: u64,
+    drops: u64,
+    swaps: u64,
+    late_max_us: u64,
+    late_over_frame: u64,
+    late_over_2ms: u64,
+    late_over_5ms: u64,
+    backlog_max: u64,
+    out_drops: u64,
+    stall_run: u64,
+    active_since: u64,
+    gap_events: u64,
+    lagged: u64,
+    behind_max: u64,
+}
+
+fn emit(line: &str) {
+    let mut out = io::stdout().lock();
+    let _ = out.write_all(line.as_bytes());
+    let _ = out.write_all(b"\n");
+    let _ = out.flush();
+}
+
+fn arg(args: &[String], i: usize, name: &str) -> usize {
+    match args.get(i).and_then(|v| v.parse::<usize>().ok()) {
+        Some(v) if v > 0 => v,
+        _ => {
+            eprintln!("frame-gate: invalid {}", name);
+            std::process::exit(2);
+        }
+    }
+}
+
+fn open_out(args: &[String], i: usize) -> File {
+    let path = args.get(i).map(String::as_str).unwrap_or("");
+    match OpenOptions::new().write(true).custom_flags(O_NONBLOCK).open(path) {
+        Ok(f) => {
+            unsafe { fcntl(f.as_raw_fd(), F_SETPIPE_SZ, PIPE_BYTES) };
+            f
+        }
+        Err(_) => {
+            eprintln!("frame-gate: cannot open encoder fifo (reader must be open first)");
+            std::process::exit(2);
+        }
+    }
+}
+
+fn main() {
+    let args: Vec<String> = std::env::args().collect();
+    let width = arg(&args, 1, "width");
+    let height = arg(&args, 2, "height");
+    let fps = arg(&args, 3, "fps");
+    let ring_frames = arg(&args, 4, "ringFrames");
+    let warm = arg(&args, 5, "warmFrames");
+    if width % 2 != 0 || height % 2 != 0 || SAMPLE_RATE % fps != 0 || warm > ring_frames {
+        eprintln!("frame-gate: geometry must be even, fps must divide 48000, warm <= ring");
+        std::process::exit(2);
+    }
+    let video_bytes = width * height * 3 / 2;
+    let audio_bytes = SAMPLE_RATE / fps * AUDIO_BYTES_PER_SAMPLE;
+    // vmsplice is only safe when a frame is at least a pipe's worth (see Pool); `copy` disables it.
+    let zero_copy = args.get(8).map_or(true, |v| v != "copy") && video_bytes >= PIPE_BYTES as usize;
+    // Encoder backlog beyond 0.5 s is an encoder that stopped reading: drop the oldest unstarted frames.
+    let max_backlog = (fps / 2).max(4);
+
+    let enc_video_file = open_out(&args, 6);
+    let enc_audio_file = open_out(&args, 7);
+    set_nonblocking(0);
+    let mut control = unsafe { File::from_raw_fd(0) };
+
+    // Two slots' rings + last + a few in flight; backlog beyond that allocates (counted in `allocs`).
+    let pool_frames = 2 * (ring_frames + 1) + 6;
+    // Compositor audio leads video by the video graph's extra latency. PCM frames are small, so the
+    // audio rings hold 4 s: the leading stream never backs up into the compositor (whose blocked
+    // audio write would stall the very video frames its pairs are waiting for).
+    let audio_ring_frames = ring_frames.max(4 * fps);
+    let mut vpool = Pool::new(video_bytes, pool_frames);
+    let mut apool = Pool::new(audio_bytes, 2 * (audio_ring_frames + 1) + 6);
+    let mut vout = Out { fd: enc_video_file.as_raw_fd(), queue: VecDeque::new(), zero_copy, written_frames: 0 };
+    let mut aout = Out { fd: enc_audio_file.as_raw_fd(), queue: VecDeque::new(), zero_copy: false, written_frames: 0 };
+
+    // Black (limited-range yuv420p) until the first compositor is promoted.
+    let mut last_video = vpool.get();
+    {
+        let b = &mut vpool.bufs[last_video];
+        b[..width * height].fill(16);
+        b[width * height..].fill(128);
+    }
+    let silence = apool.get(); // zeroed; never released
+
+    let mut active: Option<Slot> = None;
+    let mut pending: Option<Slot> = None;
+    let mut stats = Stats::default();
+    let mut line_buf: Vec<u8> = Vec::with_capacity(4096);
+    let mut read_buf = [0u8; 4096];
+    let mut last_pump = Instant::now();
+
+    let start = Instant::now();
+    let period = Duration::from_nanos(1_000_000_000 / fps as u64);
+    // Exact due instant for tick n (no per-frame rounding drift, no overflow).
+    let due_at = |n: u64| start + Duration::from_nanos(n * 1_000_000_000 / fps as u64);
+    let cpu_start = cpu_us();
+    emit(&format!("READY {} {} {} {}", video_bytes, audio_bytes, ring_frames, warm));
+
+    loop {
+        // 1. Emit every tick that is due (catch-up keeps the frame count locked to wall time).
+        let now = Instant::now();
+        while now >= due_at(stats.ticks) {
+            let late = (now - due_at(stats.ticks)).as_micros() as u64;
+            stats.late_max_us = stats.late_max_us.max(late);
+            if late > period.as_micros() as u64 {
+                stats.late_over_frame += 1;
+            }
+            if late > 2_000 {
+                stats.late_over_2ms += 1;
+            }
+            if late > 5_000 {
+                stats.late_over_5ms += 1;
+            }
+            let written = vout.written_frames;
+
+            if pending.as_ref().map_or(false, |p| p.ended()) {
+                let p = pending.take().unwrap();
+                emit(&format!("EOF {}", p.id));
+                p.close(&mut vpool, &mut apool, written);
+            }
+            // Promotion. With origins on A and B: drop B's frames older than A's next source
+            // frame and splice there (B inherits A's latency; the source never runs backwards).
+            // If B is ahead, hold its frames until A reaches them; never skip on promotion.
+            // Without origins (or no active): newest `warm` frames.
+            let target = active.as_ref().and_then(|a| a.head_seq());
+            // A's current buffer depth: B must match it (capped at `warm`) to keep the same jitter margin.
+            let active_depth = active.as_ref().map_or(warm, |a| a.video.ring.count.min(a.audio.ring.count));
+            let mut ready = false;
+            let mut aligned = false;
+            // Diagnostics for the ACTIVE line: A's depth, B's backward step, B's depth, B's age.
+            let mut promo = (active_depth, 0i64, 0usize, 0u64);
+            if let Some(p) = pending.as_mut() {
+                if p.warm_since.is_none() && p.video.ring.count > 0 {
+                    p.warm_since = Some(stats.ticks);
+                }
+                let need_aligned = active_depth.min(warm).saturating_sub(1).max(1);
+                let mut behind = 0i64;
+                if let (Some(t), Some(head)) = (target, p.head_seq()) {
+                    aligned = true;
+                    let count = p.video.ring.count.min(p.audio.ring.count);
+                    let newest = head + count as i64 - 1;
+                    if count > 0 && newest >= t {
+                        // B holds A's next source frame: splice exactly there.
+                        while p.video.ring.count > 0 && p.audio.ring.count > 0 && p.head_seq().unwrap_or(t) < t {
+                            p.video.ring.drop_oldest();
+                            p.audio.ring.drop_oldest();
+                        }
+                        behind = t - p.head_seq().unwrap_or(t);
+                    } else if count > 0 {
+                        // B's pipeline is slower than A's on-air position: take its newest frames
+                        // (smallest backward step) rather than hold the swap.
+                        while p.video.ring.count > need_aligned && p.audio.ring.count > need_aligned {
+                            p.video.ring.drop_oldest();
+                            p.audio.ring.drop_oldest();
+                        }
+                        behind = t - p.head_seq().unwrap_or(t);
+                    }
+                }
+                let have = p.video.ring.count.min(p.audio.ring.count);
+                let need = if aligned { need_aligned } else { warm };
+                let age = p.warm_since.map_or(0, |w| stats.ticks - w);
+                // Aligned but shallower than A (B's pipeline slightly slower): splicing costs no
+                // artifact, only jitter margin, so accept it after a second of production.
+                let in_step = behind == 0 && (have >= need || (have >= 1 && age >= fps as u64));
+                // Unaligned (first compositor, or no shared numbering): go with what there is after 5 s.
+                let timed_out = !aligned && age >= 5 * fps as u64 && have >= 1;
+                ready = in_step || timed_out;
+                promo = (active_depth, behind, have, age);
+                // B behind A's on-air source position: never splice backwards (that replays picture
+                // and audio). A stays on air; B is usually a CPU-starved spawn still draining its
+                // startup backlog. After 3 s report it so the worker can replace it.
+                if behind > 0 {
+                    stats.behind_max = stats.behind_max.max(behind as u64);
+                    if age >= 3 * fps as u64 && !p.lagged {
+                        p.lagged = true;
+                        stats.lagged += 1;
+                        emit(&format!("LAG {} {}", p.id, behind));
+                    }
+                }
+            }
+            if ready {
+                let mut p = pending.take().unwrap();
+                if !aligned {
+                    while p.video.ring.count > warm || p.audio.ring.count > warm {
+                        p.video.ring.skip_one();
+                        p.audio.ring.skip_one();
+                    }
+                }
+                let id = p.id;
+                let old = active.replace(p);
+                stats.swaps += 1;
+                stats.stall_run = 0;
+                stats.active_since = stats.ticks;
+                emit(&format!("ACTIVE {} {} {} {} {} {}", id, stats.ticks, promo.0, promo.1, promo.2, promo.3));
+                if let Some(o) = old {
+                    emit(&format!("RETIRED {}", o.id));
+                    o.close(&mut vpool, &mut apool, written);
+                }
+            }
+
+            let mut audio_idx = silence;
+            apool.retain(silence);
+            match active.as_mut() {
+                Some(a) => {
+                    // A joint stall repeats/silences without consuming a source position.
+                    // Skipping both future frames on every empty tick can keep a producer
+                    // running at exactly fps permanently behind the skip counters after a pause.
+                    // One-sided stalls still skip their late partner to preserve A/V lockstep.
+                    let joint_stall = a.video.ring.count == 0 && a.audio.ring.count == 0;
+                    if a.video.ring.count > 0 {
+                        let idx = a.video.ring.take(&mut vpool);
+                        vpool.release(last_video, written);
+                        last_video = idx;
+                        stats.stall_run = 0;
+                    } else {
+                        // Repeat now, discard the late frame when it arrives (keeps A/V index-locked).
+                        if !joint_stall { a.video.ring.skip_one(); }
+                        stats.vrep += 1;
+                        if stats.gap_events < 200 {
+                            stats.gap_events += 1;
+                            emit(&format!("GAP v {} {} {} {}", a.id, stats.ticks, stats.ticks - stats.active_since, late));
+                        }
+                        stats.stall_run += 1;
+                        if stats.stall_run == fps as u64 {
+                            emit(&format!("STALL {} {}", a.id, stats.ticks));
+                        }
+                    }
+                    if a.audio.ring.count > 0 {
+                        apool.release(silence, aout.written_frames);
+                        audio_idx = a.audio.ring.take(&mut apool);
+                    } else {
+                        if !joint_stall { a.audio.ring.skip_one(); }
+                        stats.asil += 1;
+                        if stats.gap_events < 200 {
+                            stats.gap_events += 1;
+                            emit(&format!("GAP a {} {} {} {}", a.id, stats.ticks, stats.ticks - stats.active_since, late));
+                        }
+                    }
+                }
+                None => stats.idle += 1,
+            }
+            if active.as_ref().map_or(false, |a| a.ended()) {
+                let a = active.take().unwrap();
+                emit(&format!("EOF {}", a.id));
+                a.close(&mut vpool, &mut apool, written);
+            }
+
+            vpool.retain(last_video);
+            vout.queue.push_back((last_video, 0));
+            aout.queue.push_back((audio_idx, 0));
+            for (out, pool) in [(&mut vout, &mut vpool), (&mut aout, &mut apool)] {
+                // Never drop the frame in flight (index 0 may be partially written).
+                while out.queue.len() > max_backlog && out.queue.len() > 1 {
+                    let (idx, _) = out.queue.remove(1).unwrap();
+                    pool.release(idx, out.written_frames);
+                    stats.out_drops += 1;
+                }
+            }
+            stats.backlog_max = stats.backlog_max.max(vout.queue.len() as u64);
+            stats.ticks += 1;
+        }
+        for (out, pool) in [(&mut vout, &mut vpool), (&mut aout, &mut apool)] {
+            if let Flush::Closed = out.flush(pool) {
+                eprintln!("frame-gate: encoder input closed");
+                std::process::exit(3);
+            }
+        }
+
+        // 2. Wait for input, encoder writability, or the next tick.
+        let due = due_at(stats.ticks);
+        let now = Instant::now();
+        // F_SETPIPE_SZ can fail under a shared uid's pipe quota. An 8 KiB video pipe
+        // must be drained as soon as readable; a 2 ms hold would cap it at ~4 MB/s.
+        let bulk_min = video_bytes * fps / 250;
+        let bulk = [active.as_ref(), pending.as_ref()].into_iter().flatten().all(|s| s.video.pipe_bytes >= bulk_min);
+        let pump_due = last_pump + if bulk { PUMP_INTERVAL } else { Duration::ZERO };
+        let pump_now = now >= pump_due;
+        let until = if pump_now { due } else { due.min(pump_due) };
+        let timeout_ms = (until.saturating_duration_since(now).as_micros() as i32 + 999) / 1000;
+        let mut fds: Vec<PollFd> = Vec::with_capacity(7);
+        fds.push(PollFd { fd: 0, events: POLLIN, revents: 0 });
+        fds.push(PollFd { fd: if vout.queue.is_empty() { -1 } else { vout.fd }, events: POLLOUT, revents: 0 });
+        fds.push(PollFd { fd: if aout.queue.is_empty() { -1 } else { aout.fd }, events: POLLOUT, revents: 0 });
+        if pump_now {
+            for slot in [active.as_ref(), pending.as_ref()] {
+                if let Some(s) = slot {
+                    for st in [&s.video, &s.audio] {
+                        let want = !st.eof && !st.ring.full();
+                        fds.push(PollFd { fd: if want { st.file.as_raw_fd() } else { -1 }, events: POLLIN, revents: 0 });
+                    }
+                }
+            }
+        }
+        unsafe { poll(fds.as_mut_ptr(), fds.len() as u64, timeout_ms) };
+
+        // 3. Pump compositor pipes, then hold off for PUMP_INTERVAL so they refill in bulk.
+        if fds.len() > 3 && fds[3..].iter().any(|f| f.revents != 0) {
+            last_pump = Instant::now();
+            if let Some(a) = active.as_mut() {
+                a.video.pump(&mut vpool);
+                a.audio.pump(&mut apool);
+            }
+            if let Some(p) = pending.as_mut() {
+                let target = active.as_ref().and_then(|a| a.head_seq());
+                stats.drops += p.pump_pending(&mut vpool, &mut apool, target);
+            }
+        }
+
+        // 4. Control lines.
+        if fds[0].revents != 0 {
+            loop {
+                match control.read(&mut read_buf) {
+                    Ok(0) => std::process::exit(0), // parent gone
+                    Ok(n) => line_buf.extend_from_slice(&read_buf[..n]),
+                    Err(e) if e.kind() == ErrorKind::WouldBlock => break,
+                    Err(e) if e.kind() == ErrorKind::Interrupted => continue,
+                    Err(_) => std::process::exit(0),
+                }
+            }
+            while let Some(pos) = line_buf.iter().position(|&b| b == b'\n') {
+                let line: Vec<u8> = line_buf.drain(..=pos).collect();
+                let text = String::from_utf8_lossy(&line[..line.len() - 1]).into_owned();
+                let parts: Vec<&str> = text.split_whitespace().collect();
+                let written = vout.written_frames;
+                match parts.as_slice() {
+                    ["ATTACH", id, vpath, apath, rest @ ..] if rest.len() <= 1 => match id.parse::<u32>() {
+                        Ok(id) => {
+                            let origin = rest.first().and_then(|v| v.parse::<i64>().ok());
+                            let video = Stream::open(vpath, ring_frames, &mut vpool);
+                            let audio = Stream::open(apath, audio_ring_frames, &mut apool);
+                            match (video, audio) {
+                                (Ok(video), Ok(audio)) => {
+                                    if let Some(old) = pending.replace(Slot { id, video, audio, origin, warm_since: None, lagged: false }) {
+                                        emit(&format!("DROPPED {}", old.id));
+                                        old.close(&mut vpool, &mut apool, written);
+                                    }
+                                    emit(&format!("ATTACHED {}", id));
+                                }
+                                (v, a) => {
+                                    if let Ok(mut s) = v {
+                                        s.ring.dispose(&mut vpool, written);
+                                    }
+                                    if let Ok(mut s) = a {
+                                        s.ring.dispose(&mut apool, written);
+                                    }
+                                    emit(&format!("ERROR {} open", id));
+                                }
+                            }
+                        }
+                        Err(_) => emit("ERROR 0 id"),
+                    },
+                    ["DETACH", id] => {
+                        let id = id.parse::<u32>().unwrap_or(u32::MAX);
+                        if pending.as_ref().map_or(false, |p| p.id == id) {
+                            pending.take().unwrap().close(&mut vpool, &mut apool, written);
+                            emit(&format!("DETACHED {}", id));
+                        } else if active.as_ref().map_or(false, |a| a.id == id) {
+                            active.take().unwrap().close(&mut vpool, &mut apool, written);
+                            emit(&format!("DETACHED {}", id));
+                        }
+                    }
+                    ["STATS"] => {
+                        let ring = |s: Option<&Slot>| s.map_or("-".to_string(), |s| format!("{}:{}/{}", s.id, s.video.ring.count, s.audio.ring.count));
+                        emit(&format!(
+                            "STATS ticks={} idle={} vrep={} asil={} drops={} swaps={} late_max_us={} late_over_frame={} write_max_us=0 cpu_us={} wall_us={} active={} pending={} gc_max_us=0 allocs={} backlog_max={} out_drops={} late_over_2ms={} late_over_5ms={} lagged={} behind_max={}",
+                            stats.ticks, stats.idle, stats.vrep, stats.asil, stats.drops, stats.swaps, stats.late_max_us,
+                            stats.late_over_frame, cpu_us() - cpu_start, start.elapsed().as_micros(),
+                            ring(active.as_ref()), ring(pending.as_ref()), vpool.allocs + apool.allocs, stats.backlog_max, stats.out_drops, stats.late_over_2ms, stats.late_over_5ms, stats.lagged, stats.behind_max
+                        ));
+                    }
+                    ["RESET"] => {
+                        stats.late_max_us = 0;
+                        stats.late_over_frame = 0;
+                        stats.late_over_2ms = 0;
+                        stats.late_over_5ms = 0;
+                        stats.backlog_max = 0;
+                        emit("RESET");
+                    }
+                    ["QUIT"] => std::process::exit(0),
+                    [] => {}
+                    _ => emit("ERROR 0 command"),
+                }
+            }
+        }
+    }
+}
diff --git a/apps/media-worker/src/gate/sink-cli.ts b/apps/media-worker/src/gate/sink-cli.ts
new file mode 100644
index 0000000..5f22ea0
--- /dev/null
+++ b/apps/media-worker/src/gate/sink-cli.ts
@@ -0,0 +1,30 @@
+/**
+ * Verifying null encoder as its own process (so its timing is not polluted by
+ * the harness that spawns compositors): `sink-cli.ts <videoFifo> <audioFifo> <w> <h> <fps>`.
+ * Opens the gate's encoder FIFOs non-blocking, prints `OPEN`; on a
+ * `REPORT <firstActiveTick>` line prints the JSON report and exits.
+ */
+import { constants, openSync } from "node:fs";
+import { Socket } from "node:net";
+import { VerifyingSink } from "./sink";
+
+function main(): void {
+  const [videoPath, audioPath, w, h, fps] = process.argv.slice(2);
+  if (!videoPath || !audioPath) throw new Error("usage: sink-cli <videoFifo> <audioFifo> <w> <h> <fps>");
+  const sink = new VerifyingSink({ width: Number(w), height: Number(h), fps: Number(fps) });
+  const open = (path: string) => new Socket({ fd: openSync(path, constants.O_RDONLY | constants.O_NONBLOCK), readable: true, writable: false });
+  sink.attach(open(videoPath), open(audioPath));
+  process.stdout.write("OPEN\n");
+  let buf = "";
+  process.stdin.setEncoding("utf8");
+  process.stdin.on("data", (chunk: string) => {
+    buf += chunk;
+    const m = /REPORT (\d+)\n/.exec(buf);
+    if (!m) return;
+    const first = Number(m[1]);
+    const r = sink.report;
+    process.stdout.write(`${JSON.stringify({ ...r, silentAt: undefined, tagChanges: r.tagChanges.slice(0, 20_000), silentAfterFirstActive: sink.silentFramesFrom(first) })}\n`, () => process.exit(0));
+  });
+}
+
+if (require.main === module) main();
diff --git a/apps/media-worker/src/gate/sink.ts b/apps/media-worker/src/gate/sink.ts
new file mode 100644
index 0000000..1277e9e
--- /dev/null
+++ b/apps/media-worker/src/gate/sink.ts
@@ -0,0 +1,139 @@
+import type { Readable } from "node:stream";
+import { audioFrameBytes, videoFrameBytes, type FrameGeometry } from "./protocol";
+
+/**
+ * Null encoder that verifies what an encoder would receive from the gate:
+ * frame counts in lockstep, arrival gaps, a luma tag per frame (Y at byte 0,
+ * which tests use as a monotonic frame/scene counter), and PCM continuity
+ * (largest sample-to-sample step, all-zero frames).
+ */
+export interface SinkReport {
+  videoFrames: number;
+  audioFrames: number;
+  /** Largest gap between two consecutive completed video frames. */
+  maxGapMs: number;
+  /** Video frames whose arrival gap exceeded two frame intervals. */
+  gapsOverTwoFrames: number;
+  /** Tag of each video frame is recorded only when it changes: [frameIndex, tag]. */
+  tagChanges: Array<[number, number]>;
+  /**
+   * Histogram of per-frame counter steps for counter tags (luma 20 + 4·(n mod 50), decoded
+   * with ±1 tolerance): "1" is a normal frame, "0" a repeat, "2+" a skip, negative backwards.
+   */
+  tagDeltas: Record<string, number>;
+  maxPcmStep: number;
+  maxPcmAbs: number;
+  silentAudioFrames: number;
+  /** Frame index of each all-zero audio frame (first 100 000). */
+  silentAt: number[];
+}
+
+export class VerifyingSink {
+  private readonly vBytes: number;
+  private readonly aBytes: number;
+  private vPos = 0;
+  private aPos = 0;
+  private lastFrameAt = 0n;
+  private prev: [number, number] | null = null;
+  private frameNonZero = false;
+  private lastTag = -1;
+  private readonly intervalNs: bigint;
+  readonly report: SinkReport = {
+    videoFrames: 0, audioFrames: 0, maxGapMs: 0, gapsOverTwoFrames: 0, tagChanges: [], tagDeltas: {},
+    maxPcmStep: 0, maxPcmAbs: 0, silentAudioFrames: 0, silentAt: [],
+  };
+  /** PCM steps are not measured before this frame (gate boot silence before the first compositor). */
+  skipSilenceBefore = 0;
+
+  /** All-zero audio frames at or after `frame` (e.g. the tick the first compositor went on air). */
+  silentFramesFrom(frame: number): number { return this.report.silentAt.filter((i) => i >= frame).length; }
+
+  constructor(geometry: FrameGeometry) {
+    this.vBytes = videoFrameBytes(geometry);
+    this.aBytes = audioFrameBytes(geometry);
+    this.intervalNs = 1_000_000_000n / BigInt(geometry.fps);
+  }
+
+  attach(video: Readable, audio: Readable): void {
+    video.on("data", (chunk: Buffer) => this.onVideo(chunk));
+    audio.on("data", (chunk: Buffer) => this.onAudio(chunk));
+  }
+
+  private onVideo(chunk: Buffer): void {
+    let at = 0;
+    while (at < chunk.length) {
+      if (this.vPos === 0) {
+        const tag = chunk[at] ?? 0;
+        if (this.lastTag >= 18 && this.lastTag < 220 && tag >= 18 && tag < 220) {
+          const decode = (y: number): number => Math.round((y - 20) / 4);
+          let d = (((decode(tag) - decode(this.lastTag)) % 50) + 50) % 50;
+          if (d > 25) d -= 50;
+          const key = String(d);
+          this.report.tagDeltas[key] = (this.report.tagDeltas[key] ?? 0) + 1;
+        }
+        if (tag !== this.lastTag) {
+          if (this.report.tagChanges.length < 100_000) this.report.tagChanges.push([this.report.videoFrames, tag]);
+          this.lastTag = tag;
+        }
+      }
+      const n = Math.min(chunk.length - at, this.vBytes - this.vPos);
+      at += n;
+      this.vPos += n;
+      if (this.vPos === this.vBytes) {
+        this.vPos = 0;
+        const now = process.hrtime.bigint();
+        if (this.lastFrameAt !== 0n) {
+          const gap = now - this.lastFrameAt;
+          this.report.maxGapMs = Math.max(this.report.maxGapMs, Number(gap) / 1e6);
+          if (gap > 2n * this.intervalNs) this.report.gapsOverTwoFrames += 1;
+        }
+        this.lastFrameAt = now;
+        this.report.videoFrames += 1;
+      }
+    }
+  }
+
+  private onAudio(chunk: Buffer): void {
+    // Chunks from a stream socket are not guaranteed to be 4-byte aligned.
+    let at = 0;
+    while (at < chunk.length) {
+      const sampleStart = this.aPos % 4 === 0;
+      if (sampleStart && at + 4 <= chunk.length) {
+        const l = chunk.readInt16LE(at);
+        const r = chunk.readInt16LE(at + 2);
+        this.sample(l, r);
+        at += 4;
+        this.aPos += 4;
+      } else {
+        // Rare split sample: fall back to byte stepping with a carry.
+        this.carry.push(chunk[at] ?? 0);
+        at += 1;
+        this.aPos += 1;
+        if (this.carry.length === 4) {
+          const b = Buffer.from(this.carry);
+          this.carry = [];
+          this.sample(b.readInt16LE(0), b.readInt16LE(2));
+        }
+      }
+      if (this.aPos === this.aBytes) {
+        this.aPos = 0;
+        if (!this.frameNonZero) {
+          this.report.silentAudioFrames += 1;
+          if (this.report.silentAt.length < 100_000) this.report.silentAt.push(this.report.audioFrames);
+        }
+        this.frameNonZero = false;
+        this.report.audioFrames += 1;
+      }
+    }
+  }
+  private carry: number[] = [];
+
+  private sample(l: number, r: number): void {
+    if (l !== 0 || r !== 0) this.frameNonZero = true;
+    this.report.maxPcmAbs = Math.max(this.report.maxPcmAbs, Math.abs(l), Math.abs(r));
+    if (this.prev && this.report.audioFrames >= this.skipSilenceBefore) {
+      this.report.maxPcmStep = Math.max(this.report.maxPcmStep, Math.abs(l - this.prev[0]), Math.abs(r - this.prev[1]));
+    }
+    this.prev = [l, r];
+  }
+}
diff --git a/apps/media-worker/src/gate/spike.ts b/apps/media-worker/src/gate/spike.ts
new file mode 100644
index 0000000..39a2441
--- /dev/null
+++ b/apps/media-worker/src/gate/spike.ts
@@ -0,0 +1,150 @@
+/**
+ * §1.4 frame-gate spike harness (not part of the test suite; numbers go to
+ * runs/wp4/s2a-report.md).
+ *
+ *   node --import tsx src/gate/spike.ts steady --impl rust --size 1920x1080 --fps 60 --seconds 20
+ *   node --import tsx src/gate/spike.ts swaps  --impl node --size 1920x1080 --fps 30 --swaps 1000
+ *
+ * Producers are compositor stand-ins (ffmpeg lavfi: solid luma tag = generation,
+ * 1500 Hz sine, so every frame holds a whole number of periods and any
+ * mis-spliced or inserted PCM shows up as a sample step). The sink is the
+ * verifying null encoder (src/gate/sink.ts).
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnManaged, type ManagedProcess } from "../relay/ffmpeg";
+import { FrameGate, type GateImpl } from "./frame-gate";
+import type { FrameGeometry } from "./protocol";
+import type { SinkReport } from "./sink";
+
+async function waitFor(cond: () => boolean, timeoutMs = 15_000): Promise<void> {
+  const t0 = Date.now();
+  while (!cond()) {
+    if (Date.now() - t0 > timeoutMs) throw new Error("timeout");
+    await new Promise((r) => setTimeout(r, 10));
+  }
+}
+
+const passthrough = { redact: (s: string) => s };
+
+export function producerArgs(g: FrameGeometry, tag: number, paced = false): string[] {
+  return [
+    "-hide_banner", "-nostdin", "-loglevel", "error",
+    ...(paced ? ["-re"] : []), "-f", "lavfi", "-i", `color=c=black:s=${g.width}x${g.height}:r=${g.fps},lutyuv=y=${tag}:u=128:v=128`,
+    ...(paced ? ["-re"] : []), "-f", "lavfi", "-i", "sine=frequency=1500:sample_rate=48000",
+    "-map", "0:v", "-f", "rawvideo", "-pix_fmt", "yuv420p", "-fps_mode", "passthrough", "pipe:1",
+    "-map", "1:a", "-ac", "2", "-f", "s16le", "-flush_packets", "1", "pipe:3",
+  ];
+}
+
+export async function startProducer(gate: FrameGate, g: FrameGeometry, tag: number, origin?: number, paced = false): Promise<{ id: number; proc: ManagedProcess }> {
+  const slot = gate.allocateSlot();
+  const proc = spawnManaged("ffmpeg", producerArgs(g, tag, paced), ["ignore", slot.fifos.videoFd, "pipe", slot.fifos.audioFd], passthrough, () => undefined);
+  slot.fifos.releaseWriters();
+  await proc.started;
+  await gate.attach(slot, origin);
+  return { id: slot.id, proc };
+}
+
+function arg(name: string, fallback: string): string {
+  const i = process.argv.indexOf(`--${name}`);
+  return i >= 0 ? (process.argv[i + 1] ?? fallback) : fallback;
+}
+
+function percentile(values: number[], p: number): number {
+  const sorted = [...values].sort((a, b) => a - b);
+  return sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))] ?? 0;
+}
+
+async function main(): Promise<void> {
+  const mode = process.argv[2] ?? "steady";
+  const impl = arg("impl", "rust") as GateImpl;
+  const [w, h] = arg("size", "1920x1080").split("x").map(Number);
+  const g: FrameGeometry = { width: w ?? 1920, height: h ?? 1080, fps: Number(arg("fps", "30")) };
+  const scratch = mkdtempSync(join(tmpdir(), "gate-spike-"));
+  const events: string[] = [];
+  const gate = new FrameGate({
+    geometry: g, scratchDir: scratch, impl, copyWrites: process.argv.includes("--copy"),
+    redactor: passthrough, onStderr: (m) => process.stderr.write(m),
+    onEvent: (e) => { if (process.env.SPIKE_DEBUG) process.stderr.write(`${JSON.stringify(e)}\n`); if (e.type === "STALL" || e.type === "EOF" || e.type === "GAP") events.push(JSON.stringify(e)); },
+  });
+  // --sink ffmpeg: a real ffmpeg demuxer reads the encoder FIFOs (-f null), as the persistent encoder would.
+  const ffmpegSink = process.argv.includes("ffmpeg");
+  // Default sink: the verifier in its own process (src/gate/sink-cli.ts).
+  const verifier = ffmpegSink ? null : spawnManaged(process.execPath, ["--import", "tsx", join(__dirname, "sink-cli.ts"),
+    gate.encoderFifos.videoPath, gate.encoderFifos.audioPath, String(g.width), String(g.height), String(g.fps)],
+  ["pipe", "pipe", "pipe"], passthrough, (m) => process.stderr.write(m), join(__dirname, "../.."));
+  let verifierOut = "";
+  verifier?.child.stdout?.setEncoding("utf8");
+  verifier?.child.stdout?.on("data", (c: string) => { verifierOut += c; });
+  if (verifier) await waitFor(() => verifierOut.includes("OPEN\n"));
+  const inputs = ffmpegSink ? gate.encoderInputs() : null;
+  const nullEncoder = inputs ? spawnManaged("ffmpeg", ["-hide_banner", "-nostdin", "-loglevel", "error",
+    "-probesize", "32", "-analyzeduration", "0", "-f", "rawvideo", "-pix_fmt", "yuv420p", "-s", `${g.width}x${g.height}`, "-framerate", String(g.fps), "-i", "pipe:0",
+    "-probesize", "32", "-analyzeduration", "0", "-f", "s16le", "-ar", "48000", "-ac", "2", "-i", "pipe:3", "-map", "0:v", "-map", "1:a", "-f", "null", "-"],
+  [inputs.videoFd, "ignore", "pipe", inputs.audioFd], passthrough, (m) => process.stderr.write(m)) : null;
+  await nullEncoder?.started;
+  await gate.start();
+  const t0 = Date.now();
+  let current = await startProducer(gate, g, 20);
+  const firstTick = await gate.waitActive(current.id, 10_000);
+  await new Promise((r) => setTimeout(r, 1_000)); // encoder/producer warm-up excluded from peaks
+  await gate.resetPeaks();
+  const base = await gate.stats();
+  const swapMs: number[] = [];
+
+  if (mode === "steady") {
+    await new Promise((r) => setTimeout(r, Number(arg("seconds", "20")) * 1000));
+  } else {
+    const swaps = Number(arg("swaps", "1000"));
+    for (let i = 1; i <= swaps; i += 1) {
+      const s0 = performance.now();
+      const next = await startProducer(gate, g, 20 + (i % 200));
+      await gate.waitActive(next.id, 10_000);
+      swapMs.push(performance.now() - s0);
+      void current.proc.terminate();
+      current = next;
+    }
+  }
+  const end = await gate.stats();
+  await gate.stop();
+  await current.proc.terminate();
+  await new Promise((r) => setTimeout(r, 200));
+  await nullEncoder?.terminate();
+  let report: SinkReport | null = null;
+  if (verifier) {
+    verifier.child.stdin?.write(`REPORT ${firstTick}\n`);
+    await verifier.exited;
+    const line = verifierOut.split("\n").find((l) => l.startsWith("{"));
+    report = line ? (JSON.parse(line) as SinkReport) : null;
+  }
+  rmSync(scratch, { recursive: true, force: true });
+
+  const ticks = end.ticks - base.ticks;
+  const wallUs = end.wallUs - base.wallUs;
+  // Producer generation g has luma tag 20 + (g % 200); frames before the first producer are gate black (16).
+  const tags = (report?.tagChanges ?? []).map(([, t]) => t).filter((t, i) => !(i === 0 && t === 16));
+  let nonMonotonic = 0;
+  for (let i = 1; i < tags.length; i += 1) {
+    const prev = tags[i - 1] ?? 0;
+    if (tags[i] !== (prev === 219 ? 20 : prev + 1)) nonMonotonic += 1;
+  }
+  const result = {
+    mode, impl, sink: ffmpegSink ? "ffmpeg-null" : "node-verifier", copyWrites: process.argv.includes("--copy"), geometry: g, wallS: (Date.now() - t0) / 1000,
+    gateCpuPctOfCore: Number((((end.cpuUs - base.cpuUs) / wallUs) * 100).toFixed(2)),
+    ticks, swaps: end.swaps - base.swaps,
+    repeatsAfterFirstActive: end.vrep - base.vrep, silenceAfterFirstActive: end.asil - base.asil,
+    drops: end.drops, lateMaxUs: end.lateMaxUs, lateOverFrame: end.lateOverFrame, lateOver2ms: end.lateOver2ms, lateOver5ms: end.lateOver5ms, writeMaxUs: end.writeMaxUs,
+    gcMaxUs: end.gcMaxUs, poolAllocs: end.allocs, encoderBacklogMax: end.backlogMax, encoderOutDrops: end.outDrops,
+    verifier: report ? { ...report, tagChanges: report.tagChanges.length } : null,
+    sinkLockstep: report ? Math.abs(report.videoFrames - report.audioFrames) <= 1 : null,
+    tagSequenceViolations: nonMonotonic, distinctGenerationsSeen: tags.length,
+    swapLatencyMs: swapMs.length ? { p50: percentile(swapMs, 50), p99: percentile(swapMs, 99), max: Math.max(...swapMs) } : null,
+    events: events.slice(0, 40),
+  };
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exit(0);
+}
+
+if (require.main === module) void main().catch((error: unknown) => { process.stderr.write(`${String(error)}\n`); process.exit(1); });
diff --git a/apps/media-worker/src/main.ts b/apps/media-worker/src/main.ts
new file mode 100644
index 0000000..90eeefb
--- /dev/null
+++ b/apps/media-worker/src/main.ts
@@ -0,0 +1,101 @@
+import * as http from "node:http";
+import { readFileSync } from "node:fs";
+import { createHash, createPublicKey } from "node:crypto";
+import { resolve } from "node:path";
+import pino from "pino";
+import { DurableFence } from "./bus/fence";
+import { RedisBus } from "./bus/redis";
+import { FfmpegRelayJob, type EgressRelayFactory, type VaultHandleBroker } from "./relay/ffmpeg";
+import type { EndpointValidator } from "./relay/endpoints";
+import { MediaSupervisor, type RelayJob } from "./supervisor";
+import { ProductionJob, type AssetStore, type ProductionEgress } from "./compositor/production-job";
+import { resolveHelperBinary } from "./gate/binary";
+import { isDesiredChannel, type DesiredChannel } from "./types";
+
+const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
+const port = Number(process.env.PORT ?? 3100);
+const workerId = process.env.MEDIA_WORKER_ID ?? "media-worker-dev";
+let supervisor: MediaSupervisor | null = null;
+let bus: RedisBus | null = null;
+let ready = false;
+
+const server = http.createServer((req, res) => {
+  if (req.url === "/healthz") {
+    res.writeHead(ready ? 200 : 503, { "content-type": "application/json" });
+    res.end(JSON.stringify({ status: ready ? "alive" : "starting", worker: workerId, channels: supervisor?.status() ?? [] }));
+    return;
+  }
+  res.writeHead(404).end();
+});
+
+function readDesired(): DesiredChannel[] {
+  const path = process.env.MEDIA_DESIRED_CONFIG;
+  if (!path) return [];
+  const value: unknown = JSON.parse(readFileSync(path, "utf8"));
+  if (!Array.isArray(value) || !value.every(isDesiredChannel)) throw new Error("invalid desired channel config");
+  return value;
+}
+
+/** Deliberately fails closed until WP7 injects an egress relay and vault broker. */
+const unavailableEgress: EgressRelayFactory = { async prepare() { throw new Error("egress relay is not configured"); } };
+const unavailableValidator: EndpointValidator = { async validate() { throw new Error("endpoint validator is not configured"); } };
+const unavailableVault: VaultHandleBroker = { async deliverPushTarget() { throw new Error("vault broker is not configured"); } };
+const unavailableProductionEgress: ProductionEgress = { async prepare() { throw new Error("production egress is not configured"); } };
+const unavailableAssets: AssetStore = { async localPath() { throw new Error("overlay asset store is not configured"); } };
+const redactor = { redact: (_chunk: string) => "[media stderr redacted until a job secret-aware redactor is injected]" };
+
+/** Per-channel scratch for gate FIFOs; the name is a hash so channel ids never reach a path. */
+function scratchFor(channel: DesiredChannel): string {
+  const id = createHash("sha256").update(`${channel.workspaceId}:${channel.channelId}`).digest("hex").slice(0, 32);
+  return resolve(process.env.MEDIA_SCRATCH_DIR ?? ".media-worker-state/scratch", id);
+}
+
+/** v2 (production) snapshots run the compositor chain; v1 snapshots keep the single relay. */
+function createRelay(channel: DesiredChannel, onExit: (reason: string) => void): RelayJob {
+  const onStderr = (message: string): void => logger.warn({ message }, "ffmpeg stderr");
+  if (channel.production) {
+    return new ProductionJob({
+      validator: unavailableValidator, egress: unavailableProductionEgress, vault: unavailableVault, assets: unavailableAssets,
+      redactor, onStderr, onExit, scratchDir: scratchFor(channel),
+    });
+  }
+  return new FfmpegRelayJob(unavailableValidator, unavailableEgress, unavailableVault, redactor, onStderr, onExit);
+}
+
+/** Production channels need the packaged native helpers; say at boot which ones resolve (src/gate/binary.ts). */
+function checkHelpers(): void {
+  for (const name of ["frame-gate", "source-bus"] as const) {
+    try { logger.info({ helper: name, path: resolveHelperBinary(name) }, "native helper"); }
+    catch (error) { logger.warn({ helper: name, err: String(error) }, "native helper missing: production channels will fail to start"); }
+  }
+}
+
+async function start(): Promise<void> {
+  checkHelpers();
+  const desired = readDesired();
+  const keyPath = process.env.MEDIA_CONTROL_PUBLIC_KEY;
+  const keys = new Map<string, ReturnType<typeof createPublicKey>>();
+  if (keyPath) keys.set(process.env.MEDIA_CONTROL_KID ?? "control-v1", createPublicKey(readFileSync(keyPath)));
+  const fence = new DurableFence(process.env.MEDIA_FENCE_PATH ?? ".media-worker-state/fence.json");
+  bus = await RedisBus.connect(process.env.REDIS_URL ?? `redis://${process.env.REDIS_HOST ?? "localhost"}:6379`);
+  supervisor = new MediaSupervisor(workerId, desired, bus, fence, keys, createRelay,
+    { transition: (event) => logger.info(event, "media state transition") });
+  await supervisor.start();
+  const workspaces = [...new Set(desired.map((item) => item.workspaceId))];
+  for (const workspaceId of workspaces) {
+    // ACLs should grant only this worker's assigned command channels.
+    await bus.subscribe(workerId, [workspaceId], (message) => {
+      let command: unknown;
+      try { command = JSON.parse(message); } catch { logger.warn("malformed command rejected"); return; }
+      void supervisor?.handle(command).catch(() => logger.warn("command rejected"));
+    });
+  }
+  ready = true;
+  logger.info({ port, workerId, channels: desired.length }, "media worker listening");
+}
+
+server.listen(port, () => { void start().catch((error: unknown) => { logger.error({ err: String(error) }, "media worker startup failed"); process.exitCode = 1; server.close(); }); });
+for (const signal of ["SIGINT", "SIGTERM"] as const) process.on(signal, () => {
+  ready = false;
+  void supervisor?.stop().finally(() => { bus?.close(); server.close(); });
+});
diff --git a/apps/media-worker/src/preview/argv.ts b/apps/media-worker/src/preview/argv.ts
new file mode 100644
index 0000000..a59cdd5
--- /dev/null
+++ b/apps/media-worker/src/preview/argv.ts
@@ -0,0 +1,103 @@
+/**
+ * Preview tap argv (streaming-architecture.md §2.1). Typed params in, argv out,
+ * like MediaCommandBuilder: every tap reads raw frames from a source-bus
+ * subscription on inherited pipes (video fd 0, PCM fd 3) and never touches a
+ * remote; HLS taps write only into their own scratch directory.
+ *
+ * - JPEG: one still per `everySeconds` (the bus delivers every n-th pair), 360p,
+ *   as an mjpeg stream on stdout (the worker splits frames and publishes).
+ * - video: 360p ≤ 500 kb/s H.264 + AAC 64 kb/s, fMP4 HLS with 0.5 s parts and a
+ *   keyframe every second (each 1 s segment = 2 parts, the first independent).
+ * - audio: AAC 64 kb/s only, same part/segment grid.
+ *
+ * FFmpeg 5.1's hls muxer has no EXT-X-PART support, so ffmpeg writes the parts
+ * as its own 0.5 s "segments" (split_by_time) and `ll-hls.ts` publishes them as
+ * LL-HLS parts, concatenates them into segments and writes the media playlists.
+ */
+import { assertGeometry, GATE_CHANNELS, GATE_SAMPLE_RATE, type FrameGeometry } from "../gate/protocol";
+
+export const TAP_HEIGHT = 360;
+export const PART_SECONDS = 0.5;
+export const VIDEO_TAP_KBPS = 400;
+export const AUDIO_TAP_KBPS = 64;
+/** The 500 kb/s rendition budget includes its AAC audio. */
+export const VIDEO_TAP_MAX_KBPS = 500 - AUDIO_TAP_KBPS;
+/** H.264 Main@3.1 + AAC-LC (also supports the 360p60 production tap). */
+export const VIDEO_TAP_CODECS = "avc1.4d401f,mp4a.40.2";
+export const AUDIO_TAP_CODECS = "mp4a.40.2";
+
+const SCRATCH = /^\/[A-Za-z0-9._/-]+$/;
+
+function scratch(dir: string): string {
+  if (!SCRATCH.test(dir) || dir.split("/").includes("..")) throw new Error("tap output must be an absolute scratch path");
+  return dir;
+}
+
+function even(n: number): number { return Math.max(2, Math.round(n / 2) * 2); }
+
+/** 360p (or the source height, if smaller) at the canvas aspect, even dimensions. */
+export function tapSize(g: FrameGeometry): { width: number; height: number } {
+  const height = Math.min(TAP_HEIGHT, g.height);
+  return { width: even((height * g.width) / g.height), height: even(height) };
+}
+
+/** Geometry of the program tap bus (the persistent encoder downscales once, §2.1 "program tap"). */
+export function programTapGeometry(canvas: FrameGeometry): FrameGeometry {
+  return { ...tapSize(canvas), fps: canvas.fps };
+}
+
+function rawVideoIn(g: FrameGeometry, rate: string): string[] {
+  return ["-thread_queue_size", "64", "-probesize", "32", "-analyzeduration", "0",
+    "-f", "rawvideo", "-pix_fmt", "yuv420p", "-s", `${g.width}x${g.height}`, "-framerate", rate, "-i", "pipe:0"];
+}
+
+function rawAudioIn(): string[] {
+  return ["-thread_queue_size", "64", "-probesize", "32", "-analyzeduration", "0",
+    "-f", "s16le", "-ar", String(GATE_SAMPLE_RATE), "-ac", String(GATE_CHANNELS), "-i", "pipe:3"];
+}
+
+function scale(g: FrameGeometry): string {
+  const { width, height } = tapSize(g);
+  return width === g.width && height === g.height ? "format=yuv420p" : `scale=${width}:${height}:flags=bilinear,format=yuv420p`;
+}
+
+export interface JpegTapPlan { geometry: FrameGeometry; everySeconds: number }
+
+/** Pairs the bus skips between stills (subscription `stride`). */
+export function jpegStride(plan: JpegTapPlan): number { return plan.everySeconds * plan.geometry.fps; }
+
+export function buildJpegTapArgs(plan: JpegTapPlan): string[] {
+  assertGeometry(plan.geometry);
+  if (!Number.isSafeInteger(plan.everySeconds) || plan.everySeconds < 1 || plan.everySeconds > 10) throw new Error("thumbnail cadence must be 1-10 s");
+  // The input runs at one frame per `everySeconds`, so every input frame becomes one still.
+  return ["-hide_banner", "-nostdin", "-loglevel", "error", ...rawVideoIn(plan.geometry, `1/${plan.everySeconds}`),
+    "-vf", scale(plan.geometry), "-c:v", "mjpeg", "-q:v", "5", "-f", "image2pipe", "pipe:1"];
+}
+
+export type HlsRendition = "video" | "audio";
+
+export interface HlsTapPlan { geometry: FrameGeometry; rendition: HlsRendition; outDir: string }
+
+/** ffmpeg's own playlist of parts (read by the packager, never published). */
+export const PARTS_PLAYLIST = "parts.m3u8";
+
+export function buildHlsTapArgs(plan: HlsTapPlan): string[] {
+  const g = plan.geometry;
+  assertGeometry(g);
+  const dir = scratch(plan.outDir);
+  const args = ["-hide_banner", "-nostdin", "-loglevel", "error"];
+  if (plan.rendition === "video") {
+    args.push(...rawVideoIn(g, String(g.fps)), ...rawAudioIn(), "-map", "0:v", "-map", "1:a", "-vf", scale(g),
+      "-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency", "-profile:v", "main", "-level:v", "3.1",
+      "-b:v", `${VIDEO_TAP_KBPS}k`, "-maxrate", `${VIDEO_TAP_MAX_KBPS}k`, "-bufsize", `${VIDEO_TAP_MAX_KBPS}k`,
+      // Keyframe exactly every second, never on scene cuts: parts alternate independent/dependent.
+      "-g", String(g.fps), "-keyint_min", String(g.fps), "-sc_threshold", "0");
+  } else {
+    args.push(...rawAudioIn(), "-map", "0:a");
+  }
+  args.push("-c:a", "aac", "-b:a", `${AUDIO_TAP_KBPS}k`, "-ac", "2", "-ar", String(GATE_SAMPLE_RATE),
+    "-f", "hls", "-hls_time", String(PART_SECONDS), "-hls_list_size", "12", "-hls_segment_type", "fmp4",
+    "-hls_fmp4_init_filename", "init.mp4", "-hls_flags", "split_by_time+temp_file+delete_segments+omit_endlist",
+    "-hls_segment_filename", `${dir}/p%d.m4s`, "-protocol_whitelist", "file", `${dir}/${PARTS_PLAYLIST}`);
+  return args;
+}
diff --git a/apps/media-worker/src/preview/contract.ts b/apps/media-worker/src/preview/contract.ts
new file mode 100644
index 0000000..e99960d
--- /dev/null
+++ b/apps/media-worker/src/preview/contract.ts
@@ -0,0 +1,85 @@
+/**
+ * Worker side of the preview contract (streaming-architecture.md §2.1).
+ *
+ * The API owns serving: `apps/api/src/production/preview.ts` mints signed,
+ * path-bound capability URLs (60 s TTL), verifies them, single-flights fills,
+ * keeps a 6-object LRU per tap, sets `ETag` from the body hash, rewrites HLS
+ * URIs to signed same-origin paths, and never redirects to S3. The worker does
+ * none of that. It only *publishes*: each preview file is stored as a
+ * content-addressed object and announced by a Redis manifest
+ *
+ *     preview:<workspaceId>:<channelId>:<tap>:<file>  →  {"key":"sha256/<hex>.<ext>","contentType":...}
+ *
+ * which is exactly what the API's `fill()` reads. `preview.contract.test.ts`
+ * checks the constants below against the API source so the two cannot drift.
+ */
+import { createHash } from "node:crypto";
+
+/** The API's preview file-name rule (also the only names its HLS rewriter accepts). */
+export const PREVIEW_FILE = /^(?:[A-Za-z0-9_-]+\.(?:m3u8|m4s|ts|aac|jpg|jpeg|mp4))$/;
+/** The API's manifest object-key rule. */
+export const PREVIEW_OBJECT_KEY = /^sha256\/[0-9a-f]{64}\.[a-z0-9]+$/;
+/** Content types the API accepts in a manifest (subset the worker produces). */
+export type PreviewContentType = "image/jpeg" | "application/vnd.apple.mpegurl" | "video/mp4" | "audio/mp4";
+export const PREVIEW_CONTENT_TYPES: readonly PreviewContentType[] = ["image/jpeg", "application/vnd.apple.mpegurl", "video/mp4", "audio/mp4"];
+
+/** Files the API hands out capability URLs for (`PreviewService.urls`). */
+export const THUMBNAIL_FILE = "thumbnail.jpg";
+export const VIDEO_PLAYLIST = "video.m3u8";
+export const AUDIO_PLAYLIST = "audio.m3u8";
+/** Multivariant playlist over the two renditions (servable by the same route; not in `urls()` yet). */
+export const MASTER_PLAYLIST = "master.m3u8";
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+/** A tap is the channel's program, or one of its sources (virtual_channel_sources.id), as the API's controller accepts. */
+export function assertTapId(tap: string): void {
+  if (tap !== "program" && !UUID.test(tap)) throw new Error("preview tap must be 'program' or a source UUID");
+}
+
+export interface PreviewChannel { workspaceId: string; channelId: string }
+
+export function previewManifestKey(channel: PreviewChannel, tap: string, file: string): string {
+  if (!UUID.test(channel.workspaceId) || !UUID.test(channel.channelId)) throw new Error("preview channel ids must be UUIDs");
+  assertTapId(tap);
+  if (!PREVIEW_FILE.test(file)) throw new Error("invalid preview file name");
+  return `preview:${channel.workspaceId}:${channel.channelId}:${tap}:${file}`;
+}
+
+/** Content-addressed object storage (the API's S3 storage with envelope encryption, or a test double). */
+export interface PreviewObjectStore { putContent(body: Buffer, contentType: PreviewContentType): Promise<{ key: string }> }
+/** The manifest store the API reads (Redis `SET key value EX ttl`). */
+export interface PreviewManifestStore { set(key: string, value: string, ttlSeconds: number): Promise<void> }
+
+export interface PreviewPublisher {
+  /** Store `body` and point the tap's `file` at it for `ttlSeconds`. */
+  publish(tap: string, file: string, body: Buffer, contentType: PreviewContentType, ttlSeconds: number): Promise<void>;
+}
+
+/**
+ * Publisher over the API's storage + manifest contract. Re-publishing an
+ * unchanged body (an init segment kept alive, a still thumbnail) only renews
+ * the manifest; the object is already stored under its hash.
+ */
+export class ManifestPreviewPublisher implements PreviewPublisher {
+  private readonly stored = new Map<string, string>();
+
+  constructor(private readonly channel: PreviewChannel, private readonly objects: PreviewObjectStore, private readonly manifests: PreviewManifestStore) {}
+
+  async publish(tap: string, file: string, body: Buffer, contentType: PreviewContentType, ttlSeconds: number): Promise<void> {
+    const manifestKey = previewManifestKey(this.channel, tap, file);
+    if (!PREVIEW_CONTENT_TYPES.includes(contentType)) throw new Error("unsupported preview content type");
+    if (body.length === 0 || body.length > 4_000_000) throw new Error("preview object size out of range");
+    if (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 1 || ttlSeconds > 86_400) throw new Error("preview ttl out of range");
+    const hash = createHash("sha256").update(body).update(contentType).digest("hex");
+    let key = this.stored.get(hash);
+    if (!key) {
+      key = (await this.objects.putContent(body, contentType)).key;
+      if (!PREVIEW_OBJECT_KEY.test(key)) throw new Error("object store returned an invalid key");
+      this.stored.set(hash, key);
+      // Hash → key only matters for recent bodies (renewals); bound the map.
+      if (this.stored.size > 512) this.stored.delete(this.stored.keys().next().value ?? "");
+    }
+    await this.manifests.set(manifestKey, JSON.stringify({ key, contentType }), ttlSeconds);
+  }
+}
diff --git a/apps/media-worker/src/preview/ll-hls.ts b/apps/media-worker/src/preview/ll-hls.ts
new file mode 100644
index 0000000..7e0f538
--- /dev/null
+++ b/apps/media-worker/src/preview/ll-hls.ts
@@ -0,0 +1,207 @@
+/**
+ * LL-HLS packaging for preview taps (streaming-architecture.md §2.1, §2.2).
+ *
+ * ffmpeg (argv.ts) writes 0.5 s fMP4 fragments and lists them in its own
+ * playlist. This module turns them into an LL-HLS media playlist:
+ *
+ * - every fragment is published as an `EXT-X-PART` (`INDEPENDENT=YES` when its
+ *   first video sample is a sync sample, read from the `moof`);
+ * - consecutive parts from one independent part to the next form a segment,
+ *   published as the parts' concatenation (fMP4 fragments concatenate);
+ * - media sequence numbers start at the wall-clock millisecond the tap started, so
+ *   they keep increasing across tap restarts (on-demand taps stop when idle)
+ *   and file names never collide with a previous run's still-cached manifests.
+ *
+ * There is no blocking playlist reload (`CAN-BLOCK-RELOAD`): the API serves
+ * stored objects with a 1 s cache, so players poll; hls.js `lowLatencyMode`
+ * still uses the parts and `PART-HOLD-BACK`.
+ */
+import { PART_SECONDS, type HlsRendition } from "./argv";
+
+// ---------------------------------------------------------------------------
+// fMP4 fragment inspection
+
+function boxes(buf: Buffer, start: number, end: number): Array<{ type: string; at: number; size: number }> {
+  const out: Array<{ type: string; at: number; size: number }> = [];
+  let at = start;
+  while (at + 8 <= end) {
+    let size = buf.readUInt32BE(at);
+    const type = buf.toString("latin1", at + 4, at + 8);
+    let header = 8;
+    if (size === 1) {
+      if (at + 16 > end) break;
+      size = Number(buf.readBigUInt64BE(at + 8));
+      header = 16;
+    } else if (size === 0) {
+      size = end - at;
+    }
+    if (size < header || at + size > end) break;
+    out.push({ type, at, size });
+    at += size;
+  }
+  return out;
+}
+
+const NON_SYNC = 0x10000;
+
+/** First-sample flags of one `traf`: trun first_sample_flags, else trun sample[0] flags, else tfhd default flags. */
+function firstSampleFlags(buf: Buffer, traf: { at: number; size: number }): number | null {
+  let defaults: number | null = null;
+  for (const child of boxes(buf, traf.at + 8, traf.at + traf.size)) {
+    const flags = buf.readUInt32BE(child.at + 8) & 0xffffff;
+    if (child.type === "tfhd") {
+      let p = child.at + 16; // version/flags, track_ID
+      if (flags & 0x1) p += 8; // base_data_offset
+      if (flags & 0x2) p += 4; // sample_description_index
+      if (flags & 0x8) p += 4; // default_sample_duration
+      if (flags & 0x10) p += 4; // default_sample_size
+      if (flags & 0x20 && p + 4 <= child.at + child.size) defaults = buf.readUInt32BE(p);
+    } else if (child.type === "trun") {
+      let p = child.at + 16; // version/flags, sample_count
+      if (flags & 0x1) p += 4; // data_offset
+      if (flags & 0x4) return buf.readUInt32BE(p);
+      if (flags & 0x400) {
+        if (flags & 0x100) p += 4; // sample_duration
+        if (flags & 0x200) p += 4; // sample_size
+        return buf.readUInt32BE(p);
+      }
+    }
+  }
+  return defaults;
+}
+
+/**
+ * Whether a fragment can start playback: every track's first sample is a sync
+ * sample. Unknown flags (no trun/tfhd information) count as not independent.
+ */
+export function fragmentIndependent(buf: Buffer): boolean {
+  let trafs = 0;
+  for (const top of boxes(buf, 0, buf.length)) {
+    if (top.type !== "moof") continue;
+    for (const traf of boxes(buf, top.at + 8, top.at + top.size)) {
+      if (traf.type !== "traf") continue;
+      trafs += 1;
+      const flags = firstSampleFlags(buf, traf);
+      if (flags === null || (flags & NON_SYNC) !== 0) return false;
+    }
+  }
+  return trafs > 0;
+}
+
+// ---------------------------------------------------------------------------
+// ffmpeg's part playlist
+
+export interface FfmpegPart { file: string; duration: number }
+
+/** Parts listed in ffmpeg's playlist (`#EXTINF:<d>,` then the file name). */
+export function parseFfmpegPlaylist(text: string): FfmpegPart[] {
+  const parts: FfmpegPart[] = [];
+  let duration: number | null = null;
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (line.startsWith("#EXTINF:")) duration = Number.parseFloat(line.slice(8));
+    else if (line !== "" && !line.startsWith("#") && duration !== null) {
+      if (/^p\d+\.m4s$/.test(line) && Number.isFinite(duration) && duration > 0) parts.push({ file: line, duration });
+      duration = null;
+    }
+  }
+  return parts;
+}
+
+// ---------------------------------------------------------------------------
+// LL-HLS media playlist
+
+export interface PublishedPart { name: string; duration: number; independent: boolean; bytes: Buffer }
+export interface ClosedSegment { msn: number; name: string; duration: number; parts: PublishedPart[] }
+
+/** Segments listed in the playlist; parts are listed for the last `PART_SEGMENTS` of them plus the open one. */
+const WINDOW_SEGMENTS = 4;
+const PART_SEGMENTS = 2;
+
+function fmt(n: number): string { return n.toFixed(5); }
+
+/**
+ * File names: `<v|a>init<base>.mp4`, segments `<v|a>s<msn>.m4s`, parts `<v|a>p<msn>_<i>.m4s`
+ * (all within the API's preview file-name rule).
+ */
+export class LlHlsPackager {
+  readonly prefix: string;
+  readonly initName: string;
+  private msn: number;
+  private open: PublishedPart[] = [];
+  private segments: ClosedSegment[] = [];
+
+  constructor(rendition: HlsRendition, readonly base: number) {
+    if (!Number.isSafeInteger(base) || base < 0) throw new Error("media sequence base must be a non-negative integer");
+    this.prefix = rendition === "video" ? "v" : "a";
+    this.initName = `${this.prefix}init${base}.mp4`;
+    this.msn = base;
+  }
+
+  /** Name the next part will be published under (it belongs to the open segment). */
+  private partName(): string { return `${this.prefix}p${this.msn}_${this.open.length}.m4s`; }
+
+  /**
+   * Adds the next fragment. Returns the part to publish (null for a dependent fragment before the
+   * first keyframe, which is dropped: a stream starts at an independent part) and, when this part
+   * starts a new segment, the segment it closed. Publish both before the playlist.
+   */
+  add(fragment: { duration: number; independent: boolean; bytes: Buffer }): { part: PublishedPart | null; closed: ClosedSegment | null } {
+    let closed: ClosedSegment | null = null;
+    if (fragment.independent && this.open.length > 0) {
+      closed = {
+        msn: this.msn, name: `${this.prefix}s${this.msn}.m4s`, parts: this.open,
+        duration: this.open.reduce((a, p) => a + p.duration, 0),
+      };
+      this.segments.push(closed);
+      while (this.segments.length > WINDOW_SEGMENTS) this.segments.shift();
+      this.msn += 1;
+      this.open = [];
+    }
+    if (this.open.length === 0 && !fragment.independent) return { part: null, closed };
+    const part: PublishedPart = { name: this.partName(), ...fragment };
+    this.open.push(part);
+    return { part, closed };
+  }
+
+  static segmentBytes(segment: ClosedSegment): Buffer { return Buffer.concat(segment.parts.map((p) => p.bytes)); }
+
+  /** null until the first segment has closed (a player needs at least one full segment). */
+  playlist(): string | null {
+    if (this.segments.length === 0) return null;
+    const first = this.segments[0]!;
+    const target = Math.max(1, ...this.segments.map((s) => Math.ceil(s.duration)));
+    const partTarget = Math.max(PART_SECONDS, ...this.segments.flatMap((s) => s.parts.map((p) => p.duration)), ...this.open.map((p) => p.duration));
+    const lines = [
+      "#EXTM3U",
+      "#EXT-X-VERSION:7",
+      `#EXT-X-TARGETDURATION:${target}`,
+      `#EXT-X-SERVER-CONTROL:PART-HOLD-BACK=${fmt(3 * partTarget)}`,
+      `#EXT-X-PART-INF:PART-TARGET=${fmt(partTarget)}`,
+      `#EXT-X-MEDIA-SEQUENCE:${first.msn}`,
+      "#EXT-X-INDEPENDENT-SEGMENTS",
+      `#EXT-X-MAP:URI="${this.initName}"`,
+    ];
+    const partLine = (p: PublishedPart): string => `#EXT-X-PART:DURATION=${fmt(p.duration)},URI="${p.name}"${p.independent ? ",INDEPENDENT=YES" : ""}`;
+    this.segments.forEach((s, i) => {
+      if (i >= this.segments.length - PART_SEGMENTS) for (const p of s.parts) lines.push(partLine(p));
+      lines.push(`#EXTINF:${fmt(s.duration)},`, s.name);
+    });
+    for (const p of this.open) lines.push(partLine(p));
+    return `${lines.join("\n")}\n`;
+  }
+}
+
+/** Multivariant playlist over a tap's two renditions (§2.1: 360p video+audio, audio-only). */
+export function masterPlaylist(video: { width: number; height: number; bandwidth: number; codecs: string }, audio: { bandwidth: number; codecs: string }): string {
+  return [
+    "#EXTM3U",
+    "#EXT-X-VERSION:7",
+    "#EXT-X-INDEPENDENT-SEGMENTS",
+    `#EXT-X-STREAM-INF:BANDWIDTH=${video.bandwidth},RESOLUTION=${video.width}x${video.height},CODECS="${video.codecs}"`,
+    "video.m3u8",
+    `#EXT-X-STREAM-INF:BANDWIDTH=${audio.bandwidth},CODECS="${audio.codecs}"`,
+    "audio.m3u8",
+    "",
+  ].join("\n");
+}
diff --git a/apps/media-worker/src/preview/preview.test.ts b/apps/media-worker/src/preview/preview.test.ts
new file mode 100644
index 0000000..96a2e34
--- /dev/null
+++ b/apps/media-worker/src/preview/preview.test.ts
@@ -0,0 +1,305 @@
+/**
+ * Preview taps (streaming-architecture.md §2.1): the API contract mirror, argv
+ * goldens, fMP4/LL-HLS packaging, and the JPEG / video / audio tap lifecycle on
+ * a real source bus, plus the program tap's isolation from the encoder.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+import { buildEncoderArgs } from "../compositor/command-builder";
+import { ProgramChain } from "../compositor/program";
+import { CounterSource, ensureGateBinary, passthroughRedactor } from "../compositor/testing";
+import { buildHlsTapArgs, buildJpegTapArgs, jpegStride, programTapGeometry, tapSize } from "./argv";
+import {
+  ManifestPreviewPublisher, PREVIEW_CONTENT_TYPES, PREVIEW_FILE, PREVIEW_OBJECT_KEY, previewManifestKey,
+  type PreviewContentType, type PreviewPublisher,
+} from "./contract";
+import { fragmentIndependent, LlHlsPackager, masterPlaylist, parseFfmpegPlaylist } from "./ll-hls";
+import { JpegSplitter, PreviewTaps, TTL } from "./taps";
+
+const WS = "8f0c5a8e-3b1d-4c3e-9a5b-0c1d2e3f4a5b";
+const CH = "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d";
+const SRC = "9e8d7c6b-5a4f-4e3d-a2c1-b0a9f8e7d6c5";
+const small = { width: 320, height: 180, fps: 30 };
+
+test("worker preview contract mirrors the API preview service (file rule, manifest key, object key, types)", () => {
+  const api = readFileSync(resolve(__dirname, "../../../api/src/production/preview.ts"), "utf8");
+  const file = /const FILE = \/(.+)\/;/.exec(api)?.[1];
+  assert.equal(file, PREVIEW_FILE.source, "file-name rule");
+  assert.ok(api.includes("`preview:${ws}:${ch}:${tap}:${file}`"), "manifest key layout");
+  assert.ok(api.includes(PREVIEW_OBJECT_KEY.source.replace(/\\\//g, "\\/")), "object key rule");
+  const types = /const TYPES = new Set\(\[(.+)\]\);/.exec(api)?.[1] ?? "";
+  for (const t of PREVIEW_CONTENT_TYPES) assert.ok(types.includes(`"${t}"`), `API accepts ${t}`);
+  // Every name the worker publishes passes the API's rule (the HLS rewriter rejects anything else).
+  const video = new LlHlsPackager("video", 1_700_000_000);
+  for (const name of ["thumbnail.jpg", "video.m3u8", "audio.m3u8", "master.m3u8", video.initName, "vs1700000000.m4s", "vp1700000000_1.m4s", "ainit1700000000.mp4"]) {
+    assert.ok(PREVIEW_FILE.test(name), name);
+  }
+  assert.equal(previewManifestKey({ workspaceId: WS, channelId: CH }, "program", "thumbnail.jpg"), `preview:${WS}:${CH}:program:thumbnail.jpg`);
+  assert.throws(() => previewManifestKey({ workspaceId: WS, channelId: CH }, "../x", "thumbnail.jpg"));
+  assert.throws(() => previewManifestKey({ workspaceId: WS, channelId: CH }, SRC, "../../etc.jpg"));
+  assert.throws(() => previewManifestKey({ workspaceId: "workspace-1", channelId: CH }, SRC, "thumbnail.jpg"));
+});
+
+test("ManifestPreviewPublisher stores content-addressed objects and renews manifests without re-uploading", async () => {
+  const puts: string[] = [];
+  const manifests = new Map<string, { value: string; ttl: number }>();
+  const publisher = new ManifestPreviewPublisher({ workspaceId: WS, channelId: CH },
+    { async putContent(body, contentType) { puts.push(contentType); return { key: `sha256/${"a".repeat(63)}${puts.length}.jpg` }; } },
+    { async set(key, value, ttl) { manifests.set(key, { value, ttl }); } });
+  await publisher.publish("program", "thumbnail.jpg", Buffer.from("jpeg-1"), "image/jpeg", 30);
+  await publisher.publish("program", "thumbnail.jpg", Buffer.from("jpeg-1"), "image/jpeg", 30);
+  assert.equal(puts.length, 1, "an unchanged body is stored once");
+  await publisher.publish("program", "thumbnail.jpg", Buffer.from("jpeg-2"), "image/jpeg", 30);
+  assert.equal(puts.length, 2);
+  const m = manifests.get(`preview:${WS}:${CH}:program:thumbnail.jpg`);
+  assert.deepEqual(JSON.parse(m?.value ?? "{}"), { key: `sha256/${"a".repeat(63)}2.jpg`, contentType: "image/jpeg" });
+  assert.equal(m?.ttl, 30);
+  await assert.rejects(publisher.publish("program", "x.exe", Buffer.from("x"), "image/jpeg", 30));
+  await assert.rejects(publisher.publish("program", "a.jpg", Buffer.alloc(0), "image/jpeg", 30));
+  const bad = new ManifestPreviewPublisher({ workspaceId: WS, channelId: CH }, { async putContent() { return { key: "https://evil/x" }; } }, { async set() {} });
+  await assert.rejects(bad.publish("program", "a.jpg", Buffer.from("x"), "image/jpeg", 30), /invalid key/);
+});
+
+test("tap argv goldens: JPEG, video and audio LL-HLS read only inherited pipes and their scratch dir", () => {
+  const hd = { width: 1920, height: 1080, fps: 30 };
+  assert.deepEqual(tapSize(hd), { width: 640, height: 360 });
+  assert.deepEqual(tapSize({ width: 1280, height: 720, fps: 30 }), { width: 640, height: 360 });
+  assert.deepEqual(programTapGeometry(hd), { width: 640, height: 360, fps: 30 });
+  assert.equal(jpegStride({ geometry: hd, everySeconds: 2 }), 60);
+  const raw = ["-thread_queue_size", "64", "-probesize", "32", "-analyzeduration", "0"];
+  assert.deepEqual(buildJpegTapArgs({ geometry: hd, everySeconds: 2 }), ["-hide_banner", "-nostdin", "-loglevel", "error",
+    ...raw, "-f", "rawvideo", "-pix_fmt", "yuv420p", "-s", "1920x1080", "-framerate", "1/2", "-i", "pipe:0",
+    "-vf", "scale=640:360:flags=bilinear,format=yuv420p", "-c:v", "mjpeg", "-q:v", "5", "-f", "image2pipe", "pipe:1"]);
+  const hlsTail = (dir: string) => ["-c:a", "aac", "-b:a", "64k", "-ac", "2", "-ar", "48000",
+    "-f", "hls", "-hls_time", "0.5", "-hls_list_size", "12", "-hls_segment_type", "fmp4", "-hls_fmp4_init_filename", "init.mp4",
+    "-hls_flags", "split_by_time+temp_file+delete_segments+omit_endlist", "-hls_segment_filename", `${dir}/p%d.m4s`, "-protocol_whitelist", "file", `${dir}/parts.m3u8`];
+  assert.deepEqual(buildHlsTapArgs({ geometry: hd, rendition: "video", outDir: "/scratch/t/v" }), ["-hide_banner", "-nostdin", "-loglevel", "error",
+    ...raw, "-f", "rawvideo", "-pix_fmt", "yuv420p", "-s", "1920x1080", "-framerate", "30", "-i", "pipe:0",
+    ...raw, "-f", "s16le", "-ar", "48000", "-ac", "2", "-i", "pipe:3", "-map", "0:v", "-map", "1:a",
+    "-vf", "scale=640:360:flags=bilinear,format=yuv420p", "-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency", "-profile:v", "main", "-level:v", "3.1",
+    "-b:v", "400k", "-maxrate", "436k", "-bufsize", "436k", "-g", "30", "-keyint_min", "30", "-sc_threshold", "0", ...hlsTail("/scratch/t/v")]);
+  assert.deepEqual(buildHlsTapArgs({ geometry: programTapGeometry(hd), rendition: "audio", outDir: "/scratch/t/a" }), ["-hide_banner", "-nostdin", "-loglevel", "error",
+    ...raw, "-f", "s16le", "-ar", "48000", "-ac", "2", "-i", "pipe:3", "-map", "0:a", ...hlsTail("/scratch/t/a")]);
+  // The 360p program bus is not scaled again.
+  assert.ok(buildJpegTapArgs({ geometry: programTapGeometry(hd), everySeconds: 1 }).includes("format=yuv420p"));
+  for (const bad of ["relative/dir", "/scratch/../etc", "/scratch/t;rm"]) assert.throws(() => buildHlsTapArgs({ geometry: hd, rendition: "audio", outDir: bad }), bad);
+  for (const s of [0, 11, 1.5]) assert.throws(() => buildJpegTapArgs({ geometry: hd, everySeconds: s }));
+  const argv = [...buildJpegTapArgs({ geometry: hd, everySeconds: 2 }), ...buildHlsTapArgs({ geometry: hd, rendition: "video", outDir: "/s/v" })].join(" ");
+  assert.ok(!/https?:|rtmp|tcp:|udp:|concat|movie=/.test(argv), "no network or concat protocols");
+});
+
+test("encoder program tap: split + 360p tee outputs with a null anchor slave, main path unchanged", () => {
+  const canvas = { width: 1920, height: 1080, fps: 30 };
+  const plain = buildEncoderArgs({ canvas, videoBitrateKbps: 6000, audioBitrateKbps: 128, output: { kind: "flvPipe", fd: 4 } });
+  const tapped = buildEncoderArgs({ canvas, videoBitrateKbps: 6000, audioBitrateKbps: 128, output: { kind: "flvPipe", fd: 4 }, programTap: { videoFd: 5, audioFd: 6, size: { width: 640, height: 360 } } });
+  assert.ok(!plain.includes("-filter_complex") && plain.includes("0:v"));
+  assert.equal(tapped[tapped.indexOf("-filter_complex") + 1], "[0:v]split=2[enc][tap];[tap]scale=640:360:flags=bilinear,format=yuv420p[tapv];[1:a]asplit=2[enca][tapa]");
+  assert.deepEqual(tapped.slice(-16), ["-f", "flv", "pipe:4",
+    "-map", "[tapv]", "-c:v", "rawvideo", "-f", "tee", "[f=rawvideo:onfail=ignore]pipe:5|[f=null]-",
+    "-map", "[tapa]", "-c:a", "pcm_s16le", "-f", "tee", "[f=s16le:onfail=ignore]pipe:6|[f=null]-"].slice(-16));
+  // Encoding options of the main output are identical with and without the tap.
+  const opts = (a: string[]) => a.slice(a.indexOf("-c:v"), a.indexOf("-f", a.indexOf("-c:v")));
+  assert.deepEqual(opts(tapped), opts(plain));
+  assert.throws(() => buildEncoderArgs({ canvas, videoBitrateKbps: 6000, audioBitrateKbps: 128, output: { kind: "null" }, programTap: { videoFd: 5, audioFd: 6, size: { width: 641, height: 360 } } }));
+});
+
+test("fMP4 independence from moof sample flags on real ffmpeg parts (keyframe every 2nd part)", () => {
+  const dir = mkdtempSync(join(tmpdir(), "fmp4-"));
+  try {
+    const r = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=s=320x180:r=30:d=3", "-f", "lavfi", "-i", "sine=d=3",
+      // Same GOP shape as the video tap (zerolatency: no B-frames, so 0.5 s splits are exact).
+      "-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency", "-g", "30", "-keyint_min", "30", "-sc_threshold", "0", "-c:a", "aac", "-b:a", "64k",
+      "-f", "hls", "-hls_time", "0.5", "-hls_list_size", "0", "-hls_segment_type", "fmp4", "-hls_flags", "split_by_time+temp_file",
+      "-hls_segment_filename", `${dir}/p%d.m4s`, `${dir}/parts.m3u8`]);
+    assert.equal(r.status, 0);
+    const parts = parseFfmpegPlaylist(readFileSync(join(dir, "parts.m3u8"), "utf8"));
+    assert.ok(parts.length >= 5, `parts ${parts.length}`);
+    assert.ok(parts.slice(0, -1).every((p) => Math.abs(p.duration - 0.5) < 0.01), "0.5 s parts");
+    const flags = parts.map((p) => fragmentIndependent(readFileSync(join(dir, p.file))));
+    assert.deepEqual(flags.slice(0, 6), [true, false, true, false, true, false]);
+    assert.equal(fragmentIndependent(Buffer.from("not an mp4")), false);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("LL-HLS packager: parts, segments at independent parts, monotonic sequence, bounded window", () => {
+  const p = new LlHlsPackager("video", 100);
+  const frag = (independent: boolean) => ({ duration: 0.5, independent, bytes: Buffer.from(independent ? "K" : "d") });
+  assert.equal(p.add(frag(false)).part, null, "a stream starts at an independent part");
+  assert.equal(p.playlist(), null, "no playlist before the first full segment");
+  const first = p.add(frag(true));
+  assert.equal(first.part?.name, "vp100_0.m4s");
+  assert.equal(p.add(frag(false)).part?.name, "vp100_1.m4s");
+  const third = p.add(frag(true));
+  assert.equal(third.closed?.name, "vs100.m4s");
+  assert.equal(third.part?.name, "vp101_0.m4s");
+  assert.equal(LlHlsPackager.segmentBytes(third.closed!).toString(), "Kd");
+  assert.equal(p.playlist(), ["#EXTM3U", "#EXT-X-VERSION:7", "#EXT-X-TARGETDURATION:1", "#EXT-X-SERVER-CONTROL:PART-HOLD-BACK=1.50000",
+    "#EXT-X-PART-INF:PART-TARGET=0.50000", "#EXT-X-MEDIA-SEQUENCE:100", "#EXT-X-INDEPENDENT-SEGMENTS", '#EXT-X-MAP:URI="vinit100.mp4"',
+    '#EXT-X-PART:DURATION=0.50000,URI="vp100_0.m4s",INDEPENDENT=YES', '#EXT-X-PART:DURATION=0.50000,URI="vp100_1.m4s"',
+    "#EXTINF:1.00000,", "vs100.m4s", '#EXT-X-PART:DURATION=0.50000,URI="vp101_0.m4s",INDEPENDENT=YES', ""].join("\n"));
+  for (let i = 0; i < 20; i += 1) p.add(frag(i % 2 === 1));
+  const text = p.playlist() ?? "";
+  assert.equal((text.match(/#EXTINF/g) ?? []).length, 4, "four segments in the window");
+  assert.match(text, /#EXT-X-MEDIA-SEQUENCE:107/);
+  assert.equal((text.match(/#EXT-X-PART:/g) ?? []).length, 2 * 2 + 1, "parts only for the last two segments + the open one");
+  assert.match(new LlHlsPackager("audio", 5).initName, /^ainit5\.mp4$/);
+  assert.equal(masterPlaylist({ width: 640, height: 360, bandwidth: 564000, codecs: "avc1.4d401e,mp4a.40.2" }, { bandwidth: 64000, codecs: "mp4a.40.2" }),
+    '#EXTM3U\n#EXT-X-VERSION:7\n#EXT-X-INDEPENDENT-SEGMENTS\n#EXT-X-STREAM-INF:BANDWIDTH=564000,RESOLUTION=640x360,CODECS="avc1.4d401e,mp4a.40.2"\nvideo.m3u8\n#EXT-X-STREAM-INF:BANDWIDTH=64000,CODECS="mp4a.40.2"\naudio.m3u8\n');
+});
+
+test("JPEG splitter yields whole stills across chunk boundaries", () => {
+  const a = Buffer.from([0xff, 0xd8, 1, 2, 0xff, 0x00, 3, 0xff, 0xd9]);
+  const b = Buffer.from([0xff, 0xd8, 9, 0xff, 0xd9]);
+  const s = new JpegSplitter();
+  const all = Buffer.concat([Buffer.from([7]), a, b]);
+  const got = [...s.push(all.subarray(0, 4)), ...s.push(all.subarray(4, 11)), ...s.push(all.subarray(11))];
+  assert.deepEqual(got, [a, b]);
+});
+
+class MemoryPublisher implements PreviewPublisher {
+  readonly files = new Map<string, { body: Buffer; contentType: PreviewContentType; ttl: number; at: number }>();
+  async publish(tap: string, file: string, body: Buffer, contentType: PreviewContentType, ttlSeconds: number): Promise<void> {
+    assert.ok(PREVIEW_FILE.test(file), file);
+    this.files.set(`${tap}/${file}`, { body, contentType, ttl: ttlSeconds, at: Date.now() });
+  }
+}
+
+async function until(cond: () => boolean, ms: number, what: string): Promise<void> {
+  const t0 = Date.now();
+  while (!cond()) {
+    if (Date.now() - t0 > ms) throw new Error(`timeout: ${what}`);
+    await new Promise((r) => setTimeout(r, 50));
+  }
+}
+
+test("tap lifecycle on a live bus: JPEG always on, video/audio LL-HLS on demand with lease expiry", { timeout: 120_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const scratch = mkdtempSync(join(tmpdir(), "taps-"));
+  const source = new CounterSource(small, scratch);
+  const publisher = new MemoryPublisher();
+  const errors: string[] = [];
+  const taps = new PreviewTaps({ publisher, scratchDir: scratch, redactor: passthroughRedactor, onStderr: () => undefined, onError: (tap, r) => errors.push(`${tap}: ${r}`) }, 5_000);
+  try {
+    await source.start();
+    await taps.add(SRC, source.bus);
+    await until(() => publisher.files.has(`${SRC}/thumbnail.jpg`), 15_000, "thumbnail");
+    const thumb = publisher.files.get(`${SRC}/thumbnail.jpg`)!;
+    assert.equal(thumb.contentType, "image/jpeg");
+    assert.equal(thumb.ttl, TTL.thumbnail);
+    assert.deepEqual([...thumb.body.subarray(0, 2)], [0xff, 0xd8]);
+    // Nothing else runs until demanded.
+    assert.equal(taps.hls(SRC, "video"), undefined);
+
+    await Promise.all([taps.demand(SRC, "video"), taps.demand(SRC, "video")]);
+    assert.equal((await source.bus.stats()).subscribers.length, 2, "concurrent demands share one video process plus JPEG");
+    await taps.demand(SRC, "audio");
+    await until(() => publisher.files.has(`${SRC}/video.m3u8`) && publisher.files.has(`${SRC}/audio.m3u8`), 30_000, "playlists");
+    await until(() => (taps.hls(SRC, "video")?.parts ?? 0) >= 4, 30_000, "video parts");
+    const video = publisher.files.get(`${SRC}/video.m3u8`)!.body.toString();
+    assert.match(video, /#EXT-X-PART-INF:PART-TARGET=0\.50000/);
+    assert.match(video, /INDEPENDENT=YES/);
+    // Every URI the playlist names has been published before it.
+    for (const uri of [...video.matchAll(/URI="([^"]+)"/g)].map((m) => m[1]!).concat(video.split("\n").filter((l) => l.endsWith(".m4s")))) {
+      assert.ok(publisher.files.has(`${SRC}/${uri}`), `published ${uri}`);
+    }
+    const audio = publisher.files.get(`${SRC}/audio.m3u8`)!.body.toString();
+    assert.match(audio, /ainit\d+\.mp4/);
+    assert.ok(publisher.files.has(`${SRC}/master.m3u8`));
+    // A video tap reads both streams of the bus and decodes to 360p (here: source size).
+    const seg = [...publisher.files.keys()].find((k) => /\/vs\d+\.m4s$/.test(k));
+    assert.ok(seg, "a closed video segment");
+
+    // A dead HLS rendition is replaced without retaining its watcher or scratch directory.
+    const dead = taps.hls(SRC, "video")!;
+    const oldInit = /URI="(vinit\d+\.mp4)"/.exec(video)?.[1];
+    process.kill(dead.pid ?? 0, "SIGKILL");
+    await until(() => !dead.running, 5_000, "video exit");
+    await Promise.all([taps.demand(SRC, "video"), taps.demand(SRC, "video")]);
+    await until(() => (taps.hls(SRC, "video")?.parts ?? 0) >= 4, 30_000, "restarted video parts");
+    assert.equal(readdirSync(join(scratch, "preview")).length, 2, "only current video and audio scratch directories");
+    const newVideo = publisher.files.get(`${SRC}/video.m3u8`)!.body.toString();
+    assert.notEqual(/URI="(vinit\d+\.mp4)"/.exec(newVideo)?.[1], oldInit, "restart never aliases a cached init");
+
+    // Re-demand extends the lease; expiry stops the process and removes its scratch files.
+    const vtap = taps.hls(SRC, "video")!;
+    const pid = vtap.pid;
+    await taps.demand(SRC, "video");
+    assert.equal(taps.hls(SRC, "video")?.pid, pid, "a live rendition is reused");
+    await taps.sweep(Date.now() + 10_000);
+    assert.equal(taps.hls(SRC, "video"), undefined);
+    assert.equal(taps.hls(SRC, "audio"), undefined);
+    assert.ok(!vtap.running);
+    assert.deepEqual(existsSync(join(scratch, "preview")) ? readdirSync(join(scratch, "preview")) : [], [], "rendition scratch removed");
+
+    // A killed JPEG tap only loses its own pairs; the bus keeps serving, and the sweep restarts it.
+    const jpeg = taps.jpeg(SRC)!;
+    const before = jpeg.stills;
+    process.kill(jpeg.pid ?? 0, "SIGKILL");
+    await until(() => !jpeg.running, 5_000, "jpeg exit");
+    const pairs = (await source.bus.stats()).pairs;
+    await taps.sweep();
+    await until(() => jpeg.stills > before, 15_000, "jpeg restarted");
+    assert.ok((await source.bus.stats()).pairs > pairs, "bus kept running");
+    assert.ok(errors.some((e) => e.includes("tap exited")), "the kill was reported");
+
+    await taps.setThumbnailCadence(SRC, 1);
+    assert.equal(taps.jpeg(SRC)?.cadence, 1);
+    await assert.rejects(taps.setThumbnailCadence(SRC, 0));
+    assert.ok(taps.jpeg(SRC)?.running, "invalid cadence leaves the live thumbnail running");
+
+    await taps.remove(SRC);
+    await taps.add(SRC, source.bus, { alwaysOn: ["video"] });
+    const masterAt = publisher.files.get(`${SRC}/master.m3u8`)!.at;
+    await new Promise((r) => setTimeout(r, 10));
+    await taps.sweep(Date.now() + TTL.init * 1000);
+    assert.ok(publisher.files.get(`${SRC}/master.m3u8`)!.at > masterAt, "active master manifest renewed before expiry");
+    assert.ok(taps.hls(SRC, "video")?.running, "always-on rendition never expires");
+  } finally {
+    await taps.stop();
+    await source.stop();
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
+
+test("program tap: the encoder feeds a 360p bus, and losing that bus never takes the encoder down", { timeout: 120_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const { composeOver, makeAssets, scriptedGraph, ZERO_GAP_CANVAS: canvas } = await import("../compositor/testing");
+  const scratch = mkdtempSync(join(tmpdir(), "pgm-tap-"));
+  const sources = Array.from({ length: 4 }, () => new CounterSource(canvas, scratch));
+  const fatal: string[] = [];
+  const chain = new ProgramChain({ canvas, scratchDir: scratch, videoBitrateKbps: 500, output: { kind: "null" }, programTap: true,
+    redactor: passthroughRedactor, onStderr: () => undefined, onFatal: (r) => fatal.push(r) });
+  const publisher = new MemoryPublisher();
+  const taps = new PreviewTaps({ publisher, scratchDir: scratch, redactor: passthroughRedactor, onStderr: () => undefined });
+  try {
+    for (const s of sources) await s.start();
+    const assets = makeAssets(scratch);
+    await chain.start(composeOver(sources.map((s) => s.bus), assets, scriptedGraph(0)));
+    const bus = chain.programBus!;
+    assert.deepEqual(bus.geometry, programTapGeometry(canvas));
+    await taps.add("program", bus);
+    await until(() => publisher.files.has("program/thumbnail.jpg"), 15_000, "program thumbnail");
+    const p0 = (await bus.stats()).pairs;
+    await new Promise((r) => setTimeout(r, 1_000));
+    const p1 = (await bus.stats()).pairs;
+    assert.ok(p1 - p0 >= canvas.fps * 0.7, `program bus at frame rate (${p1 - p0}/s)`);
+    // Kill the tap bus helper: the encoder's tee drops that slave and keeps encoding.
+    process.kill(bus.pid ?? 0, "SIGKILL");
+    const s0 = await chain.stats();
+    await new Promise((r) => setTimeout(r, 2_000));
+    const s1 = await chain.stats();
+    assert.ok(chain.encoderPid !== undefined && spawnSync("kill", ["-0", String(chain.encoderPid)]).status === 0, "encoder alive");
+    assert.ok(s1.ticks - s0.ticks >= canvas.fps, "gate kept ticking");
+    assert.equal(s1.outDrops - s0.outDrops, 0, "encoder kept reading the gate");
+    assert.deepEqual(fatal, []);
+  } finally {
+    await taps.stop();
+    await chain.stop();
+    for (const s of sources) await s.stop();
+    rmSync(scratch, { recursive: true, force: true });
+  }
+});
diff --git a/apps/media-worker/src/preview/taps.ts b/apps/media-worker/src/preview/taps.ts
new file mode 100644
index 0000000..7519a5b
--- /dev/null
+++ b/apps/media-worker/src/preview/taps.ts
@@ -0,0 +1,352 @@
+/**
+ * Preview tap lifecycle (streaming-architecture.md §2.1).
+ *
+ * Every tap is a source-bus subscriber, so taps never sit in the gate path: a
+ * slow or dead tap loses only its own pairs (the bus drops whole pairs for a
+ * subscriber that falls behind; its EPIPE removes it), and the compositors and
+ * the encoder never wait for it. The program tap's bus is fed by the persistent
+ * encoder (360p, `tee` with a null anchor), so the PGM tile shows exactly what
+ * the encoder receives.
+ *
+ * - JPEG: always on per tap, one still every 2 s by default (1–10 s; 1 s for the
+ *   PST tile), published as `thumbnail.jpg`.
+ * - video / audio LL-HLS: on demand. `demand()` starts a rendition and extends
+ *   its lease; an expired lease stops it. The program tap may be made always-on.
+ */
+import { mkdirSync, readFileSync, rmSync, watch, type FSWatcher } from "node:fs";
+import { join } from "node:path";
+import type { Readable } from "node:stream";
+import type { BusSubscription, SourceBus } from "../compositor/source-bus";
+import { spawnManaged, type ManagedProcess, type StderrRedactor } from "../relay/ffmpeg";
+import {
+  AUDIO_TAP_CODECS, AUDIO_TAP_KBPS, buildHlsTapArgs, buildJpegTapArgs, jpegStride, PARTS_PLAYLIST, tapSize,
+  VIDEO_TAP_CODECS, VIDEO_TAP_MAX_KBPS, type HlsRendition,
+} from "./argv";
+import { assertTapId, AUDIO_PLAYLIST, MASTER_PLAYLIST, THUMBNAIL_FILE, VIDEO_PLAYLIST, type PreviewPublisher } from "./contract";
+import { fragmentIndependent, LlHlsPackager, masterPlaylist, parseFfmpegPlaylist } from "./ll-hls";
+
+/** Manifest TTLs: a stopped tap's files expire on their own. */
+export const TTL = { thumbnail: 30, playlist: 10, media: 60, init: 600 } as const;
+
+let lastSequenceBase = 0;
+function nextSequenceBase(): number {
+  lastSequenceBase = Math.max(Date.now(), lastSequenceBase + 1);
+  return lastSequenceBase;
+}
+
+export interface TapDeps {
+  publisher: PreviewPublisher;
+  scratchDir: string;
+  redactor: StderrRedactor;
+  onStderr(message: string): void;
+  /** A tap process failed (it is restarted on the next demand/cadence change; on air is unaffected). */
+  onError?(tap: string, reason: string): void;
+}
+
+/**
+ * Splits an mjpeg byte stream into whole JPEGs (SOI … EOI). Inside entropy-coded
+ * data 0xFF is always stuffed (FF 00), so FF D9 occurs only as the end marker.
+ */
+export class JpegSplitter {
+  private buf: Buffer = Buffer.alloc(0);
+
+  push(chunk: Buffer): Buffer[] {
+    this.buf = this.buf.length === 0 ? chunk : Buffer.concat([this.buf, chunk]);
+    const out: Buffer[] = [];
+    for (;;) {
+      const start = this.buf.indexOf(Buffer.from([0xff, 0xd8]));
+      if (start < 0) {
+        // Keep a trailing 0xFF: it may be the first byte of the next SOI.
+        this.buf = this.buf.length > 0 && this.buf[this.buf.length - 1] === 0xff ? this.buf.subarray(-1) : Buffer.alloc(0);
+        break;
+      }
+      const end = this.buf.indexOf(Buffer.from([0xff, 0xd9]), start + 2);
+      if (end < 0) { this.buf = this.buf.subarray(start); break; }
+      out.push(Buffer.from(this.buf.subarray(start, end + 2)));
+      this.buf = this.buf.subarray(end + 2);
+    }
+    if (this.buf.length > 8_000_000) this.buf = Buffer.alloc(0); // never a valid preview still
+    return out;
+  }
+}
+
+/** One tap process reading a bus subscription. */
+abstract class BusTap {
+  protected proc: ManagedProcess | null = null;
+  protected sub: BusSubscription | null = null;
+  protected stopping = false;
+
+  constructor(readonly tap: string, protected readonly bus: SourceBus, protected readonly deps: TapDeps) { assertTapId(tap); }
+
+  get running(): boolean { return this.proc !== null; }
+  get pid(): number | undefined { return this.proc?.child.pid; }
+
+  protected async spawn(args: string[], opts: { video: boolean; audio: boolean; stride?: number }, stdout: "pipe" | "ignore"): Promise<ManagedProcess> {
+    this.stopping = false;
+    const sub = await this.bus.subscribe(opts);
+    this.sub = sub;
+    let proc: ManagedProcess;
+    try {
+      proc = spawnManaged("ffmpeg", args, [sub.videoFd ?? "ignore", stdout, "pipe", sub.audioFd ?? "ignore"], this.deps.redactor, this.deps.onStderr);
+    } finally {
+      sub.releaseReaders();
+    }
+    this.proc = proc;
+    void proc.exited.then(({ code, signal }) => {
+      if (this.proc === proc) { this.proc = null; this.sub?.unsubscribe(); this.sub = null; }
+      if (!this.stopping) this.deps.onError?.(this.tap, `tap exited code=${code} signal=${signal}`);
+    });
+    await proc.started;
+    return proc;
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    const proc = this.proc;
+    this.proc = null;
+    this.sub?.unsubscribe();
+    this.sub = null;
+    await proc?.terminate(1_000);
+  }
+}
+
+export class JpegTap extends BusTap {
+  private everySeconds = 2;
+  stills = 0;
+
+  get cadence(): number { return this.everySeconds; }
+
+  async start(everySeconds = this.everySeconds): Promise<void> {
+    this.everySeconds = everySeconds;
+    const plan = { geometry: this.bus.geometry, everySeconds };
+    const proc = await this.spawn(buildJpegTapArgs(plan), { video: true, audio: false, stride: jpegStride(plan) }, "pipe");
+    const splitter = new JpegSplitter();
+    (proc.child.stdout as Readable | null)?.on("data", (chunk: Buffer) => {
+      for (const jpeg of splitter.push(chunk)) {
+        this.stills += 1;
+        void this.deps.publisher.publish(this.tap, THUMBNAIL_FILE, jpeg, "image/jpeg", TTL.thumbnail)
+          .catch((error: unknown) => this.deps.onError?.(this.tap, `thumbnail publish failed: ${String(error)}`));
+      }
+    });
+  }
+
+  /** 1–10 s (§2.2: 2 s default, 1 s for the PST tile). Restarts the tap process. */
+  async setCadence(everySeconds: number): Promise<void> {
+    if (everySeconds === this.everySeconds && this.running) return;
+    await this.stop();
+    await this.start(everySeconds);
+  }
+}
+
+/**
+ * One LL-HLS rendition. ffmpeg writes 0.5 s fMP4 parts into a private scratch
+ * dir; each time its playlist is renamed into place, new parts are published
+ * (parts, closed segments, then the playlist), and the local files are removed.
+ */
+export class HlsTap extends BusTap {
+  private dir = "";
+  private watcher: FSWatcher | null = null;
+  private packager: LlHlsPackager | null = null;
+  private seen = new Set<string>();
+  private initPublished = "";
+  private initRenewedAt = 0;
+  private chain: Promise<void> = Promise.resolve();
+  parts = 0;
+
+  constructor(tap: string, bus: SourceBus, deps: TapDeps, readonly rendition: HlsRendition) { super(tap, bus, deps); }
+
+  get playlistFile(): string { return this.rendition === "video" ? VIDEO_PLAYLIST : AUDIO_PLAYLIST; }
+
+  async start(): Promise<void> {
+    const name = `${this.tap === "program" ? "program" : this.tap.slice(0, 8)}-${this.rendition}-${Date.now()}`;
+    this.dir = join(this.deps.scratchDir, "preview", name);
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    this.packager = new LlHlsPackager(this.rendition, nextSequenceBase());
+    this.seen = new Set();
+    this.initPublished = "";
+    this.watcher = watch(this.dir, (_event, file) => { if (file === PARTS_PLAYLIST) this.schedule(); });
+    await this.spawn(buildHlsTapArgs({ geometry: this.bus.geometry, rendition: this.rendition, outDir: this.dir }),
+      { video: this.rendition === "video", audio: true }, "ignore");
+  }
+
+  private schedule(): void {
+    this.chain = this.chain.then(() => this.collect()).catch((error: unknown) => this.deps.onError?.(this.tap, `hls publish failed: ${String(error)}`));
+  }
+
+  /** Waits for in-flight publishing (tests). */
+  settled(): Promise<void> { return this.chain; }
+
+  private async collect(): Promise<void> {
+    const packager = this.packager;
+    if (!packager) return;
+    let text: string;
+    try { text = readFileSync(join(this.dir, PARTS_PLAYLIST), "utf8"); } catch { return; }
+    const contentType = this.rendition === "video" ? "video/mp4" : "audio/mp4";
+    for (const entry of parseFfmpegPlaylist(text)) {
+      if (this.seen.has(entry.file)) continue;
+      let bytes: Buffer;
+      try { bytes = readFileSync(join(this.dir, entry.file)); } catch { continue; }
+      this.seen.add(entry.file);
+      if (this.seen.size > 64) this.seen.delete(this.seen.values().next().value ?? "");
+      rmSync(join(this.dir, entry.file), { force: true });
+      await this.publishInit(packager, contentType);
+      const { part, closed } = packager.add({ duration: entry.duration, independent: fragmentIndependent(bytes), bytes });
+      if (closed) await this.deps.publisher.publish(this.tap, closed.name, LlHlsPackager.segmentBytes(closed), contentType, TTL.media);
+      if (!part) continue;
+      await this.deps.publisher.publish(this.tap, part.name, part.bytes, contentType, TTL.media);
+      this.parts += 1;
+      const playlist = packager.playlist();
+      if (playlist) await this.deps.publisher.publish(this.tap, this.playlistFile, Buffer.from(playlist), "application/vnd.apple.mpegurl", TTL.playlist);
+    }
+  }
+
+  /** The init segment is published once and its manifest renewed well inside its TTL. */
+  private async publishInit(packager: LlHlsPackager, contentType: "video/mp4" | "audio/mp4"): Promise<void> {
+    const due = Date.now() - this.initRenewedAt > (TTL.init / 2) * 1000;
+    if (this.initPublished === packager.initName && !due) return;
+    let init: Buffer;
+    try { init = readFileSync(join(this.dir, "init.mp4")); } catch { return; }
+    await this.deps.publisher.publish(this.tap, packager.initName, init, contentType, TTL.init);
+    this.initPublished = packager.initName;
+    this.initRenewedAt = Date.now();
+  }
+
+  override async stop(): Promise<void> {
+    this.watcher?.close();
+    this.watcher = null;
+    await super.stop();
+    await this.chain;
+    this.packager = null;
+    if (this.dir) rmSync(this.dir, { recursive: true, force: true });
+  }
+}
+
+interface TapSet { bus: SourceBus; jpeg: JpegTap; hls: Partial<Record<HlsRendition, { tap: HlsTap; until: number }>>; masterRenewedAt: number }
+
+/**
+ * All preview taps of one channel: a JPEG tap per bus (always on), LL-HLS
+ * renditions on demand with a lease. `alwaysOn` renditions (the program tap's,
+ * per §2.2 "PGM always live") never expire.
+ */
+export class PreviewTaps {
+  private readonly taps = new Map<string, TapSet>();
+  private readonly alwaysOn = new Set<string>();
+  private sweeper: ReturnType<typeof setInterval> | null = null;
+  private operations: Promise<unknown> = Promise.resolve();
+
+  constructor(private readonly deps: TapDeps, private readonly leaseMs = 30_000) {}
+
+  get tapIds(): string[] { return [...this.taps.keys()]; }
+  jpeg(tap: string): JpegTap | undefined { return this.taps.get(tap)?.jpeg; }
+  hls(tap: string, rendition: HlsRendition): HlsTap | undefined { return this.taps.get(tap)?.hls[rendition]?.tap; }
+
+  private serialize<T>(operation: () => Promise<T>): Promise<T> {
+    const next = this.operations.catch(() => undefined).then(operation);
+    this.operations = next;
+    return next;
+  }
+
+  add(tap: string, bus: SourceBus, opts: { alwaysOn?: HlsRendition[] } = {}): Promise<void> {
+    return this.serialize(() => this.addNow(tap, bus, opts));
+  }
+
+  private async addNow(tap: string, bus: SourceBus, opts: { alwaysOn?: HlsRendition[] }): Promise<void> {
+    assertTapId(tap);
+    if (this.taps.has(tap)) throw new Error(`preview tap ${tap} already exists`);
+    const jpeg = new JpegTap(tap, bus, this.deps);
+    this.taps.set(tap, { bus, jpeg, hls: {}, masterRenewedAt: 0 });
+    try {
+      await jpeg.start();
+      for (const r of opts.alwaysOn ?? []) {
+        this.alwaysOn.add(`${tap}:${r}`);
+        await this.demandNow(tap, r);
+      }
+    } catch (error) {
+      await this.removeNow(tap);
+      throw error;
+    }
+    this.sweeper ??= setInterval(() => {
+      void this.sweep().catch((error: unknown) => this.deps.onError?.("program", `preview sweep failed: ${String(error)}`));
+    }, 1_000);
+  }
+
+  /** Starts (or keeps) a rendition for `leaseMs` more. */
+  demand(tap: string, rendition: HlsRendition): Promise<void> {
+    return this.serialize(() => this.demandNow(tap, rendition));
+  }
+
+  private async demandNow(tap: string, rendition: HlsRendition): Promise<void> {
+    const set = this.taps.get(tap);
+    if (!set) throw new Error(`no preview tap ${tap}`);
+    const until = this.alwaysOn.has(`${tap}:${rendition}`) ? Infinity : Date.now() + this.leaseMs;
+    const current = set.hls[rendition];
+    if (current?.tap.running) { current.until = Math.max(current.until, until); return; }
+    await current?.tap.stop();
+    const hls = new HlsTap(tap, set.bus, this.deps, rendition);
+    set.hls[rendition] = { tap: hls, until };
+    try { await hls.start(); } catch (error) {
+      delete set.hls[rendition];
+      await hls.stop();
+      throw error;
+    }
+    await this.publishMaster(tap, set.bus);
+  }
+
+  setThumbnailCadence(tap: string, everySeconds: number): Promise<void> {
+    return this.serialize(async () => {
+      const set = this.taps.get(tap);
+      if (!set) throw new Error(`no preview tap ${tap}`);
+      buildJpegTapArgs({ geometry: set.bus.geometry, everySeconds });
+      await set.jpeg.setCadence(everySeconds);
+    });
+  }
+
+  private async publishMaster(tap: string, bus: SourceBus): Promise<void> {
+    const size = tapSize(bus.geometry);
+    const body = masterPlaylist({ ...size, bandwidth: (VIDEO_TAP_MAX_KBPS + AUDIO_TAP_KBPS) * 1000, codecs: VIDEO_TAP_CODECS }, { bandwidth: AUDIO_TAP_KBPS * 1000, codecs: AUDIO_TAP_CODECS });
+    await this.deps.publisher.publish(tap, MASTER_PLAYLIST, Buffer.from(body), "application/vnd.apple.mpegurl", TTL.init);
+    const set = this.taps.get(tap);
+    if (set) set.masterRenewedAt = Date.now();
+  }
+
+  /** Stops expired renditions; restarts a JPEG tap whose process died. */
+  sweep(now = Date.now()): Promise<void> {
+    return this.serialize(() => this.sweepNow(now));
+  }
+
+  private async sweepNow(now: number): Promise<void> {
+    for (const set of this.taps.values()) {
+      for (const r of ["video", "audio"] as const) {
+        const entry = set.hls[r];
+        if (entry && entry.until <= now) { delete set.hls[r]; await entry.tap.stop(); }
+        else if (entry && !entry.tap.running) {
+          await this.demandNow(set.jpeg.tap, r).catch((error: unknown) => this.deps.onError?.(set.jpeg.tap, `hls restart failed: ${String(error)}`));
+        }
+      }
+      if (!set.jpeg.running) await set.jpeg.start().catch((error: unknown) => this.deps.onError?.(set.jpeg.tap, `thumbnail restart failed: ${String(error)}`));
+      if (Object.keys(set.hls).length && now - set.masterRenewedAt >= TTL.init * 500) await this.publishMaster(set.jpeg.tap, set.bus);
+    }
+  }
+
+  remove(tap: string): Promise<void> { return this.serialize(() => this.removeNow(tap)); }
+
+  private async removeNow(tap: string): Promise<void> {
+    const set = this.taps.get(tap);
+    if (!set) return;
+    this.taps.delete(tap);
+    this.alwaysOn.delete(`${tap}:video`);
+    this.alwaysOn.delete(`${tap}:audio`);
+    await set.jpeg.stop();
+    for (const entry of Object.values(set.hls)) await entry?.tap.stop();
+  }
+
+  async stop(): Promise<void> {
+    if (this.sweeper) clearInterval(this.sweeper);
+    this.sweeper = null;
+    await this.serialize(async () => {
+      if (this.sweeper) clearInterval(this.sweeper);
+      this.sweeper = null;
+      for (const tap of [...this.taps.keys()]) await this.removeNow(tap);
+    });
+  }
+}
diff --git a/apps/media-worker/src/production.ts b/apps/media-worker/src/production.ts
new file mode 100644
index 0000000..e8206e7
--- /dev/null
+++ b/apps/media-worker/src/production.ts
@@ -0,0 +1,358 @@
+/**
+ * Desired-state v2: the production part of a channel snapshot
+ * (docs/design/streaming-architecture.md §2, §4, §6 S1).
+ *
+ * This file is mirrored byte-for-byte at apps/media-worker/src/production.ts
+ * (a test asserts it). It has no imports so both builds compile it as-is.
+ *
+ * Everything that can reach a filtergraph or argv is typed: ids are UUIDs,
+ * assets are sha256 content ids, geometry is integer basis points, gains are
+ * 3 dB steps, enums are closed. Labels are display text for operators and logs
+ * only; they are still held to a strict allowlist so a filtergraph payload
+ * (`;`, `[`, `,`, `'`, `movie=`) can never ride along in a snapshot.
+ */
+
+export type SceneLayout = "single" | "pip" | "2x1" | "2x2" | "3x3" | "4x4" | "custom";
+export type SlotFit = "contain" | "cover" | "crop";
+export type AudioMode = "off" | "on" | "primary";
+export type OverlayKind = "lower_third" | "chyron" | "logo" | "clock";
+export type ClockFormat = "HH:MM" | "HH:MM:SS";
+export type FadeMs = 300 | 500 | 1000 | 2000;
+
+export const SCENE_LAYOUTS: readonly SceneLayout[] = ["single", "pip", "2x1", "2x2", "3x3", "4x4", "custom"];
+export const SLOT_FITS: readonly SlotFit[] = ["contain", "cover", "crop"];
+export const AUDIO_MODES: readonly AudioMode[] = ["off", "on", "primary"];
+export const OVERLAY_KINDS: readonly OverlayKind[] = ["lower_third", "chyron", "logo", "clock"];
+export const CLOCK_FORMATS: readonly ClockFormat[] = ["HH:MM", "HH:MM:SS"];
+export const FADE_MS: readonly FadeMs[] = [300, 500, 1000, 2000];
+
+/** Slot capacity per layout. `custom` places up to 16 explicit rectangles. */
+export const LAYOUT_CAPACITY: Readonly<Record<SceneLayout, number>> = {
+  single: 1, pip: 2, "2x1": 2, "2x2": 4, "3x3": 9, "4x4": 16, custom: 16,
+};
+
+/** Geometry is integer basis points of the output frame (0..10000), resolution independent. */
+export const GEOMETRY_SCALE = 10_000;
+export const GAIN_DB_MIN = -24;
+export const GAIN_DB_MAX = 0;
+export const GAIN_DB_STEP = 3;
+export const CHYRON_SPEED_MIN = 40;
+export const CHYRON_SPEED_MAX = 400;
+export const CHYRON_STRIP_MAX_PX = 16_384;
+export const MAX_SOURCES = 32;
+export const MAX_SCENES = 32;
+export const MAX_OVERLAYS = 64;
+export const MAX_PLAYLIST_ITEMS = 500;
+export const MAX_OVERLAY_LAYER = 7;
+
+export interface Rect { x: number; y: number; w: number; h: number }
+export interface Point { x: number; y: number }
+
+export interface HlsProductionSource { id: string; label: string; kind: "hls"; url: string }
+/** Ordered, pre-normalized video asset ids (video_assets.id), fed by the worker's asset feeder. */
+export interface PlaylistProductionSource { id: string; label: string; kind: "playlist"; assetIds: string[]; loop: boolean }
+export type ProductionSource = HlsProductionSource | PlaylistProductionSource;
+
+export interface SceneSlot {
+  index: number;
+  /** null = empty slot (renders the fallback). */
+  sourceId: string | null;
+  /** Required for `custom` and `pip` layouts; null means the layout's own grid cell. */
+  rect: Rect | null;
+  fit: SlotFit;
+  audioMode: AudioMode;
+  gainDb: number;
+}
+
+export interface ProductionScene { id: string; label: string; layout: SceneLayout; slots: SceneSlot[] }
+
+export interface ProductionBuses { preview: string | null; program: string | null }
+
+export interface ProductionOverlay {
+  /** overlay_slots.id */
+  id: string;
+  sceneId: string;
+  kind: OverlayKind;
+  enabled: boolean;
+  layer: number;
+  position: Point;
+  /** overlay_revisions.id; null only for the server-generated clock. */
+  revisionId: string | null;
+  /** sha256 content id of the rendered PNG; null only for the clock. */
+  assetId: string | null;
+  chyron: { speedPxPerSec: number; stripWidthPx: number } | null;
+  clock: { format: ClockFormat } | null;
+}
+
+export type Transition = { type: "cut" } | { type: "fade"; ms: FadeMs };
+
+export interface ProgramAudio { masterGainDb: number }
+
+export interface ProductionSpec {
+  scenes: ProductionScene[];
+  buses: ProductionBuses;
+  sources: ProductionSource[];
+  overlays: ProductionOverlay[];
+  transition: Transition;
+  audio: ProgramAudio;
+}
+
+export class ProductionSpecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProductionSpecError";
+  }
+}
+
+const SECRETISH = /key|secret|token|password|passwd|credential(?!HandleId)|auth/i;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+/** Letters, digits, space and `_ . -` only: no filtergraph or shell metacharacters, no `=`. */
+const LABEL = /^[\p{L}\p{N}][\p{L}\p{N} _.-]{0,63}$/u;
+
+function fail(message: string): never { throw new ProductionSpecError(message); }
+
+function record(value: unknown, field: string, allowed: readonly string[]): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${field} must be an object`);
+  for (const key of Object.keys(value)) {
+    if (allowed.includes(key)) continue;
+    if (SECRETISH.test(key)) fail(`${field}.${key}: secrets are never accepted; reference a vault credentialHandleId`);
+    fail(`${field}.${key} is not allowed`);
+  }
+  for (const key of allowed) if (!(key in value)) fail(`${field}.${key} is required`);
+  return value as Record<string, unknown>;
+}
+
+function list(value: unknown, field: string, max: number): unknown[] {
+  if (!Array.isArray(value)) fail(`${field} must be an array`);
+  if (value.length > max) fail(`${field} allows at most ${max} entries`);
+  return value;
+}
+
+function uuid(value: unknown, field: string): string {
+  if (typeof value !== "string" || !UUID.test(value)) fail(`${field} must be a lowercase UUID`);
+  return value;
+}
+
+function nullableUuid(value: unknown, field: string): string | null {
+  return value === null ? null : uuid(value, field);
+}
+
+function label(value: unknown, field: string): string {
+  if (typeof value !== "string" || !LABEL.test(value)) {
+    fail(`${field} must be 1-64 letters, digits, spaces, '_', '.', '-'`);
+  }
+  return value;
+}
+
+function int(value: unknown, field: string, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < min || value > max) {
+    fail(`${field} must be an integer in ${min}..${max}`);
+  }
+  return value;
+}
+
+function bool(value: unknown, field: string): boolean {
+  if (typeof value !== "boolean") fail(`${field} must be a boolean`);
+  return value;
+}
+
+function oneOf<T extends string | number>(value: unknown, field: string, options: readonly T[]): T {
+  const found = options.find((option) => option === value);
+  if (found === undefined) fail(`${field} must be one of ${options.join(", ")}`);
+  return found;
+}
+
+export function gainDb(value: unknown, field: string): number {
+  const gain = int(value, field, GAIN_DB_MIN, GAIN_DB_MAX);
+  if (gain % GAIN_DB_STEP !== 0) fail(`${field} must be a multiple of ${GAIN_DB_STEP} dB`);
+  return gain === 0 ? 0 : gain;
+}
+
+function rect(value: unknown, field: string): Rect {
+  const r = record(value, field, ["x", "y", "w", "h"]);
+  const x = int(r.x, `${field}.x`, 0, GEOMETRY_SCALE - 1);
+  const y = int(r.y, `${field}.y`, 0, GEOMETRY_SCALE - 1);
+  const w = int(r.w, `${field}.w`, 1, GEOMETRY_SCALE);
+  const h = int(r.h, `${field}.h`, 1, GEOMETRY_SCALE);
+  if (x + w > GEOMETRY_SCALE || y + h > GEOMETRY_SCALE) fail(`${field} must lie inside the frame`);
+  return { x, y, w, h };
+}
+
+function point(value: unknown, field: string): Point {
+  const p = record(value, field, ["x", "y"]);
+  return { x: int(p.x, `${field}.x`, 0, GEOMETRY_SCALE), y: int(p.y, `${field}.y`, 0, GEOMETRY_SCALE) };
+}
+
+function unique(ids: string[], field: string): void {
+  if (new Set(ids).size !== ids.length) fail(`${field} ids must be unique`);
+}
+
+/**
+ * HLS URLs are shape-checked by the caller with its own endpoint validator
+ * (API and worker differ on loopback strictness); here only bounds are checked.
+ */
+function source(value: unknown, field: string): ProductionSource {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${field} must be an object`);
+  const kind = (value as Record<string, unknown>).kind;
+  if (kind === "hls") {
+    const s = record(value, field, ["id", "label", "kind", "url"]);
+    if (typeof s.url !== "string" || s.url.trim() === "" || s.url.length > 2048) fail(`${field}.url must be a non-empty string`);
+    return { id: uuid(s.id, `${field}.id`), label: label(s.label, `${field}.label`), kind: "hls", url: s.url };
+  }
+  if (kind === "playlist") {
+    const s = record(value, field, ["id", "label", "kind", "assetIds", "loop"]);
+    const assetIds = list(s.assetIds, `${field}.assetIds`, MAX_PLAYLIST_ITEMS).map((item, i) => uuid(item, `${field}.assetIds[${i}]`));
+    if (assetIds.length === 0) fail(`${field}.assetIds must not be empty`);
+    return { id: uuid(s.id, `${field}.id`), label: label(s.label, `${field}.label`), kind: "playlist", assetIds, loop: bool(s.loop, `${field}.loop`) };
+  }
+  return fail(`${field}.kind must be hls or playlist`);
+}
+
+function slot(value: unknown, field: string, layout: SceneLayout, sources: ReadonlySet<string>): SceneSlot {
+  const s = record(value, field, ["index", "sourceId", "rect", "fit", "audioMode", "gainDb"]);
+  const index = int(s.index, `${field}.index`, 0, LAYOUT_CAPACITY[layout] - 1);
+  const sourceId = nullableUuid(s.sourceId, `${field}.sourceId`);
+  if (sourceId !== null && !sources.has(sourceId)) fail(`${field}.sourceId must name a source of this channel`);
+  const needsRect = layout === "custom" || (layout === "pip" && index > 0);
+  const slotRect = s.rect === null ? null : rect(s.rect, `${field}.rect`);
+  if (needsRect && slotRect === null) fail(`${field}.rect is required for the ${layout} layout`);
+  if (!needsRect && slotRect !== null) fail(`${field}.rect is only allowed for custom layouts and PIP insets`);
+  return {
+    index, sourceId, rect: slotRect,
+    fit: oneOf(s.fit, `${field}.fit`, SLOT_FITS),
+    audioMode: oneOf(s.audioMode, `${field}.audioMode`, AUDIO_MODES),
+    gainDb: gainDb(s.gainDb, `${field}.gainDb`),
+  };
+}
+
+function scene(value: unknown, field: string, sources: ReadonlySet<string>): ProductionScene {
+  const s = record(value, field, ["id", "label", "layout", "slots"]);
+  const layout = oneOf(s.layout, `${field}.layout`, SCENE_LAYOUTS);
+  const slots = list(s.slots, `${field}.slots`, LAYOUT_CAPACITY[layout]).map((item, i) => slot(item, `${field}.slots[${i}]`, layout, sources));
+  if (new Set(slots.map((x) => x.index)).size !== slots.length) fail(`${field}.slots indexes must be unique`);
+  if (slots.filter((x) => x.audioMode === "primary").length > 1) fail(`${field}.slots: at most one primary audio slot per scene`);
+  return { id: uuid(s.id, `${field}.id`), label: label(s.label, `${field}.label`), layout, slots };
+}
+
+function overlay(value: unknown, field: string, scenes: ReadonlySet<string>): ProductionOverlay {
+  const o = record(value, field, ["id", "sceneId", "kind", "enabled", "layer", "position", "revisionId", "assetId", "chyron", "clock"]);
+  const sceneId = uuid(o.sceneId, `${field}.sceneId`);
+  if (!scenes.has(sceneId)) fail(`${field}.sceneId must name a scene of this channel`);
+  const kind = oneOf(o.kind, `${field}.kind`, OVERLAY_KINDS);
+  const rendered = kind !== "clock";
+  let revisionId: string | null = null;
+  let assetId: string | null = null;
+  if (rendered) {
+    revisionId = uuid(o.revisionId, `${field}.revisionId`);
+    if (typeof o.assetId !== "string" || !SHA256.test(o.assetId)) fail(`${field}.assetId must be a sha256 content id`);
+    assetId = o.assetId;
+  } else if (o.revisionId !== null || o.assetId !== null) fail(`${field}: a clock overlay has no rendered asset`);
+
+  let chyron: ProductionOverlay["chyron"] = null;
+  if (kind === "chyron") {
+    const c = record(o.chyron, `${field}.chyron`, ["speedPxPerSec", "stripWidthPx"]);
+    chyron = {
+      speedPxPerSec: int(c.speedPxPerSec, `${field}.chyron.speedPxPerSec`, CHYRON_SPEED_MIN, CHYRON_SPEED_MAX),
+      stripWidthPx: int(c.stripWidthPx, `${field}.chyron.stripWidthPx`, 1, CHYRON_STRIP_MAX_PX),
+    };
+  } else if (o.chyron !== null) fail(`${field}.chyron is only allowed for chyron overlays`);
+
+  let clock: ProductionOverlay["clock"] = null;
+  if (kind === "clock") {
+    const c = record(o.clock, `${field}.clock`, ["format"]);
+    clock = { format: oneOf(c.format, `${field}.clock.format`, CLOCK_FORMATS) };
+  } else if (o.clock !== null) fail(`${field}.clock is only allowed for clock overlays`);
+
+  return {
+    id: uuid(o.id, `${field}.id`), sceneId, kind,
+    enabled: bool(o.enabled, `${field}.enabled`),
+    layer: int(o.layer, `${field}.layer`, 0, MAX_OVERLAY_LAYER),
+    position: point(o.position, `${field}.position`),
+    revisionId, assetId, chyron, clock,
+  };
+}
+
+function transition(value: unknown, field: string): Transition {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) fail(`${field} must be an object`);
+  const type = (value as Record<string, unknown>).type;
+  if (type === "cut") {
+    record(value, field, ["type"]);
+    return { type: "cut" };
+  }
+  if (type === "fade") {
+    const t = record(value, field, ["type", "ms"]);
+    return { type: "fade", ms: oneOf(t.ms, `${field}.ms`, FADE_MS) };
+  }
+  return fail(`${field}.type must be cut or fade`);
+}
+
+/** Parse and normalize; throws ProductionSpecError with a field path on the first problem. */
+export function parseProductionSpec(value: unknown, field = "production"): ProductionSpec {
+  const p = record(value, field, ["scenes", "buses", "sources", "overlays", "transition", "audio"]);
+  const sources = list(p.sources, `${field}.sources`, MAX_SOURCES).map((item, i) => source(item, `${field}.sources[${i}]`));
+  unique(sources.map((s) => s.id), `${field}.sources`);
+  const sourceIds = new Set(sources.map((s) => s.id));
+  const scenes = list(p.scenes, `${field}.scenes`, MAX_SCENES).map((item, i) => scene(item, `${field}.scenes[${i}]`, sourceIds));
+  unique(scenes.map((s) => s.id), `${field}.scenes`);
+  const sceneIds = new Set(scenes.map((s) => s.id));
+  const overlays = list(p.overlays, `${field}.overlays`, MAX_OVERLAYS).map((item, i) => overlay(item, `${field}.overlays[${i}]`, sceneIds));
+  unique(overlays.map((o) => o.id), `${field}.overlays`);
+
+  const b = record(p.buses, `${field}.buses`, ["preview", "program"]);
+  const buses: ProductionBuses = {
+    preview: nullableUuid(b.preview, `${field}.buses.preview`),
+    program: nullableUuid(b.program, `${field}.buses.program`),
+  };
+  for (const bus of ["preview", "program"] as const) {
+    const id = buses[bus];
+    if (id !== null && !sceneIds.has(id)) fail(`${field}.buses.${bus} must name a scene of this channel`);
+  }
+  const a = record(p.audio, `${field}.audio`, ["masterGainDb"]);
+  return {
+    scenes, buses, sources, overlays,
+    transition: transition(p.transition, `${field}.transition`),
+    audio: { masterGainDb: gainDb(a.masterGainDb, `${field}.audio.masterGainDb`) },
+  };
+}
+
+export function isProductionSpec(value: unknown): value is ProductionSpec {
+  try {
+    parseProductionSpec(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Every remote URL a production snapshot can make the worker fetch. */
+export function productionHlsUrls(spec: ProductionSpec): string[] {
+  return spec.sources.flatMap((s) => (s.kind === "hls" ? [s.url] : []));
+}
+
+/** Declared key order for signing: insertion order of the input can never drift the signed bytes. */
+export function canonicalProduction(spec: ProductionSpec): ProductionSpec {
+  return {
+    scenes: spec.scenes.map((s) => ({
+      id: s.id, label: s.label, layout: s.layout,
+      slots: s.slots.map((x) => ({
+        index: x.index, sourceId: x.sourceId,
+        rect: x.rect === null ? null : { x: x.rect.x, y: x.rect.y, w: x.rect.w, h: x.rect.h },
+        fit: x.fit, audioMode: x.audioMode, gainDb: x.gainDb,
+      })),
+    })),
+    buses: { preview: spec.buses.preview, program: spec.buses.program },
+    sources: spec.sources.map((s): ProductionSource => (s.kind === "hls"
+      ? { id: s.id, label: s.label, kind: "hls", url: s.url }
+      : { id: s.id, label: s.label, kind: "playlist", assetIds: [...s.assetIds], loop: s.loop })),
+    overlays: spec.overlays.map((o) => ({
+      id: o.id, sceneId: o.sceneId, kind: o.kind, enabled: o.enabled, layer: o.layer,
+      position: { x: o.position.x, y: o.position.y },
+      revisionId: o.revisionId, assetId: o.assetId,
+      chyron: o.chyron === null ? null : { speedPxPerSec: o.chyron.speedPxPerSec, stripWidthPx: o.chyron.stripWidthPx },
+      clock: o.clock === null ? null : { format: o.clock.format },
+    })),
+    transition: spec.transition.type === "cut" ? { type: "cut" } : { type: "fade", ms: spec.transition.ms },
+    audio: { masterGainDb: spec.audio.masterGainDb },
+  };
+}
diff --git a/apps/media-worker/src/relay/endpoints.ts b/apps/media-worker/src/relay/endpoints.ts
new file mode 100644
index 0000000..40df0a6
--- /dev/null
+++ b/apps/media-worker/src/relay/endpoints.ts
@@ -0,0 +1,39 @@
+import { BlockList, isIP } from "node:net";
+
+export type EndpointUse = "hls" | "output";
+export interface ValidatedEndpoint { url: URL; pinnedAddress: string }
+
+/** WP7 supplies DNS pinning, redirect and HLS child-URI validation. */
+export interface EndpointValidator {
+  validate(raw: string, use: EndpointUse): Promise<ValidatedEndpoint>;
+}
+
+const blocked = new BlockList();
+for (const [subnet, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+  ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
+  ["192.0.2.0", 24], ["198.18.0.0", 15], ["198.51.100.0", 24],
+  ["203.0.113.0", 24], ["224.0.0.0", 4], ["240.0.0.0", 4],
+] as const) blocked.addSubnet(subnet, prefix, "ipv4");
+for (const [subnet, prefix] of [
+  ["::", 128], ["::1", 128], ["fc00::", 7], ["fe80::", 10], ["ff00::", 8],
+  ["2001::", 32], ["2001:db8::", 32], ["2002::", 16], ["64:ff9b::", 96],
+] as const) blocked.addSubnet(subnet, prefix, "ipv6");
+
+export function assertPublicAddress(address: string): void {
+  const normalized = address.replace(/^\[|\]$/g, "").toLowerCase();
+  const family = isIP(normalized);
+  if (family === 0) throw new Error("unresolved endpoint address");
+  // Node's BlockList normalizes IPv4 to mapped IPv6 internally; reject mapped literals outright.
+  if (normalized.startsWith("::ffff:")) throw new Error("mapped endpoint rejected");
+  if (blocked.check(normalized, family === 4 ? "ipv4" : "ipv6")) throw new Error("private endpoint rejected");
+}
+
+export function validateEndpointShape(raw: string, use: EndpointUse): URL {
+  let url: URL;
+  try { url = new URL(raw); } catch { throw new Error("invalid endpoint URL"); }
+  const schemes = use === "hls" ? ["https:"] : ["rtmp:", "rtmps:"];
+  if (!schemes.includes(url.protocol) || !url.hostname || url.username || url.password || url.search || url.hash) throw new Error("endpoint scheme or credentials rejected");
+  if (isIP(url.hostname.replace(/^\[|\]$/g, ""))) assertPublicAddress(url.hostname);
+  return url;
+}
diff --git a/apps/media-worker/src/relay/ffmpeg.ts b/apps/media-worker/src/relay/ffmpeg.ts
new file mode 100644
index 0000000..1abeb82
--- /dev/null
+++ b/apps/media-worker/src/relay/ffmpeg.ts
@@ -0,0 +1,122 @@
+import { spawn, type ChildProcess, type StdioOptions } from "node:child_process";
+import { OUTPUT_PROFILES, type DesiredChannel } from "../types";
+import { assertPublicAddress, validateEndpointShape, type EndpointValidator } from "./endpoints";
+
+/** The vault broker delivers a key directly to the push relay's inherited fd. */
+export interface VaultHandleBroker {
+  deliverPushTarget(handleId: string, context: { workspaceId: string; channelId: string; assignmentEpoch: number }, relayFd: number): Promise<void>;
+}
+export interface LocalRelayPipes { ingestFd: number; pushFd: number; close(): Promise<void> }
+/** WP7 implementation fetches HLS through pinned egress and pushes RTMP with the vault key. */
+export interface EgressRelayFactory {
+  prepare(config: DesiredChannel, validator: EndpointValidator, vault: VaultHandleBroker): Promise<LocalRelayPipes>;
+}
+export interface StderrRedactor { redact(chunk: string): string }
+
+/** Media children get a minimal environment: no worker secrets, no inherited config. */
+export function mediaEnv(): NodeJS.ProcessEnv { return { PATH: process.env.PATH ?? "/usr/bin:/bin" }; }
+
+export interface ManagedProcess {
+  readonly child: ChildProcess;
+  /** Resolves on spawn, rejects if the binary cannot start. */
+  readonly started: Promise<void>;
+  /** Resolves once the process has exited (never rejects). */
+  readonly exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+  kill(signal?: NodeJS.Signals): void;
+  /** SIGTERM, then SIGKILL after `graceMs`; resolves on exit. */
+  terminate(graceMs?: number): Promise<void>;
+}
+
+/**
+ * Shared spawn path for every media child (relay, ingest, compositor, encoder,
+ * frame gate): argv only, never a shell; minimal env; stderr is redacted and
+ * truncated before it reaches the logger.
+ */
+export function spawnManaged(
+  command: string, args: readonly string[], stdio: StdioOptions,
+  redactor: StderrRedactor, onStderr: (message: string) => void, cwd?: string,
+): ManagedProcess {
+  const child = spawn(command, args, { stdio, shell: false, env: mediaEnv(), ...(cwd === undefined ? {} : { cwd }) });
+  child.stderr?.on("data", (chunk: Buffer) => onStderr(redactor.redact(chunk.toString("utf8").slice(0, 4096))));
+  const started = new Promise<void>((resolve, reject) => {
+    child.once("spawn", () => resolve());
+    child.once("error", reject);
+  });
+  started.catch(() => undefined);
+  const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>((resolve) => {
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+    child.once("error", () => { if (child.pid === undefined) resolve({ code: null, signal: null }); });
+  });
+  const kill = (signal: NodeJS.Signals = "SIGTERM"): void => { if (child.exitCode === null && child.signalCode === null) child.kill(signal); };
+  return {
+    child, started, exited, kill,
+    async terminate(graceMs = 2_000) {
+      kill("SIGTERM");
+      const timer = setTimeout(() => kill("SIGKILL"), graceMs);
+      await exited;
+      clearTimeout(timer);
+    },
+  };
+}
+
+export function ffmpegArgs(config: DesiredChannel): string[] {
+  const args = ["-hide_banner", "-nostdin", "-loglevel", "warning", "-f", "mpegts", "-i", "pipe:3"];
+  if (config.mode === "passthrough") args.push("-c", "copy");
+  else {
+    const profile = OUTPUT_PROFILES[config.profile];
+    args.push("-vf", `scale=${profile.width}:${profile.height},fps=${profile.fps}`,
+      "-c:v", "libx264", "-preset", "veryfast", "-b:v", profile.videoBitrate,
+      "-c:a", "aac", "-b:a", "128k");
+  }
+  args.push("-f", "flv", "pipe:4");
+  return args;
+}
+
+export class FfmpegRelayJob {
+  private child: ChildProcess | null = null;
+  private pipes: LocalRelayPipes | null = null;
+  private stopping = false;
+  constructor(
+    private readonly validator: EndpointValidator,
+    private readonly egress: EgressRelayFactory,
+    private readonly vault: VaultHandleBroker,
+    private readonly redactor: StderrRedactor,
+    private readonly onStderr: (message: string) => void,
+    private readonly onExit: (reason: string) => void,
+  ) {}
+
+  async start(config: DesiredChannel): Promise<void> {
+    if (!config.source || !config.output) throw new Error("running channel needs source and output");
+    validateEndpointShape(config.source.url, "hls");
+    validateEndpointShape(config.output.endpointUrl, "output");
+    const source = await this.validator.validate(config.source.url, "hls");
+    const output = await this.validator.validate(config.output.endpointUrl, "output");
+    assertPublicAddress(source.pinnedAddress);
+    assertPublicAddress(output.pinnedAddress);
+    this.pipes = await this.egress.prepare(config, this.validator, this.vault);
+    this.stopping = false;
+    const managed = spawnManaged("ffmpeg", ffmpegArgs(config),
+      ["ignore", "ignore", "pipe", this.pipes.ingestFd, this.pipes.pushFd], this.redactor, this.onStderr);
+    const child = managed.child;
+    this.child = child;
+    let spawned = false;
+    void managed.started.then(() => { spawned = true; }, () => undefined);
+    child.on("error", (error) => { if (spawned) this.onExit(this.redactor.redact(error.message)); });
+    const started = managed.started;
+    child.once("exit", (code, signal) => {
+      void this.pipes?.close();
+      this.pipes = null;
+      this.child = null;
+      if (!this.stopping) this.onExit(`ffmpeg exited code=${code} signal=${signal}`);
+    });
+    await started;
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    this.child?.kill("SIGTERM");
+    await this.pipes?.close();
+    this.pipes = null;
+    this.child = null;
+  }
+}
diff --git a/apps/media-worker/src/relay/relay.test.ts b/apps/media-worker/src/relay/relay.test.ts
new file mode 100644
index 0000000..753fbaf
--- /dev/null
+++ b/apps/media-worker/src/relay/relay.test.ts
@@ -0,0 +1,56 @@
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import test from "node:test";
+import { pathToFileURL } from "node:url";
+import { assertPublicAddress, validateEndpointShape } from "./endpoints";
+import { ffmpegArgs } from "./ffmpeg";
+import type { DesiredChannel } from "../types";
+
+const channel: DesiredChannel = {
+  workspaceId: "workspace-1", channelId: "channel-1", workerId: "worker-1",
+  assignmentEpoch: 1, desiredVersion: 1, desiredStatus: "RUNNING",
+  source: { kind: "hls", url: "https://mock.local/hls/live-1/master.m3u8" },
+  output: { endpointUrl: "rtmp://mock.local/live", credentialHandleId: "vault-handle" },
+  mode: "passthrough", profile: "720p30",
+};
+
+test("relay argv uses only local inherited pipes and mode profile", () => {
+  const passthrough = ffmpegArgs(channel);
+  assert.deepEqual(passthrough.slice(-3), ["-f", "flv", "pipe:4"]);
+  assert.ok(passthrough.includes("copy"));
+  assert.ok(!passthrough.join(" ").includes("mock.local"));
+  assert.ok(!passthrough.join(" ").includes("vault-handle"));
+  const normalized = ffmpegArgs({ ...channel, mode: "normalize", profile: "1080p60" });
+  assert.ok(normalized.includes("scale=1920:1080,fps=60"));
+});
+
+test("endpoint shape and literal/private pin denial", () => {
+  assert.equal(validateEndpointShape(channel.source?.url ?? "", "hls").protocol, "https:");
+  assert.throws(() => validateEndpointShape("file:///etc/passwd", "hls"));
+  assert.throws(() => validateEndpointShape("https://127.0.0.1/live.m3u8", "hls"));
+  assert.throws(() => validateEndpointShape("rtmp://169.254.169.254/live", "output"));
+  assert.throws(() => validateEndpointShape("rtmp://user:secret@example.com/live", "output"));
+  for (const address of ["10.0.0.1", "172.20.1.2", "192.168.1.1", "100.64.0.1", "::1", "fc00::1", "::ffff:127.0.0.1", "::ffff:7f00:1"]) {
+    assert.throws(() => assertPublicAddress(address), address);
+  }
+  assert.doesNotThrow(() => assertPublicAddress("8.8.8.8"));
+});
+
+test("mock livestream source and single-live simulator fixture feed the relay contract", async () => {
+  const mockPath = pathToFileURL(resolve(__dirname, "../../../../packages/connector-mock-livestream/src/index.ts")).href;
+  const fixturePath = pathToFileURL(resolve(__dirname, "../../../../packages/testing/src/scenarios.ts")).href;
+  const mockModule: unknown = await import(mockPath);
+  const fixtures: unknown = await import(fixturePath);
+  const mock = mockModule as { createMockLivestreamConnector(): {
+    createLiveStream(connection: null, request: { channelId: string; title: string; permanent: boolean; saveReplay: boolean }): Promise<{ remoteId: string }>;
+    getStreamPlaybackSources(connection: null, request: { remoteId: string }): Promise<Array<{ url: string; kind: string }>>;
+  } };
+  const scenarios = fixtures as { SCENARIOS: Record<string, { steps: Array<{ source: string; action: string }> }> };
+  assert.deepEqual(scenarios.SCENARIOS["single-live"]?.steps.map((step) => [step.source, step.action]), [["A", "go-live"]]);
+  const connector = mock.createMockLivestreamConnector();
+  const live = await connector.createLiveStream(null, { channelId: "A", title: "test", permanent: true, saveReplay: false });
+  const sources = await connector.getStreamPlaybackSources(null, { remoteId: live.remoteId });
+  assert.equal(sources[0]?.kind, "hls");
+  assert.equal(validateEndpointShape(sources[0]?.url ?? "", "hls").hostname, "mock.local");
+  assert.ok(!ffmpegArgs({ ...channel, source: { kind: "hls", url: sources[0]?.url ?? "" } }).join(" ").includes("mock.local"));
+});
diff --git a/apps/media-worker/src/supervisor/index.ts b/apps/media-worker/src/supervisor/index.ts
new file mode 100644
index 0000000..1b9ee81
--- /dev/null
+++ b/apps/media-worker/src/supervisor/index.ts
@@ -0,0 +1,249 @@
+import type { KeyObject } from "node:crypto";
+import { sandboxRelay, supervisorSandboxEnabled } from "./sandbox";
+import { verifyCommand } from "../bus/envelope";
+import { DurableFence } from "../bus/fence";
+import type { ObservedStore } from "../bus/redis";
+import type { ChannelState, DesiredChannel, ObservedChannel } from "../types";
+
+export interface TransitionLogger {
+  transition(event: { workspaceId: string; channelId: string; from: ChannelState; to: ChannelState; reason: string }): void;
+}
+interface ChannelRuntime {
+  desired: DesiredChannel;
+  state: ChannelState;
+  reason: string;
+  realizedVersion: number | null;
+  relay: RelayJob | null;
+  retries: number;
+  retryTimer: { cancel(): void } | null;
+  /** Consecutive failed swaps for the current desired version (the previous version stays on air). */
+  swapFailures: number;
+}
+export interface RelayJob {
+  start(channel: DesiredChannel): Promise<void>;
+  stop(): Promise<void>;
+  /**
+   * Optional in-place change (production jobs: an A/B compositor swap behind the
+   * frame gate). Resolves true once the new version is on air; false means the
+   * change needs a restart (sources, output or profile changed).
+   */
+  reconfigure?(channel: DesiredChannel): Promise<boolean>;
+}
+export interface RetryScheduler { schedule(action: () => Promise<void>, delayMs: number): { cancel(): void } }
+
+/**
+ * A swap that fails (B never went on air; A is still on air) is retried this many times, 1 s then
+ * 2 s later, before the supervisor falls back to a full restart. The full restart converges too,
+ * but it takes the encoder and the push session down (WP9 "output that does not stop").
+ */
+export const SWAP_RETRIES = 2;
+const defaultRetryScheduler: RetryScheduler = {
+  schedule(action, delayMs) {
+    const timer = setTimeout(() => { void action(); }, delayMs);
+    return { cancel: () => clearTimeout(timer) };
+  },
+};
+
+/** Accepted versions are durable; realized versions describe only this process lifetime. */
+export class MediaSupervisor {
+  private readonly channels = new Map<string, ChannelRuntime>();
+  private readonly operations = new Map<string, Promise<unknown>>();
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  /** Set by `stop()`: late retries and relaunches become no-ops. */
+  private stopped = false;
+  constructor(
+    private readonly workerId: string,
+    desired: DesiredChannel[],
+    private readonly store: ObservedStore,
+    private readonly fence: DurableFence,
+    private readonly controlKeys: ReadonlyMap<string, KeyObject>,
+    private readonly createRelay: (channel: DesiredChannel, onExit: (reason: string) => void) => RelayJob,
+    private readonly logger: TransitionLogger,
+    private readonly retryScheduler: RetryScheduler = defaultRetryScheduler,
+  ) {
+    supervisorSandboxEnabled(); // Production cannot silently opt out of confinement.
+    for (const channel of desired) {
+      if (channel.workerId !== workerId) throw new Error("config worker mismatch");
+      this.channels.set(this.key(channel.workspaceId, channel.channelId), {
+        desired: channel, state: "STOPPED", reason: "worker boot", realizedVersion: null,
+        relay: null, retries: 0, retryTimer: null, swapFailures: 0,
+      });
+    }
+  }
+
+  private key(workspaceId: string, channelId: string): string { return `${workspaceId}:${channelId}`; }
+  status(): ObservedChannel[] {
+    return [...this.channels.values()].map((runtime) => ({
+      workspaceId: runtime.desired.workspaceId, channelId: runtime.desired.channelId,
+      workerId: this.workerId, assignmentEpoch: runtime.desired.assignmentEpoch,
+      state: runtime.state, realizedVersion: runtime.realizedVersion,
+      updatedAt: new Date().toISOString(), reason: runtime.reason,
+    }));
+  }
+  private async transition(runtime: ChannelRuntime, to: ChannelState, reason: string): Promise<void> {
+    const from = runtime.state;
+    runtime.state = to;
+    runtime.reason = reason;
+    this.logger.transition({ workspaceId: runtime.desired.workspaceId, channelId: runtime.desired.channelId, from, to, reason });
+    await this.store.put(this.status().find((item) => item.workspaceId === runtime.desired.workspaceId && item.channelId === runtime.desired.channelId)!);
+  }
+
+  async start(): Promise<void> {
+    for (const runtime of this.channels.values()) {
+      const old = await this.store.get(runtime.desired.workspaceId, runtime.desired.channelId);
+      await this.transition(runtime, "STOPPED", old
+        ? `restart reconcile: prior ${old.state}; awaiting fresh signed snapshot`
+        : "start reconcile: awaiting signed snapshot");
+    }
+    await this.beat();
+    this.heartbeatTimer = setInterval(() => { void this.beat().catch((error: unknown) => this.logger.transition({ workspaceId: "", channelId: "", from: "DEGRADED", to: "DEGRADED", reason: `heartbeat failed: ${String(error)}` })); }, 5_000);
+  }
+
+  async beat(): Promise<void> { await this.store.heartbeat(this.workerId, this.status()); }
+
+  async handle(raw: unknown, now = Date.now()): Promise<"accepted" | "replay" | "stale"> {
+    const command = verifyCommand(raw, this.controlKeys, this.workerId, now);
+    const body = command.body;
+    return this.serialize(this.key(body.workspaceId, body.channelId), () => this.apply(body, now));
+  }
+
+  /** One operation at a time per channel (commands and swap retries). */
+  private serialize<T>(key: string, operation: () => Promise<T>): Promise<T> {
+    const previous = this.operations.get(key) ?? Promise.resolve();
+    const task = previous.catch(() => undefined).then(operation);
+    this.operations.set(key, task);
+    void task.then(() => { if (this.operations.get(key) === task) this.operations.delete(key); },
+      () => { if (this.operations.get(key) === task) this.operations.delete(key); });
+    return task;
+  }
+
+  private async apply(body: ReturnType<typeof verifyCommand>["body"], now: number): Promise<"accepted" | "replay" | "stale"> {
+    const runtime = this.channels.get(this.key(body.workspaceId, body.channelId));
+    if (!runtime || runtime.desired.assignmentEpoch !== body.assignmentEpoch) throw new Error("unassigned channel or epoch");
+    const result = this.fence.accept(body, now);
+    if (result !== "accepted") return result;
+    // RUNNING → RUNNING on a job that can swap: the encoder and push session stay up,
+    // and the version is realized only once the new compositor is on air.
+    const relay = runtime.relay;
+    if (runtime.state === "RUNNING" && body.snapshot.desiredStatus === "RUNNING" && relay?.reconfigure) {
+      runtime.desired = body.snapshot;
+      runtime.retryTimer?.cancel();
+      runtime.retryTimer = null;
+      runtime.swapFailures = 0;
+      if (await this.swap(runtime, relay) !== "restart") return result;
+    }
+    runtime.desired = body.snapshot;
+    runtime.swapFailures = 0;
+    runtime.realizedVersion = null;
+    runtime.retryTimer?.cancel();
+    runtime.retryTimer = null;
+    await runtime.relay?.stop();
+    runtime.relay = null;
+    if (body.snapshot.desiredStatus === "STOPPED") {
+      await this.transition(runtime, "STOPPED", "signed desired state stopped");
+      runtime.realizedVersion = body.desiredVersion;
+      await this.beat();
+      return result;
+    }
+    runtime.retries = 0;
+    await this.launch(runtime);
+    return result;
+  }
+
+  /**
+   * One swap attempt for `runtime.desired`. "done": on air (or the job is gone and its own exit
+   * path owns the channel); "retrying": B failed, A stays on air (`realizedVersion` keeps naming
+   * what viewers see) and a retry is scheduled; "restart": not swappable, or out of retries.
+   */
+  private async swap(runtime: ChannelRuntime, relay: RelayJob): Promise<"done" | "retrying" | "restart"> {
+    const version = runtime.desired.desiredVersion;
+    try {
+      if (!(await relay.reconfigure?.(runtime.desired))) return "restart";
+      if (runtime.relay !== relay) return "done";
+      runtime.swapFailures = 0;
+      runtime.realizedVersion = version;
+      await this.transition(runtime, "RUNNING", "compositor swapped at a frame boundary");
+      await this.beat();
+      return "done";
+    } catch (error: unknown) {
+      if (runtime.relay !== relay) return "done";
+      const name = error instanceof Error ? error.name : "unknown error";
+      runtime.swapFailures += 1;
+      if (runtime.swapFailures > SWAP_RETRIES) {
+        runtime.reason = `swap failed: ${name}`;
+        return "restart";
+      }
+      const delay = 1_000 * 2 ** (runtime.swapFailures - 1);
+      await this.transition(runtime, "RUNNING", `swap to v${version} failed (${name}); v${runtime.realizedVersion ?? "?"} stays on air; retry ${runtime.swapFailures}/${SWAP_RETRIES} in ${delay}ms`);
+      const key = this.key(runtime.desired.workspaceId, runtime.desired.channelId);
+      runtime.retryTimer = this.retryScheduler.schedule(() => this.serialize(key, async () => {
+        runtime.retryTimer = null;
+        if (this.stopped) return;
+        // A newer command or an exit has taken over since.
+        if (runtime.desired.desiredVersion !== version || runtime.relay !== relay || runtime.state !== "RUNNING") return;
+        if (await this.swap(runtime, relay) === "restart") await this.restart(runtime);
+      }), delay);
+      return "retrying";
+    }
+  }
+
+  /** Full restart for the current desired snapshot (the swap path gave up). */
+  private async restart(runtime: ChannelRuntime): Promise<void> {
+    runtime.realizedVersion = null;
+    runtime.swapFailures = 0;
+    await runtime.relay?.stop();
+    runtime.relay = null;
+    runtime.retries = 0;
+    await this.launch(runtime);
+  }
+
+  private async launch(runtime: ChannelRuntime): Promise<void> {
+    await this.transition(runtime, runtime.retries ? "RESTARTING" : "STARTING", runtime.retries ? "relay retry" : "signed desired state running");
+    try {
+      const relay = sandboxRelay(this.createRelay(runtime.desired, (reason) => {
+        if (runtime.relay === relay) void this.relayExited(runtime, reason);
+      }), runtime.desired);
+      runtime.relay = relay;
+      await relay.start(runtime.desired);
+      if (runtime.relay !== relay) return;
+      runtime.realizedVersion = runtime.desired.desiredVersion;
+      await this.transition(runtime, "RUNNING", "ffmpeg spawned with local relay pipes");
+      await this.beat();
+    } catch (error: unknown) {
+      runtime.relay = null;
+      await this.relayExited(runtime, `start failed: ${error instanceof Error ? error.name : "unknown error"}`);
+    }
+  }
+
+  private async relayExited(runtime: ChannelRuntime, reason: string): Promise<void> {
+    if (this.stopped || runtime.desired.desiredStatus !== "RUNNING") return;
+    runtime.realizedVersion = null;
+    runtime.relay = null;
+    await this.transition(runtime, "DEGRADED", reason);
+    if (runtime.retries >= 5) { await this.transition(runtime, "FAILED", "relay retry budget exhausted"); return; }
+    const delay = Math.min(30_000, 1_000 * 2 ** runtime.retries);
+    runtime.retries += 1;
+    await this.transition(runtime, "RESTARTING", `retry in ${delay}ms`);
+    runtime.retryTimer = this.retryScheduler.schedule(() => { runtime.retryTimer = null; return this.stopped ? Promise.resolve() : this.launch(runtime); }, delay);
+  }
+
+  /**
+   * Worker shutdown. In-flight per-channel operations (a command, a swap retry, a relaunch) finish
+   * first, so none of them can start a job after the channels were stopped.
+   */
+  async stop(): Promise<void> {
+    this.stopped = true;
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+    for (const runtime of this.channels.values()) runtime.retryTimer?.cancel();
+    await Promise.allSettled([...this.operations.values()]);
+    for (const runtime of this.channels.values()) {
+      runtime.retryTimer?.cancel();
+      runtime.retryTimer = null;
+      runtime.desired = { ...runtime.desired, desiredStatus: "STOPPED" };
+      await runtime.relay?.stop();
+      runtime.realizedVersion = null;
+      await this.transition(runtime, "STOPPED", "worker shutdown");
+    }
+  }
+}
diff --git a/apps/media-worker/src/supervisor/production.e2e.test.ts b/apps/media-worker/src/supervisor/production.e2e.test.ts
new file mode 100644
index 0000000..a788d87
--- /dev/null
+++ b/apps/media-worker/src/supervisor/production.e2e.test.ts
@@ -0,0 +1,215 @@
+/**
+ * A/B lifecycle end to end (streaming-architecture.md §6 S2): signed snapshots
+ * through the real MediaSupervisor into a real ProductionJob (synthetic
+ * ingests standing in for the WP7 relay, a playlist source through the asset
+ * feeder, the Rust gate, an x264 encoder into `-f null`, preview taps).
+ *
+ * - a TAKE (program scene change) is a swap: the encoder process is the same
+ *   one, and the version is realized only once the gate reports B on air;
+ * - a playlist edit is adopted by its feeder in place (still the same encoder);
+ * - a changed source URL is a restart (a new encoder);
+ * - STOPPED tears everything down.
+ */
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { createReadStream, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { signCommand, type CommandBody } from "../bus/envelope";
+import { DurableFence } from "../bus/fence";
+import type { ObservedStore } from "../bus/redis";
+import { ProductionJob } from "../compositor/production-job";
+import { ensureGateBinary, makeAssets, passthroughRedactor } from "../compositor/testing";
+import { parseProductionSpec, type ProductionSpec } from "../production";
+import type { PreviewContentType } from "../preview/contract";
+import type { DesiredChannel, ObservedChannel } from "../types";
+import { MediaSupervisor, type RelayJob } from "./index";
+
+const id = (n: number): string => `00000000-0000-4000-8000-${String(n).padStart(12, "0")}`;
+const WS = "8f0c5a8e-3b1d-4c3e-9a5b-0c1d2e3f4a5b";
+const CH = "1a2b3c4d-5e6f-4a1b-8c2d-3e4f5a6b7c8d";
+
+function spec(opts: { take: 10 | 11; playlist: string[]; urlB?: string }): ProductionSpec {
+  return parseProductionSpec({
+    sources: [
+      { id: id(1), label: "Cam A", kind: "hls", url: "https://a.example/live.m3u8" },
+      { id: id(2), label: "Cam B", kind: "hls", url: opts.urlB ?? "https://b.example/live.m3u8" },
+      { id: id(3), label: "Loop", kind: "playlist", assetIds: opts.playlist, loop: true },
+    ],
+    scenes: [
+      { id: id(10), label: "Two up", layout: "2x1", slots: [
+        { index: 0, sourceId: id(1), rect: null, fit: "cover", audioMode: "primary", gainDb: 0 },
+        { index: 1, sourceId: id(2), rect: null, fit: "cover", audioMode: "on", gainDb: -6 },
+      ] },
+      { id: id(11), label: "Playlist", layout: "pip", slots: [
+        { index: 0, sourceId: id(3), rect: null, fit: "contain", audioMode: "primary", gainDb: 0 },
+        { index: 1, sourceId: id(1), rect: { x: 6500, y: 6500, w: 3000, h: 3000 }, fit: "cover", audioMode: "off", gainDb: 0 },
+      ] },
+    ],
+    buses: { preview: id(10), program: id(opts.take) },
+    overlays: [
+      { id: id(20), sceneId: id(10), kind: "lower_third", enabled: true, layer: 1, position: { x: 500, y: 7500 }, revisionId: id(30), assetId: "a".repeat(64), chyron: null, clock: null },
+    ],
+    transition: { type: "cut" },
+    audio: { masterGainDb: 0 },
+  });
+}
+
+class MemoryObserved implements ObservedStore {
+  rows = new Map<string, ObservedChannel>();
+  async get(workspaceId: string, channelId: string): Promise<ObservedChannel | null> { return this.rows.get(`${workspaceId}:${channelId}`) ?? null; }
+  async put(row: ObservedChannel): Promise<void> { this.rows.set(`${row.workspaceId}:${row.channelId}`, row); }
+  async heartbeat(_workerId: string, channels: ObservedChannel[]): Promise<void> { for (const row of channels) await this.put(row); }
+}
+
+const alive = (pid: number | undefined): boolean => pid !== undefined && spawnSync("kill", ["-0", String(pid)]).status === 0;
+
+test("signed TAKE / playlist edit / source change / stop through the supervisor into a real production job", { timeout: 300_000 }, async (t) => {
+  if (!ensureGateBinary()) { t.skip("native helpers unavailable"); return; }
+  const dir = mkdtempSync(join(tmpdir(), "prod-e2e-"));
+  const [overlay] = makeAssets(dir);
+  // Two 2 s playlist assets (pre-normalized MP4, faststart), served as byte streams like a presigned GET.
+  const clips = new Map<string, string>();
+  for (const [n, hz] of [[40, 300], [41, 600], [42, 900]] as const) {
+    const path = join(dir, `asset-${n}.mp4`);
+    const r = spawnSync("ffmpeg", ["-hide_banner", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc2=s=1280x720:r=30:d=2", "-f", "lavfi", "-i", `sine=frequency=${hz}:d=2`,
+      "-c:v", "libx264", "-preset", "ultrafast", "-g", "30", "-c:a", "aac", "-movflags", "+faststart", path]);
+    assert.equal(r.status, 0, "asset encode");
+    clips.set(id(n), path);
+  }
+  const opened: string[] = [];
+  const store = new MemoryObserved();
+  const keys = generateKeyPairSync("ed25519");
+  const published = new Map<string, number>();
+  const jobs: ProductionJob[] = [];
+  const exits: string[] = [];
+  const createRelay = (_channel: DesiredChannel, onExit: (reason: string) => void): RelayJob => {
+    const job = new ProductionJob({
+      validator: { async validate() { throw new Error("not used: synthetic egress"); } },
+      vault: { async deliverPushTarget() { throw new Error("not used: null output"); } },
+      egress: {
+        // Stand-in for the WP7 relay: each HLS source becomes a synthetic, real-time ingest.
+        async prepare(config) {
+          const sources = new Map((config.production?.sources ?? []).filter((s) => s.kind === "hls")
+            .map((s, i) => [s.id, { input: { kind: "synthetic" as const, pattern: "smptehdbars" as const, seed: i + 1, toneHz: 440 + 220 * i }, fd: null }]));
+          return { sources, output: { kind: "null" as const }, async close() {} };
+        },
+      },
+      assets: { async localPath() { return overlay!; } },
+      playlists: {
+        async open(assetId) {
+          opened.push(assetId);
+          const path = clips.get(assetId);
+          if (!path) throw new Error("unknown asset");
+          return createReadStream(path);
+        },
+      },
+      preview: {
+        objects: { async putContent(body: Buffer, contentType: PreviewContentType) { return { key: `sha256/${"0".repeat(64)}.${contentType === "image/jpeg" ? "jpg" : "bin"}` }; } },
+        manifests: { async set(key: string) { published.set(key, (published.get(key) ?? 0) + 1); } },
+      },
+      redactor: passthroughRedactor, onStderr: () => undefined,
+      onExit: (reason) => { exits.push(reason); onExit(reason); },
+      scratchDir: join(dir, `scratch-${jobs.length}`),
+    });
+    jobs.push(job);
+    return job;
+  };
+  const base: DesiredChannel = {
+    workspaceId: WS, channelId: CH, workerId: "worker-1", assignmentEpoch: 1, desiredVersion: 0, desiredStatus: "RUNNING",
+    source: null, output: { endpointUrl: "rtmp://push.example/live", credentialHandleId: "keyref-1" }, profile: "720p30", mode: "normalize",
+    production: spec({ take: 10, playlist: [id(40), id(41)] }),
+  };
+  const worker = new MediaSupervisor("worker-1", [base], store, new DurableFence(join(dir, "fence.json")),
+    new Map([["control-v1", keys.publicKey]]), createRelay, { transition() {} });
+  const send = (version: number, production: ProductionSpec, status: "RUNNING" | "STOPPED" = "RUNNING") => {
+    const body: CommandBody = {
+      workspaceId: WS, channelId: CH, workerId: "worker-1", assignmentEpoch: 1, commandId: randomUUID(), desiredVersion: version,
+      issuedAt: new Date(Date.now() - 1_000).toISOString(), expiresAt: new Date(Date.now() + 120_000).toISOString(),
+      snapshot: { ...base, desiredVersion: version, desiredStatus: status, production },
+    };
+    return worker.handle(signCommand(body, "control-v1", keys.privateKey));
+  };
+  const status = () => worker.status()[0]!;
+  try {
+    await worker.start();
+    assert.equal(await send(1, spec({ take: 10, playlist: [id(40), id(41)] })), "accepted");
+    assert.equal(status().state, "RUNNING");
+    assert.equal(status().realizedVersion, 1);
+    const job1 = jobs[0]!;
+    const encoder = job1.program?.encoderPid;
+    assert.ok(alive(encoder), "encoder up");
+    // Baseline after the startup transient (compositor and x264 warming up repeat a few frames on a
+    // loaded host, as cpu-smoke reports): wait until the gate has not repeated for 1 s (at most 15 s).
+    let s1 = await job1.program!.stats();
+    for (let calm = 0, waited = 0; calm < 2 && waited < 30; waited += 1) {
+      await new Promise((r) => setTimeout(r, 500));
+      const now = await job1.program!.stats();
+      calm = now.vrep + now.asil === s1.vrep + s1.asil ? calm + 1 : 0;
+      s1 = now;
+    }
+
+    // TAKE: program scene 10 → 11 (playlist PIP). Same encoder; realized once B is on air.
+    let realizedDuringSwap: number | null = -1;
+    const swapping = send(2, spec({ take: 11, playlist: [id(40), id(41)] }));
+    await new Promise((r) => setTimeout(r, 50));
+    realizedDuringSwap = status().realizedVersion;
+    await swapping;
+    // On an oversubscribed host B can lag the on-air source (CompositorLagError): A stays on air,
+    // v1 stays realized, and the supervisor retries the swap (1 s, then 2 s). That is the contract too.
+    const retried = status().realizedVersion === 1 && /stays on air; retry/.test(status().reason);
+    const tSwap = Date.now();
+    while (status().realizedVersion !== 2 && jobs.length === 1 && Date.now() - tSwap < 30_000) await new Promise((r) => setTimeout(r, 100));
+    if (retried) t.diagnostic("TAKE went on air through a supervisor swap retry (B lagged on the first attempt)");
+    assert.equal(realizedDuringSwap, 1, "not realized before the new compositor is on air");
+    assert.equal(jobs.length, 1, `no restart (${status().reason})`);
+    assert.equal(status().realizedVersion, 2, `TAKE realized (${status().reason})`);
+    assert.match(status().reason, /frame boundary/);
+    const s2 = await job1.program!.stats();
+    assert.equal(job1.program?.encoderPid, encoder, "same encoder process: the push session never dropped");
+    assert.equal(s2.swaps, s1.swaps + 1);
+    // A fill here would be the gate itself starved on an oversubscribed host, never the splice; keep it rare.
+    const fills = s2.vrep + s2.asil - (s1.vrep + s1.asil);
+    assert.ok(fills <= 2, `no repeat or silence fill across the swap (${fills})`);
+    assert.deepEqual(job1.lastSkipped, []);
+
+    // Playlist edit: adopted in place by the feeder (no restart), and the program keeps running.
+    await send(3, spec({ take: 11, playlist: [id(42), id(40)] }));
+    assert.equal(status().realizedVersion, 3);
+    assert.equal(jobs.length, 1);
+    assert.equal(job1.program?.encoderPid, encoder);
+    const feeder = job1.feeder(id(3))!;
+    const t0 = Date.now();
+    while (!opened.includes(id(42)) && Date.now() - t0 < 15_000) await new Promise((r) => setTimeout(r, 100));
+    assert.ok(opened.includes(id(42)), `the edited list is played (opened ${opened.join(",")})`);
+    assert.equal(feeder.stats.failures, 0);
+
+    // Previews: the program tap's thumbnail and always-on LL-HLS reached the manifest store.
+    const key = (tap: string, file: string): string => `preview:${WS}:${CH}:${tap}:${file}`;
+    const t1 = Date.now();
+    while (!published.has(key("program", "video.m3u8")) && Date.now() - t1 < 30_000) await new Promise((r) => setTimeout(r, 200));
+    assert.ok(published.has(key("program", "thumbnail.jpg")), "program thumbnail");
+    assert.ok(published.has(key("program", "video.m3u8")), "program LL-HLS");
+    assert.ok(published.has(key(id(1), "thumbnail.jpg")) || published.has(key(id(2), "thumbnail.jpg")), "source thumbnails");
+
+    // A changed source URL cannot be a swap: full restart, new encoder.
+    await send(4, spec({ take: 11, playlist: [id(42), id(40)], urlB: "https://b2.example/live.m3u8" }));
+    assert.equal(status().realizedVersion, 4);
+    assert.equal(jobs.length, 2, "restarted");
+    assert.ok(!alive(encoder), "the old encoder is gone");
+    assert.ok(alive(jobs[1]!.program?.encoderPid));
+
+    const last = jobs[1]!.program?.encoderPid;
+    await send(5, spec({ take: 11, playlist: [id(42)] }), "STOPPED");
+    assert.equal(status().state, "STOPPED");
+    assert.ok(!alive(last), "stopped");
+    assert.deepEqual(exits, [], "no job exited on its own");
+  } finally {
+    // Also on failure: the heartbeat interval and any pending swap retry would keep the process alive.
+    await worker.stop();
+    for (const job of jobs) await job.stop();
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
diff --git a/apps/media-worker/src/supervisor/reconfigure.test.ts b/apps/media-worker/src/supervisor/reconfigure.test.ts
new file mode 100644
index 0000000..b1b6794
--- /dev/null
+++ b/apps/media-worker/src/supervisor/reconfigure.test.ts
@@ -0,0 +1,155 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { signCommand, type CommandBody } from "../bus/envelope";
+import { DurableFence } from "../bus/fence";
+import type { ObservedStore } from "../bus/redis";
+import { MediaSupervisor, type RelayJob, type RetryScheduler } from "./index";
+import type { DesiredChannel, ObservedChannel } from "../types";
+
+const base: DesiredChannel = {
+  workspaceId: "workspace-1", channelId: "channel-1", workerId: "worker-1",
+  assignmentEpoch: 2, desiredVersion: 1, desiredStatus: "RUNNING",
+  source: { kind: "hls", url: "https://mock.local/hls/live-1/master.m3u8" },
+  output: { endpointUrl: "rtmp://mock.local/live", credentialHandleId: "keyref-1" },
+  profile: "720p30", mode: "normalize",
+};
+
+const store: ObservedStore = {
+  async get() { return null; },
+  async put(_row: ObservedChannel) {},
+  async heartbeat() {},
+};
+
+test("RUNNING → RUNNING on a swappable job is an in-place reconfigure, realized only when on air", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-reconf-"));
+  const keys = generateKeyPairSync("ed25519");
+  const calls: string[] = [];
+  let accept = true;
+  let failures = 0;
+  const job = (): RelayJob => ({
+    async start(c) { calls.push(`start v${c.desiredVersion}`); },
+    async stop() { calls.push("stop"); },
+    async reconfigure(c) {
+      calls.push(`swap v${c.desiredVersion}`);
+      if (failures > 0) { failures -= 1; throw new Error("compositor B never went on air"); }
+      return accept;
+    },
+  });
+  // Manual retry scheduler: the test fires retries itself.
+  const pending: Array<{ action: () => Promise<void>; delayMs: number; cancelled: boolean }> = [];
+  const scheduler: RetryScheduler = {
+    schedule(action, delayMs) { const entry = { action, delayMs, cancelled: false }; pending.push(entry); return { cancel: () => { entry.cancelled = true; } }; },
+  };
+  const fire = async (): Promise<number> => { const entry = pending.shift(); assert.ok(entry && !entry.cancelled, "a retry is scheduled"); await entry.action(); return entry.delayMs; };
+  const worker = new MediaSupervisor("worker-1", [base], store, new DurableFence(join(dir, "fence.json")),
+    new Map([["control-v1", keys.publicKey]]), job, { transition() {} }, scheduler);
+  const send = (version: number, status: "RUNNING" | "STOPPED" = "RUNNING") => {
+    const body: CommandBody = {
+      workspaceId: base.workspaceId, channelId: base.channelId, workerId: base.workerId, assignmentEpoch: base.assignmentEpoch,
+      commandId: randomUUID(), desiredVersion: version, issuedAt: new Date(Date.now() - 1_000).toISOString(),
+      expiresAt: new Date(Date.now() + 60_000).toISOString(), snapshot: { ...base, desiredVersion: version, desiredStatus: status },
+    };
+    return worker.handle(signCommand(body, "control-v1", keys.privateKey));
+  };
+  const status = () => worker.status()[0]!;
+  try {
+    await worker.start();
+    await send(1);
+    assert.deepEqual(calls, ["start v1"]);
+    await send(2);
+    assert.deepEqual(calls, ["start v1", "swap v2"], "a TAKE never stops the job (encoder/RTMP stay up)");
+    assert.equal(status().state, "RUNNING");
+    assert.equal(status().realizedVersion, 2);
+    assert.match(status().reason, /frame boundary/);
+    accept = false;
+    await send(3);
+    assert.deepEqual(calls.slice(2), ["swap v3", "stop", "start v3"], "an unswappable change falls back to restart");
+    accept = true;
+
+    // A failed swap keeps the old compositor on air: still RUNNING, realized = what viewers see, retried.
+    failures = 1;
+    await send(4);
+    assert.deepEqual(calls.slice(5), ["swap v4"]);
+    assert.equal(status().state, "RUNNING");
+    assert.equal(status().realizedVersion, 3, "v3 is still on air");
+    assert.match(status().reason, /swap to v4 failed .*v3 stays on air; retry 1\/2/);
+    assert.equal(await fire(), 1_000);
+    assert.deepEqual(calls.slice(5), ["swap v4", "swap v4"], "the retry swaps; nothing restarts");
+    assert.equal(status().realizedVersion, 4);
+
+    // A newer command supersedes a pending retry.
+    failures = 1;
+    await send(5);
+    await send(6);
+    assert.deepEqual(calls.slice(7), ["swap v5", "swap v6"]);
+    assert.equal(pending.shift()?.cancelled, true, "the v5 retry was cancelled by v6");
+    assert.equal(status().realizedVersion, 6);
+
+    // Out of retries: the full restart converges (and is the only path that drops the push session).
+    failures = 3;
+    await send(7);
+    assert.equal(await fire(), 1_000);
+    assert.equal(await fire(), 2_000);
+    assert.deepEqual(calls.slice(9), ["swap v7", "swap v7", "swap v7", "stop", "start v7"]);
+    assert.equal(status().realizedVersion, 7);
+    assert.equal(status().state, "RUNNING");
+
+    await send(8, "STOPPED");
+    assert.deepEqual(calls.slice(14), ["stop"]);
+    assert.equal(pending.length, 0);
+    await worker.stop();
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("worker stop waits for an in-flight swap and no retry or relaunch runs after it", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-reconf-stop-"));
+  const keys = generateKeyPairSync("ed25519");
+  const calls: string[] = [];
+  let releaseSwap: (() => void) | null = null;
+  const job = (): RelayJob => ({
+    async start(c) { calls.push(`start v${c.desiredVersion}`); },
+    async stop() { calls.push("stop"); },
+    async reconfigure(c) {
+      calls.push(`swap v${c.desiredVersion}`);
+      // B is still trying to go on air when the worker shuts down; then it lags.
+      await new Promise<void>((resolve) => { releaseSwap = resolve; });
+      throw new Error("compositor B never went on air");
+    },
+  });
+  const pending: Array<{ action: () => Promise<void>; cancelled: boolean }> = [];
+  const scheduler: RetryScheduler = {
+    schedule(action) { const entry = { action, cancelled: false }; pending.push(entry); return { cancel: () => { entry.cancelled = true; } }; },
+  };
+  const worker = new MediaSupervisor("worker-1", [base], store, new DurableFence(join(dir, "fence.json")),
+    new Map([["control-v1", keys.publicKey]]), job, { transition() {} }, scheduler);
+  const send = (version: number) => {
+    const body: CommandBody = {
+      workspaceId: base.workspaceId, channelId: base.channelId, workerId: base.workerId, assignmentEpoch: base.assignmentEpoch,
+      commandId: randomUUID(), desiredVersion: version, issuedAt: new Date(Date.now() - 1_000).toISOString(),
+      expiresAt: new Date(Date.now() + 60_000).toISOString(), snapshot: { ...base, desiredVersion: version },
+    };
+    return worker.handle(signCommand(body, "control-v1", keys.privateKey));
+  };
+  try {
+    await worker.start();
+    await send(1);
+    const swapping = send(2);
+    while (!releaseSwap) await new Promise((r) => setImmediate(r));
+    let stopped = false;
+    const stopping = worker.stop().then(() => { stopped = true; });
+    await new Promise((r) => setImmediate(r));
+    assert.equal(stopped, false, "stop waits for the in-flight swap");
+    (releaseSwap as () => void)();
+    await swapping;
+    await stopping;
+    assert.deepEqual(calls, ["start v1", "swap v2", "stop"]);
+    assert.equal(worker.status()[0]?.state, "STOPPED");
+    // The retry the failed swap scheduled is cancelled, and running it anyway does nothing.
+    for (const entry of pending) { assert.equal(entry.cancelled, true); await entry.action(); }
+    assert.deepEqual(calls, ["start v1", "swap v2", "stop"]);
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/apps/media-worker/src/supervisor/sandbox.test.ts b/apps/media-worker/src/supervisor/sandbox.test.ts
new file mode 100644
index 0000000..86acb90
--- /dev/null
+++ b/apps/media-worker/src/supervisor/sandbox.test.ts
@@ -0,0 +1,109 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import test from "node:test";
+import { signCommand } from "../bus/envelope";
+import { DurableFence } from "../bus/fence";
+import type { ObservedStore } from "../bus/redis";
+import { buildCompositorArgs, buildEncoderArgs, buildIngestArgs, buildPlaylistRemuxArgs, buildSlateArgs } from "../compositor/command-builder";
+import { buildHlsTapArgs } from "../preview/argv";
+import { ffmpegArgs, spawnManaged, type ManagedProcess } from "../relay/ffmpeg";
+import type { DesiredChannel } from "../types";
+import { MediaSupervisor, type RelayJob } from "./index";
+import { supervisorSandboxEnabled } from "./sandbox";
+const pkg = (): {
+  sandboxCapability(options: { rootfs: string; cgroupRoot: string }): { available: boolean; reason?: string };
+  MediaCommandBuilder: new () => { supervisor(binary: "ffmpeg", args: readonly string[], scratch: string): { argv: readonly string[] } };
+} => require(resolve(__dirname, "../../../../packages/media-sandbox/dist"));
+const channel: DesiredChannel = {
+  workspaceId: "sandbox-workspace", channelId: "sandbox-channel", workerId: "sandbox-worker", assignmentEpoch: 1,
+  desiredVersion: 1, desiredStatus: "RUNNING", profile: "720p30", mode: "passthrough",
+  source: { kind: "hls", url: "https://source.example/live.m3u8" },
+  output: { endpointUrl: "rtmp://output.example/live", credentialHandleId: "opaque-handle" },
+};
+const store: ObservedStore = { async get() { return null; }, async put() {}, async heartbeat() {} };
+async function env<T>(values: Record<string, string | undefined>, action: () => Promise<T>): Promise<T> {
+  const previous = Object.fromEntries(Object.keys(values).map(key => [key, process.env[key]]));
+  for (const [key, value] of Object.entries(values)) { if (value === undefined) delete process.env[key]; else process.env[key] = value; }
+  try { return await action(); }
+  finally { for (const [key, value] of Object.entries(previous)) { if (value === undefined) delete process.env[key]; else process.env[key] = value; } }
+}
+function command(keys: ReturnType<typeof generateKeyPairSync>) {
+  return signCommand({ workspaceId: channel.workspaceId, channelId: channel.channelId, workerId: channel.workerId,
+    assignmentEpoch: 1, commandId: randomUUID(), desiredVersion: 1,
+    issuedAt: new Date(Date.now() - 1000).toISOString(), expiresAt: new Date(Date.now() + 60_000).toISOString(), snapshot: channel }, "control", keys.privateKey);
+}
+test("sandbox flag defaults locally off and on in production; production off is rejected", async () => {
+  await env({ NODE_ENV: "development", MEDIA_SANDBOX: undefined }, async () => assert.equal(supervisorSandboxEnabled(), false));
+  await env({ NODE_ENV: "production", MEDIA_SANDBOX: undefined }, async () => assert.equal(supervisorSandboxEnabled(), true));
+  await env({ NODE_ENV: "production", MEDIA_SANDBOX: "off" }, async () => assert.throws(supervisorSandboxEnabled, /requires/));
+});
+test("sandbox builder accepts existing relay/ingest/compositor/encoder/playlist/preview plans", () => {
+  const builder = new (pkg().MediaCommandBuilder)(); const canvas = { width: 1280, height: 720, fps: 30 };
+  const plans = [ffmpegArgs(channel), buildPlaylistRemuxArgs(0),
+    buildIngestArgs({ canvas, input: { kind: "mpegtsPipe" }, audio: "source" }),
+    buildIngestArgs({ canvas, input: { kind: "synthetic", pattern: "testsrc2", seed: 1, toneHz: 440 }, audio: "source" }),
+    buildEncoderArgs({ canvas, videoBitrateKbps: 2800, audioBitrateKbps: 128, output: { kind: "null" }, programTap: { videoFd: 5, audioFd: 6, size: { width: 320, height: 180 } } }),
+    buildSlateArgs({ canvas, seconds: 5, image: `/job/${"a".repeat(64)}.png`, offsetUs: 0 }),
+    buildHlsTapArgs({ geometry: canvas, rendition: "video", outDir: "/job/taps/video" }),
+    buildCompositorArgs({ sources: [{ video: { kind: "rawPipe", fd: 3 }, audio: { kind: "rawPipe", fd: 4 } }], assets: [`/job/${"a".repeat(64)}.png`],
+      graph: { canvas, layout: "single", tiles: [{ source: 0, rect: { x: 0, y: 0, w: 1280, h: 720 }, fit: "cover" }],
+        overlays: [{ kind: "chyron", asset: 0, y: 10, speedPxPerSec: 40 }], audio: { inputs: [{ source: 0, gainDb: 0 }], masterGainDb: 0 } }, output: { kind: "gate", videoFd: 1, audioFd: 3 } })];
+  for (const args of plans) assert.ok(builder.supervisor("ffmpeg", args, "/job").argv.includes("-protocol_whitelist"));
+});
+test("supervisor fails closed if sandbox is enabled without configuration", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-sandbox-closed-")); const keys = generateKeyPairSync("ed25519");
+  const lines: string[] = [];
+  await env({ NODE_ENV: "development", MEDIA_SANDBOX: "on", MEDIA_SANDBOX_ROOTFS: undefined, MEDIA_SANDBOX_CGROUP_ROOT: undefined, MEDIA_SCRATCH_DIR: join(dir, "scratch") }, async () => {
+    const worker = new MediaSupervisor(channel.workerId, [channel], store, new DurableFence(join(dir, "fence")), new Map([["control", keys.publicKey]]),
+      (): RelayJob => ({ async start() { spawnManaged("ffmpeg", ffmpegArgs(channel), ["ignore", "ignore", "pipe"], { redact: v => v }, line => lines.push(line)); }, async stop() {} }),
+      { transition: event => lines.push(JSON.stringify(event)) }, { schedule() { return { cancel() {} }; } });
+    try { await worker.start(); await worker.handle(command(keys)); assert.equal(worker.status()[0]?.state, "RESTARTING"); assert.ok(lines.join("\n").includes("SandboxUnavailable")); }
+    finally { await worker.stop(); }
+  });
+  rmSync(dir, { recursive: true, force: true });
+});
+
+for (const enabled of [false, true]) test(`secret-leak canaries through signed supervisor command (sandbox ${enabled ? "on" : "off"})`, { timeout: 20_000 }, async t => {
+  const dir = mkdtempSync(join(tmpdir(), "media-supervisor-canary-"));
+  const rootfs = join(dir, "rootfs");
+  for (const d of ["upload", "scratch", "tmp", "proc", "dev", "usr/bin"]) mkdirSync(join(rootfs, d), { recursive: true });
+  writeFileSync(join(rootfs, "dev/null"), "");
+  try {
+    if (enabled) {
+      const compiled = spawnSync("cc", ["-static", "-O0", resolve(__dirname, "../../../../packages/media-sandbox/native/test-child.c"), "-o", join(rootfs, "usr/bin/ffmpeg")]);
+      const cap = compiled.status === 0 ? pkg().sandboxCapability({ rootfs, cgroupRoot: process.env.MEDIA_SANDBOX_CGROUP_ROOT ?? "/sys/fs/cgroup" }) : { available: false, reason: "static compiler unavailable" };
+      if (!cap.available) { t.skip(`rootless sandbox canary skipped: ${cap.reason}`); return; }
+    }
+    const canaries = ["stream-key-canary-supervisor-531", "oauth-token-canary-supervisor-794", "srt-passphrase-canary-supervisor-652"];
+    await env({ NODE_ENV: "development", MEDIA_SANDBOX: enabled ? "on" : "off", MEDIA_SANDBOX_ROOTFS: rootfs,
+      MEDIA_SANDBOX_CGROUP_ROOT: process.env.MEDIA_SANDBOX_CGROUP_ROOT ?? "/sys/fs/cgroup", MEDIA_SCRATCH_DIR: join(dir, "scratch"),
+      CANARY_STREAM_KEY: canaries[0], CANARY_OAUTH_TOKEN: canaries[1], CANARY_SRT_PASSPHRASE: canaries[2] }, async () => {
+      const keys = generateKeyPairSync("ed25519"); const lines: string[] = []; let proc: ManagedProcess | undefined;
+      const worker = new MediaSupervisor(channel.workerId, [channel], store, new DurableFence(join(dir, "fence")), new Map([["control", keys.publicKey]]),
+        (_channel, onExit): RelayJob => ({
+          async start() {
+            proc = spawnManaged("ffmpeg", ["-hide_banner", "-nostdin", "-loglevel", "error", "-f", "mpegts", "-i", "pipe:0", "-f", "null", "pipe:1"],
+              ["pipe", "ignore", "pipe"], { redact: value => value }, line => lines.push(line));
+            void proc.exited.then(({ code }) => onExit(`ffmpeg exited code=${code}`)); await proc.started;
+          },
+          async stop() { await proc?.terminate(100); },
+        }), { transition: event => lines.push(JSON.stringify(event)) }, { schedule() { return { cancel() {} }; } });
+      try {
+        await worker.start(); await worker.handle(command(keys));
+        assert.equal(worker.status()[0]?.state, "RUNNING"); assert.ok(proc?.child.pid);
+        assert.equal(proc.child.spawnfile.endsWith("media-confine"), enabled);
+        const cmdline = readFileSync(`/proc/${proc.child.pid}/cmdline`, "utf8");
+        const environment = readFileSync(`/proc/${proc.child.pid}/environ`, "utf8");
+        proc.child.stdin!.end("invalid-media-to-force-ffmpeg-error");
+        const result = await proc.exited; assert.notEqual(result.code, 0);
+        await worker.stop();
+        assert.ok(lines.some(line => enabled ? line.includes("stderr suppressed") : /Invalid data|could not find codec|End of file/i.test(line)));
+        for (const canary of canaries) for (const output of [cmdline, environment, ...lines]) assert.ok(!output.includes(canary));
+      } finally { await worker.stop(); }
+    });
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/apps/media-worker/src/supervisor/sandbox.ts b/apps/media-worker/src/supervisor/sandbox.ts
new file mode 100644
index 0000000..877e2e2
--- /dev/null
+++ b/apps/media-worker/src/supervisor/sandbox.ts
@@ -0,0 +1,99 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+import type * as ChildProcessApi from "node:child_process";
+import { chmodSync, mkdirSync, constants, openSync, closeSync, fchmodSync } from "node:fs";
+import { resolve } from "node:path";
+import { Transform } from "node:stream";
+import type { DesiredChannel } from "../types";
+import type { RelayJob } from "./index";
+
+const childProcess: { spawn: typeof ChildProcessApi.spawn } = require("node:child_process");
+
+// Resolve the CommonJS package from either src/supervisor or dist/supervisor.
+// A small structural boundary keeps worker typechecking independent of package build order.
+interface MediaCommand { binary: "ffmpeg" | "ffprobe"; argv: readonly string[] }
+interface SandboxModule {
+  MediaCommandBuilder: new () => { supervisor(binary: MediaCommand["binary"], argv: readonly string[], scratch: string): MediaCommand };
+  SandboxUnavailable: new () => Error;
+  spawnSandbox(command: MediaCommand, options: { rootfs: string; cgroupRoot: string; scratchDir: string; limits: { wallTimeMs: number } }, spawnOptions: ChildProcessApi.SpawnOptions | undefined, spawner: typeof ChildProcessApi.spawn): { child: ChildProcessApi.ChildProcess };
+}
+const sandbox = (): SandboxModule => require(resolve(__dirname, "../../../../packages/media-sandbox/dist")) as SandboxModule;
+interface Context { scratch: string }
+const context = new AsyncLocalStorage<Context>();
+let installed = false;
+
+/**
+ * The only common spawn path lives in relay/, outside this change's boundary.
+ * A scoped Node spawn adapter covers existing typed FFmpeg builders, including
+ * asynchronous swaps/playlist producers, without altering their process API.
+ * Non-media children and calls outside a supervisor job retain normal spawning.
+ */
+function installAdapter(): void {
+  if (installed) return;
+  const original = childProcess.spawn;
+  childProcess.spawn = ((command: string, args?: readonly string[] | ChildProcessApi.SpawnOptions, options?: ChildProcessApi.SpawnOptions) => {
+    const job = context.getStore();
+    if (!job || !/(?:^|\/)(?:ffmpeg|ffprobe)$/.test(command)) {
+      return typeof args === "object" && !Array.isArray(args)
+        ? original(command, args as ChildProcessApi.SpawnOptions)
+        : original(command, (args as readonly string[] | undefined) ?? [], options ?? {});
+    }
+    if (!Array.isArray(args)) throw new Error("media argv required");
+    const runtime = sandbox();
+    const rootfs = process.env.MEDIA_SANDBOX_ROOTFS;
+    const cgroupRoot = process.env.MEDIA_SANDBOX_CGROUP_ROOT;
+    if (!rootfs || !cgroupRoot) throw new runtime.SandboxUnavailable();
+    const media = new runtime.MediaCommandBuilder().supervisor(command.endsWith("ffprobe") ? "ffprobe" : "ffmpeg", args, job.scratch);
+    // Make only generated output directories writable by the mapped UID.
+    // Traverse through directory fds: a compromised sibling cannot race a
+    // symlink replacement into chmod of a host file.
+    for (const path of media.argv.filter(value => value.startsWith("file:/scratch/"))) {
+      const parts = path.slice("file:/scratch/".length).split("/").slice(0, -1).filter(part => part && part !== ".");
+      if (parts.length > 32 || parts.some(part => part === "..")) throw new runtime.SandboxUnavailable();
+      let fd = openSync(job.scratch, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+      try {
+        fchmodSync(fd, 0o777);
+        for (const part of parts) {
+          const next = openSync(`/proc/self/fd/${fd}/${part}`, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+          closeSync(fd); fd = next; fchmodSync(fd, 0o777);
+        }
+      } finally { closeSync(fd); }
+    }
+    const child = runtime.spawnSandbox(media, {
+      rootfs, cgroupRoot, scratchDir: job.scratch,
+      // Long-running channels still have a finite job lease; uploads use the package defaults.
+      limits: { wallTimeMs: Number(process.env.MEDIA_SANDBOX_WALL_TIME_MS ?? 86_400_000) },
+    }, options, original).child;
+    // Replace the public stderr stream BEFORE spawnManaged attaches its logger.
+    // Arbitrary media bytes cannot bypass a caller-supplied passthrough redactor.
+    if (child.stderr) {
+      const safe = new Transform({ transform(_chunk, _encoding, done) { done(null, Buffer.from("[media stderr suppressed]\n")); } });
+      child.stderr.pipe(safe); child.stderr = safe; child.stdio[2] = safe;
+    }
+    return child;
+  }) as typeof childProcess.spawn;
+  installed = true;
+}
+function enabled(): boolean {
+  const flag = process.env.MEDIA_SANDBOX;
+  if (flag !== undefined && flag !== "on" && flag !== "off") throw new Error("MEDIA_SANDBOX must be on or off");
+  if (process.env.NODE_ENV === "production" && flag === "off") throw new Error("production requires media sandbox");
+  return flag === "on" || process.env.NODE_ENV === "production";
+}
+export function supervisorSandboxEnabled(): boolean { return enabled(); }
+
+export function sandboxRelay(job: RelayJob, channel: DesiredChannel): RelayJob {
+  if (!enabled()) return job;
+  installAdapter();
+  const id = createHash("sha256").update(`${channel.workspaceId}:${channel.channelId}`).digest("hex").slice(0, 32);
+  const parent = resolve(process.env.MEDIA_SCRATCH_DIR ?? ".media-worker-state/scratch");
+  const scratch = resolve(parent, id);
+  mkdirSync(parent, { recursive: true }); chmodSync(parent, 0o700);
+  mkdirSync(scratch, { recursive: true }); chmodSync(scratch, 0o777);
+  const run = <T>(action: () => T): T => context.run({ scratch }, action);
+  return {
+    start: config => run(() => job.start(config)),
+    stop: () => run(() => job.stop()),
+    ...(job.reconfigure ? { reconfigure: (config: DesiredChannel) => run(() => job.reconfigure!(config)) } : {}),
+  };
+}
diff --git a/apps/media-worker/src/supervisor/supervisor.test.ts b/apps/media-worker/src/supervisor/supervisor.test.ts
new file mode 100644
index 0000000..adde96f
--- /dev/null
+++ b/apps/media-worker/src/supervisor/supervisor.test.ts
@@ -0,0 +1,135 @@
+import assert from "node:assert/strict";
+import { generateKeyPairSync, randomUUID } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { signCommand, type CommandBody } from "../bus/envelope";
+import { DurableFence } from "../bus/fence";
+import type { ObservedStore } from "../bus/redis";
+import { MediaSupervisor, type RelayJob, type RetryScheduler } from "./index";
+import type { DesiredChannel, ObservedChannel } from "../types";
+
+const source: DesiredChannel = {
+  workspaceId: "workspace-1", channelId: "channel-1", workerId: "worker-1",
+  assignmentEpoch: 2, desiredVersion: 4, desiredStatus: "RUNNING",
+  // Same HLS/RTMP endpoint shape supplied by connector-mock-livestream and the single-live simulator.
+  source: { kind: "hls", url: "https://mock.local/hls/live-1/master.m3u8" },
+  output: { endpointUrl: "rtmp://mock.local/live", credentialHandleId: "keyref-1" },
+  profile: "720p30", mode: "passthrough",
+};
+
+class MemoryObserved implements ObservedStore {
+  rows = new Map<string, ObservedChannel>();
+  heartbeats: Array<{ workerId: string; channels: ObservedChannel[] }> = [];
+  async get(workspaceId: string, channelId: string): Promise<ObservedChannel | null> { return this.rows.get(`${workspaceId}:${channelId}`) ?? null; }
+  async put(row: ObservedChannel): Promise<void> { this.rows.set(`${row.workspaceId}:${row.channelId}`, row); }
+  async heartbeat(workerId: string, channels: ObservedChannel[]): Promise<void> {
+    this.heartbeats.push({ workerId, channels });
+    for (const row of channels) await this.put(row);
+  }
+}
+
+test("durable replay fence, stale version, and restart reconcile", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-fence-"));
+  const store = new MemoryObserved();
+  const keys = generateKeyPairSync("ed25519");
+  const pinned = new Map([["control-v1", keys.publicKey]]);
+  let starts = 0;
+  const makeSupervisor = () => new MediaSupervisor("worker-1", [source], store,
+    new DurableFence(join(dir, "fence.json")), pinned,
+    (): RelayJob => ({ async start() { starts += 1; }, async stop() {} }),
+    { transition() {} });
+  const makeBody = (commandId: string, version: number): CommandBody => ({
+    workspaceId: source.workspaceId, channelId: source.channelId, workerId: source.workerId,
+    assignmentEpoch: source.assignmentEpoch, commandId, desiredVersion: version,
+    issuedAt: new Date(Date.now() - 1_000).toISOString(),
+    expiresAt: new Date(Date.now() + 60_000).toISOString(),
+    snapshot: { ...source, desiredVersion: version },
+  });
+  try {
+    const first = signCommand(makeBody(randomUUID(), 4), "control-v1", keys.privateKey);
+    const worker = makeSupervisor();
+    await worker.start();
+    assert.equal(worker.status()[0]?.realizedVersion, null);
+    assert.equal(await worker.handle(first), "accepted");
+    assert.equal(worker.status()[0]?.state, "RUNNING");
+    assert.equal(worker.status()[0]?.realizedVersion, 4);
+    assert.equal(starts, 1);
+    await worker.stop();
+
+    const restarted = makeSupervisor();
+    await restarted.start();
+    assert.equal(restarted.status()[0]?.realizedVersion, null);
+    assert.match(restarted.status()[0]?.reason ?? "", /restart reconcile/);
+    assert.equal(await restarted.handle(first), "replay");
+    assert.equal(starts, 1);
+    const stale = signCommand(makeBody(randomUUID(), 3), "control-v1", keys.privateKey);
+    assert.equal(await restarted.handle(stale), "stale");
+    const freshSnapshot = signCommand(makeBody(randomUUID(), 4), "control-v1", keys.privateKey);
+    assert.equal(await restarted.handle(freshSnapshot), "accepted");
+    assert.equal(restarted.status()[0]?.realizedVersion, 4);
+    assert.equal(starts, 2);
+    await restarted.stop();
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("unsigned, expired, wrong target and tampered snapshots are rejected", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-command-"));
+  const keys = generateKeyPairSync("ed25519");
+  const worker = new MediaSupervisor("worker-1", [source], new MemoryObserved(),
+    new DurableFence(join(dir, "fence.json")), new Map([["control-v1", keys.publicKey]]),
+    (): RelayJob => ({ async start() {}, async stop() {} }), { transition() {} });
+  const body: CommandBody = {
+    workspaceId: source.workspaceId, channelId: source.channelId, workerId: source.workerId,
+    assignmentEpoch: source.assignmentEpoch, commandId: randomUUID(), desiredVersion: 4,
+    issuedAt: new Date(Date.now() - 2_000).toISOString(), expiresAt: new Date(Date.now() + 30_000).toISOString(), snapshot: source,
+  };
+  try {
+    await worker.start();
+    await assert.rejects(worker.handle({ kid: "control-v1", body, signature: "" }), /signature/);
+    await assert.rejects(worker.handle(signCommand({ ...body, workerId: "other" }, "control-v1", keys.privateKey)), /fields/);
+    const expired = { ...body, expiresAt: new Date(Date.now() - 1).toISOString() };
+    await assert.rejects(worker.handle(signCommand(expired, "control-v1", keys.privateKey)), /expired/);
+    const tampered = signCommand(body, "control-v1", keys.privateKey);
+    tampered.body.snapshot = { ...source, desiredStatus: "STOPPED" };
+    await assert.rejects(worker.handle(tampered), /signature/);
+    await worker.stop();
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
+
+test("relay failure follows DEGRADED, RESTARTING and bounded FAILED states", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "media-retry-"));
+  const keys = generateKeyPairSync("ed25519");
+  const queued: Array<{ action: () => Promise<void>; delay: number }> = [];
+  const scheduler: RetryScheduler = {
+    schedule(action, delay) { queued.push({ action, delay }); return { cancel() {} }; },
+  };
+  const transitions: string[] = [];
+  const worker = new MediaSupervisor("worker-1", [source], new MemoryObserved(),
+    new DurableFence(join(dir, "fence.json")), new Map([["control-v1", keys.publicKey]]),
+    (): RelayJob => ({ async start() { throw new Error("ingest unavailable"); }, async stop() {} }),
+    { transition(event) { transitions.push(event.to); } }, scheduler);
+  try {
+    await worker.start();
+    const body: CommandBody = {
+      workspaceId: source.workspaceId, channelId: source.channelId, workerId: source.workerId,
+      assignmentEpoch: source.assignmentEpoch, commandId: randomUUID(), desiredVersion: 4,
+      issuedAt: new Date(Date.now() - 1_000).toISOString(), expiresAt: new Date(Date.now() + 60_000).toISOString(), snapshot: source,
+    };
+    assert.equal(await worker.handle(signCommand(body, "control-v1", keys.privateKey)), "accepted");
+    assert.equal(worker.status()[0]?.state, "RESTARTING");
+    const delays: number[] = [];
+    while (queued.length) {
+      const next = queued.shift();
+      assert.ok(next);
+      delays.push(next.delay);
+      await next.action();
+    }
+    assert.deepEqual(delays, [1_000, 2_000, 4_000, 8_000, 16_000]);
+    assert.equal(worker.status()[0]?.state, "FAILED");
+    assert.equal(worker.status()[0]?.realizedVersion, null);
+    assert.ok(transitions.includes("DEGRADED"));
+    await worker.stop();
+  } finally { rmSync(dir, { recursive: true, force: true }); }
+});
diff --git a/apps/media-worker/src/types.ts b/apps/media-worker/src/types.ts
new file mode 100644
index 0000000..32ce8d4
--- /dev/null
+++ b/apps/media-worker/src/types.ts
@@ -0,0 +1,69 @@
+import { isProductionSpec, productionHlsUrls, type ProductionSpec } from "./production";
+
+export type ChannelState = "STOPPED" | "STARTING" | "RUNNING" | "DEGRADED" | "RESTARTING" | "FAILED";
+export type DesiredState = "STOPPED" | "RUNNING";
+export type OutputPreset = "720p30" | "1080p30" | "1080p60";
+export type OutputMode = "passthrough" | "normalize";
+
+export const OUTPUT_PROFILES: Record<OutputPreset, { width: number; height: number; fps: number; videoBitrate: string }> = {
+  "720p30": { width: 1280, height: 720, fps: 30, videoBitrate: "3000k" },
+  "1080p30": { width: 1920, height: 1080, fps: 30, videoBitrate: "6000k" },
+  "1080p60": { width: 1920, height: 1080, fps: 60, videoBitrate: "9000k" },
+};
+
+/** A complete, secret-free channel snapshot. The control plane owns this record. */
+export interface DesiredChannel {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  desiredVersion: number;
+  desiredStatus: DesiredState;
+  source: { kind: "hls"; url: string } | null;
+  output: { endpointUrl: string; credentialHandleId: string } | null;
+  profile: OutputPreset;
+  mode: OutputMode;
+  /**
+   * Desired-state v2 (production: scenes, buses, sources, overlays,
+   * transition, audio). Absent on v1 snapshots; when present, `source` is null.
+   */
+  production?: ProductionSpec;
+}
+
+export interface ObservedChannel {
+  workspaceId: string;
+  channelId: string;
+  workerId: string;
+  assignmentEpoch: number;
+  state: ChannelState;
+  realizedVersion: number | null;
+  updatedAt: string;
+  reason: string;
+}
+
+export function isDesiredChannel(value: unknown): value is DesiredChannel {
+  if (typeof value !== "object" || value === null) return false;
+  const x = value as Partial<DesiredChannel>;
+  if (!onlyKeys(value, ["workspaceId", "channelId", "workerId", "assignmentEpoch", "desiredVersion", "desiredStatus", "source", "output", "profile", "mode", "production"])) return false;
+  if ("production" in value && (x.source !== null || !isProductionSpec(x.production))) return false;
+  return typeof x.workspaceId === "string" && x.workspaceId.length > 0 &&
+    typeof x.channelId === "string" && x.channelId.length > 0 &&
+    typeof x.workerId === "string" && x.workerId.length > 0 &&
+    Number.isSafeInteger(x.assignmentEpoch) && (x.assignmentEpoch ?? -1) >= 0 &&
+    Number.isSafeInteger(x.desiredVersion) && (x.desiredVersion ?? -1) >= 0 &&
+    (x.desiredStatus === "STOPPED" || x.desiredStatus === "RUNNING") &&
+    (x.mode === "passthrough" || x.mode === "normalize") &&
+    (x.profile === "720p30" || x.profile === "1080p30" || x.profile === "1080p60") &&
+    (x.source === null || (typeof x.source === "object" && x.source?.kind === "hls" && typeof x.source.url === "string" && x.source.url.length > 0 && onlyKeys(x.source, ["kind", "url"]))) &&
+    (x.output === null || (typeof x.output === "object" && typeof x.output?.endpointUrl === "string" && x.output.endpointUrl.length > 0 && typeof x.output.credentialHandleId === "string" && x.output.credentialHandleId.length > 0 && onlyKeys(x.output, ["endpointUrl", "credentialHandleId"]))) &&
+    (x.desiredStatus !== "RUNNING" || (x.output !== null && (x.production === undefined ? x.source !== null : x.production.buses.program !== null)));
+}
+
+/** Every remote HLS URL a snapshot can make the worker fetch (v1 source or v2 production sources). */
+export function snapshotHlsUrls(s: DesiredChannel): string[] {
+  return [...(s.source === null ? [] : [s.source.url]), ...(s.production === undefined ? [] : productionHlsUrls(s.production))];
+}
+
+function onlyKeys(value: object, allowed: string[]): boolean {
+  return Object.keys(value).every((key) => allowed.includes(key));
+}
diff --git a/apps/media-worker/tsconfig.json b/apps/media-worker/tsconfig.json
new file mode 100644
index 0000000..acb1540
--- /dev/null
+++ b/apps/media-worker/tsconfig.json
@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "CommonJS",
+    "moduleResolution": "node"
+  },
+  "include": [
+    "src"
+  ],
+  "exclude": [
+    "src/compositor/wp12-hardening.test.ts"
+  ]
+}
\ No newline at end of file
diff --git a/apps/scheduler/package.json b/apps/scheduler/package.json
new file mode 100644
index 0000000..7fdb4e3
--- /dev/null
+++ b/apps/scheduler/package.json
@@ -0,0 +1,39 @@
+{
+  "name": "@tactical-media-broadcast-hub/scheduler",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "tsx watch src/worker.ts",
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:integration": "node scripts/wp3-integration.mjs"
+  },
+  "dependencies": {
+    "@temporalio/client": "1.24.0",
+    "@temporalio/worker": "1.24.0",
+    "@temporalio/workflow": "1.24.0",
+    "pino": "^9.3.2",
+    "@tactical-media-broadcast-hub/publishing-execution": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-runtime": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-mastodon": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-telegram": "workspace:*",
+    "@temporalio/activity": "1.24.0",
+    "@temporalio/common": "1.24.0",
+    "pg": "^8.23.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "tsx": "^4.17.0",
+    "vitest": "^2.0.5",
+    "@types/pg": "^8.23.1",
+    "typescript": "^5.5.4"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "type": "module"
+}
diff --git a/apps/scheduler/scripts/wp3-integration.mjs b/apps/scheduler/scripts/wp3-integration.mjs
new file mode 100644
index 0000000..12e0a51
--- /dev/null
+++ b/apps/scheduler/scripts/wp3-integration.mjs
@@ -0,0 +1,57 @@
+// Local compiled-worker smoke. Uses a dedicated queue and only safe missing-job input.
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { resolve } from "node:path";
+import { Client, Connection, WorkflowExecutionAlreadyStartedError } from "@temporalio/client";
+import { randomUUID } from "node:crypto";
+if (!process.env.PUBLISHING_IT_DATABASE_URL) throw new Error("PUBLISHING_IT_DATABASE_URL is required (migrate dedicated local DB first)");
+const probe = createServer();
+await new Promise((done) => probe.listen(0, "127.0.0.1", done));
+const port = probe.address().port;
+await new Promise((done) => probe.close(done));
+const queue = `wp3-sol-${randomUUID()}`;
+const child = spawn(process.execPath, [resolve("dist/worker.js")], { env: { ...process.env, SCHEDULER_DATABASE_URL: process.env.PUBLISHING_IT_DATABASE_URL, SCHEDULER_HEALTH_PORT: String(port), TEMPORAL_TASK_QUEUE: queue, TEMPORAL_ADDRESS: "127.0.0.1:7233" }, stdio: ["ignore", "pipe", "pipe"] });
+let output = "";
+child.stdout.on("data", (chunk) => { output += chunk.toString(); });
+child.stderr.on("data", (chunk) => { output += chunk.toString(); });
+const exit = new Promise((done) => child.once("exit", (code) => done(code)));
+let connection;
+try {
+  let ready = false;
+  for (let count = 0; count < 100; count++) {
+    if (child.exitCode !== null) throw new Error("compiled worker exited before readiness");
+    try { const response = await fetch(`http://127.0.0.1:${port}/ready`, { signal: AbortSignal.timeout(1000) }); ready = response.status === 200; } catch {}
+    if (ready) break;
+    await new Promise((done) => setTimeout(done, 300));
+  }
+  if (!ready) throw new Error("compiled worker readiness timed out");
+  connection = await Connection.connect({ address: "127.0.0.1:7233" });
+  const client = new Client({ connection, namespace: process.env.TEMPORAL_NAMESPACE ?? "default" });
+  const ref = { workspaceId: randomUUID(), scheduleId: randomUUID(), generation: "1", idempotencyKey: `wp3-smoke-${randomUUID()}` };
+  // Use an existing, empty fixture workspace so claim returns a safe missing-fence
+  // outcome. This smoke does not acquire any credential or call a provider.
+  const { Pool } = await import("pg");
+  const pool = new Pool({ connectionString: process.env.PUBLISHING_IT_SUPER_DATABASE_URL });
+  const workspace = await pool.query("INSERT INTO workspaces(name,slug) VALUES('Temporal Smoke',$1) RETURNING id", [queue]);
+  ref.workspaceId = workspace.rows[0].id;
+  try {
+    const workflowId = `scheduled-publication-${ref.idempotencyKey}`;
+    const handle = await client.workflow.start("scheduledPublish", { taskQueue: queue, workflowId, args: [ref] });
+    const result = await handle.result();
+    if (result.kind !== "failed" || result.code !== "EXECUTION_FENCE_MISSING") throw new Error("unexpected workflow result");
+    let duplicate = false;
+    try { await client.workflow.start("scheduledPublish", { taskQueue: queue, workflowId, args: [ref], workflowIdReusePolicy: "REJECT_DUPLICATE" }); }
+    catch (error) { if (!(error instanceof WorkflowExecutionAlreadyStartedError)) throw error; duplicate = true; }
+    if (!duplicate) throw new Error("duplicate start was not fenced");
+    console.log("PASS: compiled worker readiness, registry/workflow bundle, real Temporal activity, structured outcome, duplicate start, graceful shutdown. No provider sends.");
+  } finally { await pool.query("DELETE FROM workspaces WHERE id=$1", [ref.workspaceId]); await pool.end(); }
+} catch (error) {
+  console.error(output.slice(-6000));
+  throw error;
+} finally {
+  child.kill("SIGTERM");
+  const code = await Promise.race([exit, new Promise((done) => setTimeout(() => done("timeout"), 15_000))]);
+  if (code === "timeout") { child.kill("SIGKILL"); throw new Error("worker did not drain"); }
+  if (code !== 0) throw new Error(`worker shutdown exit code ${code}`);
+  await connection?.close();
+}
diff --git a/apps/scheduler/src/activities/dispatch-gate.test.ts b/apps/scheduler/src/activities/dispatch-gate.test.ts
new file mode 100644
index 0000000..6c2e08d
--- /dev/null
+++ b/apps/scheduler/src/activities/dispatch-gate.test.ts
@@ -0,0 +1,101 @@
+import { describe, expect, it } from "vitest";
+import { evaluateE3, E3_REASON_CODES, type E3Outcome } from "./dispatch-gate.js";
+
+/**
+ * E3 pre-dispatch re-check (chatgov-design.md §4 step 5) — pure decision table.
+ * Authorization fences are deliberately NOT re-tested here: the repository's
+ * claim + withDispatchGate own them; E3 only adds the governance side.
+ */
+
+type Row = Parameters<typeof evaluateE3>[0];
+
+function row(overrides: Partial<NonNullable<Row>> = {}): NonNullable<Row> {
+  return {
+    state: "approved",
+    approved_hash: "abc123",
+    approved_revision: "1",
+    reviewer_user_id: "20000000-0000-4000-8000-000000000002",
+    effective: { mode: "immediate" },
+    policy_version: "pv1",
+    poll_state: null,
+    ...overrides,
+  };
+}
+
+describe("E3 pre-dispatch evaluation", () => {
+  it("fires an approved draft under a live snapshot", () => {
+    expect(evaluateE3(row())).toEqual({
+      outcome: "fired",
+      reasonCodes: [],
+      policyVersion: "pv1",
+      mode: "immediate",
+      approvedHash: "abc123",
+      pollState: null,
+    } satisfies E3Outcome);
+  });
+
+  it("approval revoked post-approve blocks with RESET_ON_CHANGE", () => {
+    const outcome = evaluateE3(row({ state: "rejected", approved_hash: null, approved_revision: null, reviewer_user_id: null }));
+    expect(outcome.outcome).toBe("blocked");
+    expect(outcome.reasonCodes).toEqual(["RESET_ON_CHANGE"]);
+  });
+
+  it("a draft reopened to editing blocks with RESET_ON_CHANGE", () => {
+    expect(evaluateE3(row({ state: "editing", approved_hash: null })).reasonCodes).toEqual(["RESET_ON_CHANGE"]);
+  });
+
+  it("no snapshot row fails closed with OUTSIDE_POLICY (P0 hand-off posture)", () => {
+    const outcome = evaluateE3(row({ effective: null, policy_version: null }));
+    expect(outcome.outcome).toBe("blocked");
+    expect(outcome.reasonCodes).toEqual(["OUTSIDE_POLICY"]);
+    expect(outcome.policyVersion).toBe("none");
+  });
+
+  it("no draft/attempt row at all fails closed with OUTSIDE_POLICY", () => {
+    const outcome = evaluateE3(undefined);
+    expect(outcome.outcome).toBe("blocked");
+    expect(outcome.reasonCodes).toEqual(["OUTSIDE_POLICY"]);
+  });
+
+  it("quorum mode blocks until the linked poll passed (P2 seam)", () => {
+    const blocked = evaluateE3(row({ effective: { mode: "quorum" }, poll_state: "open" }));
+    expect(blocked.outcome).toBe("blocked");
+    expect(blocked.reasonCodes).toEqual(["INSUFFICIENT_QUORUM", "PENDING_POLL"]);
+    const fired = evaluateE3(row({ effective: { mode: "quorum" }, poll_state: "passed" }));
+    expect(fired.outcome).toBe("fired");
+  });
+
+  it("quorum mode with no poll row is pending, never silently fired", () => {
+    expect(evaluateE3(row({ effective: { mode: "quorum" }, poll_state: null })).reasonCodes).toEqual(["INSUFFICIENT_QUORUM", "PENDING_POLL"]);
+  });
+
+  it("admin_only does not re-gate at E3 (its E1 verdict already fired)", () => {
+    expect(evaluateE3(row({ effective: { mode: "admin_only" } })).outcome).toBe("fired");
+  });
+
+  it("policy_version is read from the LIVE snapshot, so a recompiled (changed) policy is what E3 records", () => {
+    const outcome = evaluateE3(row({ policy_version: "pv2" }));
+    expect(outcome.policyVersion).toBe("pv2");
+  });
+});
+
+describe("reason-code vocabulary mirror", () => {
+  it("matches the §4 closed vocabulary the gate_decisions CHECK enforces", () => {
+    expect(E3_REASON_CODES).toEqual([
+      "INSUFFICIENT_QUORUM",
+      "INELIGIBLE_ACTOR",
+      "SELF_APPROVAL_DENIED",
+      "TIMEBOX_EXPIRED_AUTO_REJECT",
+      "TIMEBOX_EXPIRED_AUTO_APPROVE",
+      "RESET_ON_CHANGE",
+      "PENDING_POLL",
+      "VETOED",
+      "OUTSIDE_POLICY",
+      "POLICY_DRY_RUN",
+      "OVERRIDDEN_BY_OWNER",
+      "LOCKED_CHANNEL",
+      "NO_CHANNEL_BOUND",
+      "CONFIRM_EXPIRED",
+    ]);
+  });
+});
diff --git a/apps/scheduler/src/activities/dispatch-gate.ts b/apps/scheduler/src/activities/dispatch-gate.ts
new file mode 100644
index 0000000..f00eb38
--- /dev/null
+++ b/apps/scheduler/src/activities/dispatch-gate.ts
@@ -0,0 +1,228 @@
+import type { Pool } from "pg";
+
+/**
+ * §4 reason-code vocabulary (chatgov-design.md §4). Mirrored from the P0
+ * spine (apps/api/src/chatgov/policy.ts REASON_CODES) rather than imported
+ * across the app package boundary; gate_decisions CHECKs values, so this list
+ * must stay in sync — the unit tests assert the mirror.
+ */
+export const E3_REASON_CODES = [
+  "INSUFFICIENT_QUORUM",
+  "INELIGIBLE_ACTOR",
+  "SELF_APPROVAL_DENIED",
+  "TIMEBOX_EXPIRED_AUTO_REJECT",
+  "TIMEBOX_EXPIRED_AUTO_APPROVE",
+  "RESET_ON_CHANGE",
+  "PENDING_POLL",
+  "VETOED",
+  "OUTSIDE_POLICY",
+  "POLICY_DRY_RUN",
+  "OVERRIDDEN_BY_OWNER",
+  "LOCKED_CHANNEL",
+  "NO_CHANNEL_BOUND",
+  "CONFIRM_EXPIRED",
+] as const;
+export type ReasonCode = (typeof E3_REASON_CODES)[number];
+
+/**
+ * E3 pre-dispatch re-check (chatgov-design.md §4 step 5, P1).
+ *
+ * Re-evaluated IMMEDIATELY BEFORE each platform dispatch, per destination:
+ *   - approval still holds (the draft is still `approved`/`scheduled` with its
+ *     pinned approved_hash/revision — contentFenceHolds owns the content side
+ *     in the execution claim; E3 owns the *governance* side and re-reads the
+ *     draft row so a revocation that landed after the claim is caught here);
+ *   - the destination's compiled policy_version is still current (a rule
+ *     change after approval recompiles the snapshot ⇒ RESET_ON_CHANGE);
+ *   - a compiled snapshot exists at all — none is OUTSIDE_POLICY, fail closed
+ *     (P0 hand-off: "OUTSIDE_POLICY is the evaluation posture when no
+ *     snapshot row exists").
+ *
+ * Authorization fences (principal/approver/credential) are NOT duplicated
+ * here: the repository's claim + withDispatchGate already re-read every live
+ * authz input; E3 integrates by never weakening them.
+ *
+ * Every evaluation writes a gate_decisions row (fired or blocked) with the
+ * §4 reason codes, so partial fan-out ("A fired, B blocked") is observable
+ * from the blocked queue without touching the publishing spine.
+ */
+
+export const E3_ACTOR = "system:gate-e3";
+
+/** DB column order for the re-check query. */
+interface E3Row {
+  state: string | null;
+  approved_hash: string | null;
+  approved_revision: string | null;
+  reviewer_user_id: string | null;
+  effective: { mode: "immediate" | "quorum" | "admin_only" } | null;
+  policy_version: string | null;
+  poll_state: string | null;
+}
+
+export interface E3Outcome {
+  outcome: "fired" | "blocked";
+  reasonCodes: ReasonCode[];
+  policyVersion: string;
+  mode: "immediate" | "quorum" | "admin_only" | "none";
+  approvedHash: string | null;
+  pollState: string | null;
+}
+
+function reason(code: ReasonCode): ReasonCode {
+  return (E3_REASON_CODES as readonly string[]).includes(code) ? code : "OUTSIDE_POLICY";
+}
+
+export function evaluateE3(row: E3Row | undefined): E3Outcome {
+  // Fail closed: no attempt/draft/snapshot row at all.
+  if (row === undefined) {
+    return { outcome: "blocked", reasonCodes: [reason("OUTSIDE_POLICY")], policyVersion: "none", mode: "none", approvedHash: null, pollState: null };
+  }
+  const approvedHash = row.approved_hash === null ? null : String(row.approved_hash);
+
+  // 1) Approval still holds. `approved`/`scheduled` with a pinned hash is the
+  //    approved posture; anything else (rejected, editing, revoked approval)
+  //    is RESET_ON_CHANGE — the approval changed after it landed.
+  if (row.state !== "approved" && row.state !== "scheduled") {
+    return { outcome: "blocked", reasonCodes: [reason("RESET_ON_CHANGE")], policyVersion: row.policy_version ?? "none", mode: row.effective?.mode ?? "none", approvedHash, pollState: null };
+  }
+
+  // 2) A compiled snapshot exists for this destination. None => fail closed
+  //    (P0 hand-off: OUTSIDE_POLICY posture, never a silent ungated send).
+  if (row.effective === null || row.policy_version === null) {
+    return { outcome: "blocked", reasonCodes: [reason("OUTSIDE_POLICY")], policyVersion: "none", mode: "none", approvedHash, pollState: null };
+  }
+
+  // 3) Policy version still current is implied by reading the LIVE snapshot
+  //    row: a rule change recompiled it in place (whole-block replacement),
+  //    so the row we read here IS the current version — recorded below. A
+  //    version pinned in an E1/E2 decision that no longer matches is the
+  //    RESET_ON_CHANGE case the UI surfaces from gate_decisions history.
+
+  // 4) Mode: immediate/admin_only gate nothing at E3 (their E1 verdict already
+  //    fired; §4 "immediate mode = E1 minimal + E3 always" — E3 re-checks the
+  //    fences above and fires). quorum still requires the linked poll passed.
+  if (row.effective.mode === "quorum") {
+    const pollState = row.poll_state === null ? "none" : String(row.poll_state);
+    if (pollState !== "passed") {
+      return {
+        outcome: "blocked",
+        reasonCodes: [reason("INSUFFICIENT_QUORUM"), reason("PENDING_POLL")],
+        policyVersion: String(row.policy_version),
+        mode: "quorum",
+        approvedHash,
+        pollState,
+      };
+    }
+  }
+  return {
+    outcome: "fired",
+    reasonCodes: [],
+    policyVersion: String(row.policy_version),
+    mode: row.effective.mode,
+    approvedHash,
+    pollState: row.poll_state === null ? null : String(row.poll_state),
+  };
+}
+
+export class DispatchGateService {
+  constructor(private readonly pool: Pool) {}
+
+  /**
+   * E3 re-check + decision record for one destination. One round-trip: the
+   * CTE reads draft + live snapshot + latest poll, evaluates, and inserts the
+   * gate_decisions row (and its audit event) in the same transaction.
+   * Returns the outcome the dispatch path must obey.
+   */
+  async check(args: {
+    workspaceId: string;
+    draftId: string;
+    idempotencyKey: string;
+    connectionId: string;
+    platform: string;
+    topicBindingId?: string | null;
+  }): Promise<E3Outcome> {
+    let outcome: E3Outcome;
+    let decisionId: string | null = null;
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [args.workspaceId]);
+      // NOTE: parameter numbering must be dense from $1 — PostgreSQL cannot
+      // type an unused placeholder, and the workspace id rides in set_config.
+      const result = await client.query<E3Row>(
+        `WITH attempt AS (
+           SELECT a.id AS attempt_id, a.draft_id, a.connection_id
+             FROM publishing_attempts a
+            WHERE a.idempotency_key = $1::text
+         ), target AS (
+           SELECT d.state, d.approved_hash, d.approved_revision, d.reviewer_user_id,
+                  s.effective, s.policy_version,
+                  (SELECT p.state FROM polls p WHERE p.draft_id = d.id AND p.state <> 'cancelled'
+                    ORDER BY p.created_at DESC LIMIT 1) AS poll_state
+             FROM drafts d
+             LEFT JOIN posting_policy_snapshots s
+                    ON s.workspace_id = d.workspace_id
+                   AND s.account_id = $2::uuid
+                   AND s.content_type = ''
+                   AND s.topic_binding_id IS NOT DISTINCT FROM NULLIF($3::text, '')::uuid
+            WHERE d.id = (SELECT draft_id FROM attempt)
+         )
+         SELECT state, approved_hash, approved_revision, reviewer_user_id, effective, policy_version, poll_state FROM target`,
+        [args.idempotencyKey, args.connectionId, args.topicBindingId ?? null],
+      );
+      const row = result.rows[0] as E3Row | undefined;
+      outcome = evaluateE3(row);
+      const inserted = await client.query<{ id: string }>(
+        `INSERT INTO gate_decisions
+           (workspace_id, draft_id, destination, gate, policy_version, outcome, inputs, reason_codes, actor)
+         SELECT d.workspace_id, d.id,
+                jsonb_build_object('platform', $1::text, 'accountId', $2::uuid,
+                                   'topicBindingId', $3::uuid, 'idempotencyKey', $4::text),
+                'E3', $5::text, $6::text,
+                jsonb_build_object('approvals', 1, 'approvedHash', d.approved_hash,
+                                   'policyMode', $7::text, 'pollState', $8::text),
+                $9::text[], 'system:gate-e3'
+           FROM drafts d WHERE d.id = $10::uuid
+         RETURNING id`,
+        [
+          args.platform,
+          args.connectionId,
+          args.topicBindingId ?? null,
+          args.idempotencyKey,
+          outcome.policyVersion,
+          outcome.outcome,
+          outcome.mode,
+          outcome.pollState ?? "none",
+          outcome.reasonCodes,
+          args.draftId,
+        ],
+      );
+      decisionId = inserted.rows[0]?.id ?? null;
+      if (decisionId !== null) {
+        await client.query("SELECT audit_append($1::uuid, NULL, 'sp_scheduler', 'policy.gate', 'draft', $2::text, $3::jsonb)", [
+          args.workspaceId,
+          args.draftId,
+          JSON.stringify({
+            gate: "E3",
+            decisionId,
+            idempotencyKey: args.idempotencyKey,
+            destination: { platform: args.platform, accountId: args.connectionId },
+            outcome: outcome.outcome,
+            reasonCodes: outcome.reasonCodes,
+            policyVersion: outcome.policyVersion,
+            mode: outcome.mode,
+            pollState: outcome.pollState ?? "none",
+          }),
+        ]);
+      }
+      await client.query("COMMIT");
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => undefined);
+      throw error;
+    } finally {
+      client.release();
+    }
+    return outcome;
+  }
+}
diff --git a/apps/scheduler/src/activities/publish.activity.gate.test.ts b/apps/scheduler/src/activities/publish.activity.gate.test.ts
new file mode 100644
index 0000000..1d4f9e0
--- /dev/null
+++ b/apps/scheduler/src/activities/publish.activity.gate.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, it, vi } from "vitest";
+import { RateLimitedHttpClient, type PlatformConnector } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { AttemptRef, ClaimedJob, ClaimOutcome, GateOutcome, Lease, StoredPublication } from "@tactical-media-broadcast-hub/publishing-execution";
+import { PublishActivity, type ActivityRepository } from "./publish.activity.js";
+import type { DispatchGateService, E3Outcome } from "./dispatch-gate.js";
+
+/**
+ * E3 integration into the dispatch path (chatgov-design.md §4 step 5): the
+ * gate runs before any provider call, settles a blocked destination as a
+ * known no-send, and is skipped (ungated, dispatch as today) when absent.
+ */
+
+const ref: AttemptRef = { workspaceId: "workspace", scheduleId: "schedule", generation: "1", idempotencyKey: "key" };
+const job: ClaimedJob = {
+  lease: { ...ref, attemptId: "attempt", draftId: "draft", ownerToken: "owner", claimEpoch: "1", leaseUntil: new Date(Date.now() + 90_000) },
+  attemptNo: "1", retryCount: 0, post: { text: "hello", mediaAssetIds: [], visibility: "public", providerMetadata: {} },
+  connection: { id: "connection", provider: "telegram", channelId: "channel", fields: {}, createdAt: new Date() },
+  credential: { id: "credential-uuid", generation: "3" }, priorDispatch: undefined,
+};
+const publication: StoredPublication = { id: "publication", workspaceId: ref.workspaceId, draftId: "draft", connectionId: "connection", idempotencyKey: "key", remoteId: "remote", publishedAt: new Date(), providerMetadata: {} };
+
+function harness(claim: ClaimOutcome = { kind: "claimed", job }, gate?: DispatchGateService | null) {
+  let stored = false;
+  const repository: ActivityRepository = {
+    claim: vi.fn(async () => stored ? { kind: "done" as const, publication } : claim),
+    heartbeat: vi.fn(async () => true),
+    withDispatchGate: vi.fn(async (_lease: Lease, _policy: { allowRedispatch?: boolean; dedupeWindowMs?: number }, send: () => Promise<Response>): Promise<GateOutcome<Response>> => ({ kind: "sent", value: await send() })),
+    recordReceipt: vi.fn(async () => ({ inserted: true, receipt: { id: "receipt", workspaceId: ref.workspaceId, attemptId: "attempt", remoteId: "remote", receivedAt: new Date(), providerMetadata: {} } })),
+    finalize: vi.fn(async () => { stored = true; return { kind: "done" as const, publication }; }),
+    retryLater: vi.fn(async () => ({ kind: "settled" as const })), retryDeduplicated: vi.fn(async () => ({ kind: "settled" as const })),
+    pauseForReauthorization: vi.fn(async () => ({ kind: "settled" as const })), fail: vi.fn(async () => ({ kind: "settled" as const })), markUnknown: vi.fn(async () => ({ kind: "settled" as const })),
+  };
+  const fetchImpl = vi.fn(async () => new Response("{}"));
+  const http = new RateLimitedHttpClient({ fetchImpl });
+  const publish = vi.fn(async () => { await http.request("telegram", "https://api.telegram.org/sendMessage", { method: "POST" }, { retry: false }); return publication; });
+  const connector = { publish } as unknown as PlatformConnector;
+  const activity = new PublishActivity(repository, { get: () => connector }, () => ({ heartbeat: vi.fn() }), gate);
+  return { activity, repository, publish, fetchImpl };
+}
+
+function gateReturning(outcome: E3Outcome): DispatchGateService {
+  return {
+    check: vi.fn(async () => outcome),
+  } as unknown as DispatchGateService;
+}
+
+describe("E3 gate in the dispatch path", () => {
+  it("no gate configured: dispatches exactly as today (existing drafts unchanged)", async () => {
+    const h = harness();
+    await expect(h.activity.publishScheduled(ref)).resolves.toMatchObject({ kind: "done", publicationId: "publication" });
+    expect(h.publish).toHaveBeenCalledTimes(1);
+    expect(h.repository.fail).not.toHaveBeenCalled();
+  });
+
+  it("gate fires: send proceeds and no policy settlement occurs", async () => {
+    const gate = gateReturning({ outcome: "fired", reasonCodes: [], policyVersion: "pv1", mode: "immediate", approvedHash: "abc", pollState: null });
+    const h = harness({ kind: "claimed", job }, gate);
+    await expect(h.activity.publishScheduled(ref)).resolves.toMatchObject({ kind: "done" });
+    expect(h.publish).toHaveBeenCalledTimes(1);
+    expect(h.repository.fail).not.toHaveBeenCalled();
+  });
+
+  it("approval revoked post-approve: blocks with RESET_ON_CHANGE before any send", async () => {
+    const gate = gateReturning({ outcome: "blocked", reasonCodes: ["RESET_ON_CHANGE"], policyVersion: "pv1", mode: "immediate", approvedHash: null, pollState: null });
+    const h = harness({ kind: "claimed", job }, gate);
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "failed", code: "POLICY_RESET_ON_CHANGE" });
+    expect(h.fetchImpl).not.toHaveBeenCalled();
+    expect(h.publish).not.toHaveBeenCalled();
+    expect(h.repository.fail).toHaveBeenCalledWith(job.lease, "POLICY_RESET_ON_CHANGE");
+  });
+
+  it("no snapshot: fails closed with POLICY_OUTSIDE_POLICY and zero HTTP requests", async () => {
+    const gate = gateReturning({ outcome: "blocked", reasonCodes: ["OUTSIDE_POLICY"], policyVersion: "none", mode: "none", approvedHash: null, pollState: null });
+    const h = harness({ kind: "claimed", job }, gate);
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "failed", code: "POLICY_OUTSIDE_POLICY" });
+    expect(h.fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("stale settle (lease lost) yields wait, never a second send", async () => {
+    const gate = gateReturning({ outcome: "blocked", reasonCodes: ["RESET_ON_CHANGE"], policyVersion: "pv1", mode: "immediate", approvedHash: null, pollState: null });
+    const h = harness({ kind: "claimed", job }, gate);
+    vi.mocked(h.repository.fail).mockResolvedValue({ kind: "stale" });
+    const outcome = await h.activity.publishScheduled(ref);
+    expect(outcome).toEqual({ kind: "wait", until: expect.any(String) });
+    expect(h.publish).not.toHaveBeenCalled();
+  });
+
+  it("gate evaluated per destination with the lease's idempotency key", async () => {
+    const gate = gateReturning({ outcome: "fired", reasonCodes: [], policyVersion: "pv1", mode: "immediate", approvedHash: "abc", pollState: null });
+    const h = harness({ kind: "claimed", job }, gate);
+    await h.activity.publishScheduled(ref);
+    expect(gate.check).toHaveBeenCalledWith(expect.objectContaining({
+      workspaceId: job.lease.workspaceId,
+      draftId: job.lease.draftId,
+      idempotencyKey: job.lease.idempotencyKey,
+      connectionId: job.connection.id,
+      platform: job.connection.provider,
+    }));
+  });
+});
diff --git a/apps/scheduler/src/activities/publish.activity.test.ts b/apps/scheduler/src/activities/publish.activity.test.ts
new file mode 100644
index 0000000..aab3b6c
--- /dev/null
+++ b/apps/scheduler/src/activities/publish.activity.test.ts
@@ -0,0 +1,85 @@
+import { ApplicationFailure } from "@temporalio/common";
+import { describe, expect, it, vi } from "vitest";
+import { RateLimitedHttpClient, type PlatformConnector } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { AttemptRef, ClaimedJob, ClaimOutcome, StoredPublication, Lease, GateOutcome } from "@tactical-media-broadcast-hub/publishing-execution";
+import { PublishActivity, type ActivityRepository } from "./publish.activity.js";
+const ref: AttemptRef = { workspaceId: "workspace", scheduleId: "schedule", generation: "1", idempotencyKey: "key" };
+const job: ClaimedJob = {
+  lease: { ...ref, attemptId: "attempt", draftId: "draft", ownerToken: "owner", claimEpoch: "1", leaseUntil: new Date(Date.now() + 90_000) },
+  attemptNo: "1", retryCount: 0, post: { text: "hello", mediaAssetIds: [], visibility: "public", providerMetadata: {} },
+  connection: { id: "connection", provider: "telegram", channelId: "channel", fields: {}, createdAt: new Date() },
+  credential: { id: "credential-uuid", generation: "3" }, priorDispatch: undefined,
+};
+const publication: StoredPublication = { id: "publication", workspaceId: ref.workspaceId, draftId: "draft", connectionId: "connection", idempotencyKey: "key", remoteId: "remote", publishedAt: new Date(), providerMetadata: {} };
+function harness(claim: ClaimOutcome = { kind: "claimed", job }) {
+  let stored = false;
+  const repository: ActivityRepository = {
+    claim: vi.fn(async () => stored ? { kind: "done" as const, publication } : claim),
+    heartbeat: vi.fn(async () => true),
+    withDispatchGate: vi.fn(async (_lease: Lease, _policy: { allowRedispatch?: boolean; dedupeWindowMs?: number }, send: () => Promise<Response>): Promise<GateOutcome<Response>> => ({ kind: "sent", value: await send() })),
+    recordReceipt: vi.fn(async () => ({ inserted: true, receipt: { id: "receipt", workspaceId: ref.workspaceId, attemptId: "attempt", remoteId: "remote", receivedAt: new Date(), providerMetadata: {} } })),
+    finalize: vi.fn(async () => { stored = true; return { kind: "done" as const, publication }; }),
+    retryLater: vi.fn(async () => ({ kind: "settled" as const })), retryDeduplicated: vi.fn(async () => ({ kind: "settled" as const })),
+    pauseForReauthorization: vi.fn(async () => ({ kind: "settled" as const })), fail: vi.fn(async () => ({ kind: "settled" as const })), markUnknown: vi.fn(async () => ({ kind: "settled" as const })),
+  };
+  const fetchImpl = vi.fn(async () => new Response("{}"));
+  const http = new RateLimitedHttpClient({ fetchImpl });
+  const publish = vi.fn(async () => { await http.request("telegram", "https://api.telegram.org/sendMessage", { method: "POST" }, { retry: false }); return publication; });
+  // Only publish is used by this test composition; production registers complete connectors.
+  const connector = { publish } as unknown as PlatformConnector;
+  const activity = new PublishActivity(repository, { get: () => connector }, () => ({ heartbeat: vi.fn() }));
+  return { activity, repository, publish, fetchImpl };
+}
+describe("publishing execution wiring", () => {
+  it("propagates a non-retryable claim refusal without publishing or failing a job", async () => {
+    const h = harness();
+    const claimError = ApplicationFailure.nonRetryable("draft is not approved");
+    vi.mocked(h.repository.claim).mockRejectedValue(claimError);
+    await expect(h.activity.publishScheduled(ref)).rejects.toBe(claimError);
+    expect(claimError.nonRetryable).toBe(true);
+    expect(h.publish).not.toHaveBeenCalled(); expect(h.repository.fail).not.toHaveBeenCalled();
+  });
+  it("returns stored publication without publishing twice", async () => {
+    const h = harness();
+    const first = await h.activity.publishScheduled(ref); const second = await h.activity.publishScheduled(ref);
+    expect(second).toEqual(first); expect(h.publish).toHaveBeenCalledTimes(1);
+    expect(h.repository.recordReceipt).toHaveBeenCalledTimes(1); expect(h.repository.finalize).toHaveBeenCalledTimes(1);
+    expect(h.repository.withDispatchGate).toHaveBeenCalledTimes(1); expect(h.fetchImpl).toHaveBeenCalledTimes(1);
+  });
+  it("finalizes durable evidence with zero provider calls", async () => {
+    const h = harness({ kind: "finalize", job, receipt: { id: "receipt", workspaceId: ref.workspaceId, attemptId: "attempt", remoteId: "remote", providerMetadata: {}, receivedAt: new Date() } });
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "done", publicationId: "publication" });
+    expect(h.publish).not.toHaveBeenCalled(); expect(h.repository.recordReceipt).not.toHaveBeenCalled();
+  });
+  it("never routes a receipt failure into a fresh send or safe retry", async () => {
+    const h = harness(); const error = new Error("database unavailable"); vi.mocked(h.repository.recordReceipt).mockRejectedValue(error);
+    await expect(h.activity.publishScheduled(ref)).rejects.toBe(error);
+    expect(h.publish).toHaveBeenCalledTimes(1); expect(h.repository.retryLater).not.toHaveBeenCalled(); expect(h.repository.fail).not.toHaveBeenCalled(); expect(h.repository.finalize).not.toHaveBeenCalled();
+  });
+  it("refuses a fenced send with zero HTTP requests", async () => {
+    const h = harness(); vi.mocked(h.repository.withDispatchGate).mockResolvedValue({ kind: "paused", code: "AUTHZ_REVOKED" });
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "paused", code: "AUTHZ_REVOKED" });
+    expect(h.fetchImpl).not.toHaveBeenCalled(); expect(h.repository.retryLater).not.toHaveBeenCalled();
+  });
+  it("does not resend ambiguous Telegram work", async () => {
+    const h = harness({ kind: "claimed", job: { ...job, priorDispatch: { startedAt: new Date(), count: 1 } } });
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" });
+    expect(h.fetchImpl).not.toHaveBeenCalled(); expect(h.repository.markUnknown).toHaveBeenCalledTimes(1);
+  });
+  it("pauses an authentication rejection", async () => {
+    const h = harness(); const { AuthError } = await import("@tactical-media-broadcast-hub/connector-sdk"); h.publish.mockRejectedValue(new AuthError("rejected", "telegram", false));
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "paused", code: "CREDENTIAL_REJECTED" });
+    expect(h.repository.pauseForReauthorization).toHaveBeenCalledTimes(1); expect(h.repository.retryLater).not.toHaveBeenCalled();
+  });
+  it("retains unexpected provider scheduling evidence as unknown without a fabricated Publication", async () => {
+    const h = harness();
+    const http = new RateLimitedHttpClient({ fetchImpl: h.fetchImpl });
+    h.publish.mockImplementation(async () => {
+      await http.request("telegram", "https://api.telegram.org/sendMessage", { method: "POST" }, { retry: false });
+      return { ...publication, remoteId: "scheduled:42", providerMetadata: { outcome: "provider_scheduled", scheduledAt: "2030-01-01T00:00:00.000Z" } };
+    });
+    await expect(h.activity.publishScheduled(ref)).resolves.toEqual({ kind: "unknown", code: "UNEXPECTED_PROVIDER_SCHEDULED" });
+    expect(h.repository.markUnknown).toHaveBeenCalledWith(job.lease, { remoteId: "scheduled:42", scheduledAt: "2030-01-01T00:00:00.000Z" });
+    expect(h.repository.recordReceipt).not.toHaveBeenCalled(); expect(h.repository.finalize).not.toHaveBeenCalled(); expect(h.repository.retryLater).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/scheduler/src/activities/publish.activity.ts b/apps/scheduler/src/activities/publish.activity.ts
new file mode 100644
index 0000000..3a35e83
--- /dev/null
+++ b/apps/scheduler/src/activities/publish.activity.ts
@@ -0,0 +1,164 @@
+import { Context } from "@temporalio/activity";
+import type { ConnectorConnection, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import type { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import { DispatchFenceError, publishWithPolicy, publishingDispatchPolicy, runWithPublishingContext } from "@tactical-media-broadcast-hub/connector-runtime";
+import { DispatchGateService, type E3Outcome } from "./dispatch-gate.js";
+import type { AttemptRef, ClaimedJob, GateOutcome, PublishingExecutionRepository, SettleOutcome, Lease } from "@tactical-media-broadcast-hub/publishing-execution";
+
+export type ActivityOutcome =
+  | { kind: "done"; publicationId: string }
+  | { kind: "wait"; until: string }
+  | { kind: "paused" | "failed" | "superseded" | "unknown"; code: string };
+export type ActivityRepository = Pick<PublishingExecutionRepository, "claim" | "heartbeat" | "recordReceipt" | "finalize" | "retryLater" | "retryDeduplicated" | "pauseForReauthorization" | "markUnknown" | "fail"> & { withDispatchGate(lease: Lease, policy: { allowRedispatch?: boolean; dedupeWindowMs?: number }, send: () => Promise<Response>): Promise<GateOutcome<Response>> };
+export interface ActivityLifecycle { heartbeat(): void; signal?: AbortSignal }
+function temporalLifecycle(): ActivityLifecycle {
+  const context = Context.current();
+  return { heartbeat: () => context.heartbeat(), signal: context.cancellationSignal };
+}
+function connectionOf(job: ClaimedJob): ConnectorConnection {
+  const fields: Record<string, string> = {};
+  for (const [key, value] of Object.entries(job.connection.fields)) if (typeof value === "string") fields[key] = value;
+  return { ...job.connection, fields, workspaceId: job.lease.workspaceId, credentialId: { kind: "credential-ref", id: job.connection.id } };
+}
+function postOf(job: ClaimedJob): NormalizedPost {
+  const visibility = job.post.visibility;
+  if (!["public", "unlisted", "private", "followers", "provider_default"].includes(visibility)) throw new Error("INVALID_POST_VISIBILITY");
+  return { ...job.post, visibility: visibility as NormalizedPost["visibility"] };
+}
+/** Persist only documented remote evidence; unknown fields never enter DB/history. */
+export function safeMetadata(metadata: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const key of ["messageId", "chatId", "channelId", "outcome", "scheduledAt"]) {
+    const value = metadata[key];
+    if ((typeof value === "string" && value.length <= 512) || (typeof value === "number" && Number.isSafeInteger(value))) result[key] = value;
+  }
+  return result;
+}
+class GateRefusal extends Error {
+  constructor(readonly outcome: Exclude<GateOutcome<Response>, { kind: "sent" }>) { super("DISPATCH_FENCE_REFUSED"); }
+}
+export class PublishActivity {
+  /**
+   * E3 chatgov pre-dispatch re-check (chatgov-design.md §4 step 5). Optional:
+   * `undefined` preserves today's ungated dispatch (used by suites whose DB
+   * predates the chatgov spine); `null` explicitly disables it.
+   */
+  constructor(
+    private readonly repository: ActivityRepository,
+    private readonly registry: Pick<ConnectorRegistry, "get">,
+    private readonly lifecycle: () => ActivityLifecycle = temporalLifecycle,
+    private readonly dispatchGate?: DispatchGateService | null,
+  ) {}
+
+  /** E3 re-check before any send. Authorization fences are NOT duplicated:
+   * the repository's claim + withDispatchGate already re-read every live
+   * authz input; this gate adds the governance side (approval + policy
+   * currency) and blocks closed when it cannot prove a destination is
+   * inside policy. Absent gate or absent chatgov tables => dispatch as today. */
+  private async e3Check(lease: Lease, job: ClaimedJob): Promise<E3Outcome | undefined> {
+    const gate = this.dispatchGate ?? null;
+    if (gate === null) return undefined;
+    try {
+      return await gate.check({
+        workspaceId: lease.workspaceId,
+        draftId: lease.draftId,
+        idempotencyKey: lease.idempotencyKey,
+        connectionId: job.connection.id,
+        platform: job.connection.provider,
+      });
+    } catch (error) {
+      if (error instanceof Error && error.message.includes("does not exist")) return undefined; // chatgov tables absent: ungated
+      throw error;
+    }
+  }
+
+  async publishScheduled(ref: AttemptRef): Promise<ActivityOutcome> {
+    const claim = await this.repository.claim(ref);
+    if (claim.kind === "done") return { kind: "done", publicationId: claim.publication.id };
+    if (claim.kind === "wait") return { kind: "wait", until: claim.until.toISOString() };
+    if (claim.kind !== "claimed" && claim.kind !== "finalize") return claim;
+    const job = claim.job;
+    const lease = job.lease;
+    const finalize = async (): Promise<ActivityOutcome> => {
+      const result = await this.repository.finalize(lease);
+      return result.kind === "done" ? { kind: "done", publicationId: result.publication.id } : { kind: "wait", until: new Date(Date.now() + 1000).toISOString() };
+    };
+    // Evidence/finalization errors propagate to infrastructure retries. They
+    // never pass through provider failure classification or trigger a send.
+    if (claim.kind === "finalize") return finalize();
+    const lifecycle = this.lifecycle();
+    const abort = new AbortController();
+    const signal = AbortSignal.any([abort.signal, ...(lifecycle.signal ? [lifecycle.signal] : [])]);
+    const heartbeatTimer = setInterval(() => { try { lifecycle.heartbeat(); } catch { abort.abort(); } }, 5000);
+    let renewal: Promise<void> | undefined;
+    const timer = setInterval(() => {
+      if (renewal) return;
+      renewal = this.repository.heartbeat(lease).then((owned) => { if (!owned) abort.abort(); else lifecycle.heartbeat(); }).catch(() => abort.abort()).finally(() => { renewal = undefined; });
+    }, 10_000);
+    const settle = (result: SettleOutcome, outcome: ActivityOutcome): ActivityOutcome => result.kind === "stale" ? { kind: "wait", until: new Date(Date.now() + 1000).toISOString() } : outcome;
+    try {
+      lifecycle.heartbeat();
+      const connection = connectionOf(job);
+      // E3: chatgov pre-dispatch re-check, per destination, before any send.
+      const gate = await this.e3Check(lease, job);
+      if (gate !== undefined && gate.outcome === "blocked") {
+        // Known no-send: settle the attempt failed (governance refusal) so the
+        // blocked destination surfaces in the failed schedule + gate_decisions.
+        const settled = await this.repository.fail(lease, `POLICY_${gate.reasonCodes[0] ?? "OUTSIDE_POLICY"}`);
+        return settled.kind === "stale"
+          ? { kind: "wait", until: new Date(Date.now() + 1000).toISOString() }
+          : { kind: "failed", code: `POLICY_${gate.reasonCodes[0] ?? "OUTSIDE_POLICY"}` };
+      }
+      const connector = this.registry.get(connection.provider);
+      const { policy, origin, dedupeVerified } = publishingDispatchPolicy(connection);
+      let outcome;
+      try {
+        outcome = await runWithPublishingContext({ workspaceId: lease.workspaceId, connectionId: connection.id, credentialId: job.credential.id, credentialGeneration: job.credential.generation, signal }, () => publishWithPolicy(connector, connection, postOf(job), {
+          idempotencyKey: lease.idempotencyKey, policy, dedupeVerified,
+          firstDispatchAt: job.firstDispatchStartedAt,
+          unsettledPriorDispatch: job.priorDispatch !== undefined,
+          aroundMutation: async (event, send) => {
+            signal.throwIfAborted();
+            const gate = await this.repository.withDispatchGate(lease, { allowRedispatch: dedupeVerified && event.origin === origin, dedupeWindowMs: dedupeVerified && event.origin === origin ? policy.dedupeWindowMs : 0 }, send);
+            if (gate.kind === "sent") return gate.value;
+            throw new DispatchFenceError(job.priorDispatch !== undefined, new GateRefusal(gate));
+          },
+        }));
+      } catch (error) {
+        if (error instanceof DispatchFenceError && error.cause instanceof GateRefusal) {
+          const gate = error.cause.outcome;
+          if (gate.kind === "finalize") return finalize();
+          if (gate.kind === "lost") return { kind: "wait", until: new Date(Date.now() + 1000).toISOString() };
+          return gate;
+        }
+        // Infrastructure faults are retried by Temporal and re-claim the same journal.
+        throw error;
+      }
+      if (outcome.kind === "published") {
+        const receipt = outcome.receipt;
+        await this.repository.recordReceipt(lease, { remoteId: receipt.remoteId, remoteUrl: receipt.remoteUrl, publishedAt: receipt.publishedAt, providerMetadata: safeMetadata(receipt.providerMetadata) });
+        return finalize();
+      }
+      if (outcome.kind === "provider_scheduled") {
+        // This is remote evidence, not a published receipt. Keep it in the
+        // unknown journal via a safe audit; never manufacture a Publication.
+        return settle(await this.repository.markUnknown(lease, { remoteId: outcome.scheduledRemoteId, scheduledAt: outcome.scheduledAt.toISOString() }), { kind: "unknown", code: "UNEXPECTED_PROVIDER_SCHEDULED" });
+      }
+      if (outcome.kind === "unknown") return settle(await this.repository.markUnknown(lease), { kind: "unknown", code: outcome.code });
+      if (outcome.kind === "rejected_permanent") {
+        // An earlier ambiguous send cannot be disproved by this rejection.
+        if (job.priorDispatch) return settle(await this.repository.markUnknown(lease), { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" });
+        return outcome.needsReauthorization
+          ? settle(await this.repository.pauseForReauthorization(lease, outcome.code), { kind: "paused", code: outcome.code })
+          : settle(await this.repository.fail(lease, outcome.code), { kind: "failed", code: outcome.code });
+      }
+      const delay = Math.max(outcome.retryAfterMs ?? 0, Math.min(300_000, 1000 * 2 ** job.retryCount));
+      const until = new Date(Date.now() + delay);
+      const result = outcome.resend === "deduplicated"
+        ? await this.repository.retryDeduplicated(lease, outcome.code, until)
+        : await this.repository.retryLater(lease, outcome.code, until);
+      // Settlement may exhaust the budget: re-claim reads the authoritative terminal state.
+      return settle(result, { kind: "wait", until: (result.kind === "settled" ? result.until ?? until : until).toISOString() });
+    } finally { clearInterval(timer); clearInterval(heartbeatTimer); await renewal; }
+  }
+}
diff --git a/apps/scheduler/src/director/adapters.ts b/apps/scheduler/src/director/adapters.ts
new file mode 100644
index 0000000..0290e15
--- /dev/null
+++ b/apps/scheduler/src/director/adapters.ts
@@ -0,0 +1,75 @@
+/**
+ * Port adapters for the scheduler side of the director wiring (WP10).
+ *
+ * The engine's ports (director.activity.ts) speak engine types; the API
+ * answers in transport shapes (ports.ts). These adapters bridge them:
+ * sources are converted with the same semantics engine.sourceInput uses, and
+ * the desired-state calls are forwarded to the API's internal endpoints.
+ */
+import type { DirectorSourceInput } from "./engine.js";
+import type { ChannelRef, ChannelSnapshot, DesiredFence, DesiredStatePort, DirectorStatePort, ProgramSwitchCommand } from "./director.activity.js";
+import type { DirectorApi, DirectorApplyRequest, DirectorChannelSource, DirectorStateRead } from "./ports.js";
+
+/** Engine source input from the transport shape: the shapes agree field-for-field. */
+export function engineSource(source: DirectorChannelSource): DirectorSourceInput {
+  return { ...source };
+}
+
+/** Transport snapshot -> engine snapshot. */
+export function engineSnapshot(read: DirectorStateRead & { kind: "current" }): ChannelSnapshot {
+  return {
+    kind: "current",
+    desiredVersion: read.desiredVersion,
+    authzEpoch: read.authzEpoch,
+    sources: read.sources.map(engineSource),
+    rules: read.rules,
+    policy: read.policy,
+    fallbackSceneId: read.fallbackSceneId,
+    override: read.override,
+    principalPermissions: read.principalPermissions,
+  };
+}
+
+/** DirectorStatePort backed by the API's internal state endpoint. */
+export class HttpDirectorStatePort implements DirectorStatePort {
+  constructor(private readonly api: DirectorApi) {}
+
+  async read(ref: ChannelRef): Promise<ChannelSnapshot> {
+    const read = await this.api.channelState(ref);
+    return read.kind === "superseded" ? { kind: "superseded", code: "SUPERSEDED" } : engineSnapshot(read);
+  }
+}
+
+/** DesiredStatePort backed by the API's apply/audit endpoints. */
+export class HttpDesiredStatePort implements DesiredStatePort {
+  constructor(private readonly api: DirectorApi) {}
+
+  async fence(ref: ChannelRef): Promise<DesiredFence | undefined> {
+    return this.api.fence(ref);
+  }
+
+  async findCommand(_ref: ChannelRef, _commandId: string): Promise<{ desiredVersion: number } | undefined> {
+    // Idempotency is the API's job: the apply endpoint records the commandId in
+    // the production_command audit chain and replays the stored receipt. A
+    // pre-check here would double the round trips for no extra safety.
+    return undefined;
+  }
+
+  async writeProgram(command: ProgramSwitchCommand): Promise<{ kind: "applied"; desiredVersion: number } | { kind: "conflict" }> {
+    const body: DirectorApplyRequest = {
+      commandId: command.commandId,
+      expectedDesiredVersion: command.expectedDesiredVersion,
+      authzEpoch: command.authzEpoch,
+      program: command.program,
+      layout: command.layout,
+      reasons: command.reasons,
+      ...(command.releaseOverride === undefined ? {} : { releaseOverride: command.releaseOverride }),
+    };
+    const result = await this.api.applyProgramSwitch(command.ref, body);
+    return result.kind === "conflict" ? { kind: "conflict" } : { kind: "applied", desiredVersion: result.desiredVersion };
+  }
+
+  async audit(ref: ChannelRef, event: { commandId: string; outcome: "SUPERSEDED" | "AUTHZ_REVOKED"; reason: string }): Promise<void> {
+    await this.api.audit(ref, event);
+  }
+}
diff --git a/apps/scheduler/src/director/config.ts b/apps/scheduler/src/director/config.ts
new file mode 100644
index 0000000..a178ecf
--- /dev/null
+++ b/apps/scheduler/src/director/config.ts
@@ -0,0 +1,144 @@
+import type { AutoDirectorRule, DirectorAction, DirectorCondition, SceneLayout, SwitchPolicy } from "@tactical-media-broadcast-hub/core";
+
+/**
+ * Director channel configuration (WP10 wiring slice).
+ *
+ * `DIRECTOR_CHANNELS` is a server-controlled JSON array — the same pattern as
+ * MEDIA_POLLER_SOURCES / MEDIA_CONTROL_ASSIGNMENTS. Rule CRUD is a later
+ * work package; this slice makes the configured set live, so the array is the
+ * authority for which channels get an evaluator, which rules it evaluates and
+ * which generation fences its writes.
+ *
+ * The API side parses the same document (apps/api/src/director/config.ts) to
+ * answer snapshot/fence reads, so the two parsers must stay shape-compatible:
+ * both are tested against the same fixtures.
+ */
+export interface DirectorChannelConfig {
+  readonly workspaceId: string;
+  readonly channelId: string;
+  /** Assignment generation; a newer value supersedes running evaluators. */
+  readonly generation: string;
+  readonly rules: readonly AutoDirectorRule[];
+  readonly policy: SwitchPolicy | undefined;
+  readonly fallbackSceneId: string | null;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+const GENERATION = /^[\x21-\x7e]{1,64}$/;
+const POLICY_NAMES: readonly SwitchPolicy["name"][] = [
+  "highest_priority", "oldest_live", "newest_live", "round_robin", "operator_required",
+  "picture_in_picture", "two_up", "split_screen", "grid",
+];
+const LAYOUTS: readonly SceneLayout[] = ["single", "pip", "two_up", "split_horizontal", "split_vertical", "grid", "custom"];
+const CONDITION_FIELDS: readonly DirectorCondition["field"][] = ["live_source_count", "max_priority", "source_state"];
+const CONDITION_OPS: readonly DirectorCondition["op"][] = [">=", "<=", "==", ">"];
+const SELECTIONS: readonly DirectorAction["selection"][] = ["top_priority", "all_live", "oldest_live", "explicit"];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function uuid(value: unknown, field: string): string {
+  if (typeof value !== "string" || !UUID.test(value)) throw new Error(`${field} must be a UUID`);
+  return value;
+}
+
+function nonNegativeInt(value: unknown, field: string): number {
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) throw new Error(`${field} must be a non-negative integer`);
+  return value;
+}
+
+function parseCondition(value: unknown, field: string): DirectorCondition {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const conditionField = value.field;
+  const op = value.op;
+  if (typeof conditionField !== "string" || !CONDITION_FIELDS.includes(conditionField as DirectorCondition["field"])) {
+    throw new Error(`${field}.field must be one of ${CONDITION_FIELDS.join(", ")}`);
+  }
+  if (typeof op !== "string" || !CONDITION_OPS.includes(op as DirectorCondition["op"])) {
+    throw new Error(`${field}.op must be one of ${CONDITION_OPS.join(", ")}`);
+  }
+  const ruleValue = value.value;
+  if (typeof ruleValue !== "number" && typeof ruleValue !== "string") throw new Error(`${field}.value must be a number or string`);
+  return { field: conditionField as DirectorCondition["field"], op: op as DirectorCondition["op"], value: ruleValue };
+}
+
+function parseAction(value: unknown, field: string): DirectorAction {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const selection = value.selection;
+  if (typeof selection !== "string" || !SELECTIONS.includes(selection as DirectorAction["selection"])) {
+    throw new Error(`${field}.selection must be one of ${SELECTIONS.join(", ")}`);
+  }
+  const layout = value.layout;
+  if (typeof layout !== "string" || !LAYOUTS.includes(layout as SceneLayout)) {
+    throw new Error(`${field}.layout must be one of ${LAYOUTS.join(", ")}`);
+  }
+  let sourceIds: string[] | undefined;
+  if (value.sourceIds !== undefined) {
+    if (!Array.isArray(value.sourceIds)) throw new Error(`${field}.sourceIds must be an array`);
+    sourceIds = value.sourceIds.map((id, i) => uuid(id, `${field}.sourceIds[${i}]`));
+    if (new Set(sourceIds).size !== sourceIds.length) throw new Error(`${field}.sourceIds must be unique`);
+  }
+  if (selection === "explicit" && (sourceIds === undefined || sourceIds.length === 0)) {
+    throw new Error(`${field}.selection explicit requires sourceIds`);
+  }
+  return { layout: layout as SceneLayout, selection: selection as DirectorAction["selection"], ...(sourceIds === undefined ? {} : { sourceIds }) };
+}
+
+function parseRule(value: unknown, channelId: string, index: number): AutoDirectorRule {
+  const field = `DIRECTOR_CHANNELS[${index}].rules[${index}]`;
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  if (value.virtualChannelId !== undefined && value.virtualChannelId !== channelId) {
+    throw new Error(`${field}.virtualChannelId must match the channel it is configured on`);
+  }
+  return {
+    id: uuid(value.id, `${field}.id`),
+    virtualChannelId: channelId,
+    priority: nonNegativeInt(value.priority ?? 0, `${field}.priority`),
+    condition: parseCondition(value.condition, `${field}.condition`),
+    action: parseAction(value.action, `${field}.action`),
+  };
+}
+
+function parsePolicy(value: unknown, field: string): SwitchPolicy {
+  if (!isRecord(value)) throw new Error(`${field} must be an object`);
+  const name = value.name;
+  if (typeof name !== "string" || !POLICY_NAMES.includes(name as SwitchPolicy["name"])) {
+    throw new Error(`${field}.name must be one of ${POLICY_NAMES.join(", ")}`);
+  }
+  return {
+    name: name as SwitchPolicy["name"],
+    liveConfirmations: nonNegativeInt(value.liveConfirmations ?? 2, `${field}.liveConfirmations`),
+    offlineConfirmations: nonNegativeInt(value.offlineConfirmations ?? 3, `${field}.offlineConfirmations`),
+    noMediaSeconds: nonNegativeInt(value.noMediaSeconds ?? 10, `${field}.noMediaSeconds`),
+    minHoldMs: nonNegativeInt(value.minHoldMs ?? 2_000, `${field}.minHoldMs`),
+    switchCooldownMs: nonNegativeInt(value.switchCooldownMs ?? 10_000, `${field}.switchCooldownMs`),
+  };
+}
+
+/** Parse and validate DIRECTOR_CHANNELS; throws with a field path on the first problem. */
+export function parseDirectorChannels(raw: string | undefined): DirectorChannelConfig[] {
+  if (raw === undefined || raw.trim() === "") return [];
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed)) throw new Error("DIRECTOR_CHANNELS must be a JSON array");
+  return parsed.map((entry, index) => {
+    const field = `DIRECTOR_CHANNELS[${index}]`;
+    if (!isRecord(entry)) throw new Error(`${field} must be an object`);
+    const channelId = uuid(entry.channelId, `${field}.channelId`);
+    const generation = entry.generation;
+    if (typeof generation !== "string" || !GENERATION.test(generation)) {
+      throw new Error(`${field}.generation must be 1-64 printable characters`);
+    }
+    const rules = Array.isArray(entry.rules) ? entry.rules.map((rule, i) => parseRule(rule, channelId, i)) : [];
+    const fallbackSceneId = entry.fallbackSceneId === undefined || entry.fallbackSceneId === null
+      ? null : uuid(entry.fallbackSceneId, `${field}.fallbackSceneId`);
+    return {
+      workspaceId: uuid(entry.workspaceId, `${field}.workspaceId`),
+      channelId,
+      generation,
+      rules,
+      policy: entry.policy === undefined ? undefined : parsePolicy(entry.policy, `${field}.policy`),
+      fallbackSceneId,
+    };
+  });
+}
diff --git a/apps/scheduler/src/director/director.activity.test.ts b/apps/scheduler/src/director/director.activity.test.ts
new file mode 100644
index 0000000..a28c9ed
--- /dev/null
+++ b/apps/scheduler/src/director/director.activity.test.ts
@@ -0,0 +1,75 @@
+import { describe, expect, it, vi } from "vitest";
+import { Client, WorkflowExecutionAlreadyStartedError } from "@temporalio/client";
+import { DirectorActivity, unwiredDesiredPort, type DesiredFence, type DesiredStatePort, type ProgramSwitchCommand } from "./director.activity.js";
+import { ensureDirector, evaluatorWorkflowId } from "./starter.js";
+
+const ref = { workspaceId: "ws", channelId: "vc", generation: "g2" };
+const command: ProgramSwitchCommand = { ref, commandId: "vc:g2:1", expectedDesiredVersion: 7, authzEpoch: 3, program: { kind: "sources", sourceIds: ["a"] }, layout: "single", reasons: [] };
+function port(fence: DesiredFence | undefined, over: Partial<DesiredStatePort> = {}): DesiredStatePort & { writeProgram: ReturnType<typeof vi.fn>; audit: ReturnType<typeof vi.fn> } {
+  return { fence: async () => fence, findCommand: async () => undefined, writeProgram: vi.fn(async () => ({ kind: "applied" as const, desiredVersion: 8 })), audit: vi.fn(async () => undefined), ...over } as never;
+}
+const current: DesiredFence = { generation: "g2", desiredVersion: 7, authzEpoch: 3, directorAuthorized: true };
+const activity = (desired: DesiredStatePort): DirectorActivity => new DirectorActivity(undefined, desired);
+
+describe("applyProgramSwitch generation fences", () => {
+  it("applies under a current fence", async () => {
+    const desired = port(current);
+    await expect(activity(desired).applyProgramSwitch(command)).resolves.toEqual({ kind: "applied", desiredVersion: 8 });
+    expect(desired.writeProgram).toHaveBeenCalledWith(command);
+  });
+  it("a retried command with a recorded commandId is a no-op duplicate", async () => {
+    const desired = port(current, { findCommand: async () => ({ desiredVersion: 8 }) });
+    await expect(activity(desired).applyProgramSwitch(command)).resolves.toEqual({ kind: "duplicate", desiredVersion: 8 });
+    expect(desired.writeProgram).not.toHaveBeenCalled();
+  });
+  it("a superseded channel generation is audited SUPERSEDED and never writes", async () => {
+    for (const fence of [{ ...current, generation: "g3" }, undefined]) {
+      const desired = port(fence);
+      await expect(activity(desired).applyProgramSwitch(command)).resolves.toEqual({ kind: "generation_superseded", code: "SUPERSEDED" });
+      expect(desired.writeProgram).not.toHaveBeenCalled();
+      expect(desired.audit).toHaveBeenCalledWith(ref, expect.objectContaining({ outcome: "SUPERSEDED" }));
+    }
+  });
+  it("a stale authzEpoch whose principal lost director.* is audited AUTHZ_REVOKED", async () => {
+    const desired = port({ ...current, authzEpoch: 4, directorAuthorized: false });
+    await expect(activity(desired).applyProgramSwitch(command)).resolves.toEqual({ kind: "authz_revoked", code: "AUTHZ_REVOKED" });
+    expect(desired.writeProgram).not.toHaveBeenCalled();
+    expect(desired.audit).toHaveBeenCalledWith(ref, expect.objectContaining({ outcome: "AUTHZ_REVOKED" }));
+  });
+  it("an unrelated epoch bump with the principal still authorized proceeds", async () => {
+    await expect(activity(port({ ...current, authzEpoch: 4 })).applyProgramSwitch(command)).resolves.toMatchObject({ kind: "applied" });
+  });
+  it("a superseded desiredVersion or lost CAS is SUPERSEDED", async () => {
+    const stale = port({ ...current, desiredVersion: 9 });
+    await expect(activity(stale).applyProgramSwitch(command)).resolves.toEqual({ kind: "superseded", code: "SUPERSEDED" });
+    expect(stale.writeProgram).not.toHaveBeenCalled();
+    const raced = port(current, { writeProgram: vi.fn(async () => ({ kind: "conflict" as const })) });
+    await expect(activity(raced).applyProgramSwitch(command)).resolves.toEqual({ kind: "superseded", code: "SUPERSEDED" });
+  });
+  it("is inert until the go-live slice wires the port", async () => {
+    await expect(activity(unwiredDesiredPort).applyProgramSwitch(command)).rejects.toMatchObject({ type: "DIRECTOR_NOT_WIRED", nonRetryable: true });
+  });
+});
+
+describe("ensureDirector", () => {
+  const already = (): WorkflowExecutionAlreadyStartedError => new WorkflowExecutionAlreadyStartedError("existing", evaluatorWorkflowId(ref), "autoDirectorEvaluator");
+  it("starts one evaluator per channel", async () => {
+    const start = vi.fn(async () => ({}));
+    await expect(ensureDirector({ workflow: { start } } as unknown as Client, ref, "q")).resolves.toBe("started");
+    expect(start).toHaveBeenCalledWith("autoDirectorEvaluator", expect.objectContaining({ workflowId: "auto-director-ws-vc", args: [{ ref }] }));
+  });
+  it("nudges a running evaluator instead of starting a duplicate", async () => {
+    const start = vi.fn().mockRejectedValue(already());
+    const signal = vi.fn(async () => undefined);
+    const client = { workflow: { start, getHandle: () => ({ describe: async () => ({ status: { name: "RUNNING" } }), signal }) } } as unknown as Client;
+    await expect(ensureDirector(client, ref, "q")).resolves.toBe("running");
+    expect(start).toHaveBeenCalledTimes(1);
+    expect(signal).toHaveBeenCalledWith("sourceChanged", { sourceId: "*", version: 0 });
+  });
+  it("restarts once when the evaluator closed between start and describe", async () => {
+    const start = vi.fn().mockRejectedValueOnce(already()).mockResolvedValue({});
+    const client = { workflow: { start, getHandle: () => ({ describe: async () => ({ status: { name: "COMPLETED" } }), signal: vi.fn() }) } } as unknown as Client;
+    await expect(ensureDirector(client, ref, "q")).resolves.toBe("restarted");
+    expect(start).toHaveBeenCalledTimes(2);
+  });
+});
diff --git a/apps/scheduler/src/director/director.activity.ts b/apps/scheduler/src/director/director.activity.ts
new file mode 100644
index 0000000..9bf0cae
--- /dev/null
+++ b/apps/scheduler/src/director/director.activity.ts
@@ -0,0 +1,103 @@
+import { ApplicationFailure } from "@temporalio/common";
+import type { AutoDirectorRule, DirectorOverrideReleaseReason, SceneLayout, SwitchPolicy } from "@tactical-media-broadcast-hub/core";
+import type { DirectorOverride, DirectorProgram, DirectorSourceInput } from "./engine.js";
+
+/** Workflow identity. `generation` is the channel assignment generation; a newer one supersedes this evaluator. */
+export interface ChannelRef { workspaceId: string; channelId: string; generation: string }
+
+/** Fresh monitor + desired-state snapshot; signals carry only hints, every evaluation re-reads this. */
+export type ChannelSnapshot =
+  | {
+    kind: "current";
+    desiredVersion: number;
+    authzEpoch: number;
+    sources: DirectorSourceInput[];
+    rules: AutoDirectorRule[];
+    policy: SwitchPolicy;
+    fallbackSceneId: string | null;
+    override: DirectorOverride | null;
+    principalPermissions: Record<string, string[]>;
+  }
+  | { kind: "superseded"; code: "SUPERSEDED" };
+
+export interface ProgramSwitchCommand {
+  ref: ChannelRef;
+  /** Deterministic per workflow decision: retries and replays reuse it (idempotency key). */
+  commandId: string;
+  expectedDesiredVersion: number;
+  authzEpoch: number;
+  program: DirectorProgram;
+  layout: SceneLayout;
+  reasons: string[];
+  releaseOverride?: DirectorOverrideReleaseReason;
+}
+
+export type SwitchOutcome =
+  | { kind: "applied" | "duplicate"; desiredVersion: number }
+  | { kind: "superseded"; code: "SUPERSEDED" }
+  | { kind: "generation_superseded"; code: "SUPERSEDED" }
+  | { kind: "authz_revoked"; code: "AUTHZ_REVOKED" };
+
+export interface DesiredFence {
+  generation: string;
+  desiredVersion: number;
+  authzEpoch: number;
+  /** The evaluator's recorded principal still holds `director.*` under the current epoch. */
+  directorAuthorized: boolean;
+}
+
+/**
+ * Ports owned by the media-control go-live slice. `writeProgram` must be one
+ * transaction: CAS on `expectedDesiredVersion`, desired row + `desiredVersion`
+ * bump + outbox row keyed by `commandId`.
+ */
+export interface DirectorStatePort { read(ref: ChannelRef): Promise<ChannelSnapshot> }
+export interface DesiredStatePort {
+  fence(ref: ChannelRef): Promise<DesiredFence | undefined>;
+  findCommand(ref: ChannelRef, commandId: string): Promise<{ desiredVersion: number } | undefined>;
+  writeProgram(command: ProgramSwitchCommand): Promise<{ kind: "applied"; desiredVersion: number } | { kind: "conflict" }>;
+  audit(ref: ChannelRef, event: { commandId: string; outcome: "SUPERSEDED" | "AUTHZ_REVOKED"; reason: string }): Promise<void>;
+}
+
+function notWired(): never {
+  throw ApplicationFailure.nonRetryable("director desired-state port is not wired", "DIRECTOR_NOT_WIRED");
+}
+/** Placeholder until the go-live slice provides the media-control desired-state adapter. */
+export const unwiredStatePort: DirectorStatePort = { read: async () => notWired() };
+export const unwiredDesiredPort: DesiredStatePort = {
+  fence: async () => notWired(), findCommand: async () => notWired(), writeProgram: async () => notWired(), audit: async () => notWired(),
+};
+
+export class DirectorActivity {
+  constructor(private readonly state: DirectorStatePort = unwiredStatePort, private readonly desired: DesiredStatePort = unwiredDesiredPort) {}
+
+  async readChannelState(ref: ChannelRef): Promise<ChannelSnapshot> {
+    return this.state.read(ref);
+  }
+
+  /** Generation fences are re-checked here, at emission time, never trusted from the workflow. */
+  async applyProgramSwitch(command: ProgramSwitchCommand): Promise<SwitchOutcome> {
+    const { ref, commandId } = command;
+    const prior = await this.desired.findCommand(ref, commandId);
+    if (prior) return { kind: "duplicate", desiredVersion: prior.desiredVersion };
+    const fence = await this.desired.fence(ref);
+    if (!fence || fence.generation !== ref.generation) {
+      await this.desired.audit(ref, { commandId, outcome: "SUPERSEDED", reason: "channel generation superseded" });
+      return { kind: "generation_superseded", code: "SUPERSEDED" };
+    }
+    if (fence.authzEpoch !== command.authzEpoch && !fence.directorAuthorized) {
+      await this.desired.audit(ref, { commandId, outcome: "AUTHZ_REVOKED", reason: "director principal lost director.*" });
+      return { kind: "authz_revoked", code: "AUTHZ_REVOKED" };
+    }
+    if (fence.desiredVersion !== command.expectedDesiredVersion) {
+      await this.desired.audit(ref, { commandId, outcome: "SUPERSEDED", reason: "desiredVersion advanced since snapshot" });
+      return { kind: "superseded", code: "SUPERSEDED" };
+    }
+    const written = await this.desired.writeProgram(command);
+    if (written.kind === "conflict") {
+      await this.desired.audit(ref, { commandId, outcome: "SUPERSEDED", reason: "desiredVersion CAS lost" });
+      return { kind: "superseded", code: "SUPERSEDED" };
+    }
+    return written;
+  }
+}
diff --git a/apps/scheduler/src/director/discovery.ts b/apps/scheduler/src/director/discovery.ts
new file mode 100644
index 0000000..fce5855
--- /dev/null
+++ b/apps/scheduler/src/director/discovery.ts
@@ -0,0 +1,54 @@
+/**
+ * Director evaluator discovery (WP10 wiring slice).
+ *
+ * Mirrors sweepDue: starts are repair hints, and ensureDirector handles
+ * AlreadyStarted itself (nudge a running evaluator, restart a closed one).
+ * A discovery pass that fails must never take the scheduler down, so every
+ * channel error is logged and skipped.
+ */
+import type { Client } from "@temporalio/client";
+import { ensureDirector } from "./starter.js";
+import { parseDirectorChannels, type DirectorChannelConfig } from "./config.js";
+
+export interface DirectorSweepOutcome {
+  started: number;
+  running: number;
+  restarted: number;
+}
+
+/** Configured channels whose generation (and therefore evaluator identity) is still current. */
+export function currentChannels(channels: readonly DirectorChannelConfig[]): DirectorChannelConfig[] {
+  const latest = new Map<string, DirectorChannelConfig>();
+  for (const channel of channels) {
+    const key = `${channel.workspaceId}:${channel.channelId}`;
+    const existing = latest.get(key);
+    // Generations are opaque tokens; the highest wins only when comparable, so
+    // keep the last-declared entry for equal tokens (config is authoritative).
+    if (existing === undefined || existing.generation !== channel.generation) latest.set(key, channel);
+  }
+  return [...latest.values()];
+}
+
+/** Start (or nudge) one evaluator per configured channel. */
+export async function sweepDirectors(
+  client: Client,
+  options: { taskQueue: string; channels: readonly DirectorChannelConfig[] },
+): Promise<DirectorSweepOutcome> {
+  const outcome: DirectorSweepOutcome = { started: 0, running: 0, restarted: 0 };
+  for (const channel of currentChannels(options.channels)) {
+    const ref = { workspaceId: channel.workspaceId, channelId: channel.channelId, generation: channel.generation };
+    try {
+      const result = await ensureDirector(client, ref, options.taskQueue);
+      outcome[result] += 1;
+    } catch {
+      // Temporal unavailable or the start refused: the next sweep retries.
+      continue;
+    }
+  }
+  return outcome;
+}
+
+/** Parse DIRECTOR_CHANNELS, failing startup loudly (a malformed doc must not silently disable the director). */
+export function directorChannelsFromEnv(env: NodeJS.ProcessEnv = process.env): DirectorChannelConfig[] {
+  return parseDirectorChannels(env.DIRECTOR_CHANNELS);
+}
diff --git a/apps/scheduler/src/director/engine.test.ts b/apps/scheduler/src/director/engine.test.ts
new file mode 100644
index 0000000..19d021a
--- /dev/null
+++ b/apps/scheduler/src/director/engine.test.ts
@@ -0,0 +1,279 @@
+import { describe, expect, it } from "vitest";
+import type { AutoDirectorRule, DirectorCondition, DirectorAction, SwitchPolicy } from "@tactical-media-broadcast-hub/core";
+import { decide, type DecideInput, type Decision, type DirectorMemory, type DirectorOverride, type DirectorSourceInput, type LastSwitch } from "./engine.js";
+
+const policy = (over: Partial<SwitchPolicy> = {}): SwitchPolicy => ({ name: "highest_priority", liveConfirmations: 2, offlineConfirmations: 3, noMediaSeconds: 10, minHoldMs: 2_000, switchCooldownMs: 10_000, ...over });
+const src = (id: string, priority: number, state: DirectorSourceInput["state"] = "LIVE", extra: Partial<DirectorSourceInput> = {}): DirectorSourceInput => ({ id, priority, enabled: true, autoSelect: true, state, ...extra });
+const confirmed = (...ids: string[]): DirectorMemory => ({ sources: Object.fromEntries(ids.map((id) => [id, { liveStreak: 2, offlineStreak: 0, confirmed: true, confirmedAtMs: 0 }])) });
+const rule = (id: string, priority: number, condition: DirectorCondition, action: DirectorAction): AutoDirectorRule => ({ id, virtualChannelId: "vc", priority, condition, action });
+const on = (ids: string[], atMs = 0, layout: LastSwitch["layout"] = "single", heldSinceMs = atMs): LastSwitch => ({ atMs, program: { kind: "sources", sourceIds: ids }, layout, heldSinceMs });
+const program = (decision: Decision): string[] => decision.program.kind === "sources" ? decision.program.sourceIds : [`FALLBACK:${decision.program.sceneId ?? ""}`];
+const base = (over: Partial<DecideInput>): DecideInput => ({ sources: [], rules: [], policy: policy(), now: 100_000, ...over });
+
+/** Feed successive snapshots through decide, carrying memory and lastSwitch like the workflow does. */
+function run(steps: Array<{ now: number; sources: DirectorSourceInput[] }>, over: Partial<DecideInput> = {}): Decision[] {
+  let memory: DirectorMemory | undefined = over.memory;
+  let lastSwitch: LastSwitch | undefined = over.lastSwitch;
+  return steps.map(({ now, sources }) => {
+    const decision = decide({ ...base(over), now, sources, ...(memory ? { memory } : {}), ...(lastSwitch ? { lastSwitch } : {}) });
+    memory = decision.memory; lastSwitch = decision.lastSwitch;
+    return decision;
+  });
+}
+
+describe("rule evaluation", () => {
+  const sources = [src("a", 10), src("b", 50), src("c", 30)];
+  it("evaluates by priority desc and the first matching rule wins regardless of list order", () => {
+    const rules = [
+      rule("low", 1, { field: "live_source_count", op: ">=", value: 1 }, { layout: "single", selection: "top_priority" }),
+      rule("high", 9, { field: "live_source_count", op: ">=", value: 3 }, { layout: "grid", selection: "all_live" }),
+      rule("mid", 5, { field: "live_source_count", op: ">=", value: 2 }, { layout: "two_up", selection: "top_priority" }),
+    ];
+    const decision = decide(base({ sources, rules, memory: confirmed("a", "b", "c") }));
+    expect(decision.ruleId).toBe("high");
+    expect(decision.layout).toBe("grid");
+    expect(program(decision)).toEqual(["b", "c", "a"]);
+  });
+  it("breaks priority ties by rule id and skips non-matching rules", () => {
+    const rules = [
+      rule("z", 5, { field: "live_source_count", op: ">=", value: 1 }, { layout: "single", selection: "top_priority" }),
+      rule("y", 5, { field: "live_source_count", op: ">=", value: 1 }, { layout: "pip", selection: "top_priority" }),
+      rule("never", 99, { field: "live_source_count", op: ">", value: 3 }, { layout: "grid", selection: "all_live" }),
+    ];
+    expect(decide(base({ sources, rules, memory: confirmed("a", "b", "c") })).ruleId).toBe("y");
+  });
+  it("supports every condition op on live_source_count and max_priority", () => {
+    const pick = (condition: DirectorCondition): string | undefined => decide(base({ sources, memory: confirmed("a", "b", "c"),
+      rules: [rule("r", 1, condition, { layout: "single", selection: "oldest_live" })] })).ruleId;
+    expect(pick({ field: "live_source_count", op: "==", value: 3 })).toBe("r");
+    expect(pick({ field: "live_source_count", op: "<=", value: 2 })).toBeUndefined();
+    expect(pick({ field: "max_priority", op: ">", value: 49 })).toBe("r");
+    expect(pick({ field: "max_priority", op: ">", value: 50 })).toBeUndefined();
+    expect(pick({ field: "max_priority", op: ">=", value: "50" })).toBe("r");
+    expect(pick({ field: "max_priority", op: "<=", value: 10 })).toBeUndefined();
+  });
+  it("matches source_state on the debounced state, globally or per source", () => {
+    const action: DirectorAction = { layout: "single", selection: "explicit", sourceIds: ["c"] };
+    const memory = confirmed("a", "c");
+    const pick = (value: string, op: DirectorCondition["op"] = "=="): string | undefined =>
+      decide(base({ sources, memory, rules: [rule("r", 1, { field: "source_state", op, value }, action)] })).ruleId;
+    expect(pick("c:LIVE")).toBe("r");
+    // b reports LIVE but is unconfirmed: debounced state is PROBING.
+    expect(pick("b:LIVE")).toBeUndefined();
+    expect(pick("b:PROBING")).toBe("r");
+    expect(pick("LIVE")).toBe("r");
+    expect(pick("LIVE", ">=")).toBeUndefined();
+  });
+  it("ignores rules for other channels when channelId is given", () => {
+    const foreign = { ...rule("x", 9, { field: "live_source_count", op: ">=", value: 1 }, { layout: "pip", selection: "top_priority" }), virtualChannelId: "other" };
+    expect(decide(base({ channelId: "vc", sources, rules: [foreign], memory: confirmed("a", "b") })).ruleId).toBeUndefined();
+  });
+  it("explicit sourceIds pick the listed sources, even lower priority or non-auto ones", () => {
+    const decision = decide(base({ sources: [src("a", 10, "LIVE", { autoSelect: false }), src("b", 50)], memory: confirmed("a", "b"),
+      rules: [rule("r", 1, { field: "live_source_count", op: ">=", value: 1 }, { layout: "single", selection: "explicit", sourceIds: ["a"] })] }));
+    expect(program(decision)).toEqual(["a"]);
+  });
+  it("falls through an explicit rule whose sources are all dead", () => {
+    const decision = decide(base({ sources: [src("a", 10, "OFFLINE"), src("b", 50)], memory: confirmed("b"),
+      rules: [rule("r", 9, { field: "live_source_count", op: ">=", value: 1 }, { layout: "single", selection: "explicit", sourceIds: ["a"] })] }));
+    expect(decision.ruleId).toBeUndefined();
+    expect(program(decision)).toEqual(["b"]);
+    expect(decision.reasons.join("\n")).toContain("falling through");
+  });
+  it("oldest_live rule selection orders by liveSince", () => {
+    const decision = decide(base({ sources: [src("a", 99, "LIVE", { liveSinceMs: 5 }), src("b", 1, "LIVE", { liveSinceMs: 1 })], memory: confirmed("a", "b"),
+      rules: [rule("r", 1, { field: "live_source_count", op: ">=", value: 1 }, { layout: "single", selection: "oldest_live" })] }));
+    expect(program(decision)).toEqual(["b"]);
+  });
+});
+
+describe("selection policies", () => {
+  const sources = [src("a", 10, "LIVE", { liveSinceMs: 300 }), src("b", 50, "LIVE", { liveSinceMs: 100 }), src("c", 30, "LIVE", { liveSinceMs: 200 }), src("d", 20, "LIVE", { liveSinceMs: 400 }), src("e", 5, "LIVE", { liveSinceMs: 500 })];
+  const memory = confirmed("a", "b", "c", "d", "e");
+  const pick = (name: SwitchPolicy["name"], over: Partial<DecideInput> = {}): Decision => decide(base({ sources, memory, policy: policy({ name }), ...over }));
+  it("highest_priority", () => { expect(program(pick("highest_priority"))).toEqual(["b"]); });
+  it("oldest_live", () => { expect(program(pick("oldest_live"))).toEqual(["b"]); expect(program(pick("oldest_live", { sources: sources.filter((s) => s.id !== "b") }))).toEqual(["c"]); });
+  it("newest_live", () => { expect(program(pick("newest_live"))).toEqual(["e"]); });
+  it("round_robin holds for minHold then rotates in a stable order", () => {
+    const rr = policy({ name: "round_robin", minHoldMs: 30_000, switchCooldownMs: 0 });
+    const decisions = run([0, 10_000, 30_000, 60_000, 90_000, 120_000, 150_000].map((now) => ({ now, sources })), { policy: rr, memory });
+    expect(decisions.map((d) => program(d)[0])).toEqual(["a", "a", "b", "c", "d", "e", "a"]);
+  });
+  it("operator_required never auto-selects; keeps a healthy program; dead program -> fallback", () => {
+    expect(program(pick("operator_required", { fallbackSceneId: "slate" }))).toEqual(["FALLBACK:slate"]);
+    expect(pick("operator_required").reasons).toContain("operator_required: awaiting operator TAKE");
+    expect(program(pick("operator_required", { lastSwitch: on(["e"]) }))).toEqual(["e"]);
+    const dead = pick("operator_required", { lastSwitch: on(["e"]), sources: sources.map((s) => s.id === "e" ? { ...s, state: "ERROR" as const } : s) });
+    expect(program(dead)).toEqual(["FALLBACK:"]);
+    expect(dead.forced).toBe(true);
+  });
+  it("picture_in_picture / two_up / split_screen take the top two", () => {
+    expect([pick("picture_in_picture").layout, program(pick("picture_in_picture"))]).toEqual(["pip", ["b", "c"]]);
+    expect([pick("two_up").layout, program(pick("two_up"))]).toEqual(["two_up", ["b", "c"]]);
+    expect([pick("split_screen").layout, program(pick("split_screen"))]).toEqual(["split_horizontal", ["b", "c"]]);
+  });
+  it("grid caps at four slots", () => {
+    expect([pick("grid").layout, program(pick("grid"))]).toEqual(["grid", ["b", "c", "d", "a"]]);
+  });
+  it("composites degrade to single with one live source", () => {
+    for (const name of ["picture_in_picture", "two_up", "split_screen", "grid"] as const) {
+      const decision = decide(base({ sources: [src("a", 1)], memory: confirmed("a"), policy: policy({ name }) }));
+      expect([decision.layout, program(decision)]).toEqual(["single", ["a"]]);
+    }
+  });
+  it("skips disabled and non-autoSelect sources", () => {
+    const decision = decide(base({ sources: [src("a", 99, "LIVE", { enabled: false }), src("b", 50, "LIVE", { autoSelect: false }), src("c", 1)], memory: confirmed("a", "b", "c") }));
+    expect(program(decision)).toEqual(["c"]);
+  });
+});
+
+describe("anti-flapping", () => {
+  it("needs liveConfirmations samples before a source is eligible", () => {
+    const decisions = run([{ now: 1_000, sources: [src("a", 1, "LIVE", { version: 1 })] }, { now: 2_000, sources: [src("a", 1, "LIVE", { version: 2 })] }]);
+    expect(program(decisions[0]!)).toEqual(["FALLBACK:"]);
+    expect(program(decisions[1]!)).toEqual(["a"]);
+  });
+  it("does not count a re-read of the same monitor version as a confirmation", () => {
+    const decisions = run([1_000, 2_000, 3_000].map((now) => ({ now, sources: [src("a", 1, "LIVE", { version: 7 })] })));
+    expect(decisions.map((d) => program(d)[0])).toEqual(["FALLBACK:", "FALLBACK:", "FALLBACK:"]);
+  });
+  it("keeps program through offlineConfirmations - 1 failures (UNSTABLE counts) then fails over", () => {
+    const a = (state: DirectorSourceInput["state"], version: number): DirectorSourceInput => src("a", 10, state, { version });
+    const decisions = run([
+      { now: 1_000, sources: [a("UNSTABLE", 1), src("b", 1)] },
+      { now: 2_000, sources: [a("OFFLINE", 2), src("b", 1)] },
+      { now: 3_000, sources: [a("OFFLINE", 3), src("b", 1)] },
+    ], { memory: confirmed("a", "b"), lastSwitch: on(["a"], 0) });
+    expect(decisions.map((d) => program(d)[0])).toEqual(["a", "a", "b"]);
+    expect(decisions[2]!.forced).toBe(true);
+    expect(decisions[2]!.reasons.join("\n")).toContain("failover: a offline_confirmed");
+  });
+  it("a LIVE sample resets the offline streak", () => {
+    const decisions = run([["OFFLINE", 1], ["OFFLINE", 2], ["LIVE", 3], ["OFFLINE", 4], ["OFFLINE", 5]].map(([state, version], i) => ({ now: 1_000 * (i + 1), sources: [src("a", 10, state as "LIVE", { version: version as number }), src("b", 1)] })),
+      { memory: confirmed("a", "b"), lastSwitch: on(["a"], 0) });
+    expect(decisions.every((d) => program(d)[0] === "a")).toBe(true);
+  });
+  it("fails over after noMediaSeconds without media and wakes exactly at the timeout", () => {
+    const sources = (now: number): DirectorSourceInput[] => [src("a", 10, "LIVE", { lastMediaAtMs: 50_000 }), src("b", 1, "LIVE", { lastMediaAtMs: now })];
+    const before = decide(base({ now: 59_999, sources: sources(59_999), memory: confirmed("a", "b"), lastSwitch: on(["a"], 0) }));
+    expect(program(before)).toEqual(["a"]);
+    expect(before.nextWakeMs).toBe(60_000);
+    const after = decide(base({ now: 60_000, sources: sources(60_000), memory: before.memory, lastSwitch: before.lastSwitch }));
+    expect(program(after)).toEqual(["b"]);
+    expect(after.memory.sources.a).toMatchObject({ confirmed: false, degraded: "no_media" });
+  });
+  it("media-health failure bypasses confirmations", () => {
+    const decision = decide(base({ sources: [src("a", 10, "LIVE", { mediaFailed: true }), src("b", 1)], memory: confirmed("a", "b"), lastSwitch: on(["a"], 99_000) }));
+    expect(program(decision)).toEqual(["b"]);
+    expect(decision.forced).toBe(true);
+  });
+  it("switch cooldown blocks a non-forced preemption until it lapses", () => {
+    const sources = [src("a", 10), src("hi", 99)];
+    const opts = { memory: confirmed("a", "hi"), lastSwitch: on(["a"], 95_000, "single", 0) };
+    const held = decide(base({ now: 100_000, sources, ...opts }));
+    expect(program(held)).toEqual(["a"]);
+    expect(held.switched).toBe(false);
+    expect(held.nextWakeMs).toBe(105_000);
+    expect(program(decide(base({ now: 105_000, sources, ...opts })))).toEqual(["hi"]);
+  });
+  it("minHold keeps the main source but cooldown alone does not apply when zero", () => {
+    const sources = [src("a", 10), src("hi", 99)];
+    const opts = { memory: confirmed("a", "hi"), policy: policy({ switchCooldownMs: 0, minHoldMs: 15_000 }), lastSwitch: on(["a"], 90_000) };
+    const held = decide(base({ now: 100_000, sources, ...opts }));
+    expect(program(held)).toEqual(["a"]);
+    expect(held.reasons.join("\n")).toContain("min hold");
+    const moved = decide(base({ now: 105_000, sources, ...opts }));
+    expect(program(moved)).toEqual(["hi"]);
+    expect(moved.lastSwitch).toEqual({ atMs: 105_000, program: { kind: "sources", sourceIds: ["hi"] }, layout: "single", heldSinceMs: 105_000 });
+  });
+  it("high-priority interrupt happens after hold and cooldown", () => {
+    const decisions = run([0, 2_000, 4_000].map((now) => ({ now, sources: [src("a", 10), src("hi", 99, now === 0 ? "OFFLINE" : "LIVE", { version: now })] })),
+      { memory: confirmed("a"), policy: policy({ minHoldMs: 1_000, switchCooldownMs: 3_000 }) });
+    expect(decisions.map((d) => program(d)[0])).toEqual(["a", "a", "hi"]);
+  });
+});
+
+describe("failover ladder and fallback", () => {
+  it("degrades down the priority ladder then to the fallback scene, then recovers", () => {
+    const step = (now: number, a: DirectorSourceInput["state"], b: DirectorSourceInput["state"], c: DirectorSourceInput["state"]): { now: number; sources: DirectorSourceInput[] } =>
+      ({ now, sources: [src("a", 30, a), src("b", 20, b), src("c", 10, c)] });
+    const decisions = run([
+      step(1_000, "LIVE", "LIVE", "LIVE"),
+      step(1_100, "ERROR", "LIVE", "LIVE"),
+      step(1_200, "ERROR", "ERROR", "LIVE"),
+      step(1_300, "ERROR", "ERROR", "ERROR"),
+      step(1_400, "LIVE", "ERROR", "ERROR"),
+      step(1_500, "LIVE", "ERROR", "ERROR"),
+    ], { memory: confirmed("a", "b", "c"), fallbackSceneId: "slate" });
+    expect(decisions.map((d) => program(d)[0])).toEqual(["a", "b", "c", "FALLBACK:slate", "FALLBACK:slate", "a"]);
+    expect(decisions.slice(1, 4).every((d) => d.forced && d.switched)).toBe(true);
+    expect(decisions[3]!.mode).toBe("FALLBACK");
+    expect(decisions[5]!.reasons).toContain("leaving fallback scene");
+  });
+  it("a composite with one dead slot re-forms immediately", () => {
+    const decision = decide(base({ policy: policy({ name: "two_up" }), sources: [src("a", 30), src("b", 20, "ERROR"), src("c", 10)], memory: confirmed("a", "b", "c"), lastSwitch: on(["a", "b"], 99_000, "two_up") }));
+    expect([decision.layout, program(decision), decision.forced]).toEqual(["two_up", ["a", "c"], true]);
+  });
+  it("all sources OFFLINE from a cold start -> fallback with null scene", () => {
+    const decision = decide(base({ sources: [src("a", 1, "OFFLINE"), src("b", 2, "OFFLINE")] }));
+    expect(decision.program).toEqual({ kind: "fallback", sceneId: null });
+    expect(decision.reasons).toContain("all sources dead: fallback scene");
+  });
+  it("no sources at all -> fallback", () => {
+    expect(decide(base({ fallbackSceneId: "loop" })).program).toEqual({ kind: "fallback", sceneId: "loop" });
+  });
+  it("single source stays on program and is not re-switched", () => {
+    const first = decide(base({ sources: [src("only", 1)], memory: confirmed("only") }));
+    expect([program(first), first.switched]).toEqual([["only"], true]);
+    const second = decide(base({ now: 200_000, sources: [src("only", 1)], memory: first.memory, lastSwitch: first.lastSwitch }));
+    expect([program(second), second.switched]).toEqual([["only"], false]);
+  });
+});
+
+describe("operator override", () => {
+  const take = (over: Partial<DirectorOverride> = {}): DirectorOverride => ({ kind: "take", release: "until_released", program: { kind: "sources", sourceIds: ["low"] }, layout: "single", principalId: "op", takenAtMs: 90_000, ...over });
+  const sources = [src("low", 1), src("hi", 99)];
+  const permitted = { op: ["director.switch"] };
+  const rules = [rule("r", 9, { field: "live_source_count", op: ">=", value: 1 }, { layout: "single", selection: "top_priority" })];
+  it("operator TAKE wins over AUTO rules and is not undone by automation", () => {
+    const decision = decide(base({ sources, rules, override: take(), principalPermissions: permitted, memory: confirmed("low", "hi"), lastSwitch: on(["low"], 90_000) }));
+    expect([program(decision), decision.mode, decision.switched, decision.override]).toEqual([["low"], "MANUAL", false, take()]);
+  });
+  it("program lock holds even when its source is dead", () => {
+    const decision = decide(base({ sources: [src("low", 1, "ERROR"), src("hi", 99)], override: take({ kind: "lock" }), principalPermissions: permitted, memory: confirmed("low", "hi"), lastSwitch: on(["low"], 0) }));
+    expect([program(decision), decision.mode]).toEqual([["low"], "LOCKED"]);
+    expect(decision.reasons).toContain("program lock holds an unhealthy source");
+  });
+  it("revoking director.* releases the override back to AUTO immediately (revocation matrix)", () => {
+    for (const [kind, permissions] of [["take", {}], ["lock", { op: ["posts.read"] }], ["take", { other: ["director.switch"] }]] as const) {
+      const decision = decide(base({ sources, override: take({ kind }), principalPermissions: permissions, memory: confirmed("low", "hi"), lastSwitch: on(["low"], 99_999) }));
+      expect([decision.overrideReleased, decision.override, decision.mode, program(decision), decision.forced]).toEqual(["AUTHZ_REVOKED", null, "AUTO", ["hi"], true]);
+    }
+  });
+  it("timed override expires; until_source_offline and until_next_event release on their triggers", () => {
+    const opts = { sources, principalPermissions: permitted, lastSwitch: on(["low"], 99_000) };
+    const expired = decide(base({ ...opts, override: take({ release: "timed", expiresAtMs: 100_000 }), memory: confirmed("low", "hi") }));
+    expect([expired.overrideReleased, program(expired)]).toEqual(["OVERRIDE_EXPIRED", ["hi"]]);
+    const pending = decide(base({ ...opts, now: 99_000, override: take({ release: "timed", expiresAtMs: 100_000 }), memory: confirmed("low", "hi") }));
+    expect([pending.override?.release, pending.nextWakeMs]).toEqual(["timed", 100_000]);
+
+    const offline = decide(base({ ...opts, sources: [src("low", 1, "ERROR"), src("hi", 99)], override: take({ release: "until_source_offline" }), memory: confirmed("low", "hi") }));
+    expect([offline.overrideReleased, program(offline)]).toEqual(["SOURCE_OFFLINE", ["hi"]]);
+
+    const armed = decide(base({ ...opts, override: take({ release: "until_next_event" }), memory: confirmed("low", "hi") }));
+    expect(armed.override?.eligibleAtTake).toEqual(["hi", "low"]);
+    const same = decide(base({ ...opts, override: armed.override, memory: armed.memory }));
+    expect(same.override).not.toBeNull();
+    const event = decide(base({ ...opts, sources: [...sources, src("new", 50)], override: armed.override, memory: confirmed("low", "hi", "new") }));
+    expect([event.overrideReleased, program(event)]).toEqual(["NEXT_EVENT", ["hi"]]);
+  });
+  it("a lock ignores source-offline release modes", () => {
+    const decision = decide(base({ sources: [src("low", 1, "ERROR")], override: take({ kind: "lock", release: "until_source_offline" }), principalPermissions: permitted, memory: confirmed("low") }));
+    expect([decision.override?.kind, program(decision)]).toEqual(["lock", ["low"]]);
+  });
+  it("override applies with switch and keeps counting confirmations underneath", () => {
+    const decision = decide(base({ sources: [src("low", 1), src("hi", 99, "LIVE", { version: 1 })], override: take(), principalPermissions: permitted, memory: confirmed("low"), lastSwitch: on(["hi"], 0) }));
+    expect([decision.switched, program(decision)]).toEqual([true, ["low"]]);
+    expect(decision.memory.sources.hi).toMatchObject({ liveStreak: 1, confirmed: false });
+  });
+});
diff --git a/apps/scheduler/src/director/engine.ts b/apps/scheduler/src/director/engine.ts
new file mode 100644
index 0000000..68806dd
--- /dev/null
+++ b/apps/scheduler/src/director/engine.ts
@@ -0,0 +1,344 @@
+/**
+ * WP10 Auto Director decision engine. Pure and deterministic: no I/O, no clock,
+ * no Temporal. Every timestamp is epoch milliseconds so inputs and outputs stay
+ * JSON-serializable across activity boundaries and continue-as-new.
+ * Imports from core are type-only so the workflow bundle stays sandbox-safe.
+ */
+import type {
+  AutoDirectorRule, DirectorCondition, DirectorMode, DirectorOverrideKind, DirectorOverrideRelease,
+  DirectorOverrideReleaseReason, LiveSourceState, LiveSourceStateType, SceneLayout, SwitchPolicy, VirtualChannelSource,
+} from "@tactical-media-broadcast-hub/core";
+
+export interface DirectorSourceInput {
+  id: string;
+  priority: number;
+  enabled: boolean;
+  autoSelect: boolean;
+  state: LiveSourceStateType;
+  /** Monitor row version; a re-read of the same version is not a new confirmation sample. */
+  version?: number;
+  liveSinceMs?: number;
+  /** Last media-health "media present" instant; drives the no-media timeout. */
+  lastMediaAtMs?: number;
+  /** Media-health tier reports failure: bypasses confirmations (proposal §5.2 ladder step 2). */
+  mediaFailed?: boolean;
+}
+
+export interface SourceTrack {
+  liveStreak: number;
+  offlineStreak: number;
+  confirmed: boolean;
+  confirmedAtMs?: number;
+  lastVersion?: number;
+  /** Why the source last lost (or never had) eligibility. */
+  degraded?: string;
+}
+
+export interface DirectorMemory { sources: Record<string, SourceTrack> }
+
+export type DirectorProgram =
+  | { kind: "sources"; sourceIds: string[] }
+  | { kind: "fallback"; sceneId: string | null };
+
+export interface LastSwitch {
+  atMs: number;
+  program: DirectorProgram;
+  layout: SceneLayout;
+  /** When the program's main (first-slot) source went on air; minHold is measured from here. */
+  heldSinceMs: number;
+}
+
+export interface DirectorOverride {
+  kind: DirectorOverrideKind;
+  release: DirectorOverrideRelease;
+  program: DirectorProgram;
+  layout: SceneLayout;
+  principalId: string;
+  takenAtMs: number;
+  expiresAtMs?: number;
+  /** Eligible set at TAKE time, filled by the engine for `until_next_event`. */
+  eligibleAtTake?: string[];
+}
+
+export interface DecideInput {
+  sources: readonly DirectorSourceInput[];
+  rules: readonly AutoDirectorRule[];
+  policy: SwitchPolicy;
+  now: number;
+  lastSwitch?: LastSwitch;
+  memory?: DirectorMemory;
+  channelId?: string;
+  fallbackSceneId?: string | null;
+  override?: DirectorOverride | null;
+  /** Current permissions per principal (re-read every evaluation, never the TAKE-time snapshot). */
+  principalPermissions?: Readonly<Record<string, readonly string[]>>;
+}
+
+export interface Decision {
+  program: DirectorProgram;
+  layout: SceneLayout;
+  reasons: string[];
+  mode: DirectorMode;
+  /** Program or layout differs from `lastSwitch`; the wrapper must emit a desired-state write. */
+  switched: boolean;
+  /** Switch bypassed minHold/cooldown (failover, fallback exit, override end). */
+  forced: boolean;
+  ruleId?: string;
+  memory: DirectorMemory;
+  override: DirectorOverride | null;
+  overrideReleased?: DirectorOverrideReleaseReason;
+  lastSwitch: LastSwitch;
+  /** Earliest instant a purely time-based change could alter the decision. */
+  nextWakeMs?: number;
+}
+
+interface Candidate { id: string; priority: number; liveSinceMs: number }
+interface Selection { program: DirectorProgram; layout: SceneLayout; ruleId?: string }
+
+const CAPACITY: Record<SceneLayout, number> = { single: 1, pip: 2, two_up: 2, split_horizontal: 2, split_vertical: 2, grid: 4, custom: Number.POSITIVE_INFINITY };
+const COMPOSITE_POLICY: Partial<Record<SwitchPolicy["name"], SceneLayout>> = { picture_in_picture: "pip", two_up: "two_up", split_screen: "split_horizontal", grid: "grid" };
+
+/** Adapt the persisted monitor/domain types into engine input. */
+export function sourceInput(source: Pick<VirtualChannelSource, "id" | "priority" | "enabled" | "autoSelect">, state: LiveSourceState, extra: { version?: number; mediaFailed?: boolean } = {}): DirectorSourceInput {
+  return {
+    id: source.id, priority: source.priority, enabled: source.enabled, autoSelect: source.autoSelect, state: state.state,
+    ...(extra.version === undefined ? {} : { version: extra.version }),
+    ...(state.liveSince ? { liveSinceMs: state.liveSince.getTime() } : {}),
+    ...(state.lastHealthyAt ? { lastMediaAtMs: state.lastHealthyAt.getTime() } : {}),
+    ...(extra.mediaFailed === undefined ? {} : { mediaFailed: extra.mediaFailed }),
+  };
+}
+
+/** Fold one snapshot into per-source confirmation tracking. */
+function track(previous: SourceTrack | undefined, source: DirectorSourceInput, policy: SwitchPolicy, now: number): SourceTrack {
+  let next: SourceTrack = previous ? { ...previous } : { liveStreak: 0, offlineStreak: 0, confirmed: false };
+  const fresh = source.version === undefined || previous?.lastVersion !== source.version;
+  if (fresh) {
+    if (source.version !== undefined) next.lastVersion = source.version;
+    switch (source.state) {
+      case "LIVE":
+        next.liveStreak += 1; next.offlineStreak = 0;
+        if (!next.confirmed && next.liveStreak >= policy.liveConfirmations) next = { ...next, confirmed: true, confirmedAtMs: now, degraded: undefined };
+        break;
+      case "OFFLINE": case "ENDING": case "UNSTABLE":
+        next.offlineStreak += 1; next.liveStreak = 0;
+        if (next.confirmed && next.offlineStreak >= policy.offlineConfirmations) next = { ...next, confirmed: false, degraded: "offline_confirmed" };
+        break;
+      case "ERROR":
+        next = { ...next, liveStreak: 0, offlineStreak: 0, confirmed: false, degraded: next.confirmed ? "error" : next.degraded };
+        break;
+      default:
+        next.liveStreak = 0;
+    }
+  }
+  // Hard media failures override confirmations and force re-confirmation.
+  if (next.confirmed && source.mediaFailed === true) next = { ...next, confirmed: false, liveStreak: 0, degraded: "media_failed" };
+  if (next.confirmed && source.lastMediaAtMs !== undefined && now - source.lastMediaAtMs >= policy.noMediaSeconds * 1000) {
+    next = { ...next, confirmed: false, liveStreak: 0, degraded: "no_media" };
+  }
+  if (!source.enabled && next.confirmed) next = { ...next, confirmed: false, degraded: "disabled" };
+  if (next.degraded === undefined) delete next.degraded;
+  return next;
+}
+
+function byPriority(a: Candidate, b: Candidate): number {
+  return b.priority - a.priority || a.liveSinceMs - b.liveSinceMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+}
+function byAge(a: Candidate, b: Candidate): number {
+  return a.liveSinceMs - b.liveSinceMs || byPriority(a, b);
+}
+function compare(actual: number, op: DirectorCondition["op"], expected: number): boolean {
+  switch (op) {
+    case ">=": return actual >= expected;
+    case "<=": return actual <= expected;
+    case "==": return actual === expected;
+    case ">": return actual > expected;
+  }
+}
+function programKey(program: DirectorProgram, layout: SceneLayout): string {
+  return program.kind === "fallback" ? `fallback:${program.sceneId ?? ""}` : `${layout}:${program.sourceIds.join(",")}`;
+}
+function mainSource(program: DirectorProgram): string | undefined {
+  return program.kind === "sources" ? program.sourceIds[0] : undefined;
+}
+/** Composite layouts collapse to `single` when only one source can fill them. */
+function fill(ids: string[], layout: SceneLayout, reasons: string[]): { program: DirectorProgram; layout: SceneLayout } | undefined {
+  const picked = ids.slice(0, CAPACITY[layout]);
+  if (picked.length === 0) return undefined;
+  if (layout !== "single" && layout !== "custom" && picked.length < 2) {
+    reasons.push(`layout ${layout} degraded to single: one eligible source`);
+    return { program: { kind: "sources", sourceIds: picked }, layout: "single" };
+  }
+  return { program: { kind: "sources", sourceIds: picked }, layout };
+}
+
+export function decide(input: DecideInput): Decision {
+  const { policy, now } = input;
+  const reasons: string[] = [];
+  const memory: DirectorMemory = { sources: {} };
+  for (const source of input.sources) memory.sources[source.id] = track(input.memory?.sources[source.id], source, policy, now);
+
+  const live: Candidate[] = input.sources
+    .filter((source) => source.enabled && memory.sources[source.id]?.confirmed === true)
+    .map((source) => ({ id: source.id, priority: source.priority, liveSinceMs: source.liveSinceMs ?? memory.sources[source.id]?.confirmedAtMs ?? now }))
+    .sort(byPriority);
+  const liveIds = new Set(live.map((candidate) => candidate.id));
+  const autoPool = live.filter((candidate) => input.sources.find((source) => source.id === candidate.id)?.autoSelect !== false);
+  const healthy = (program: DirectorProgram): boolean => program.kind === "sources" && program.sourceIds.length > 0 && program.sourceIds.every((id) => liveIds.has(id));
+  const fallback: DirectorProgram = { kind: "fallback", sceneId: input.fallbackSceneId ?? null };
+
+  // Wake for the earliest no-media timeout among eligible sources.
+  const wakes: number[] = [];
+  for (const source of input.sources) {
+    if (liveIds.has(source.id) && source.lastMediaAtMs !== undefined) wakes.push(source.lastMediaAtMs + policy.noMediaSeconds * 1000);
+  }
+  const nextWake = (): number | undefined => {
+    const future = wakes.filter((at) => at > now);
+    return future.length === 0 ? undefined : Math.min(...future);
+  };
+
+  // Ladder step 1: operator override / program lock.
+  let override = input.override ? { ...input.override } : null;
+  let overrideReleased: DirectorOverrideReleaseReason | undefined;
+  if (override) {
+    const permissions = input.principalPermissions?.[override.principalId] ?? [];
+    const liveSet = [...liveIds].sort();
+    if (!permissions.some((permission) => permission.startsWith("director."))) overrideReleased = "AUTHZ_REVOKED";
+    else if (override.expiresAtMs !== undefined && now >= override.expiresAtMs) overrideReleased = "OVERRIDE_EXPIRED";
+    else if (override.kind === "take" && override.release === "until_source_offline" && !healthy(override.program)) overrideReleased = "SOURCE_OFFLINE";
+    else if (override.kind === "take" && override.release === "until_next_event") {
+      if (override.eligibleAtTake === undefined) override.eligibleAtTake = liveSet;
+      else if (override.eligibleAtTake.join(",") !== liveSet.join(",")) overrideReleased = "NEXT_EVENT";
+    }
+    if (overrideReleased) {
+      reasons.push(`${override.kind} by ${override.principalId} released: ${overrideReleased}; returning to AUTO`);
+      override = null;
+    } else {
+      if (override.expiresAtMs !== undefined) wakes.push(override.expiresAtMs);
+      const switched = !input.lastSwitch || programKey(input.lastSwitch.program, input.lastSwitch.layout) !== programKey(override.program, override.layout);
+      if (override.kind === "lock" && !healthy(override.program) && override.program.kind === "sources") reasons.push("program lock holds an unhealthy source");
+      reasons.push(`${override.kind === "lock" ? "program lock" : "operator TAKE"} by ${override.principalId} wins over AUTO`);
+      const lastSwitch: LastSwitch = switched
+        ? { atMs: now, program: override.program, layout: override.layout, heldSinceMs: mainSource(override.program) === mainSource(input.lastSwitch?.program ?? fallback) ? input.lastSwitch?.heldSinceMs ?? now : now }
+        : input.lastSwitch!;
+      return {
+        program: override.program, layout: override.layout, reasons, mode: override.kind === "lock" ? "LOCKED" : "MANUAL",
+        switched, forced: switched, memory, override, lastSwitch, ...(nextWake() === undefined ? {} : { nextWakeMs: nextWake()! }),
+      };
+    }
+  }
+
+  // Ladder: ordered rules (priority desc, id asc for determinism), first match wins.
+  let selection: Selection | undefined;
+  const rules = input.rules.filter((rule) => input.channelId === undefined || rule.virtualChannelId === input.channelId)
+    .sort((a, b) => b.priority - a.priority || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  for (const rule of rules) {
+    if (!matches(rule, input.sources, live, memory, reasons)) continue;
+    const pool = rule.action.selection === "explicit"
+      ? (rule.action.sourceIds ?? []).map((id) => live.find((candidate) => candidate.id === id)).filter((candidate): candidate is Candidate => candidate !== undefined)
+      : autoPool;
+    const ordered = rule.action.selection === "oldest_live" ? [...pool].sort(byAge) : pool;
+    const filled = fill(ordered.map((candidate) => candidate.id), rule.action.layout, reasons);
+    if (!filled) { reasons.push(`rule ${rule.id} matched but has no eligible source; falling through`); continue; }
+    reasons.push(`rule ${rule.id} matched (${rule.condition.field} ${rule.condition.op} ${String(rule.condition.value)})`);
+    selection = { ...filled, ruleId: rule.id };
+    break;
+  }
+
+  // No rule matched: the channel's selection policy.
+  if (!selection) {
+    const ids = autoPool.map((candidate) => candidate.id);
+    const current = input.lastSwitch;
+    const currentMain = current ? mainSource(current.program) : undefined;
+    let picked: { program: DirectorProgram; layout: SceneLayout } | undefined;
+    switch (policy.name) {
+      case "highest_priority": picked = fill(ids, "single", reasons); break;
+      case "oldest_live": picked = fill([...autoPool].sort(byAge).map((candidate) => candidate.id), "single", reasons); break;
+      case "newest_live": picked = fill([...autoPool].sort((a, b) => byAge(b, a)).map((candidate) => candidate.id), "single", reasons); break;
+      case "round_robin": {
+        const rotation = [...ids].sort();
+        const index = currentMain === undefined ? -1 : rotation.indexOf(currentMain);
+        if (index >= 0 && current && now - current.heldSinceMs < policy.minHoldMs) {
+          picked = fill([rotation[index]!], "single", reasons);
+          wakes.push(current.heldSinceMs + policy.minHoldMs);
+        } else {
+          picked = fill(rotation.length === 0 ? [] : [rotation[(index + 1) % rotation.length]!], "single", reasons);
+          if (index >= 0 && rotation.length > 1) reasons.push("round_robin rotation");
+        }
+        break;
+      }
+      case "operator_required":
+        if (current && healthy(current.program)) picked = { program: current.program, layout: current.layout };
+        else if (live.length > 0) reasons.push("operator_required: awaiting operator TAKE");
+        break;
+      default: picked = fill(ids, COMPOSITE_POLICY[policy.name] ?? "single", reasons);
+    }
+    if (picked) { selection = picked; reasons.push(`policy ${policy.name} selected ${programKey(picked.program, picked.layout)}`); }
+  }
+
+  // Ladder terminal: fallback scene keeps output alive.
+  if (!selection) {
+    selection = { program: fallback, layout: "single" };
+    reasons.push(live.length === 0 ? "all sources dead: fallback scene" : "no selection: fallback scene");
+  }
+
+  // Anti-flapping against the current program.
+  const current = input.lastSwitch;
+  const desiredKey = programKey(selection.program, selection.layout);
+  let outcome: Selection = selection;
+  let switched = false;
+  let forced = false;
+  if (!current) {
+    switched = true; forced = true;
+    reasons.push("initial program");
+  } else if (programKey(current.program, current.layout) !== desiredKey) {
+    if (overrideReleased || !healthy(current.program)) {
+      switched = true; forced = true;
+      if (current.program.kind === "sources") {
+        const lost = current.program.sourceIds.filter((id) => !liveIds.has(id));
+        reasons.push(`failover: ${lost.map((id) => `${id} ${memory.sources[id]?.degraded ?? "not live"}`).join(", ") || "override released"}`);
+      } else if (!overrideReleased) reasons.push("leaving fallback scene");
+    } else if (now - current.atMs < policy.switchCooldownMs) {
+      outcome = { program: current.program, layout: current.layout };
+      wakes.push(current.atMs + policy.switchCooldownMs);
+      reasons.push(`switch cooldown holds program until ${current.atMs + policy.switchCooldownMs}`);
+    } else if (mainSource(current.program) !== mainSource(selection.program) && now - current.heldSinceMs < policy.minHoldMs) {
+      outcome = { program: current.program, layout: current.layout };
+      wakes.push(current.heldSinceMs + policy.minHoldMs);
+      reasons.push(`min hold keeps ${mainSource(current.program) ?? "program"} until ${current.heldSinceMs + policy.minHoldMs}`);
+    } else {
+      switched = true;
+    }
+  }
+  const lastSwitch: LastSwitch = switched
+    ? { atMs: now, program: outcome.program, layout: outcome.layout, heldSinceMs: current && mainSource(current.program) === mainSource(outcome.program) && mainSource(outcome.program) !== undefined ? current.heldSinceMs : now }
+    : current!;
+  const wake = nextWake();
+  return {
+    program: outcome.program, layout: outcome.layout, reasons, mode: outcome.program.kind === "fallback" ? "FALLBACK" : "AUTO",
+    switched, forced, ...(outcome.ruleId === undefined || outcome !== selection ? {} : { ruleId: outcome.ruleId }),
+    memory, override: null, ...(overrideReleased ? { overrideReleased } : {}), lastSwitch, ...(wake === undefined ? {} : { nextWakeMs: wake }),
+  };
+}
+
+/** Effective (debounced) state: LIVE only once confirmed and healthy. */
+function effectiveState(source: DirectorSourceInput, memory: DirectorMemory): LiveSourceStateType {
+  if (source.enabled && memory.sources[source.id]?.confirmed === true) return "LIVE";
+  return source.state === "LIVE" ? "PROBING" : source.state;
+}
+
+function matches(rule: AutoDirectorRule, sources: readonly DirectorSourceInput[], live: readonly Candidate[], memory: DirectorMemory, reasons: string[]): boolean {
+  const { field, op, value } = rule.condition;
+  if (field === "source_state") {
+    if (op !== "==" || typeof value !== "string") { reasons.push(`rule ${rule.id} skipped: source_state supports only == "<STATE>" or "<sourceId>:<STATE>"`); return false; }
+    const split = value.lastIndexOf(":");
+    const wanted = split < 0 ? value : value.slice(split + 1);
+    const scope = split >= 0 ? [value.slice(0, split)] : rule.action.selection === "explicit" ? rule.action.sourceIds ?? [] : undefined;
+    return sources.some((source) => (scope === undefined ? source.enabled : scope.includes(source.id)) && effectiveState(source, memory) === wanted);
+  }
+  const expected = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(expected)) { reasons.push(`rule ${rule.id} skipped: non-numeric ${field} value`); return false; }
+  if (field === "live_source_count") return compare(live.length, op, expected);
+  if (live.length === 0) return false;
+  return compare(Math.max(...live.map((candidate) => candidate.priority)), op, expected);
+}
diff --git a/apps/scheduler/src/director/evaluator.workflow.ts b/apps/scheduler/src/director/evaluator.workflow.ts
new file mode 100644
index 0000000..18c90a9
--- /dev/null
+++ b/apps/scheduler/src/director/evaluator.workflow.ts
@@ -0,0 +1,100 @@
+import { condition, continueAsNew, defineQuery, defineSignal, proxyActivities, setHandler, workflowInfo } from "@temporalio/workflow";
+import type { DirectorMode } from "@tactical-media-broadcast-hub/core";
+import { decide, type DirectorMemory, type LastSwitch } from "./engine.js";
+import type { ChannelRef, DirectorActivity } from "./director.activity.js";
+
+const { readChannelState } = proxyActivities<Pick<DirectorActivity, "readChannelState">>({
+  startToCloseTimeout: "10 seconds",
+  retry: { initialInterval: "500 milliseconds", maximumInterval: "5 seconds", nonRetryableErrorTypes: ["DIRECTOR_NOT_WIRED"] },
+});
+const { applyProgramSwitch } = proxyActivities<Pick<DirectorActivity, "applyProgramSwitch">>({
+  startToCloseTimeout: "15 seconds",
+  retry: { initialInterval: "500 milliseconds", maximumInterval: "5 seconds", maximumAttempts: 5, nonRetryableErrorTypes: ["DIRECTOR_NOT_WIRED"] },
+});
+
+/** Hint only: `(sourceId, version)`. Evaluations always re-read a fresh snapshot. */
+export interface SourceHint { sourceId: string; version: number; urgent?: boolean }
+export interface EvaluatorCarry { memory: DirectorMemory; lastSwitch?: LastSwitch; seq: number }
+export interface EvaluatorInput { ref: ChannelRef; carry?: EvaluatorCarry }
+export type EvaluatorResult = { kind: "stopped" } | { kind: "superseded"; code: "SUPERSEDED" } | { kind: "needs_reauthorization"; code: "AUTHZ_REVOKED" };
+export interface EvaluatorStatus { mode?: DirectorMode; lastSwitch?: LastSwitch; reasons: string[]; evaluations: number }
+
+export const sourceChanged = defineSignal<[SourceHint]>("sourceChanged");
+export const stopDirector = defineSignal("stopDirector");
+export const directorStatus = defineQuery<EvaluatorStatus>("directorStatus");
+
+export const DEBOUNCE_MS = 250;
+export const MAX_WAIT_MS = 1000;
+export const POLL_MS = 5000;
+export const CONTINUE_AS_NEW_EVENTS = 2000;
+
+/** One evaluator per virtual channel: debounce hints, decide, emit fenced desired-state writes. */
+export async function autoDirectorEvaluator({ ref, carry }: EvaluatorInput): Promise<EvaluatorResult> {
+  let memory: DirectorMemory = carry?.memory ?? { sources: {} };
+  let lastSwitch = carry?.lastSwitch;
+  let seq = carry?.seq ?? 0;
+  let dirty = true;
+  let urgent = false;
+  let stopping = false;
+  let firstPendingAt: number | undefined;
+  let lastSignalAt = 0;
+  let events = 0;
+  let evaluations = 0;
+  let nextWakeMs: number | undefined;
+  let status: EvaluatorStatus = { reasons: [], evaluations: 0, ...(lastSwitch ? { lastSwitch } : {}) };
+
+  setHandler(sourceChanged, (hint) => {
+    events += 1; dirty = true;
+    if (hint.urgent === true) urgent = true;
+    lastSignalAt = Date.now();
+    firstPendingAt ??= lastSignalAt;
+  });
+  setHandler(stopDirector, () => { stopping = true; });
+  setHandler(directorStatus, () => status);
+
+  for (;;) {
+    const idle = Math.min(POLL_MS, nextWakeMs === undefined ? POLL_MS : Math.max(0, nextWakeMs - Date.now()));
+    await condition(() => dirty || stopping, idle);
+    if (stopping) return { kind: "stopped" };
+    // Trailing debounce: 250 ms quiet window, 1 s max wait; urgent program-source failure bypasses.
+    while (dirty && !urgent && firstPendingAt !== undefined) {
+      const deadline = Math.min(lastSignalAt + DEBOUNCE_MS, firstPendingAt + MAX_WAIT_MS);
+      if (Date.now() >= deadline) break;
+      const seen = lastSignalAt;
+      if (!(await condition(() => urgent || stopping || lastSignalAt !== seen, deadline - Date.now()))) break;
+      if (stopping) return { kind: "stopped" };
+    }
+    dirty = false; urgent = false; firstPendingAt = undefined;
+
+    const snapshot = await readChannelState(ref);
+    if (snapshot.kind === "superseded") return { kind: "superseded", code: "SUPERSEDED" };
+    const decision = decide({
+      sources: snapshot.sources, rules: snapshot.rules, policy: snapshot.policy, now: Date.now(), channelId: ref.channelId,
+      fallbackSceneId: snapshot.fallbackSceneId, override: snapshot.override, principalPermissions: snapshot.principalPermissions,
+      memory, ...(lastSwitch ? { lastSwitch } : {}),
+    });
+    memory = decision.memory;
+    evaluations += 1;
+    nextWakeMs = decision.nextWakeMs;
+    if (decision.switched || decision.overrideReleased) {
+      seq += 1;
+      const outcome = await applyProgramSwitch({
+        ref, commandId: `${ref.channelId}:${ref.generation}:${seq}`, expectedDesiredVersion: snapshot.desiredVersion,
+        authzEpoch: snapshot.authzEpoch, program: decision.program, layout: decision.layout, reasons: decision.reasons,
+        ...(decision.overrideReleased ? { releaseOverride: decision.overrideReleased } : {}),
+      });
+      if (outcome.kind === "generation_superseded") return { kind: "superseded", code: "SUPERSEDED" };
+      if (outcome.kind === "authz_revoked") return { kind: "needs_reauthorization", code: "AUTHZ_REVOKED" };
+      // A concurrent writer (e.g. operator TAKE) won the CAS: re-read rather than re-apply.
+      if (outcome.kind === "superseded") dirty = true;
+      else lastSwitch = decision.lastSwitch;
+    } else {
+      lastSwitch = decision.lastSwitch;
+    }
+    status = { mode: decision.mode, reasons: decision.reasons, evaluations, ...(lastSwitch ? { lastSwitch } : {}) };
+
+    if (events + evaluations >= CONTINUE_AS_NEW_EVENTS || workflowInfo().continueAsNewSuggested) {
+      return continueAsNew<typeof autoDirectorEvaluator>({ ref, carry: { memory, seq, ...(lastSwitch ? { lastSwitch } : {}) } });
+    }
+  }
+}
diff --git a/apps/scheduler/src/director/http.client.ts b/apps/scheduler/src/director/http.client.ts
new file mode 100644
index 0000000..e4206f8
--- /dev/null
+++ b/apps/scheduler/src/director/http.client.ts
@@ -0,0 +1,128 @@
+/**
+ * HTTP implementation of the director ports (WP10 wiring slice).
+ *
+ * The scheduler worker dials the API's internal director endpoints. Every
+ * response is validated before it reaches the engine: the API is a different
+ * process, so a malformed or truncated reply must surface as a transport
+ * error (retryable) rather than poison the evaluator's memory.
+ *
+ * Endpoints (apps/api/src/director/director.controller.ts):
+ *   GET  /internal/director/channels/:workspaceId/:channelId/state
+ *   GET  /internal/director/channels/:workspaceId/:channelId/fence
+ *   POST /internal/director/channels/:workspaceId/:channelId/apply
+ *   POST /internal/director/channels/:workspaceId/:channelId/audit
+ */
+import type { ChannelRef, DesiredFence } from "./director.activity.js";
+import type { DirectorApplyRequest, DirectorApplyResult, DirectorApi, DirectorStateRead } from "./ports.js";
+
+export interface DirectorHttpClientDependencies {
+  /** Base URL of the API (default http://127.0.0.1:3000). */
+  baseUrl?: string;
+  /** Shared-secret bearer for the internal route group. */
+  token?: string;
+  fetch?: typeof fetch;
+  /** Default 8s; short so an unresponsive API fails the activity fast. */
+  timeoutMs?: number;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function requiredString(value: unknown, path: string): string {
+  if (typeof value !== "string" || value === "") throw new Error(`director api: ${path} must be a non-empty string`);
+  return value;
+}
+
+/** Shape-check an apply response without trusting the status code alone. */
+export function parseApplyResult(value: unknown): DirectorApplyResult {
+  if (!isRecord(value)) throw new Error("director api: apply response must be an object");
+  const kind = value.kind;
+  if (kind === "conflict") return { kind: "conflict" };
+  if (kind !== "applied" && kind !== "duplicate") throw new Error("director api: apply response kind is invalid");
+  const desiredVersion = value.desiredVersion;
+  if (typeof desiredVersion !== "number" || !Number.isSafeInteger(desiredVersion) || desiredVersion < 0) {
+    throw new Error("director api: apply response desiredVersion is invalid");
+  }
+  return { kind, desiredVersion };
+}
+
+/** Shape-check a fence response (fence may legitimately be absent). */
+export function parseFence(value: unknown): DesiredFence | undefined {
+  if (value === null || value === undefined) return undefined;
+  if (!isRecord(value)) throw new Error("director api: fence response must be an object or null");
+  const generation = requiredString(value.generation, "fence.generation");
+  const desiredVersion = value.desiredVersion;
+  const authzEpoch = value.authzEpoch;
+  if (typeof desiredVersion !== "number" || !Number.isSafeInteger(desiredVersion) || desiredVersion < 0) {
+    throw new Error("director api: fence.desiredVersion is invalid");
+  }
+  if (typeof authzEpoch !== "number" || !Number.isSafeInteger(authzEpoch) || authzEpoch < 0) {
+    throw new Error("director api: fence.authzEpoch is invalid");
+  }
+  if (typeof value.directorAuthorized !== "boolean") throw new Error("director api: fence.directorAuthorized is invalid");
+  return { generation, desiredVersion, authzEpoch, directorAuthorized: value.directorAuthorized };
+}
+
+export class DirectorHttpClient implements DirectorApi {
+  private readonly baseUrl: string;
+  private readonly token: string | undefined;
+  private readonly fetchImpl: typeof fetch;
+  private readonly timeoutMs: number;
+
+  constructor(dependencies: DirectorHttpClientDependencies = {}) {
+    this.baseUrl = (dependencies.baseUrl ?? process.env.DIRECTOR_API_URL ?? "http://127.0.0.1:3000").replace(/\/+$/, "");
+    this.token = dependencies.token ?? process.env.DIRECTOR_API_TOKEN;
+    this.fetchImpl = dependencies.fetch ?? fetch;
+    this.timeoutMs = dependencies.timeoutMs ?? 8_000;
+  }
+
+  private path(ref: ChannelRef, suffix: string): string {
+    return `${this.baseUrl}/internal/director/channels/${encodeURIComponent(ref.workspaceId)}/${encodeURIComponent(ref.channelId)}/${suffix}`;
+  }
+
+  private async request(path: string, init?: RequestInit): Promise<unknown> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const response = await this.fetchImpl(path, {
+        ...init,
+        signal: controller.signal,
+        headers: {
+          "content-type": "application/json",
+          ...(this.token === undefined ? {} : { authorization: `Bearer ${this.token}` }),
+          ...init?.headers,
+        },
+      });
+      if (!response.ok) {
+        // Transport/server errors are retryable; the evaluator treats 4xx-shaped
+        // outcomes as fenced results, which the callers parse explicitly.
+        throw new Error(`director api: ${response.status} ${response.statusText} for ${path}`);
+      }
+      const text = await response.text();
+      return text === "" ? null : JSON.parse(text) as unknown;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async channelState(ref: ChannelRef): Promise<DirectorStateRead> {
+    const value = await this.request(this.path(ref, "state"));
+    if (!isRecord(value)) throw new Error("director api: state response must be an object");
+    if (value.kind === "superseded") return { kind: "superseded", code: "SUPERSEDED" };
+    if (value.kind !== "current") throw new Error("director api: state response kind is invalid");
+    return value as DirectorStateRead;
+  }
+
+  async fence(ref: ChannelRef): Promise<DesiredFence | undefined> {
+    return parseFence(await this.request(this.path(ref, "fence")));
+  }
+
+  async applyProgramSwitch(ref: ChannelRef, body: DirectorApplyRequest): Promise<DirectorApplyResult> {
+    return parseApplyResult(await this.request(this.path(ref, "apply"), { method: "POST", body: JSON.stringify(body) }));
+  }
+
+  async audit(ref: ChannelRef, event: { commandId: string; outcome: string; reason: string }): Promise<void> {
+    await this.request(this.path(ref, "audit"), { method: "POST", body: JSON.stringify(event) });
+  }
+}
diff --git a/apps/scheduler/src/director/ports.ts b/apps/scheduler/src/director/ports.ts
new file mode 100644
index 0000000..413947a
--- /dev/null
+++ b/apps/scheduler/src/director/ports.ts
@@ -0,0 +1,104 @@
+/**
+ * Transport-agnostic port contracts for the auto-director evaluator (WP10
+ * wiring slice).
+ *
+ * The Temporal worker hosts the evaluator workflow and proxies these ports;
+ * the API process implements them. Because the worker runs in the scheduler
+ * package and the implementations in apps/api, the interfaces are declared
+ * with JSON-serializable shapes only (the scheduler cannot compile apps/api
+ * sources), and both sides share the engine's type definitions via relative
+ * imports — the same cross-package pattern apps/api/src/live-monitor/poller
+ * uses for packages/connector-mock-livestream.
+ *
+ * `read`/`fence` return `kind: "superseded"` / `undefined` rather than throwing
+ * so a dead generation never becomes a retryable activity failure loop.
+ */
+import type { AutoDirectorRule, SceneLayout, SwitchPolicy } from "@tactical-media-broadcast-hub/core";
+import type { DirectorOverride, DirectorProgram } from "./engine.js";
+import type { ChannelRef, DesiredFence } from "./director.activity.js";
+
+/**
+ * A channel source with its monitor state resolved for engine consumption.
+ *
+ * Optional fields mirror the engine's DirectorSourceInput exactly: ABSENT, not
+ * null — the engine treats `lastMediaAtMs !== undefined` as "known", so a null
+ * would read as epoch 0 and de-confirm every source as no-media. JSON drops
+ * undefined keys, which keeps the wire form and the engine form identical.
+ */
+export interface DirectorChannelSource {
+  id: string;
+  priority: number;
+  enabled: boolean;
+  autoSelect: boolean;
+  /** Debounced monitor state (LIVE only once confirmed). */
+  state:
+    | "OFFLINE" | "UNKNOWN" | "PROBING" | "STARTING" | "LIVE" | "UNSTABLE" | "ENDING" | "ERROR";
+  /** Monitor row version; absent when no monitor row exists (every read is then a fresh sample). */
+  version?: number;
+  /** `source_monitor_states.state_entered_at` — when the current state was entered. */
+  liveSinceMs?: number;
+  /** Last media-health "media present" instant, for the no-media timeout. */
+  lastMediaAtMs?: number;
+  /** Media-health tier reports failure: de-confirms immediately (§5.2 step 2). */
+  mediaFailed?: boolean;
+}
+
+/** Result of a DirectorStatePort.read: the engine's full input for one channel. */
+export interface DirectorChannelState {
+  kind: "current";
+  desiredVersion: number;
+  authzEpoch: number;
+  generation: string;
+  sources: DirectorChannelSource[];
+  rules: AutoDirectorRule[];
+  policy: SwitchPolicy;
+  fallbackSceneId: string | null;
+  override: DirectorOverride | null;
+  principalPermissions: Record<string, string[]>;
+}
+
+export type DirectorStateRead = DirectorChannelState | { kind: "superseded"; code: "SUPERSEDED" };
+
+/** The read port: everything the evaluator needs for one decision. */
+export interface DirectorStatePort {
+  read(ref: ChannelRef): Promise<DirectorStateRead>;
+}
+
+/** The desired-state port contract, transport-agnostic twin of DesiredStatePort. */
+export interface DesiredStateOperations {
+  fence(ref: ChannelRef): Promise<DesiredFence | undefined>;
+  /** The engine's decision applied as a desired-state write; the director's commandId is the idempotency reference. */
+  apply(command: {
+    ref: ChannelRef;
+    commandId: string;
+    expectedDesiredVersion: number;
+    authzEpoch: number;
+    program: DirectorProgram;
+    layout: SceneLayout;
+    reasons: string[];
+    releaseOverride?: string;
+  }): Promise<{ kind: "applied" | "duplicate"; desiredVersion: number } | { kind: "conflict" }>;
+  audit(ref: ChannelRef, event: { commandId: string; outcome: "SUPERSEDED" | "AUTHZ_REVOKED"; reason: string }): Promise<void>;
+}
+
+/** An HTTP implementation of the API's /director endpoints (see api-side director.service.ts). */
+export interface DirectorApi {
+  channelState(ref: ChannelRef): Promise<DirectorStateRead>;
+  fence(ref: ChannelRef): Promise<DesiredFence | undefined>;
+  applyProgramSwitch(ref: ChannelRef, body: DirectorApplyRequest): Promise<DirectorApplyResult>;
+  audit(ref: ChannelRef, event: { commandId: string; outcome: string; reason: string }): Promise<void>;
+}
+
+export interface DirectorApplyRequest {
+  commandId: string;
+  expectedDesiredVersion: number;
+  authzEpoch: number;
+  program: DirectorProgram;
+  layout: SceneLayout;
+  reasons: string[];
+  releaseOverride?: string;
+}
+
+export type DirectorApplyResult =
+  | { kind: "applied" | "duplicate"; desiredVersion: number }
+  | { kind: "conflict" };
diff --git a/apps/scheduler/src/director/starter.ts b/apps/scheduler/src/director/starter.ts
new file mode 100644
index 0000000..f4cbf3b
--- /dev/null
+++ b/apps/scheduler/src/director/starter.ts
@@ -0,0 +1,33 @@
+import { WorkflowExecutionAlreadyStartedError, type Client } from "@temporalio/client";
+import { WorkflowIdReusePolicy } from "@temporalio/common";
+import type { ChannelRef } from "./director.activity.js";
+
+export function evaluatorWorkflowId(ref: Pick<ChannelRef, "workspaceId" | "channelId">): string {
+  return `auto-director-${ref.workspaceId}-${ref.channelId}`;
+}
+
+export type EnsureOutcome = "started" | "running" | "restarted";
+
+/**
+ * Starts are idempotent hints. A running evaluator is only nudged (it re-reads
+ * state and fences its own generation); a closed one may be started afresh.
+ */
+export async function ensureDirector(client: Client, ref: ChannelRef, taskQueue: string): Promise<EnsureOutcome> {
+  const workflowId = evaluatorWorkflowId(ref);
+  const options = { taskQueue, workflowId, args: [{ ref }] as const, workflowIdReusePolicy: WorkflowIdReusePolicy.ALLOW_DUPLICATE };
+  try {
+    await client.workflow.start("autoDirectorEvaluator", options);
+    return "started";
+  } catch (error) {
+    if (!(error instanceof WorkflowExecutionAlreadyStartedError)) throw error;
+    const handle = client.workflow.getHandle(workflowId);
+    const description = await handle.describe().catch(() => undefined);
+    if (description?.status.name === "RUNNING") {
+      await handle.signal("sourceChanged", { sourceId: "*", version: 0 });
+      return "running";
+    }
+    // Closed between start and describe: one retry; a concurrent starter winning is fine.
+    try { await client.workflow.start("autoDirectorEvaluator", options); return "restarted"; }
+    catch (retryError) { if (retryError instanceof WorkflowExecutionAlreadyStartedError) return "running"; throw retryError; }
+  }
+}
diff --git a/apps/scheduler/src/director/wiring.test.ts b/apps/scheduler/src/director/wiring.test.ts
new file mode 100644
index 0000000..b0d7b08
--- /dev/null
+++ b/apps/scheduler/src/director/wiring.test.ts
@@ -0,0 +1,223 @@
+import { describe, expect, it } from "vitest";
+import { parseDirectorChannels } from "./config.js";
+import { currentChannels, sweepDirectors, directorChannelsFromEnv } from "./discovery.js";
+import { DirectorHttpClient, parseApplyResult, parseFence } from "./http.client.js";
+import { HttpDirectorStatePort, HttpDesiredStatePort, engineSource, engineSnapshot } from "./adapters.js";
+import type { DirectorApi, DirectorChannelSource, DirectorStateRead } from "./ports.js";
+import type { ChannelRef } from "./director.activity.js";
+import { decide } from "./engine.js";
+
+/**
+ * WP10 wiring slice, scheduler side: config parsing, the HTTP port adapters
+ * against a fake API, and the evaluator's discovery sweep. The port-pair
+ * behaviour (state read -> decide -> desired applied) lives in
+ * apps/api/src/director/director.service.test.ts, which imports this
+ * package's engine directly.
+ */
+
+const WS = "0b7c6d50-93a4-4a1e-8e94-93b7e0000001";
+const CH = "0b7c6d50-93a4-4a1e-8e94-93b7e0000002";
+const SRC = "0b7c6d50-93a4-4a1e-8e94-93b7e0000003";
+const RULE = "0b7c6d50-93a4-4a1e-8e94-93b7e0000004";
+
+const rule = {
+  id: RULE, virtualChannelId: CH, priority: 1,
+  condition: { field: "live_source_count" as const, op: ">=" as const, value: 1 },
+  action: { layout: "single" as const, selection: "top_priority" as const },
+};
+const policy = { name: "highest_priority" as const, liveConfirmations: 1, offlineConfirmations: 1, noMediaSeconds: 600, minHoldMs: 0, switchCooldownMs: 0 };
+const document = JSON.stringify([{ workspaceId: WS, channelId: CH, generation: "g1", rules: [rule], policy, fallbackSceneId: null }]);
+
+describe("parseDirectorChannels", () => {
+  it("parses the full document", () => {
+    const channels = parseDirectorChannels(document);
+    expect(channels).toHaveLength(1);
+    expect(channels[0]).toMatchObject({ workspaceId: WS, channelId: CH, generation: "g1", fallbackSceneId: null });
+    expect(channels[0]?.rules).toEqual([rule]);
+    expect(channels[0]?.policy).toEqual(policy);
+  });
+  it("rejects malformed entries with a field path", () => {
+    expect(parseDirectorChannels(undefined)).toEqual([]);
+    expect(parseDirectorChannels("")).toEqual([]);
+    expect(() => parseDirectorChannels("[]{}")).toThrow();
+    expect(() => parseDirectorChannels('{"a":1}')).toThrow(/must be a JSON array/);
+    expect(() => parseDirectorChannels('[{"channelId":"x"}]')).toThrow(/channelId must be a UUID/);
+    expect(() => parseDirectorChannels(`[{"workspaceId":"${WS}","channelId":"x","generation":"g"}]`)).toThrow(/channelId must be a UUID/);
+    expect(() => parseDirectorChannels(`[{"workspaceId":"${WS}","channelId":"${CH}","generation":""}]`)).toThrow(/generation/);
+    expect(() => parseDirectorChannels(`[{"workspaceId":"${WS}","channelId":"${CH}","generation":"g","rules":[{"id":"bad"}]}]`)).toThrow(/rules\[0\]\.id/);
+    expect(() => parseDirectorChannels(`[{"workspaceId":"${WS}","channelId":"${CH}","generation":"g","policy":{"name":"nope"}}]`)).toThrow(/policy\.name/);
+  });
+  it("reads from env and defaults to none", () => {
+    expect(directorChannelsFromEnv({})).toEqual([]);
+    expect(directorChannelsFromEnv({ DIRECTOR_CHANNELS: document })).toHaveLength(1);
+  });
+});
+
+describe("discovery", () => {
+  it("keeps the latest declared entry per channel", () => {
+    const channels = parseDirectorChannels(`[${document.slice(1, -1)},${document.slice(1, -1).replace('"g1"', '"g2"')}]`);
+    expect(channels).toHaveLength(2);
+    expect(currentChannels(channels)).toHaveLength(1);
+    expect(currentChannels(channels)[0]?.generation).toBe("g2");
+  });
+  it("ensures one evaluator per configured channel and swallows start failures", async () => {
+    const channels = parseDirectorChannels(document);
+    const workflowIds: string[] = [];
+    const clientFor = (behaviour: () => Promise<"started" | "running" | "restarted" | "failed">): Parameters<typeof sweepDirectors>[0] =>
+      ({
+        workflow: {
+          start: async (_name: string, options: { workflowId: string }) => {
+            workflowIds.push(options.workflowId);
+            return behaviour();
+          },
+          getHandle: () => ({ describe: async () => ({ status: { name: "RUNNING" } }), signal: async () => undefined }),
+        },
+      }) as unknown as Parameters<typeof sweepDirectors>[0];
+    // start succeeds: one evaluator ensured
+    const started = await sweepDirectors(clientFor(async () => "started"), { taskQueue: "tmbh-publishing", channels });
+    expect(started).toEqual({ started: 1, running: 0, restarted: 0 });
+    // every Temporal failure is contained: the sweep reports zero and lives on
+    const failing = await sweepDirectors(clientFor(async () => { throw new Error("temporal down"); }), { taskQueue: "q", channels });
+    expect(failing).toEqual({ started: 0, running: 0, restarted: 0 });
+    expect(workflowIds).toEqual([`auto-director-${WS}-${CH}`, `auto-director-${WS}-${CH}`]);
+  });
+});
+
+/** In-memory DirectorApi double used by the adapter tests. */
+function fakeApi(over: Partial<DirectorApi> = {}): DirectorApi & { requests: string[] } {
+  const requests: string[] = [];
+  const current: DirectorStateRead = {
+    kind: "current", desiredVersion: 4, authzEpoch: 7, generation: "g1",
+    sources: [{ id: SRC, priority: 50, enabled: true, autoSelect: true, state: "LIVE", version: 3 }],
+    rules: [rule], policy, fallbackSceneId: null, override: null, principalPermissions: {},
+  };
+  return {
+    requests,
+    channelState: async (ref) => { requests.push(`state:${ref.channelId}`); return current; },
+    fence: async (ref) => { requests.push(`fence:${ref.channelId}`); return { generation: "g1", desiredVersion: 4, authzEpoch: 7, directorAuthorized: true }; },
+    applyProgramSwitch: async (ref, body) => { requests.push(`apply:${body.commandId}`); return { kind: "applied", desiredVersion: 5 }; },
+    audit: async (ref, event) => { requests.push(`audit:${event.outcome}`); },
+    ...over,
+  };
+}
+
+describe("port adapters", () => {
+  const ref: ChannelRef = { workspaceId: WS, channelId: CH, generation: "g1" };
+
+  it("converts transport sources without inventing optional engine fields", () => {
+    const source: DirectorChannelSource = { id: SRC, priority: 50, enabled: true, autoSelect: true, state: "LIVE" };
+    const input = engineSource(source);
+    expect(input).toEqual({ id: SRC, priority: 50, enabled: true, autoSelect: true, state: "LIVE" });
+    expect("version" in input).toBe(false);
+    expect("lastMediaAtMs" in input).toBe(false);
+    expect("mediaFailed" in input).toBe(false);
+  });
+
+  it("state read feeds decide() unchanged (engine input round-trip)", async () => {
+    const api = fakeApi();
+    const port = new HttpDirectorStatePort(api);
+    const snapshot = await port.read(ref);
+    if (snapshot.kind !== "current") throw new Error("expected current");
+    expect(snapshot.sources[0]).toEqual({ id: SRC, priority: 50, enabled: true, autoSelect: true, state: "LIVE", version: 3 });
+    const decision = decide({ sources: snapshot.sources, rules: snapshot.rules, policy: snapshot.policy, now: 1_000 });
+    expect(decision.program).toEqual({ kind: "sources", sourceIds: [SRC] });
+  });
+
+  it("engineSnapshot maps a transport read to the engine snapshot", () => {
+    const read = { kind: "current" as const, desiredVersion: 4, authzEpoch: 7, generation: "g1",
+      sources: [{ id: SRC, priority: 50, enabled: true, autoSelect: true, state: "LIVE", version: 3 } as DirectorChannelSource],
+      rules: [rule], policy, fallbackSceneId: null, override: null, principalPermissions: {} };
+    expect(engineSnapshot(read)).toMatchObject({ kind: "current", desiredVersion: 4, authzEpoch: 7 });
+  });
+
+  it("desired-state port forwards fence/apply/audit with the commandId as idempotency key", async () => {
+    const api = fakeApi();
+    const port = new HttpDesiredStatePort(api);
+    expect(await port.fence(ref)).toMatchObject({ generation: "g1", desiredVersion: 4 });
+    expect(await port.findCommand(ref, "cmd")).toBeUndefined();
+    const outcome = await port.writeProgram({
+      ref, commandId: `${CH}:1`, expectedDesiredVersion: 4, authzEpoch: 7,
+      program: { kind: "sources", sourceIds: [SRC] }, layout: "single", reasons: ["rule"],
+    });
+    expect(outcome).toEqual({ kind: "applied", desiredVersion: 5 });
+    await port.audit(ref, { commandId: "c", outcome: "SUPERSEDED", reason: "generation" });
+    expect(api.requests).toEqual([`fence:${CH}`, `apply:${CH}:1`, "audit:SUPERSEDED"]);
+  });
+});
+
+describe("response parsers (fail closed on malformed API replies)", () => {
+  it("parseFence accepts a fence or absence and rejects junk", () => {
+    expect(parseFence(null)).toBeUndefined();
+    expect(parseFence({ generation: "g1", desiredVersion: 4, authzEpoch: 7, directorAuthorized: true })).toEqual({ generation: "g1", desiredVersion: 4, authzEpoch: 7, directorAuthorized: true });
+    expect(() => parseFence({})).toThrow(/generation/);
+    expect(() => parseFence({ generation: "g1", desiredVersion: "4", authzEpoch: 7, directorAuthorized: true })).toThrow(/desiredVersion/);
+    expect(() => parseFence({ generation: "g1", desiredVersion: 4, authzEpoch: 7, directorAuthorized: "yes" })).toThrow(/directorAuthorized/);
+  });
+  it("parseApplyResult accepts applied/duplicate/conflict and rejects junk", () => {
+    expect(parseApplyResult({ kind: "applied", desiredVersion: 5 })).toEqual({ kind: "applied", desiredVersion: 5 });
+    expect(parseApplyResult({ kind: "duplicate", desiredVersion: 5 })).toEqual({ kind: "duplicate", desiredVersion: 5 });
+    expect(parseApplyResult({ kind: "conflict" })).toEqual({ kind: "conflict" });
+    expect(() => parseApplyResult({ kind: "applied" })).toThrow(/desiredVersion/);
+    expect(() => parseApplyResult({ kind: "nope" })).toThrow(/kind/);
+    expect(() => parseApplyResult("x")).toThrow();
+  });
+});
+
+describe("DirectorHttpClient", () => {
+  const ref: ChannelRef = { workspaceId: WS, channelId: CH, generation: "g1" };
+
+  function harness(): { client: DirectorHttpClient; seen: Array<{ path: string; init: RequestInit | undefined }> } {
+    const seen: Array<{ path: string; init: RequestInit | undefined }> = [];
+    const client = new DirectorHttpClient({
+      baseUrl: "http://api.test/",
+      token: "sekrit",
+      fetch: async (input, init) => {
+        seen.push({ path: String(input), init });
+        const path = String(input);
+        if (path.endsWith("/state")) return new Response(JSON.stringify({ kind: "superseded", code: "SUPERSEDED" }), { status: 200 });
+        if (path.endsWith("/fence")) return new Response(JSON.stringify({ generation: "g1", desiredVersion: 4, authzEpoch: 7, directorAuthorized: true }), { status: 200 });
+        if (path.endsWith("/apply")) return new Response(JSON.stringify({ kind: "applied", desiredVersion: 5 }), { status: 200 });
+        return new Response(null, { status: 204 });
+      },
+    });
+    return { client, seen };
+  }
+
+  it("routes to the internal endpoints with the bearer token and validates replies", async () => {
+    const { client, seen } = harness();
+    expect(await client.channelState(ref)).toEqual({ kind: "superseded", code: "SUPERSEDED" });
+    expect(await client.fence(ref)).toMatchObject({ generation: "g1" });
+    expect(await client.applyProgramSwitch(ref, {
+      commandId: "c1", expectedDesiredVersion: 4, authzEpoch: 7,
+      program: { kind: "sources", sourceIds: [SRC] }, layout: "single", reasons: ["r"],
+    })).toEqual({ kind: "applied", desiredVersion: 5 });
+    await client.audit(ref, { commandId: "c1", outcome: "SUPERSEDED", reason: "gen" });
+    expect(seen.map((entry) => entry.path)).toEqual([
+      `http://api.test/internal/director/channels/${WS}/${CH}/state`,
+      `http://api.test/internal/director/channels/${WS}/${CH}/fence`,
+      `http://api.test/internal/director/channels/${WS}/${CH}/apply`,
+      `http://api.test/internal/director/channels/${WS}/${CH}/audit`,
+    ]);
+    for (const entry of seen) {
+      expect((entry.init?.headers as Record<string, string>).authorization).toBe("Bearer sekrit");
+      expect((entry.init?.headers as Record<string, string>)["content-type"]).toBe("application/json");
+    }
+  });
+
+  it("surfaces non-2xx as transport errors (retryable by Temporal)", async () => {
+    const client = new DirectorHttpClient({
+      baseUrl: "http://api.test", fetch: async () => new Response("nope", { status: 503, statusText: "Service Unavailable" }),
+    });
+    await expect(client.channelState(ref)).rejects.toThrow(/503/);
+  });
+
+  it("aborts a slow API within the timeout budget", async () => {
+    const client = new DirectorHttpClient({
+      baseUrl: "http://api.test", timeoutMs: 20,
+      fetch: async (_input, init) => new Promise((_resolve, reject) => {
+        init?.signal?.addEventListener("abort", () => reject(new Error("aborted")));
+      }),
+    });
+    await expect(client.fence(ref)).rejects.toThrow();
+  });
+});
diff --git a/apps/scheduler/src/publishing.integration.test.ts b/apps/scheduler/src/publishing.integration.test.ts
new file mode 100644
index 0000000..d454e3c
--- /dev/null
+++ b/apps/scheduler/src/publishing.integration.test.ts
@@ -0,0 +1,80 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Pool } from "pg";
+import { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import { createMastodonConnector } from "@tactical-media-broadcast-hub/connector-mastodon";
+import { createTelegramConnector } from "@tactical-media-broadcast-hub/connector-telegram";
+import { Vault, createPublishingCredentialAccessor } from "@tactical-media-broadcast-hub/connector-runtime";
+import { PublishingExecutionRepository, canonicalPostHash, assertPublishingSchema, type AttemptRef } from "@tactical-media-broadcast-hub/publishing-execution";
+import { PublishActivity } from "./activities/publish.activity.js";
+const appUrl = process.env.PUBLISHING_IT_DATABASE_URL;
+const ownerUrl = process.env.PUBLISHING_IT_SUPER_DATABASE_URL;
+describe.skipIf(!appUrl || !ownerUrl)("TEST MODE real connectors with fenced DB activity", () => {
+  let pool: Pool; let owner: Pool; let repository: PublishingExecutionRepository; let workspaceId: string; let userId: string;
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: appUrl, max: 12 }); owner = new Pool({ connectionString: ownerUrl });
+    await assertPublishingSchema(pool); repository = new PublishingExecutionRepository(pool);
+    workspaceId = String((await owner.query("INSERT INTO workspaces(name,slug) VALUES('Scheduler Test',$1) RETURNING id", [`scheduler-sol-${Date.now()}`])).rows[0].id);
+    userId = String((await owner.query("INSERT INTO users(external_id,username,display_name) VALUES($1,$1,'Scheduler Test') RETURNING id", [`scheduler-sol-${Date.now()}`])).rows[0].id);
+    await owner.query("INSERT INTO memberships(workspace_id,user_id,role,status) VALUES($1,$2,'Owner','active')", [workspaceId, userId]);
+  });
+  afterAll(async () => {
+    if (workspaceId) await owner.query("DELETE FROM workspaces WHERE id=$1", [workspaceId]);
+    if (userId) await owner.query("DELETE FROM users WHERE id=$1", [userId]);
+    await pool?.end(); await owner?.end();
+  });
+  async function fixture(provider: "mastodon" | "telegram"): Promise<AttemptRef> {
+    const fields = provider === "mastodon" ? { instanceUrl: "https://social.test" } : { channelId: "-10042" };
+    const connectionId = String((await owner.query("INSERT INTO connections(workspace_id,provider,channel_id,fields) VALUES($1,$2,$3,$4) RETURNING id", [workspaceId, provider, `channel-${provider}`, fields])).rows[0].id);
+    const sealed = await new Vault().seal(workspaceId, connectionId, Buffer.from(JSON.stringify(provider === "mastodon" ? { access_token: "canary-mastodon-secret" } : { botToken: "canary-telegram-secret" })));
+    await owner.query("INSERT INTO credentials(workspace_id,connection_id,kind,ciphertext,key_version) VALUES($1,$2,'connector-oauth',$3,$4)", [workspaceId, connectionId, sealed.ciphertext, sealed.keyVersion]);
+    const post = { text: "[TMBH TEST MODE] hello", mediaAssetIds: [], visibility: "public", providerMetadata: { connectionId } };
+    const draftId = String((await owner.query("INSERT INTO drafts(workspace_id,author_user_id,post,state,reviewer_user_id,approved_revision,approved_hash,approved_at) VALUES($1,$2,$3,'approved',$2,1,$4,now()) RETURNING id", [workspaceId, userId, post, canonicalPostHash(post)])).rows[0].id);
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN"); await client.query("SELECT set_config('app.workspace_id',$1,true)", [workspaceId]);
+      const attempt = await repository.scheduleAttempt(client, { workspaceId, draftId, connectionId, scheduledByUserId: userId, requiredPermission: "publication.publish", publishAt: new Date(Date.now() - 1000) });
+      await client.query("COMMIT"); return { workspaceId, scheduleId: attempt.scheduleId, generation: attempt.generation, idempotencyKey: attempt.idempotencyKey };
+    } catch (error) { await client.query("ROLLBACK"); throw error; } finally { client.release(); }
+  }
+  for (const provider of ["mastodon", "telegram"] as const) it(`publishes ${provider} through exact APV1 credentials, gate, receipt and one canonical Publication`, async () => {
+    const ref = await fixture(provider); let sends = 0; let observedKey: string | null = null;
+    const fetchImpl: typeof fetch = async (input, init) => {
+      const url = new URL(String(input));
+      if (url.pathname.endsWith("/getChat")) return new Response(JSON.stringify({ ok: true, result: { id: -10042, type: "channel" } }), { headers: { "content-type": "application/json" } });
+      sends += 1;
+      expect(init?.method).toBe("POST");
+      if (provider === "mastodon") {
+        expect(url.pathname).toBe("/api/v1/statuses"); expect(new Headers(init?.headers).get("authorization")).toBe("Bearer canary-mastodon-secret");
+        observedKey = new Headers(init?.headers).get("idempotency-key");
+        return new Response(JSON.stringify({ id: "10942", created_at: new Date().toISOString(), url: "https://social.test/@test/10942", visibility: "public" }), { headers: { "content-type": "application/json" } });
+      }
+      expect(url.pathname).toBe("/botcanary-telegram-secret/sendMessage");
+      expect(JSON.parse(String(init?.body))).toMatchObject({ chat_id: "-10042" });
+      return new Response(JSON.stringify({ ok: true, result: { message_id: 42, date: Math.floor(Date.now()/1000), chat: { id: -10042 } } }), { headers: { "content-type": "application/json" } });
+    };
+    const registry = new ConnectorRegistry(); const options = { credentials: createPublishingCredentialAccessor(pool), fetchImpl, requestsPerSecond: 1000 };
+    registry.register(createMastodonConnector(options)); registry.register(createTelegramConnector(options));
+    const activity = new PublishActivity(repository, registry, () => ({ heartbeat: () => undefined }));
+    const first = await activity.publishScheduled(ref); const second = await activity.publishScheduled(ref);
+    expect(first.kind).toBe("done"); expect(second).toEqual(first); expect(sends).toBe(1);
+    if (provider === "mastodon") expect(observedKey).toBe(ref.idempotencyKey);
+    const evidence = await owner.query("SELECT p.provider_metadata, a.dispatch_count, (SELECT count(*)::int FROM publications WHERE idempotency_key=$1) AS publications, (SELECT count(*)::int FROM publishing_receipts WHERE attempt_id=a.id) AS receipts FROM publishing_attempts a JOIN publications p ON p.idempotency_key=a.idempotency_key WHERE a.idempotency_key=$1", [ref.idempotencyKey]);
+    expect(evidence.rows[0]).toMatchObject({ dispatch_count: 1, publications: 1, receipts: 1 });
+    expect(JSON.stringify({ first, second, evidence: evidence.rows })).not.toContain("canary-");
+  });
+  it("retains accepted-response-loss as unknown with no Telegram resend", async () => {
+    const ref = await fixture("telegram"); let sends = 0;
+    const fetchImpl: typeof fetch = async (input) => {
+      const url = new URL(String(input));
+      if (url.pathname.endsWith("/getChat")) return new Response(JSON.stringify({ ok: true, result: { id: -10042, type: "channel" } }));
+      expect(url.pathname).toBe("/botcanary-telegram-secret/sendMessage"); sends += 1;
+      throw new Error("TEST_RESPONSE_LOST_AFTER_ACCEPT");
+    };
+    const registry = new ConnectorRegistry(); registry.register(createTelegramConnector({ credentials: createPublishingCredentialAccessor(pool), fetchImpl, requestsPerSecond: 1000 }));
+    const activity = new PublishActivity(repository, registry, () => ({ heartbeat: () => undefined }));
+    await expect(activity.publishScheduled(ref)).resolves.toMatchObject({ kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" });
+    await expect(activity.publishScheduled(ref)).resolves.toMatchObject({ kind: "unknown" });
+    expect(sends).toBe(1);
+    expect((await owner.query("SELECT count(*)::int AS n FROM publications WHERE idempotency_key=$1", [ref.idempotencyKey])).rows[0]?.n).toBe(0);
+  });
+});
diff --git a/apps/scheduler/src/worker.test.ts b/apps/scheduler/src/worker.test.ts
new file mode 100644
index 0000000..6ece4b7
--- /dev/null
+++ b/apps/scheduler/src/worker.test.ts
@@ -0,0 +1,20 @@
+import { describe, expect, it, vi } from "vitest";
+import { Client, WorkflowExecutionAlreadyStartedError } from "@temporalio/client";
+import { WorkflowIdReusePolicy } from "@temporalio/common";
+import { sweepDue } from "./worker.js";
+const due = { workspaceId: "workspace", scheduleId: "schedule", generation: "1", idempotencyKey: "key", publishAt: new Date(), evidenceOnly: false };
+describe("durable discovery", () => {
+  it("passes only fenced identifiers and uses a separate receipt recovery workflow", async () => {
+    const start = vi.fn(async () => ({}));
+    await sweepDue({ listDue: async () => [{ ...due, evidenceOnly: true }] }, { workflow: { start } } as unknown as Client);
+    expect(start).toHaveBeenCalledWith("scheduledPublish", expect.objectContaining({ workflowId: "scheduled-publication-key-receipt", args: [{ workspaceId: "workspace", scheduleId: "schedule", generation: "1", idempotencyKey: "key" }] }));
+  });
+  for (const status of ["COMPLETED", "RUNNING", "FAILED"]) it(`describes ${status} before allowing recovery`, async () => {
+    const start = vi.fn().mockRejectedValueOnce(new WorkflowExecutionAlreadyStartedError("existing", "scheduled-publication-key", "scheduledPublish")).mockResolvedValue({});
+    const describeWorkflow = vi.fn(async () => ({ status: { name: status } }));
+    await sweepDue({ listDue: async () => [due] }, { workflow: { start, getHandle: () => ({ describe: describeWorkflow }) } } as unknown as Client);
+    expect(describeWorkflow).toHaveBeenCalledTimes(1);
+    expect(start).toHaveBeenCalledTimes(status === "FAILED" ? 2 : 1);
+    if (status === "FAILED") expect(start.mock.calls[1]?.[1]).toMatchObject({ workflowIdReusePolicy: WorkflowIdReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY });
+  });
+});
diff --git a/apps/scheduler/src/worker.ts b/apps/scheduler/src/worker.ts
new file mode 100644
index 0000000..77e2512
--- /dev/null
+++ b/apps/scheduler/src/worker.ts
@@ -0,0 +1,106 @@
+import { Client, Connection, WorkflowExecutionAlreadyStartedError } from "@temporalio/client";
+import { WorkflowIdReusePolicy } from "@temporalio/common";
+import { NativeConnection, Worker } from "@temporalio/worker";
+import { Pool } from "pg";
+import { createServer } from "node:http";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+import pino from "pino";
+import { createPublishingRegistry } from "@tactical-media-broadcast-hub/connector-runtime";
+import { PublishingExecutionRepository, assertPublishingSchema, type AttemptRef } from "@tactical-media-broadcast-hub/publishing-execution";
+import { PublishActivity } from "./activities/publish.activity.js";
+import { DirectorActivity } from "./director/director.activity.js";
+import { DirectorHttpClient } from "./director/http.client.js";
+import { HttpDirectorStatePort, HttpDesiredStatePort } from "./director/adapters.js";
+import { directorChannelsFromEnv, sweepDirectors } from "./director/discovery.js";
+import { DispatchGateService } from "./activities/dispatch-gate.js";
+
+const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
+const address = process.env.TEMPORAL_ADDRESS ?? "localhost:7233";
+const namespace = process.env.TEMPORAL_NAMESPACE ?? "default";
+const taskQueue = process.env.TEMPORAL_TASK_QUEUE ?? "tmbh-publishing";
+
+/** Starts are repair hints. Only repository claim/gate can authorize a send. */
+export async function sweepDue(repository: Pick<PublishingExecutionRepository, "listDue">, client: Client): Promise<void> {
+  const due = await repository.listDue(100);
+  for (let offset = 0; offset < due.length; offset += 4) {
+    await Promise.all(due.slice(offset, offset + 4).map(async (item) => {
+      const ref: AttemptRef = { workspaceId: item.workspaceId, scheduleId: item.scheduleId, generation: item.generation, idempotencyKey: item.idempotencyKey };
+      const workflowId = `scheduled-publication-${ref.idempotencyKey}${item.evidenceOnly ? "-receipt" : ""}`;
+      try {
+        await client.workflow.start("scheduledPublish", { taskQueue, workflowId, args: [ref], workflowIdReusePolicy: WorkflowIdReusePolicy.REJECT_DUPLICATE });
+      } catch (error) {
+        if (error instanceof WorkflowExecutionAlreadyStartedError) {
+          // Closed terminal workflows stay closed. A failed workflow can be
+          // repaired on the next sweep only while DB discovery still allows it.
+          const description = await client.workflow.getHandle(workflowId).describe().catch(() => undefined);
+          if (description?.status.name === "FAILED") {
+            try { await client.workflow.start("scheduledPublish", { taskQueue, workflowId, args: [ref], workflowIdReusePolicy: WorkflowIdReusePolicy.ALLOW_DUPLICATE_FAILED_ONLY }); }
+            catch (retryError) { if (!(retryError instanceof WorkflowExecutionAlreadyStartedError)) logger.warn({ code: "WORKFLOW_RECOVERY_FAILED", scheduleId: item.scheduleId }, "scheduler recovery failed"); }
+          }
+          return;
+        }
+        logger.warn({ code: "WORKFLOW_START_FAILED", scheduleId: item.scheduleId }, "scheduler sweep failed");
+      }
+    }));
+  }
+}
+export async function main(): Promise<void> {
+  if (!process.env.SCHEDULER_DATABASE_URL) throw new Error("SCHEDULER_DATABASE_URL is required");
+  const pool = new Pool({ connectionString: process.env.SCHEDULER_DATABASE_URL, max: 20 });
+  let native: NativeConnection | undefined;
+  let connection: Connection | undefined;
+  let worker: Worker | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let sweeping: Promise<void> | undefined;
+  let closing = false;
+  let ready = false;
+  const health = createServer((_request, response) => { response.writeHead(ready ? 200 : 503, { "content-type": "application/json" }); response.end(JSON.stringify({ ready })); });
+  const stop = (): void => { closing = true; ready = false; clearTimeout(timer); if (worker?.getState() === "RUNNING") worker.shutdown(); };
+  process.once("SIGTERM", stop); process.once("SIGINT", stop);
+  try {
+    await assertPublishingSchema(pool);
+    const repository = new PublishingExecutionRepository(pool);
+    const registry = createPublishingRegistry(pool);
+    native = await NativeConnection.connect({ address });
+    connection = await Connection.connect({ address });
+    const temporal = new Client({ connection, namespace });
+    const activity = new PublishActivity(repository, registry, undefined, new DispatchGateService(pool));
+    const directorApi = new DirectorHttpClient();
+    const director = new DirectorActivity(new HttpDirectorStatePort(directorApi), new HttpDesiredStatePort(directorApi));
+    const channels = directorChannelsFromEnv();
+    worker = await Worker.create({ connection: native, namespace, taskQueue,
+      workflowsPath: fileURLToPath(new URL("./workflows/index.js", import.meta.url)),
+      activities: {
+        publishScheduled: activity.publishScheduled.bind(activity),
+        readChannelState: director.readChannelState.bind(director),
+        applyProgramSwitch: director.applyProgramSwitch.bind(director),
+      }, maxConcurrentActivityTaskExecutions: 4 });
+    await new Promise<void>((resolveListen, reject) => { health.once("error", reject); health.listen(Number(process.env.SCHEDULER_HEALTH_PORT ?? 8081), resolveListen); });
+    const sweep = async (): Promise<void> => {
+      if (closing) return;
+      try {
+        await assertPublishingSchema(pool); await connection?.workflowService.getSystemInfo({}); await sweepDue(repository, temporal);
+        const directors = await sweepDirectors(temporal, { taskQueue, channels });
+        if (directors.started + directors.restarted > 0) logger.info(directors, "director evaluators ensured");
+        ready = !closing;
+      }
+      catch { ready = false; logger.warn({ code: "DISCOVERY_UNAVAILABLE" }, "scheduler discovery unavailable"); }
+      if (!closing) timer = setTimeout(() => { sweeping = sweep(); }, 5000 + Math.floor(Math.random() * 500));
+    };
+    sweeping = sweep();
+    await sweeping;
+    if (ready) logger.info({ namespace, taskQueue }, "scheduler sweep started");
+    const running = worker.run();
+    if (closing) stop();
+    await running;
+  } finally {
+    stop(); await sweeping;
+    process.off("SIGTERM", stop); process.off("SIGINT", stop);
+    if (health.listening) await new Promise<void>((done) => health.close(() => done()));
+    await connection?.close(); await native?.close(); await pool.end();
+  }
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  void main().catch(() => { logger.error({ code: "SCHEDULER_STARTUP_FAILED" }, "scheduler failed readiness"); process.exitCode = 1; });
+}
diff --git a/apps/scheduler/src/workflows/index.ts b/apps/scheduler/src/workflows/index.ts
new file mode 100644
index 0000000..9026997
--- /dev/null
+++ b/apps/scheduler/src/workflows/index.ts
@@ -0,0 +1,8 @@
+/**
+ * Workflow entrypoints the scheduler worker registers. One file keeps the
+ * worker's workflow bundle small: publish.workflow.js stays the only publishing
+ * entrypoint, and the director evaluator joins it without a second Worker
+ * instance. Both are pure re-exports so bundling stays stable.
+ */
+export * from "./publish.workflow.js";
+export * from "../director/evaluator.workflow.js";
diff --git a/apps/scheduler/src/workflows/publish.workflow.ts b/apps/scheduler/src/workflows/publish.workflow.ts
new file mode 100644
index 0000000..3c27b18
--- /dev/null
+++ b/apps/scheduler/src/workflows/publish.workflow.ts
@@ -0,0 +1,14 @@
+import { proxyActivities, sleep } from "@temporalio/workflow";
+import type { AttemptRef } from "@tactical-media-broadcast-hub/publishing-execution";
+import type { PublishActivity, ActivityOutcome } from "../activities/publish.activity.js";
+const { publishScheduled } = proxyActivities<Pick<PublishActivity, "publishScheduled">>({
+  startToCloseTimeout: "60 seconds", heartbeatTimeout: "10 seconds",
+  retry: { initialInterval: "1 second", maximumInterval: "30 seconds", maximumAttempts: 5 },
+});
+export async function scheduledPublish(ref: AttemptRef): Promise<ActivityOutcome> {
+  for (;;) {
+    const outcome = await publishScheduled(ref);
+    if (outcome.kind !== "wait") return outcome;
+    await sleep(Math.max(1000, Date.parse(outcome.until) - Date.now()));
+  }
+}
diff --git a/apps/scheduler/tsconfig.json b/apps/scheduler/tsconfig.json
new file mode 100644
index 0000000..bd8a252
--- /dev/null
+++ b/apps/scheduler/tsconfig.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "rootDir": "src"
+  },
+  "include": [
+    "src"
+  ]
+}
diff --git a/apps/web/next-env.d.ts b/apps/web/next-env.d.ts
new file mode 100644
index 0000000..40c3d68
--- /dev/null
+++ b/apps/web/next-env.d.ts
@@ -0,0 +1,5 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
diff --git a/apps/web/next.config.mjs b/apps/web/next.config.mjs
new file mode 100644
index 0000000..fbb13fe
--- /dev/null
+++ b/apps/web/next.config.mjs
@@ -0,0 +1,13 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  reactStrictMode: true,
+  async redirects() {
+    return [{ source: "/", destination: "/streams", permanent: false }];
+  },
+  async rewrites() {
+    const api = (process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3000").replace(/\/$/, "");
+    return [{ source: "/media-control/preview/:path*", destination: `${api}/media-control/preview/:path*` }];
+  },
+};
+
+export default nextConfig;
diff --git a/apps/web/package.json b/apps/web/package.json
new file mode 100644
index 0000000..0472028
--- /dev/null
+++ b/apps/web/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@tactical-media-broadcast-hub/web",
+  "private": true,
+  "version": "0.1.0",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:^",
+    "@tailwindcss/postcss": "^4.3.3",
+    "@tanstack/react-virtual": "^3.14.13",
+    "@tiptap/extension-character-count": "^3.31.4",
+    "@tiptap/extension-placeholder": "^3.31.4",
+    "@tiptap/react": "^3.31.4",
+    "@tiptap/starter-kit": "^3.31.4",
+    "cmdk": "^1.1.1",
+    "next": "^14.2.5",
+    "postcss": "^8.5.29",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tailwindcss": "^4.3.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "playwright": "^1.63.0",
+    "typescript": "^5.5.4"
+  }
+}
diff --git a/apps/web/postcss.config.mjs b/apps/web/postcss.config.mjs
new file mode 100644
index 0000000..a9b5c43
--- /dev/null
+++ b/apps/web/postcss.config.mjs
@@ -0,0 +1 @@
+export default { plugins: { "@tailwindcss/postcss": {} } };
diff --git a/apps/web/public/brand/empty-state.svg b/apps/web/public/brand/empty-state.svg
new file mode 100644
index 0000000..6dc6b6f
--- /dev/null
+++ b/apps/web/public/brand/empty-state.svg
@@ -0,0 +1,11 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="200" height="200" viewBox="0 0 1700 1700">
+  <g transform="rotate(-17.5 850 850)" opacity="0.25">
+    <circle cx="850" cy="850" r="350" fill="none" stroke="#FF1610" stroke-width="60" stroke-linecap="round"/>
+    <path d="M 850 405 L 464.77 1269.52 M 850 405 L 1235.23 1269.52 M 345 850 L 1355 850"
+          fill="none" stroke="#FF1610" stroke-width="75" stroke-linecap="round" stroke-linejoin="round"/>
+  </g>
+  <g opacity="0.6">
+    <polygon points="1450,850 1550,810 1550,890" fill="#FF1610"/>
+    <line x1="1280" y1="850" x2="1470" y2="850" stroke="#FF1610" stroke-width="30" stroke-linecap="round"/>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/favicon.svg b/apps/web/public/brand/favicon.svg
new file mode 100644
index 0000000..cef6a31
--- /dev/null
+++ b/apps/web/public/brand/favicon.svg
@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <g transform="rotate(-17.5 850 850)">
+    <circle cx="850" cy="850" r="350" fill="none" stroke="#FF1610" stroke-width="74" stroke-linecap="round"/>
+    <path d="M 850 405 L 464.77 1269.52 M 850 405 L 1235.23 1269.52 M 345 850 L 1355 850"
+          fill="none" stroke="#FF1610" stroke-width="88" stroke-linecap="round" stroke-linejoin="round"/>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/hero.png b/apps/web/public/brand/hero.png
new file mode 100644
index 0000000..521a713
Binary files /dev/null and b/apps/web/public/brand/hero.png differ
diff --git a/apps/web/public/brand/icon-bluesky.svg b/apps/web/public/brand/icon-bluesky.svg
new file mode 100644
index 0000000..7295511
--- /dev/null
+++ b/apps/web/public/brand/icon-bluesky.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Bluesky</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 350 450 Q 400 350 500 400 L 600 480 L 700 400 Q 800 350 850 450 Q 850 550 750 650 L 600 780 L 450 650 Q 350 550 350 450 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-discord.svg b/apps/web/public/brand/icon-discord.svg
new file mode 100644
index 0000000..cf2d999
--- /dev/null
+++ b/apps/web/public/brand/icon-discord.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Discord</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 450 450 Q 550 400 600 400 Q 650 400 750 450 L 800 500 Q 850 600 800 700 L 750 750 L 700 700 L 650 720 L 550 720 L 500 700 L 450 750 L 400 700 Q 350 600 400 500 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linejoin="round"/><circle cx="520" cy="570" r="18" fill="#FF1610"/><circle cx="680" cy="570" r="18" fill="#FF1610"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-facebook.svg b/apps/web/public/brand/icon-facebook.svg
new file mode 100644
index 0000000..2359872
--- /dev/null
+++ b/apps/web/public/brand/icon-facebook.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Facebook</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 500 450 L 500 550 L 450 550 L 450 650 L 500 650 L 500 850 L 600 850 L 600 650 L 680 650 L 700 550 L 600 550 L 600 480 Q 600 450 630 450 L 700 450 L 700 380 L 620 380 Q 500 380 500 450 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-instagram.svg b/apps/web/public/brand/icon-instagram.svg
new file mode 100644
index 0000000..edfe6bd
--- /dev/null
+++ b/apps/web/public/brand/icon-instagram.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Instagram</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <rect x="350" y="350" width="500" height="500" rx="120" fill="none" stroke="#FF1610" stroke-width="35"/><circle cx="600" cy="600" r="130" fill="none" stroke="#FF1610" stroke-width="35"/><circle cx="770" cy="430" r="25" fill="#FF1610"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-linkedin.svg b/apps/web/public/brand/icon-linkedin.svg
new file mode 100644
index 0000000..7797174
--- /dev/null
+++ b/apps/web/public/brand/icon-linkedin.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Linkedin</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <rect x="350" y="350" width="500" height="100" rx="20" fill="none" stroke="#FF1610" stroke-width="35"/><line x1="400" y1="500" x2="400" y2="750" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><line x1="500" y1="500" x2="500" y2="750" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><path d="M 500 500 Q 550 450 600 500 L 600 600 Q 650 550 700 600 Q 750 650 700 700 Q 650 750 500 750" fill="none" stroke="#FF1610" stroke-width="35" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-mastodon.svg b/apps/web/public/brand/icon-mastodon.svg
new file mode 100644
index 0000000..2d92c11
--- /dev/null
+++ b/apps/web/public/brand/icon-mastodon.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Mastodon</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 400 500 L 400 700 Q 400 780 480 780 L 520 780 Q 560 780 560 740 L 560 560 Q 560 540 580 540 Q 600 540 600 560 L 600 740 Q 600 780 640 780 L 680 780 Q 760 780 760 700 L 760 500 Q 760 420 680 420 L 520 420 Q 440 420 400 500 Z M 400 500 L 360 460 Q 320 420 320 500 L 320 660 Q 320 740 380 760" fill="none" stroke="#FF1610" stroke-width="35" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-peertube.svg b/apps/web/public/brand/icon-peertube.svg
new file mode 100644
index 0000000..787cdb0
--- /dev/null
+++ b/apps/web/public/brand/icon-peertube.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Peertube</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 400 350 L 400 850 L 800 600 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-reddit.svg b/apps/web/public/brand/icon-reddit.svg
new file mode 100644
index 0000000..497ad38
--- /dev/null
+++ b/apps/web/public/brand/icon-reddit.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Reddit</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <circle cx="600" cy="500" r="50" fill="#FF1610"/><path d="M 550 500 L 400 450" stroke="#FF1610" stroke-width="25" stroke-linecap="round"/><path d="M 650 500 L 800 450" stroke="#FF1610" stroke-width="25" stroke-linecap="round"/><ellipse cx="600" cy="650" rx="200" ry="140" fill="none" stroke="#FF1610" stroke-width="35"/><circle cx="500" cy="620" r="20" fill="#FF1610"/><circle cx="700" cy="620" r="20" fill="#FF1610"/><path d="M 520 700 Q 600 740 680 700" fill="none" stroke="#FF1610" stroke-width="25" stroke-linecap="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-slack.svg b/apps/web/public/brand/icon-slack.svg
new file mode 100644
index 0000000..21dbdbc
--- /dev/null
+++ b/apps/web/public/brand/icon-slack.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Slack</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <rect x="450" y="350" width="80" height="140" rx="20" fill="none" stroke="#FF1610" stroke-width="30"/><rect x="670" y="350" width="80" height="140" rx="20" fill="none" stroke="#FF1610" stroke-width="30"/><rect x="350" y="530" width="140" height="80" rx="20" fill="none" stroke="#FF1610" stroke-width="30"/><rect x="710" y="530" width="140" height="80" rx="20" fill="none" stroke="#FF1610" stroke-width="30"/><rect x="450" y="700" width="80" height="140" rx="20" fill="none" stroke="#FF1610" stroke-width="30"/><rect x="670" y="700" width="80" height="140" rx="20" fill="none" stroke="#FF1610" stroke-width="30"/><path d="M 530 570 L 670 570" stroke="#FF1610" stroke-width="30" stroke-linecap="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-telegram.svg b/apps/web/public/brand/icon-telegram.svg
new file mode 100644
index 0000000..2c04c3b
--- /dev/null
+++ b/apps/web/public/brand/icon-telegram.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Telegram</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 300 600 L 850 400 L 700 800 L 550 650 L 300 600 Z M 550 650 L 550 750 L 620 680" fill="none" stroke="#FF1610" stroke-width="35" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-threads.svg b/apps/web/public/brand/icon-threads.svg
new file mode 100644
index 0000000..87aa902
--- /dev/null
+++ b/apps/web/public/brand/icon-threads.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Threads</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 600 350 Q 450 350 400 500 Q 350 650 400 750 Q 450 850 600 850 Q 750 850 800 750 Q 850 650 800 500 Q 750 350 600 350 Z M 550 550 Q 600 500 650 550 Q 700 600 650 650 Q 600 700 550 650 Q 500 600 550 550 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/icon-twitch.svg b/apps/web/public/brand/icon-twitch.svg
new file mode 100644
index 0000000..dd99360
--- /dev/null
+++ b/apps/web/public/brand/icon-twitch.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1700 1700">
+  <title>Twitch</title>
+  <circle cx="850" cy="850" r="560" fill="#0a0a0b" stroke="#FF1610" stroke-width="38"
+          transform="rotate(-17.5 850 850)"/>
+  <path d="M 400 350 L 800 350 L 800 600 L 650 750 L 500 750 L 400 850 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linejoin="round"/><line x1="550" y1="450" x2="550" y2="550" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><line x1="670" y1="450" x2="670" y2="550" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/logo-new.svg b/apps/web/public/brand/logo-new.svg
new file mode 100644
index 0000000..64d429b
--- /dev/null
+++ b/apps/web/public/brand/logo-new.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="20.9 18.0 587.8 592.0" width="588" height="592" fill="none">
+  <title>Tactical Media Broadcast Hub — broadcast logo — circle with signal arrows</title>
+  <g fill="#FF1610" fill-rule="evenodd">
+    <path d="M 441.4,600.2 C 437.1,598.0 431.7,595.5 429.5,594.5 C 427.3,593.5 418.1,589.1 409.1,584.8 C 400.1,580.5 392.6,577.0 392.4,577.0 C 392.1,577.0 387.8,575.0 382.7,572.7 C 377.7,570.3 370.6,567.0 367.0,565.4 C 359.3,562.1 354.0,559.1 354.0,558.2 C 354.0,557.8 357.2,555.7 361.2,553.5 C 379.6,543.2 387.0,538.7 387.0,537.9 C 387.0,537.3 361.2,493.8 355.9,485.5 C 354.8,483.9 350.9,477.3 347.1,471.0 C 343.3,464.7 339.6,459.6 338.8,459.7 C 338.1,459.7 333.2,460.9 328.0,462.3 C 310.2,466.9 305.4,467.5 284.5,467.4 C 266.8,467.4 263.1,467.1 252.5,464.8 C 238.0,461.6 227.3,458.1 216.0,452.9 C 199.5,445.2 183.1,434.1 171.2,422.6 C 167.7,419.2 164.5,416.3 163.9,416.2 C 163.1,415.9 160.4,417.2 151.0,422.7 C 149.1,423.8 138.5,429.9 127.5,436.3 C 116.6,442.6 107.2,448.4 106.7,449.2 C 105.8,450.5 112.9,463.6 120.6,475.1 C 124.1,480.2 123.8,482.2 119.8,481.6 C 118.0,481.3 112.9,480.6 108.5,480.0 C 104.1,479.4 97.8,478.5 94.5,478.0 C 91.2,477.5 78.4,475.7 66.0,474.0 C 53.6,472.4 41.1,470.5 38.1,470.0 C 35.1,469.4 31.3,469.0 29.6,469.0 C 24.0,469.0 23.7,468.1 26.9,459.4 C 29.9,451.4 32.4,445.1 34.0,441.5 C 34.5,440.4 35.6,437.5 36.4,435.0 C 37.7,430.8 42.1,419.4 54.2,388.5 C 57.0,381.4 59.5,375.3 59.7,375.1 C 60.4,374.2 62.7,377.4 71.6,391.8 C 77.6,401.5 81.3,406.5 82.3,406.4 C 83.2,406.3 91.5,402.0 100.7,396.7 C 118.8,386.5 123.0,384.1 130.0,380.2 C 132.5,378.9 134.9,377.4 135.4,376.9 C 135.9,376.4 134.8,372.9 132.8,368.3 C 128.6,359.0 124.6,346.9 121.8,334.5 C 119.2,322.9 118.2,294.7 120.0,281.6 C 124.7,246.6 140.4,213.4 163.9,188.7 L 166.1,179.7 C 164.8,177.4 162.3,173.2 160.5,170.5 C 158.7,167.8 155.5,162.6 153.3,159.0 C 146.7,148.1 129.0,119.8 125.3,114.2 C 123.4,111.4 121.4,109.0 120.7,109.0 C 120.0,109.0 115.5,111.3 110.5,114.1 C 97.6,121.4 85.9,127.2 85.3,126.6 C 85.0,126.4 85.3,123.1 85.9,119.3 C 87.2,111.3 89.8,93.4 91.1,83.5 C 91.6,79.7 92.4,73.3 93.0,69.5 C 93.6,65.7 94.4,59.1 95.0,55.0 C 96.1,46.5 97.5,35.7 98.6,28.7 C 99.0,25.8 99.8,24.0 100.6,24.0 C 103.2,24.0 194.0,68.6 194.0,69.9 C 194.0,70.4 188.2,73.9 181.1,77.6 C 164.0,86.5 163.4,87.0 165.0,90.1 C 166.1,92.2 180.5,115.5 199.8,146.3 C 202.8,151.1 205.9,155.0 206.6,155.0 C 207.3,155.0 209.4,154.1 211.2,153.1 C 218.5,148.8 237.6,142.0 249.7,139.4 C 261.6,136.8 264.1,136.6 286.0,136.6 C 306.3,136.6 310.9,136.9 319.6,138.8 C 351.3,145.6 379.3,159.5 401.0,179.1 L 414.5,182.6 C 421.5,178.8 440.0,168.2 448.0,163.5 C 451.0,161.8 456.1,158.9 459.2,157.1 C 462.4,155.3 465.0,153.5 465.0,153.2 C 465.0,152.8 460.7,145.3 455.5,136.6 C 450.3,127.8 446.0,120.2 446.0,119.7 C 446.0,119.1 448.1,119.0 451.2,119.4 C 454.1,119.8 460.1,120.5 464.5,121.0 C 468.9,121.6 476.2,122.4 480.8,123.0 C 485.3,123.5 492.6,124.4 497.0,125.0 C 513.1,127.0 521.7,128.0 531.5,129.1 C 537.0,129.7 542.0,130.6 542.7,131.2 C 543.5,131.9 543.1,134.2 540.8,140.3 C 539.2,144.8 537.0,150.8 536.0,153.5 C 535.0,156.2 533.1,161.4 531.7,165.0 C 530.3,168.6 526.4,179.2 523.0,188.5 C 510.7,222.7 510.4,223.3 508.8,222.8 C 508.2,222.6 503.9,216.1 499.3,208.4 C 494.6,200.8 490.5,194.2 490.1,193.8 C 489.7,193.4 484.8,195.7 479.1,199.0 C 473.4,202.3 468.6,205.0 468.4,205.0 C 468.3,205.0 464.6,207.2 460.3,209.8 C 456.0,212.5 449.4,216.4 445.5,218.4 C 435.0,224.1 435.1,223.9 438.2,230.7 C 444.9,245.4 449.8,261.6 451.5,275.0 C 451.9,278.0 452.6,281.5 453.1,282.8 L 479.7,285.0 C 493.9,285.0 507.9,284.7 510.8,284.4 L 516.0,265.9 C 516.0,251.9 516.3,248.0 517.3,248.0 C 518.5,248.0 522.4,250.6 544.0,265.5 C 548.1,268.3 555.8,273.5 561.0,277.1 C 566.2,280.6 571.0,283.8 571.5,284.3 C 572.0,284.7 579.2,289.7 587.4,295.4 C 595.7,301.0 602.5,306.1 602.7,306.7 C 602.9,307.3 600.7,309.5 597.8,311.6 C 587.7,318.8 533.3,358.6 523.3,366.1 C 516.3,371.2 516.1,370.7 515.8,349.8 L 492.5,331.2 C 479.9,331.0 465.4,331.2 460.4,331.5 L 450.0,337.7 C 442.1,373.2 419.6,408.3 389.3,432.5 C 385.8,435.3 383.0,438.0 383.0,438.6 C 383.0,439.3 387.7,447.6 393.5,457.1 C 399.3,466.7 409.3,483.4 415.8,494.2 C 422.2,505.0 428.1,514.1 428.8,514.4 C 429.5,514.7 431.5,514.1 433.3,513.1 C 465.4,494.7 465.8,494.6 464.6,500.2 C 464.2,502.0 463.5,507.1 463.0,511.5 C 462.4,515.9 461.6,522.9 461.0,527.0 C 460.4,531.1 459.3,540.6 458.5,548.0 C 457.2,559.9 454.0,587.4 452.4,599.8 C 452.1,602.2 451.3,604.0 450.6,604.0 C 450.0,604.0 445.8,602.3 441.4,600.2 Z"/>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/logo.svg b/apps/web/public/brand/logo.svg
new file mode 100644
index 0000000..310c380
--- /dev/null
+++ b/apps/web/public/brand/logo.svg
@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1700" height="1700" viewBox="0 0 1700 1700">
+  <title>Tactical Media Broadcast Hub — broadcast mark</title>
+  <desc>Red anarchist arrow A rotated 17.5 degrees counterclockwise so its top arrow points upper-left.</desc>
+
+  <rect width="100%" height="100%" fill="#000000"/>
+
+  <!-- Rotate the complete symbol 35 degrees to the left -->
+  <g transform="rotate(-17.5 850 850)">
+
+    <circle cx="850" cy="850" r="350"
+            fill="none" stroke="#FF1610" stroke-width="74"
+            stroke-linecap="round"/>
+
+    <g fill="none" stroke="#FF1610" stroke-width="88"
+       stroke-linecap="round" stroke-linejoin="round">
+      <path d="M 850 405
+               L 464.77 1269.52"/>
+      <path d="M 850 405
+               L 1235.23 1269.52"/>
+      <path d="M 850 405
+               L 850.00 350.00"/>
+      <path d="M 345.00 850.00
+               L 1355.00 850.00"/>
+    </g>
+
+    <g fill="#FF1610">
+      <polygon points="850.00,240.00 925.00,385.00 775.00,385.00"/>
+      <polygon points="235.00,850.00 380.00,775.00 380.00,925.00"/>
+      <polygon points="1465.00,850.00 1320.00,925.00 1320.00,775.00"/>
+      <polygon points="420.00,1370.00 410.51,1207.03 547.52,1268.08"/>
+      <polygon points="1280.00,1370.00 1152.48,1268.08 1289.49,1207.03"/>
+    </g>
+
+    <g fill="#000000" opacity="0.95">
+      <path d="M 630 640 l 20 4 -28 85 -18 -8 z"/>
+      <path d="M 1052 650 l 19 -5 27 82 -18 8 z"/>
+      <path d="M 655 1052 l 24 5 -26 78 -20 -9 z"/>
+      <path d="M 1025 1052 l 23 -6 28 78 -20 9 z"/>
+      <path d="M 454 838 l 60 -5 2 18 -61 5 z"/>
+      <path d="M 1186 849 l 60 4 -2 18 -61 -4 z"/>
+    </g>
+
+  </g>
+</svg>
diff --git a/apps/web/public/brand/nav-analytics.svg b/apps/web/public/brand/nav-analytics.svg
new file mode 100644
index 0000000..96c623d
--- /dev/null
+++ b/apps/web/public/brand/nav-analytics.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Analytics</title>
+  <line x1="350" y1="850" x2="850" y2="850" stroke="#FF1610" stroke-width="40" stroke-linecap="round"/><line x1="420" y1="700" x2="420" y2="850" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><line x1="600" y1="500" x2="600" y2="850" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><line x1="780" y1="400" x2="780" y2="850" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-audit.svg b/apps/web/public/brand/nav-audit.svg
new file mode 100644
index 0000000..82dd8ef
--- /dev/null
+++ b/apps/web/public/brand/nav-audit.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Audit</title>
+  <path d="M 500 350 L 700 350 L 700 500 L 800 500 L 600 850 L 400 500 L 500 500 Z" fill="none" stroke="#FF1610" stroke-width="35" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-calendar.svg b/apps/web/public/brand/nav-calendar.svg
new file mode 100644
index 0000000..1398cca
--- /dev/null
+++ b/apps/web/public/brand/nav-calendar.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Calendar</title>
+  <rect x="350" y="400" width="500" height="450" rx="30" fill="none" stroke="#FF1610" stroke-width="40"/><line x1="350" y1="520" x2="850" y2="520" stroke="#FF1610" stroke-width="30"/><line x1="450" y1="400" x2="450" y2="350" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><line x1="750" y1="400" x2="750" y2="350" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/><circle cx="500" cy="620" r="20" fill="#FF1610"/><circle cx="600" cy="620" r="20" fill="#FF1610"/><circle cx="700" cy="620" r="20" fill="#FF1610"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-compose.svg b/apps/web/public/brand/nav-compose.svg
new file mode 100644
index 0000000..eb9228c
--- /dev/null
+++ b/apps/web/public/brand/nav-compose.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Compose</title>
+  <path d="M 400 800 L 350 850 L 400 850 L 850 400 L 800 350 L 350 800" fill="none" stroke="#FF1610" stroke-width="40" stroke-linecap="round" stroke-linejoin="round"/><line x1="750" y1="400" x2="800" y2="450" stroke="#FF1610" stroke-width="30"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-connections.svg b/apps/web/public/brand/nav-connections.svg
new file mode 100644
index 0000000..a6f759c
--- /dev/null
+++ b/apps/web/public/brand/nav-connections.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Connections</title>
+  <circle cx="450" cy="500" r="80" fill="none" stroke="#FF1610" stroke-width="35"/><circle cx="750" cy="700" r="80" fill="none" stroke="#FF1610" stroke-width="35"/><line x1="500" y1="550" x2="700" y2="650" stroke="#FF1610" stroke-width="35" stroke-linecap="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-home.svg b/apps/web/public/brand/nav-home.svg
new file mode 100644
index 0000000..c324549
--- /dev/null
+++ b/apps/web/public/brand/nav-home.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Home</title>
+  <path d="M 600 350 L 850 550 L 850 850 L 350 850 L 350 550 Z" fill="none" stroke="#FF1610" stroke-width="40" stroke-linejoin="round"/><line x1="600" y1="350" x2="600" y2="850" stroke="#FF1610" stroke-width="30"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-inbox.svg b/apps/web/public/brand/nav-inbox.svg
new file mode 100644
index 0000000..fb4dde6
--- /dev/null
+++ b/apps/web/public/brand/nav-inbox.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Inbox</title>
+  <path d="M 350 400 L 850 400 L 850 700 L 700 700 L 600 800 L 500 700 L 350 700 Z" fill="none" stroke="#FF1610" stroke-width="40" stroke-linejoin="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-more.svg b/apps/web/public/brand/nav-more.svg
new file mode 100644
index 0000000..86d7e8e
--- /dev/null
+++ b/apps/web/public/brand/nav-more.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav More</title>
+  <circle cx="500" cy="600" r="30" fill="#FF1610"/><circle cx="600" cy="600" r="30" fill="#FF1610"/><circle cx="700" cy="600" r="30" fill="#FF1610"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-search.svg b/apps/web/public/brand/nav-search.svg
new file mode 100644
index 0000000..424d7fe
--- /dev/null
+++ b/apps/web/public/brand/nav-search.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Search</title>
+  <circle cx="550" cy="550" r="200" fill="none" stroke="#FF1610" stroke-width="40"/><line x1="700" y1="700" x2="850" y2="850" stroke="#FF1610" stroke-width="40" stroke-linecap="round"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-settings.svg b/apps/web/public/brand/nav-settings.svg
new file mode 100644
index 0000000..6ab306a
--- /dev/null
+++ b/apps/web/public/brand/nav-settings.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Settings</title>
+  <circle cx="600" cy="600" r="150" fill="none" stroke="#FF1610" stroke-width="40"/><g stroke="#FF1610" stroke-width="35" stroke-linecap="round"><line x1="600" y1="350" x2="600" y2="420"/><line x1="600" y1="780" x2="600" y2="850"/><line x1="350" y1="600" x2="420" y2="600"/><line x1="780" y1="600" x2="850" y2="600"/><line x1="420" y1="420" x2="470" y2="470"/><line x1="730" y1="730" x2="780" y2="780"/><line x1="420" y1="780" x2="470" y2="730"/><line x1="730" y1="470" x2="780" y2="420"/></g>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-team.svg b/apps/web/public/brand/nav-team.svg
new file mode 100644
index 0000000..0a5fe68
--- /dev/null
+++ b/apps/web/public/brand/nav-team.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Team</title>
+  <circle cx="500" cy="500" r="70" fill="none" stroke="#FF1610" stroke-width="35"/><circle cx="700" cy="500" r="70" fill="none" stroke="#FF1610" stroke-width="35"/><path d="M 400 750 Q 400 650 500 650 Q 600 650 600 750" fill="none" stroke="#FF1610" stroke-width="35"/><path d="M 600 750 Q 600 650 700 650 Q 800 650 800 750" fill="none" stroke="#FF1610" stroke-width="35"/>
+</svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/nav-video.svg b/apps/web/public/brand/nav-video.svg
new file mode 100644
index 0000000..74e982a
--- /dev/null
+++ b/apps/web/public/brand/nav-video.svg
@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 1200 1200">
+  <title>Nav Video</title>
+  <rect x="260" y="400" width="680" height="400" rx="70" fill="none" stroke="#FF1610" stroke-width="70"/><path d="M 940 600 L 1120 480 L 1120 720 Z" fill="#FF1610"/><path d="M 360 470 L 360 730" stroke="#FF1610" stroke-width="40" stroke-linecap="round"/><path d="M 480 470 L 480 730" stroke="#FF1610" stroke-width="40" stroke-linecap="round"/>
+</svg>
diff --git a/apps/web/public/brand/pattern.svg b/apps/web/public/brand/pattern.svg
new file mode 100644
index 0000000..8a38621
--- /dev/null
+++ b/apps/web/public/brand/pattern.svg
@@ -0,0 +1,24 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1920" height="1080" viewBox="0 0 1920 1080">
+  <rect width="1920" height="1080" fill="#0a0a0b"/>
+  <defs>
+    <g id="ca">
+      <g transform="rotate(-17.5 0 0)">
+        <circle cx="0" cy="0" r="45" fill="none" stroke="#FF1610" stroke-width="10"/>
+        <path d="M 0 -38 L -28 38 M 0 -38 L 28 38 M -34 0 L 34 0" fill="none" stroke="#FF1610" stroke-width="12" stroke-linecap="round"/>
+      </g>
+    </g>
+  </defs>
+  <use href="#ca" transform="translate(200,200) scale(1.2)" opacity="0.03"/>
+  <use href="#ca" transform="translate(600,150) scale(0.8)" opacity="0.05"/>
+  <use href="#ca" transform="translate(1100,220) scale(1.5)" opacity="0.02"/>
+  <use href="#ca" transform="translate(1600,180) scale(1.0)" opacity="0.04"/>
+  <use href="#ca" transform="translate(300,500) scale(0.6)" opacity="0.06"/>
+  <use href="#ca" transform="translate(900,450) scale(1.1)" opacity="0.03"/>
+  <use href="#ca" transform="translate(1400,550) scale(0.7)" opacity="0.05"/>
+  <use href="#ca" transform="translate(1750,480) scale(1.3)" opacity="0.02"/>
+  <use href="#ca" transform="translate(150,800) scale(1.4)" opacity="0.03"/>
+  <use href="#ca" transform="translate(650,850) scale(0.9)" opacity="0.04"/>
+  <use href="#ca" transform="translate(1200,780) scale(0.5)" opacity="0.07"/>
+  <use href="#ca" transform="translate(1700,850) scale(1.0)" opacity="0.03"/>
+  <use href="#ca" transform="translate(960,540) scale(2.5)" opacity="0.015"/>
+  </svg>
\ No newline at end of file
diff --git a/apps/web/public/brand/spinner.svg b/apps/web/public/brand/spinner.svg
new file mode 100644
index 0000000..ca6de79
--- /dev/null
+++ b/apps/web/public/brand/spinner.svg
@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 1700 1700">
+  <g transform="rotate(-17.5 850 850)">
+    <path d="M 850 500 A 350 350 0 0 1 1200 850" fill="none" stroke="#FF1610" stroke-width="70" stroke-linecap="round"/>
+    <path d="M 1200 850 A 350 350 0 0 1 850 1200" fill="none" stroke="#FF1610" stroke-width="70" stroke-linecap="round" opacity="0.2"/>
+    <path d="M 850 1200 A 350 350 0 0 1 500 850" fill="none" stroke="#FF1610" stroke-width="70" stroke-linecap="round" opacity="0.2"/>
+    <path d="M 500 850 A 350 350 0 0 1 850 500" fill="none" stroke="#FF1610" stroke-width="70" stroke-linecap="round" opacity="0.2"/>
+  </g>
+</svg>
\ No newline at end of file
diff --git a/apps/web/scripts/control-room-audit.cjs b/apps/web/scripts/control-room-audit.cjs
new file mode 100644
index 0000000..bfe1567
--- /dev/null
+++ b/apps/web/scripts/control-room-audit.cjs
@@ -0,0 +1,152 @@
+const { chromium } = require("playwright");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const path = require("node:path");
+require("./control-room-register.cjs");
+const { fixtureChannel } = require("../src/components/control-room/fixtures.ts");
+const web = path.resolve(__dirname, "..");
+const origin = "http://audit.local";
+const workspaceId = "50000000-0000-4000-8000-000000000001";
+const mime = { ".js": "application/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".png": "image/png", ".html": "text/html", ".rsc": "text/x-component" };
+const results = [];
+const cors = { "Access-Control-Allow-Origin": origin, "Access-Control-Allow-Credentials": "true", "Access-Control-Allow-Headers": "Authorization,Content-Type,Idempotency-Key", "Access-Control-Allow-Methods": "GET,POST,OPTIONS" };
+const json = (route, body, status = 200) => route.fulfill({ status, headers: cors, json: body });
+async function auditViewport(browser, viewport) {
+  const context = await browser.newContext({ viewport, isMobile: viewport.width < 1024, hasTouch: viewport.width < 1024 });
+  const page = await context.newPage();
+  const errors = []; page.on("pageerror", error => errors.push(error.message));
+  let channel = fixtureChannel(), mode = "live", seq = 0, socket;
+  const requests = [], keys = new Set();
+  const observation = version => ({ workspaceId, channelId: channel.channelId, workerId: channel.workerId, assignmentEpoch: channel.assignmentEpoch, state: "RUNNING", realizedVersion: version, updatedAt: new Date().toISOString(), reason: "Audit worker" });
+  channel.observed = observation(1);
+  const inject = (kind, data) => socket.send(JSON.stringify({ type: "state", workspaceId, channelId: channel.channelId, seq: ++seq, kind, data }));
+  await context.addInitScript(() => localStorage.setItem("tmbh.session", "audit-token"));
+  await page.routeWebSocket(/\/realtime$/, ws => {
+    socket = ws;
+    ws.onMessage(raw => {
+      const message = JSON.parse(String(raw));
+      if (message.type === "auth") { assert.equal(message.token, "audit-token"); assert.equal(message.workspaceId, workspaceId); ws.send(JSON.stringify({ type: "auth_ack", workspaceId })); }
+      if (message.type === "subscribe") {
+        ws.send(JSON.stringify({ type: "subscribe_ack", channelId: channel.channelId, seq }));
+        inject("desired", channel.desired); inject("observed", channel.observed);
+      }
+    });
+  });
+  await page.route("**/*", async route => {
+    const request = route.request(), url = new URL(request.url());
+    if (request.method() === "OPTIONS") return route.fulfill({ status: 204, headers: cors });
+    if (url.pathname === "/auth/me") return json(route, { user: { id: workspaceId, email: "operator@audit.local", displayName: "Operator" }, workspace: { id: workspaceId, name: "Audit studio", slug: "audit" }, role: "owner", permissions: ["director.take", "director.view", "director.lock_program", "director.override_auto", "director.change_layout", "media.view", "stream.view"], expiresAt: Date.now() + 3600000 });
+    if (url.pathname === "/media-control/status") {
+      if (mode === "offline") return route.abort();
+      if (mode === "forbidden") return json(route, { message: "Missing media.view" }, 403);
+      return json(route, { channels: mode === "empty" ? [] : [channel], workers: [] });
+    }
+    const action = /\/media-control\/channels\/[^/]+\/(pst-select|cut|take|lock|override)$/.exec(url.pathname)?.[1];
+    if (action && request.method() === "POST" || url.pathname.startsWith("/production/overlays/") && request.method() === "POST") {
+      const key = request.headers()["idempotency-key"]; assert.match(key, /^[\x20-\x7e]{1,128}$/); assert.match(key, /^[0-9a-f-]{36}$/); assert.ok(!keys.has(key)); keys.add(key);
+      const body = request.postDataJSON(); requests.push({ action: action ?? "overlay", body, key });
+      if (action === "pst-select") channel.desired.production.buses.preview = body.sceneId;
+      if (action === "cut" || action === "take") channel.desired.production.buses.program = channel.desired.production.buses.preview;
+      if (action === "lock") channel.desired.director.locked = body.enabled;
+      if (action === "override") channel.desired.director.override = body.mode ? { mode: body.mode, expiresAt: null } : null;
+      if (!action) channel.desired.production.overlays.find(item => url.pathname.endsWith(item.id)).revisionId = "60000000-0000-4000-8000-000000000001";
+      channel.desired.desiredVersion += 1;
+      await json(route, { desiredVersion: channel.desired.desiredVersion, commandId: key });
+      inject("desired", channel.desired); return;
+    }
+    if (url.pathname.includes("/preview/")) return json(route, { message: "No audit media" }, 404);
+    if (url.hostname !== "audit.local") return route.abort();
+    let file;
+    if (url.pathname.startsWith("/_next/")) file = path.join(web, ".next", url.pathname.slice(7));
+    else if (url.pathname.startsWith("/brand/")) file = path.join(web, "public", url.pathname);
+    else {
+      const name = url.pathname === "/" ? "index" : url.pathname.slice(1);
+      const rsc = request.headers().rsc === "1" || url.searchParams.has("_rsc");
+      file = path.join(web, ".next/server/app", `${name}.${rsc ? "rsc" : "html"}`);
+    }
+    if (!fs.existsSync(file)) return route.fulfill({ status: 404, body: "Not found" });
+    return route.fulfill({ contentType: mime[path.extname(file)] || "application/octet-stream", body: fs.readFileSync(file) });
+  });
+  const first = channel.desired.production.sources[0].id, second = channel.desired.production.sources[1].id;
+  const sceneB = channel.desired.production.scenes[1].id;
+  const tally = id => page.locator(`[data-source='${id}']`).getAttribute("data-tally");
+  const waitTally = (id, value) => page.waitForFunction(({ id, value }) => document.querySelector(`[data-source='${id}']`)?.getAttribute("data-tally") === value, { id, value });
+  const checkLayout = async stage => {
+    const layout = await page.evaluate(() => {
+      const root = document.querySelector(".control-room");
+      const undersized = Array.from(root.querySelectorAll("button, input, select, textarea, a[href]")).filter(el => { const r = el.getBoundingClientRect(); return r.width && r.height && (r.width < 43.5 || r.height < 43.5); }).map(el => ({ text: el.getAttribute("aria-label") || el.textContent.trim().slice(0, 50), width: el.getBoundingClientRect().width, height: el.getBoundingClientRect().height }));
+      return { width: document.documentElement.clientWidth, scrollWidth: document.documentElement.scrollWidth, rootWidth: root.clientWidth, rootScrollWidth: root.scrollWidth, undersized, liveDecodes: document.querySelectorAll("[data-live-decode]").length };
+    });
+    assert.ok(layout.scrollWidth <= layout.width, `${stage}: document overflow`);
+    assert.ok(layout.rootScrollWidth <= layout.rootWidth, `${stage}: control room overflow`);
+    assert.deepEqual(layout.undersized, [], `${stage}: tap targets`);
+    assert.ok(layout.liveDecodes <= (viewport.width < 1024 ? 1 : 4));
+    results.push({ viewport, stage, ...layout });
+  };
+  await page.goto(`${origin}/control-room`, { waitUntil: "networkidle" });
+  await waitTally(first, "program"); await checkLayout("initial");
+  await page.getByRole("combobox", { name: "PST scene", exact: true }).selectOption(sceneB);
+  await page.getByRole("status").filter({ hasText: "Request accepted" }).waitFor();
+  assert.equal(await tally(first), "program"); assert.equal(await tally(second), "none");
+  inject("observed", observation(channel.desired.desiredVersion));
+  await waitTally(second, "preview");
+  await page.getByRole("button", { name: "CUT", exact: true }).click();
+  await page.waitForFunction(() => document.querySelector("[role='status']")?.textContent.includes("version 3"));
+  assert.equal(await tally(first), "program"); assert.equal(await tally(second), "preview");
+  const injectedAt = Date.now();
+  inject("observed", observation(3)); await waitTally(second, "program"); assert.equal(await tally(first), "none");
+  const observedToTallyMs = Date.now() - injectedAt;
+  assert.ok(observedToTallyMs < 300, "observed frame to tally must take under 300 ms");
+  await page.getByRole("button", { name: "TAKE", exact: true }).click();
+  await page.getByRole("button", { name: "Lock program", exact: true }).click();
+  await page.getByRole("button", { name: "Unlock program", exact: true }).waitFor();
+  await page.getByRole("combobox", { name: "Operator override" }).selectOption("five_minutes");
+  await page.getByRole("combobox", { name: "Operator override" }).selectOption("auto");
+  for (const template of ["lower_third", "chyron", "logo"]) {
+    const slot = channel.desired.production.overlays.find(item => item.kind === template);
+    await page.getByRole("combobox", { name: "Overlay slot" }).selectOption(slot.id);
+    if (template === "logo") await page.getByRole("textbox", { name: "Logo SVG" }).fill('<svg width="64" height="64"><rect width="64" height="64" fill="#FF1610"/></svg>');
+    else await page.getByRole("textbox", { name: template === "chyron" ? /Chyron text/ : /Title/ }).fill("Audit title");
+    await page.getByRole("button", { name: "Render overlay" }).click();
+    await page.getByRole("status").filter({ hasText: "Render accepted" }).waitFor();
+    assert.equal(requests.at(-1).body.templateId, template);
+  }
+  for (const tier of ["2x1", "2x2", "3x3", "4x4", "custom"]) {
+    await page.getByRole("combobox", { name: "Multiview layout" }).selectOption(tier);
+    await checkLayout(tier);
+  }
+  if (viewport.width >= 1024) {
+    await page.getByRole("combobox", { name: "Multiview layout" }).selectOption("4x4");
+    await page.getByRole("button", { name: "Focus Sample source 1", exact: true }).click();
+    const upgrades = page.getByRole("button", { name: "Upgrade live", exact: true });
+    await upgrades.nth(0).click(); await upgrades.nth(0).click();
+    assert.ok(await upgrades.nth(0).isDisabled(), "5th decode must be refused");
+  }
+  const resyncBefore = requests.length;
+  socket.send(JSON.stringify({ type: "RESYNC_REQUIRED", channelId: channel.channelId }));
+  await page.waitForTimeout(100); assert.equal(requests.length, resyncBefore);
+  mode = "empty"; await page.getByRole("button", { name: "Reconnect", exact: true }).click();
+  await page.getByRole("heading", { name: "No production scenes configured" }).waitFor();
+  assert.equal(await page.locator("[data-tally='program']").count(), 0); assert.equal(await page.getByText("FIXTURE · sample data", { exact: true }).count(), 0);
+  await checkLayout("empty");
+  mode = "forbidden"; await page.getByRole("button", { name: "Reconnect", exact: true }).click();
+  await page.getByRole("status").filter({ hasText: "Missing media.view" }).waitFor();
+  assert.equal(await page.getByText("FIXTURE · sample data", { exact: true }).count(), 0);
+  mode = "offline"; await page.getByRole("button", { name: "Reconnect", exact: true }).click();
+  await page.getByText("FIXTURE · sample data", { exact: true }).waitFor();
+  assert.equal(await page.locator("[data-tally='program']").count(), 0);
+  const before = requests.length;
+  await page.getByRole("button", { name: "CUT", exact: true }).click();
+  assert.equal(requests.length, before); assert.equal(await page.locator("[data-tally='program']").count(), 0);
+  await checkLayout("offline-fixture");
+  assert.deepEqual(errors, [], "browser runtime errors");
+  results.push({ viewport, flow: "PST→observed preview→CUT→observed program", actions: requests.map(item => item.action), uniqueKeys: keys.size, observedToTallyMs, runtimeErrors: errors });
+  await context.close();
+}
+async function run() {
+  const browser = await chromium.launch({ headless: true });
+  try { for (const viewport of [{ width: 1440, height: 900 }, { width: 390, height: 844 }]) await auditViewport(browser, viewport); }
+  finally { await browser.close(); }
+  console.log(JSON.stringify(results, null, 2));
+}
+run().catch(error => { console.error(error); process.exitCode = 1; });
diff --git a/apps/web/scripts/control-room-register.cjs b/apps/web/scripts/control-room-register.cjs
new file mode 100644
index 0000000..d7768f5
--- /dev/null
+++ b/apps/web/scripts/control-room-register.cjs
@@ -0,0 +1,11 @@
+// Existing TypeScript compiler only; node:test remains the test runner. No runtime dependency.
+const ts = require("typescript");
+const fs = require("node:fs");
+function compile(module, filename) {
+  const result = ts.transpileModule(fs.readFileSync(filename, "utf8"), {
+    compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022, jsx: ts.JsxEmit.ReactJSX, esModuleInterop: true }, fileName: filename,
+  });
+  module._compile(result.outputText, filename);
+}
+require.extensions[".ts"] = compile;
+require.extensions[".tsx"] = compile;
diff --git a/apps/web/scripts/manual-shots.mjs b/apps/web/scripts/manual-shots.mjs
new file mode 100644
index 0000000..9056cbc
--- /dev/null
+++ b/apps/web/scripts/manual-shots.mjs
@@ -0,0 +1,85 @@
+import { chromium } from "playwright";
+import { mkdirSync } from "node:fs";
+
+const BASE = "http://localhost:3111";
+const OUT = "runs/manual/shots";
+mkdirSync(OUT, { recursive: true });
+
+const browser = await chromium.launch();
+const ctx = await browser.newContext({ viewport: { width: 1440, height: 900 }, deviceScaleFactor: 2 });
+const page = await ctx.newPage();
+const errors = [];
+page.on("pageerror", (e) => errors.push(String(e).slice(0, 150)));
+
+async function shot(name) {
+  await page.waitForTimeout(500);
+  await page.screenshot({ path: `${OUT}/${name}.png` });
+  console.log(`✓ ${name}`);
+}
+
+async function safeClick(text, fallback) {
+  try { await page.getByRole("button", { name: text, timeout: 5000 }).click(); }
+  catch { try { await page.getByText(text, { timeout: 3000 }).first().click(); }
+  catch { if (fallback) fallback(); else console.log(`  (skip: ${text})`); } }
+}
+
+async function safeType(selector, text) {
+  try { const el = page.locator(selector).first(); await el.click({ timeout: 5000 }); await el.fill(text); }
+  catch { console.log(`  (skip type: ${selector})`); }
+}
+
+// ONBOARDING
+await page.goto(`${BASE}/onboard`); await page.waitForTimeout(1500);
+// redirect to /onboarding
+await page.goto(`${BASE}/onboarding`); await page.waitForTimeout(1500);
+await shot("onboard-01-start");
+safeType("input", "Global News Desk");
+await shot("onboard-02-named");
+safeClick("Continue");
+await shot("onboard-03-invite");
+safeType("textarea", "sarah@globalnews.io, marcus@globalnews.io");
+await shot("onboard-04-emails-filled");
+safeClick("Continue");
+await shot("onboard-05-connect");
+
+// STREAMS
+await page.goto(`${BASE}/streams`); await page.waitForTimeout(1000);
+await shot("streams-01-overview");
+await page.keyboard.press("j"); await page.keyboard.press("j"); await page.keyboard.press("j");
+await shot("streams-02-item-selected");
+await page.keyboard.press("r");
+await shot("streams-03-repost-toast");
+await page.keyboard.press("q");
+await shot("streams-04-quote-popover");
+try { const ta = page.locator("textarea").first(); if (await ta.isVisible({ timeout: 3000 })) { await ta.fill("This analysis is essential reading for anyone tracking the Fed's next move."); } } catch {}
+await shot("streams-05-quote-typed");
+await page.keyboard.press("Escape");
+
+// COMPOSE
+await page.goto(`${BASE}/compose`); await page.waitForTimeout(1000);
+await shot("compose-01-blank");
+try { const ed = page.locator(".ProseMirror").first(); await ed.click({ timeout: 5000 }); await page.keyboard.type("Breaking: Central bank signals first rate cut of the year as inflation cools to 2.1%. Full analysis at globalnews.io/fed-rates #markets #economy"); } catch { console.log("  (compose editor not found)"); }
+await shot("compose-02-typed");
+
+// CONNECTIONS
+await page.goto(`${BASE}/connections`); await page.waitForTimeout(800);
+await shot("connections-01-overview");
+
+// TEAM
+await page.goto(`${BASE}/team`); await page.waitForTimeout(800);
+await shot("team-01-overview");
+
+// INBOX
+await page.goto(`${BASE}/inbox`); await page.waitForTimeout(800);
+await shot("inbox-01-overview");
+
+// AUDIT
+await page.goto(`${BASE}/audit`); await page.waitForTimeout(800);
+await shot("audit-01-overview");
+try { await page.locator("tr").filter({ hasText: "credential" }).first().click({ timeout: 5000 }); } catch {}
+await shot("audit-02-diff-open");
+
+await browser.close();
+console.log(`\nShots: ${OUT}/`);
+console.log(`Errors: ${errors.length}`);
+for (const e of errors.slice(0, 5)) console.log(`  ${e}`);
diff --git a/apps/web/scripts/mobile-phase1-audit.cjs b/apps/web/scripts/mobile-phase1-audit.cjs
new file mode 100644
index 0000000..5bf10c8
--- /dev/null
+++ b/apps/web/scripts/mobile-phase1-audit.cjs
@@ -0,0 +1,58 @@
+const { chromium } = require("playwright");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const origin = "http://audit.local";
+const mime = { ".js": "application/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".png": "image/png", ".html": "text/html", ".rsc": "text/x-component", ".json": "application/json" };
+
+const routes = ["/streams", "/compose", "/inbox", "/approvals", "/connections", "/team", "/video", "/audit", "/onboarding", "/analytics", "/calendar", "/settings", "/more", "/search"];
+
+async function run() {
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage({ viewport: { width: 390, height: 844 }, deviceScaleFactor: 1, isMobile: true, hasTouch: true });
+  await page.route("**/*", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    if (url.hostname !== "audit.local") return route.abort();
+    let file;
+    if (url.pathname.startsWith("/_next/")) file = path.join(process.cwd(), ".next", url.pathname.slice(7));
+    else if (url.pathname.startsWith("/brand/")) file = path.join(process.cwd(), "public", url.pathname);
+    else {
+      const name = url.pathname === "/" ? "index" : url.pathname.slice(1);
+      const isRsc = request.headers().rsc === "1" || url.searchParams.has("_rsc");
+      file = path.join(process.cwd(), ".next/server/app", `${name}.${isRsc ? "rsc" : "html"}`);
+    }
+    if (!fs.existsSync(file)) return route.fulfill({ status: 404, body: "Not found" });
+    return route.fulfill({ status: 200, contentType: mime[path.extname(file)] || "application/octet-stream", body: fs.readFileSync(file) });
+  });
+  const results = [];
+  for (const route of routes) {
+    await page.goto(`${origin}${route}`, { waitUntil: "networkidle" });
+    await page.waitForTimeout(200);
+    const result = await page.evaluate(() => {
+      const width = document.documentElement.clientWidth;
+      const all = Array.from(document.querySelectorAll("button, a[href], input, select, textarea, [role='tab']"));
+      const undersized = all.filter((el) => {
+        const rect = el.getBoundingClientRect();
+        const style = getComputedStyle(el);
+        return rect.width > 0 && rect.height > 0 && rect.left < innerWidth && rect.right > 0 && rect.top < innerHeight && rect.bottom > 0 && style.visibility !== "hidden" && style.display !== "none" && (rect.width < 43.5 || rect.height < 43.5);
+      }).map((el) => ({ tag: el.tagName, text: (el.getAttribute("aria-label") || el.textContent || "").trim().slice(0, 40), width: Math.round(el.getBoundingClientRect().width), height: Math.round(el.getBoundingClientRect().height) }));
+      return { title: document.title, width, scrollWidth: document.documentElement.scrollWidth, bodyScrollWidth: document.body.scrollWidth, nav: !!document.querySelector("nav[aria-label='Primary navigation']"), undersized };
+    });
+    results.push({ route, ...result });
+  }
+  await page.goto(`${origin}/more`, { waitUntil: "networkidle" });
+  const scroller = page.locator("[data-mobile-main]");
+  await scroller.evaluate((el) => { el.scrollTop = 300; });
+  const before = await scroller.evaluate((el) => el.scrollTop);
+  await page.getByRole("navigation", { name: "Primary navigation" }).getByRole("link", { name: "Home" }).click();
+  await page.waitForURL(`${origin}/streams`);
+  await page.getByRole("navigation", { name: "Primary navigation" }).getByRole("link", { name: "More" }).click();
+  await page.waitForURL(`${origin}/more`);
+  await page.waitForTimeout(100);
+  const after = await scroller.evaluate((el) => el.scrollTop);
+  console.log(JSON.stringify({ routes: results, scrollPreservation: { before, after } }, null, 2));
+  await browser.close();
+  if (results.some((r) => r.scrollWidth > r.width || r.bodyScrollWidth > r.width || r.undersized.length > 0 || !r.nav) || before < 1 || Math.abs(before - after) > 1) process.exitCode = 1;
+}
+run().catch((error) => { console.error(error); process.exitCode = 1; });
diff --git a/apps/web/scripts/mobile-phase2-audit.cjs b/apps/web/scripts/mobile-phase2-audit.cjs
new file mode 100644
index 0000000..2490e9a
--- /dev/null
+++ b/apps/web/scripts/mobile-phase2-audit.cjs
@@ -0,0 +1,121 @@
+// The repo's Node 18 runtime can run this Chromium audit; Playwright 1.63's
+// bootstrap refuses it before launch, so bypass only that version gate here.
+if (Number(process.versions.node.split(".")[0]) < 20) Object.defineProperty(process.versions, "node", { value: "20.0.0" });
+const { chromium } = require("playwright");
+const fs = require("node:fs");
+const path = require("node:path");
+
+const origin = "http://audit.local";
+const routes = ["/streams", "/search", "/inbox", "/inbox/1", "/approvals", "/connections", "/compose", "/audit"];
+const mime = { ".js": "application/javascript", ".css": "text/css", ".svg": "image/svg+xml", ".png": "image/png", ".html": "text/html", ".rsc": "text/x-component", ".json": "application/json" };
+
+async function serveBuild(context) {
+  await context.route(`${origin}/**`, async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    let file;
+    if (url.pathname.startsWith("/_next/")) file = path.join(process.cwd(), ".next", url.pathname.slice(7));
+    else if (url.pathname.startsWith("/brand/")) file = path.join(process.cwd(), "public", url.pathname);
+    else {
+      const name = url.pathname === "/" ? "index" : url.pathname.slice(1);
+      const isRsc = request.headers().rsc === "1" || url.searchParams.has("_rsc");
+      file = path.join(process.cwd(), ".next/server/app", `${name}.${isRsc ? "rsc" : "html"}`);
+    }
+    if (!fs.existsSync(file)) return route.fulfill({ status: 404, body: "Not found" });
+    return route.fulfill({ status: 200, contentType: mime[path.extname(file)] || "application/octet-stream", body: fs.readFileSync(file) });
+  });
+}
+
+async function inspect(page) {
+  return page.evaluate(() => {
+    const width = document.documentElement.clientWidth;
+    const undersized = Array.from(document.querySelectorAll("button, a[href], input, select, textarea, [role='tab']")).filter((element) => {
+      const rect = element.getBoundingClientRect();
+      const style = getComputedStyle(element);
+      return rect.width > 0 && rect.height > 0 && rect.left < innerWidth && rect.right > 0 && rect.top < innerHeight && rect.bottom > 0 && style.visibility !== "hidden" && style.display !== "none" && style.opacity !== "0" && !element.classList.contains("sr-only") && (rect.width < 43.5 || rect.height < 43.5);
+    }).map((element) => ({ text: (element.getAttribute("aria-label") || element.textContent || "").trim().slice(0, 36), width: Math.round(element.getBoundingClientRect().width), height: Math.round(element.getBoundingClientRect().height) }));
+    return { width, scrollWidth: document.documentElement.scrollWidth, bodyScrollWidth: document.body.scrollWidth, undersized };
+  });
+}
+
+async function routeAudit(browser) {
+  const context = await browser.newContext({ viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true, deviceScaleFactor: 1 });
+  await serveBuild(context);
+  await context.route("http://localhost:3000/**", (route) => route.abort());
+  const page = await context.newPage();
+  const results = [];
+  for (const route of routes) {
+    const parent = route.startsWith("/inbox/") || route === "/approvals" ? "/inbox" : "/more";
+    await page.goto(`${origin}${parent}`, { waitUntil: "networkidle" });
+    await page.goto(`${origin}${route}`, { waitUntil: "networkidle" });
+    await page.waitForTimeout(150);
+    const sizes = await inspect(page);
+    const back = page.getByRole("button", { name: "Go back" });
+    if (await back.count()) await back.click();
+    else await page.goBack({ waitUntil: "domcontentloaded" });
+    await page.waitForTimeout(100);
+    results.push({ route, ...sizes, backResolved: new URL(page.url()).pathname === parent });
+  }
+  await page.goto(`${origin}/streams`, { waitUntil: "networkidle" });
+  await page.getByRole("tab", { name: /Mastodon/ }).click();
+  await page.getByRole("button", { name: /Amplify @/ }).first().click();
+  const mastodonLabels = await page.getByRole("dialog").innerText();
+  await page.getByRole("button", { name: "Close", exact: true }).click();
+  await page.getByRole("tab", { name: /Telegram/ }).click();
+  await page.getByRole("button", { name: /Amplify @/ }).first().click();
+  const telegramLabels = await page.getByRole("dialog").innerText();
+  await context.close();
+  return { routes: results, capabilityLabels: { mastodonBoost: mastodonLabels.includes("Boost"), mastodonQuote: mastodonLabels.includes("Quote"), telegramForward: telegramLabels.includes("Forward"), telegramNoQuote: !telegramLabels.includes("Quote") } };
+}
+
+async function approvalAudit(browser) {
+  const context = await browser.newContext({ viewport: { width: 390, height: 844 }, isMobile: true, hasTouch: true });
+  await serveBuild(context);
+  await context.addInitScript(() => localStorage.setItem("tmbh.session", "audit-token"));
+  const drafts = ["approve", "reject"].map((id) => ({ id, workspaceId: "w", authorUserId: "contributor-1", state: "in_review", createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), post: { text: `${id} this draft`, mediaAssetIds: [], visibility: "public", providerMetadata: { targetConnectionIds: [] } } }));
+  const audit = [];
+  const calls = [];
+  await context.route("http://localhost:3000/**", async (route) => {
+    const request = route.request();
+    const url = new URL(request.url());
+    const headers = { "access-control-allow-origin": origin, "access-control-allow-methods": "GET,POST,OPTIONS", "access-control-allow-headers": "authorization,content-type", "content-type": "application/json" };
+    if (request.method() === "OPTIONS") return route.fulfill({ status: 204, headers, body: "" });
+    let body;
+    if (url.pathname === "/auth/me") body = { user: { id: "editor-1", email: "editor@example.test", displayName: "Editor" }, workspace: { id: "w", name: "Test", slug: "test" }, role: "Editor", permissions: ["approval.grant", "draft.view"], expiresAt: Date.now() + 60000 };
+    else if (url.pathname === "/publishing/drafts" && request.method() === "GET") body = drafts.filter((draft) => draft.state === "in_review");
+    else if (url.pathname.match(/^\/publishing\/drafts\/(approve|reject)\/(approve|reject)$/) && request.method() === "POST") {
+      const [, id, decision] = url.pathname.match(/^\/publishing\/drafts\/(approve|reject)\/(approve|reject)$/);
+      const draft = drafts.find((item) => item.id === id);
+      draft.state = decision === "approve" ? "approved" : "rejected";
+      calls.push({ id, decision, path: url.pathname });
+      audit.unshift({ id: `audit-${audit.length}`, seq: String(audit.length + 1), at: new Date().toISOString(), actorUserId: "editor-1", actorEmail: "editor@example.test", actorRole: "Editor", action: `draft.${decision === "approve" ? "approved" : "rejected"}`, targetType: "draft", targetId: id, diff: null });
+      body = draft;
+    } else if (url.pathname === "/audit") body = { entries: audit, nextCursor: null, facets: { actions: [...new Set(audit.map((item) => item.action))], actors: [{ id: "editor-1", email: "editor@example.test" }] } };
+    else if (url.pathname === "/connections") body = [];
+    else body = [];
+    return route.fulfill({ status: 200, headers, body: JSON.stringify(body) });
+  });
+  const page = await context.newPage();
+  await page.goto(`${origin}/approvals`, { waitUntil: "networkidle" });
+  await page.getByRole("button", { name: "Approve", exact: true }).first().click();
+  await page.getByRole("button", { name: "Reject", exact: true }).first().click();
+  await page.getByRole("button", { name: "Needs edits" }).click();
+  await page.getByRole("button", { name: "Reject with reason" }).click();
+  await page.goto(`${origin}/audit`, { waitUntil: "networkidle" });
+  const text = await page.locator("[data-mobile-main]").innerText();
+  await context.close();
+  return { calls, auditActions: audit.map((item) => item.action), visibleInAudit: text.includes("draft.approved") && text.includes("draft.rejected") };
+}
+
+async function main() {
+  let browser;
+  try {
+    browser = await chromium.launch({ headless: true });
+    const routes = await routeAudit(browser);
+    const approvals = await approvalAudit(browser);
+    const result = { ...routes, approvals };
+    console.log(JSON.stringify(result, null, 2));
+    if (routes.routes.some((row) => row.scrollWidth > row.width || row.bodyScrollWidth > row.width || row.undersized.length > 0 || !row.backResolved) || Object.values(routes.capabilityLabels).some((value) => !value) || approvals.calls.length !== 2 || !approvals.visibleInAudit) process.exitCode = 1;
+  } finally { await browser?.close(); }
+}
+main().catch((error) => { console.error(error); process.exitCode = 1; });
diff --git a/apps/web/scripts/mobile-swipe.test.cjs b/apps/web/scripts/mobile-swipe.test.cjs
new file mode 100644
index 0000000..2c2a2b1
--- /dev/null
+++ b/apps/web/scripts/mobile-swipe.test.cjs
@@ -0,0 +1,33 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const Module = require("node:module");
+const ts = require("typescript");
+function load(file) {
+  const source = fs.readFileSync(file, "utf8");
+  const compiled = ts.transpileModule(source, { compilerOptions: { module: ts.ModuleKind.CommonJS, target: ts.ScriptTarget.ES2022 } }).outputText;
+  const loaded = new Module(file, module);
+  loaded._compile(compiled, file);
+  return loaded.exports;
+}
+const { swipeIntent, swipeResult } = load("src/lib/gestures.ts");
+const { nativeAmplifyActions } = load("src/lib/amplify.ts");
+const { PLATFORMS } = load("src/lib/platforms.ts");
+
+test("vertical scroll never locks to horizontal reveal", () => {
+  for (const [dx, dy] of [[0, 12], [9, 20], [-20, 60], [15, 50], [-40, 120]]) assert.equal(swipeIntent(dx, dy), "vertical");
+});
+test("small motion remains pending and deliberate horizontal motion reveals", () => {
+  assert.equal(swipeIntent(6, 3), "pending");
+  assert.equal(swipeIntent(-40, 10), "horizontal");
+  assert.equal(swipeResult(-50, 0.2, "left"), "closed");
+  assert.equal(swipeResult(-90, 0.2, "left"), "open");
+  assert.equal(swipeResult(-180, 0.2, "left"), "full");
+});
+test("native amplify labels follow platform capabilities", () => {
+  assert.deepEqual(nativeAmplifyActions(PLATFORMS.mastodon).map((item) => item.label), ["Boost", "Quote"]);
+  assert.deepEqual(nativeAmplifyActions(PLATFORMS.telegram).map((item) => item.label), ["Forward"]);
+  assert.deepEqual(nativeAmplifyActions(PLATFORMS.facebook).map((item) => item.label), ["Share link"]);
+  assert.deepEqual(nativeAmplifyActions(PLATFORMS.instagram), []);
+  assert.deepEqual(nativeAmplifyActions(PLATFORMS.limited), []);
+});
diff --git a/apps/web/scripts/visual-qa.mjs b/apps/web/scripts/visual-qa.mjs
new file mode 100644
index 0000000..b601e98
--- /dev/null
+++ b/apps/web/scripts/visual-qa.mjs
@@ -0,0 +1,75 @@
+import { chromium } from "playwright";
+import { mkdirSync } from "node:fs";
+
+const BASE = process.env.QA_BASE ?? "http://localhost:3111";
+const OUT = "runs/qa";
+mkdirSync(OUT, { recursive: true });
+
+const browser = await chromium.launch();
+const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+
+async function shot(name, { fullPage = false } = {}) {
+  await page.waitForTimeout(350);
+  await page.screenshot({ path: `${OUT}/${name}.png`, fullPage });
+  console.log(`✓ ${name}`);
+}
+
+console.log("console errors will be collected at the end");
+const errors = [];
+page.on("console", (msg) => {
+  if (msg.type() === "error") errors.push(msg.text().slice(0, 200));
+});
+page.on("pageerror", (err) => errors.push(`PAGEERROR: ${String(err).slice(0, 200)}`));
+
+await page.goto(`${BASE}/streams`);
+await shot("01-streams");
+
+await page.keyboard.press("j");
+await page.keyboard.press("j");
+await page.keyboard.press("j");
+await shot("02-streams-selected");
+
+await page.keyboard.press("r");
+await shot("03-streams-repost-toast");
+
+await page.keyboard.press("q");
+await shot("04-streams-quote-popover");
+await page.keyboard.press("Escape");
+
+await page.keyboard.press("j");
+await page.keyboard.press("k");
+await page.keyboard.press("k");
+await shot("05-streams-keyboard-moved");
+
+await page.goto(`${BASE}/compose`);
+await page.locator(".ProseMirror").click();
+await page.keyboard.type("Shipping the visual QA pass — capability-gated amplify, keyboard-first streams.");
+await shot("06-compose-typed");
+
+await page.goto(`${BASE}/connections`);
+await shot("07-connections");
+
+await page.goto(`${BASE}/inbox`);
+await shot("08-inbox");
+
+await page.goto(`${BASE}/team`);
+await shot("09-team");
+
+await page.goto(`${BASE}/audit`);
+await shot("10-audit");
+await page.locator("tr", { hasText: "credential.rotated" }).first().click();
+await shot("11-audit-diff-open");
+
+await page.goto(`${BASE}/onboarding`);
+await shot("12-onboarding-step1");
+await page.getByPlaceholder("Studio, Newsroom, Acme Social…").fill("Studio");
+await page.getByRole("button", { name: "Continue" }).click();
+await shot("13-onboarding-step2");
+
+await page.goto(`${BASE}/streams`);
+await page.keyboard.press("Meta+k");
+await shot("14-command-palette");
+
+await browser.close();
+console.log(`\nconsole errors: ${errors.length}`);
+for (const e of errors.slice(0, 10)) console.log(`  - ${e}`);
diff --git a/apps/web/src/app/(main)/analytics/page.tsx b/apps/web/src/app/(main)/analytics/page.tsx
new file mode 100644
index 0000000..a3e6962
--- /dev/null
+++ b/apps/web/src/app/(main)/analytics/page.tsx
@@ -0,0 +1,481 @@
+"use client";
+
+import { Fragment, useCallback, useEffect, useState } from "react";
+import { Badge, Button, Card } from "../../../components/ui/primitives";
+import { EmptyState } from "../../../components/brand/empty-state";
+import { Loading } from "../../../components/brand/loading";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { api, ApiUnreachableError, errorMessage } from "../../../lib/api-client";
+import { useAuth } from "../../../lib/auth-store";
+import { useApiResource } from "../../../lib/use-api";
+import type { DataSource } from "../../../lib/use-api";
+
+/**
+ * Analytics wiring: GET /analytics/summary (current vs previous month with
+ * deltas) and GET /analytics/snapshots (month history, keyset-paginated by
+ * cursor). Response types mirror apps/api/src/analytics/snapshot.service.ts.
+ *
+ * Honesty rules (audit-page pattern): no analytics fixtures exist, so the
+ * offline fallback is an empty screen behind the offline badge — never invented
+ * numbers — and on a live API error the data is withheld rather than faked.
+ * The production API may not serve /analytics yet, in which case the page
+ * degrades to the error state with a retry.
+ */
+
+interface SnapshotRecord {
+  id: string;
+  workspaceId: string;
+  month: string; // YYYY-MM
+  publicationsTotal: number;
+  publicationsByProvider: Record<string, number>;
+  postsArchivedTotal: number;
+  activeConnections: number;
+  draftsCreatedTotal: number;
+  publishingAttemptsTotal: number;
+  publishFailuresTotal: number;
+  snapshotStartedAt: string;
+  snapshotCompletedAt: string;
+}
+
+type SnapshotMetrics = Pick<
+  SnapshotRecord,
+  | "publicationsTotal"
+  | "postsArchivedTotal"
+  | "activeConnections"
+  | "draftsCreatedTotal"
+  | "publishingAttemptsTotal"
+  | "publishFailuresTotal"
+>;
+
+/** Deltas from GET /analytics/summary (monthDeltas shape); provider deltas stay per-provider. */
+interface MetricDeltas {
+  publicationsTotal: number;
+  publicationsByProvider: Record<string, number>;
+  postsArchivedTotal: number;
+  activeConnections: number;
+  draftsCreatedTotal: number;
+  publishingAttemptsTotal: number;
+  publishFailuresTotal: number;
+}
+
+interface SummaryResponse {
+  currentMonth: string;
+  previousMonth: string;
+  current: SnapshotRecord | null;
+  previous: SnapshotRecord | null;
+  deltas: MetricDeltas | null;
+}
+
+interface SnapshotPage {
+  items: SnapshotRecord[];
+  nextCursor: string | null;
+}
+
+const identity = <T,>(value: T): T => value;
+const PAGE_SIZE = 12; // server default; hard cap is 24
+
+interface MetricDef {
+  key: keyof SnapshotMetrics;
+  label: string;
+  /** Fewer failures is good, so invert the up/down coloring for that metric. */
+  invert?: boolean;
+}
+
+const METRICS: MetricDef[] = [
+  { key: "publicationsTotal", label: "Publications" },
+  { key: "postsArchivedTotal", label: "Posts archived" },
+  { key: "activeConnections", label: "Active channels" },
+  { key: "draftsCreatedTotal", label: "Drafts created" },
+  { key: "publishingAttemptsTotal", label: "Publish attempts" },
+  { key: "publishFailuresTotal", label: "Publish failures", invert: true },
+];
+
+function monthLabel(month: string): string {
+  return new Date(`${month}-01T00:00:00Z`).toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "long",
+    timeZone: "UTC",
+  });
+}
+
+function numberDelta(deltas: MetricDeltas | null, key: keyof SnapshotMetrics): number | null {
+  return deltas === null ? null : deltas[key];
+}
+
+function providerDeltas(deltas: MetricDeltas | null): Record<string, number> | null {
+  return deltas === null ? null : deltas.publicationsByProvider;
+}
+
+function Delta({
+  value,
+  previousMonth,
+  invert,
+}: {
+  value: number;
+  previousMonth: string;
+  invert?: boolean;
+}): React.ReactElement {
+  if (value === 0) {
+    return (
+      <span className="text-2xs text-text-faint" title={`No change vs ${monthLabel(previousMonth)}`}>
+        —
+      </span>
+    );
+  }
+  const up = value > 0;
+  const good = invert ? !up : up;
+  return (
+    <span
+      title={`${up ? "+" : "−"}${Math.abs(value).toLocaleString()} vs ${monthLabel(previousMonth)}`}
+      className={`text-2xs font-medium tabular-nums ${good ? "text-live" : "text-danger"}`}
+    >
+      {up ? "▲" : "▼"} {Math.abs(value).toLocaleString()}
+    </span>
+  );
+}
+
+function MetricCard({
+  metric,
+  value,
+  delta,
+  previousMonth,
+}: {
+  metric: MetricDef;
+  value: number;
+  delta: number | null;
+  previousMonth: string;
+}): React.ReactElement {
+  return (
+    <div className="rounded-lg border border-border-subtle bg-surface p-3">
+      <div className="text-2xs uppercase tracking-wide text-text-faint">{metric.label}</div>
+      <div className="mt-1 flex items-baseline gap-2">
+        <span className="text-xl font-semibold tabular-nums">{value.toLocaleString()}</span>
+        {delta !== null && <Delta value={delta} previousMonth={previousMonth} invert={metric.invert} />}
+      </div>
+    </div>
+  );
+}
+
+/** Provider breakdown chips with a relative bar; optional per-provider deltas. */
+function ProviderBreakdown({
+  byProvider,
+  deltas,
+  previousMonth,
+}: {
+  byProvider: Record<string, number>;
+  deltas: Record<string, number> | null;
+  previousMonth: string;
+}): React.ReactElement {
+  const entries = Object.entries(byProvider).sort((a, b) => b[1] - a[1]);
+  if (entries.length === 0) {
+    return <p className="text-2xs text-text-faint">No publications by any provider.</p>;
+  }
+  const max = Math.max(...entries.map(([, n]) => n), 1);
+  return (
+    <div className="flex flex-wrap gap-2">
+      {entries.map(([provider, count]) => {
+        const delta = deltas === null ? undefined : deltas[provider];
+        return (
+          <span
+            key={provider}
+            className="inline-flex min-w-[7.5rem] flex-col gap-1 rounded-md border border-border-subtle bg-surface-2 px-2 py-1.5"
+          >
+            <span className="flex items-center justify-between gap-3 text-2xs">
+              <span className="font-medium text-text-dim">{provider}</span>
+              <span className="tabular-nums">{count.toLocaleString()}</span>
+            </span>
+            <span
+              className="h-1 rounded-full bg-accent"
+              style={{ width: `${Math.max(8, Math.round((count / max) * 100))}%` }}
+            />
+            {delta !== undefined && <Delta value={delta} previousMonth={previousMonth} />}
+          </span>
+        );
+      })}
+    </div>
+  );
+}
+
+export default function Page(): React.ReactElement {
+  const { status, can } = useAuth();
+  const live = status === "authenticated";
+  // Offline screens render sample data (house pattern); permission checks only
+  // bite against a real session — can() is false for everyone while offline.
+  const allowed = !live || can("analytics.view");
+
+  // Summary panel: current month vs previous month, via the house hook.
+  const summary = useApiResource<SummaryResponse, SummaryResponse | null>("/analytics/summary", identity, null);
+
+  // Snapshot history: audit-page-style manual fetch because keyset "load older"
+  // appends pages instead of replacing the view.
+  const [historySource, setHistorySource] = useState<DataSource>("loading");
+  const [rows, setRows] = useState<SnapshotRecord[]>([]);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [historyError, setHistoryError] = useState<string | null>(null);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [expanded, setExpanded] = useState<string | null>(null);
+  const [nonce, setNonce] = useState(0);
+  const reload = useCallback(() => setNonce((n) => n + 1), []);
+
+  const [generating, setGenerating] = useState(false);
+  const [message, setMessage] = useState<{ tone: "ok" | "error"; text: string } | null>(null);
+
+  useEffect(() => {
+    if (status === "loading" || !allowed) return;
+    if (status !== "authenticated") {
+      setHistorySource("sample");
+      return;
+    }
+    const controller = new AbortController();
+    setHistorySource("loading");
+    api
+      .get<SnapshotPage>("/analytics/snapshots", { limit: PAGE_SIZE }, controller.signal)
+      .then((page) => {
+        setRows(page.items);
+        setCursor(page.nextCursor);
+        setHistorySource("live");
+        setHistoryError(null);
+      })
+      .catch((err: unknown) => {
+        if (controller.signal.aborted) return;
+        if (err instanceof ApiUnreachableError) setHistorySource("sample");
+        else {
+          setHistorySource("live");
+          setHistoryError(errorMessage(err));
+        }
+      });
+    return () => controller.abort();
+  }, [status, allowed, nonce]);
+
+  async function loadOlder(): Promise<void> {
+    if (cursor === null || historySource !== "live") return;
+    setLoadingMore(true);
+    try {
+      const page = await api.get<SnapshotPage>("/analytics/snapshots", { cursor, limit: PAGE_SIZE });
+      setRows((current) => [...current, ...page.items]);
+      setCursor(page.nextCursor);
+    } catch (err) {
+      setHistoryError(errorMessage(err));
+    } finally {
+      setLoadingMore(false);
+    }
+  }
+
+  /** Manual trigger for the current month (POST /analytics/snapshot). */
+  async function generateSnapshot(): Promise<void> {
+    setGenerating(true);
+    setMessage(null);
+    try {
+      const record = await api.post<SnapshotRecord>("/analytics/snapshot", {});
+      setMessage({ tone: "ok", text: `Snapshot generated for ${monthLabel(record.month)}.` });
+      reload();
+    } catch (err) {
+      setMessage({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setGenerating(false);
+    }
+  }
+
+  if (!allowed) {
+    return (
+      <div className="flex h-full items-center justify-center p-6">
+        <EmptyState
+          title="No access"
+          hint="Analytics needs the analytics.view permission, which your role does not have. Ask an Owner or Admin for access."
+        />
+      </div>
+    );
+  }
+
+  const sampleMode = summary.source === "sample" || historySource === "sample";
+  const view = summary.data;
+  const canGenerate = live && historySource !== "loading";
+
+  return (
+    <div className="h-full overflow-y-auto p-6 scrollbar-thin">
+      <div className="mb-6">
+        <div className="flex items-center gap-3">
+          <h1 className="text-lg font-semibold">Analytics</h1>
+          <OfflineBadge source={sampleMode ? "sample" : historySource} />
+        </div>
+        <p className="mt-1 text-2xs text-text-faint">
+          Monthly rollups of publishing activity · deltas compare the current month with the previous one
+        </p>
+      </div>
+
+      {/* Summary: current month + previous-month deltas */}
+      {summary.source === "loading" ? (
+        <Card className="mb-6 flex items-center gap-2 p-4 text-xs text-text-faint">
+          <Loading size={14} label="Loading summary" /> Loading summary…
+        </Card>
+      ) : summary.error !== null ? (
+        <Card className="mb-6 p-4">
+          <p className="text-xs text-danger">Could not load the monthly summary — {summary.error}</p>
+          <Button variant="outline" size="sm" className="mt-2" onClick={reload}>
+            Retry
+          </Button>
+        </Card>
+      ) : view !== null ? (
+        <Card className="mb-6 p-4">
+          <div className="mb-3 flex items-center justify-between gap-2">
+            <h2 className="text-sm font-semibold">{monthLabel(view.currentMonth)}</h2>
+            <Badge tone="neutral">vs {monthLabel(view.previousMonth)}</Badge>
+          </div>
+          {view.current === null ? (
+            <div className="rounded-md border border-border-subtle bg-surface-2 p-3 text-xs text-text-faint">
+              No snapshot exists for {monthLabel(view.currentMonth)} yet — it is generated on schedule, or
+              immediately via <code className="text-accent">POST /analytics/snapshot</code>.
+            </div>
+          ) : (
+            <>
+              <div className="grid grid-cols-2 gap-2 md:grid-cols-3">
+                {METRICS.map((metric) => (
+                  <MetricCard
+                    key={metric.key}
+                    metric={metric}
+                    value={view.current![metric.key]}
+                    delta={numberDelta(view.deltas, metric.key)}
+                    previousMonth={view.previousMonth}
+                  />
+                ))}
+              </div>
+              <div className="mt-4">
+                <h3 className="mb-2 text-2xs font-medium uppercase tracking-wide text-text-faint">
+                  Publications by provider
+                </h3>
+                <ProviderBreakdown
+                  byProvider={view.current.publicationsByProvider}
+                  deltas={providerDeltas(view.deltas)}
+                  previousMonth={view.previousMonth}
+                />
+              </div>
+              {view.previous === null && (
+                <p className="mt-3 text-2xs text-text-faint">
+                  No snapshot for {monthLabel(view.previousMonth)} — deltas appear once the previous month has one.
+                </p>
+              )}
+            </>
+          )}
+        </Card>
+      ) : null}
+
+      {/* Snapshot history */}
+      <Card className="p-4">
+        <div className="mb-3 flex items-center justify-between">
+          <h2 className="text-sm font-semibold">Snapshot history</h2>
+          {rows.length > 0 && <span className="text-2xs text-text-faint">{rows.length} months</span>}
+        </div>
+
+        {message !== null && (
+          <p className={`mb-3 text-2xs ${message.tone === "ok" ? "text-live" : "text-danger"}`}>{message.text}</p>
+        )}
+
+        {historySource === "loading" ? (
+          <div className="flex items-center gap-2 py-3 text-xs text-text-faint">
+            <Loading size={14} label="Loading snapshots" /> Loading snapshots…
+          </div>
+        ) : historyError !== null && rows.length === 0 ? (
+          <div className="py-2">
+            <p className="text-xs text-danger">Failed to load analytics snapshots — {historyError}</p>
+            <Button variant="outline" size="sm" className="mt-2" onClick={reload}>
+              Retry
+            </Button>
+          </div>
+        ) : rows.length === 0 ? (
+          <>
+            <EmptyState
+              title={sampleMode ? "No analytics data while offline" : "No analytics snapshots yet"}
+              hint={
+                sampleMode
+                  ? "The API is unreachable, so there is no snapshot data to show. Analytics is live-API only — reconnect to see real numbers."
+                  : "Snapshots roll up one row per month. They are generated on schedule, or immediately via POST /analytics/snapshot."
+              }
+            />
+            {!sampleMode && historyError === null && (
+              <div className="flex justify-center pb-2">
+                <Button variant="outline" size="sm" disabled={!canGenerate || generating} onClick={() => void generateSnapshot()}>
+                  {generating ? "Generating…" : "Generate current-month snapshot"}
+                </Button>
+              </div>
+            )}
+          </>
+        ) : (
+          <>
+            {historyError !== null && (
+              <p className="mb-3 text-xs text-danger">Could not load older months — {historyError}</p>
+            )}
+            <div className="rounded-lg border border-border-subtle">
+              <table className="mobile-stack-table w-full text-sm">
+                <thead>
+                  <tr className="border-b border-border-subtle text-left text-2xs text-text-faint">
+                    <th className="px-4 py-2 font-medium">Month</th>
+                    <th className="px-4 py-2 font-medium">Publications</th>
+                    <th className="px-4 py-2 font-medium">Archived</th>
+                    <th className="px-4 py-2 font-medium">Drafts</th>
+                    <th className="px-4 py-2 font-medium">Attempts</th>
+                    <th className="px-4 py-2 font-medium">Failures</th>
+                    <th className="px-4 py-2 font-medium">Channels</th>
+                    <th className="px-4 py-2" />
+                  </tr>
+                </thead>
+                <tbody>
+                  {rows.map((record) => (
+                    <Fragment key={record.id}>
+                      <tr
+                        className="cursor-pointer border-b border-border-subtle transition-colors duration-150 hover:bg-surface-2"
+                        onClick={() => setExpanded(expanded === record.id ? null : record.id)}
+                      >
+                        <td className="px-4 py-2.5 text-xs font-medium">{monthLabel(record.month)}</td>
+                        <td className="px-4 py-2.5 text-xs tabular-nums">{record.publicationsTotal.toLocaleString()}</td>
+                        <td className="px-4 py-2.5 text-xs tabular-nums">{record.postsArchivedTotal.toLocaleString()}</td>
+                        <td className="px-4 py-2.5 text-xs tabular-nums">{record.draftsCreatedTotal.toLocaleString()}</td>
+                        <td className="px-4 py-2.5 text-xs tabular-nums">{record.publishingAttemptsTotal.toLocaleString()}</td>
+                        <td className="px-4 py-2.5 text-xs tabular-nums">
+                          <span className={record.publishFailuresTotal > 0 ? "text-danger" : undefined}>
+                            {record.publishFailuresTotal.toLocaleString()}
+                          </span>
+                        </td>
+                        <td className="px-4 py-2.5 text-xs tabular-nums">{record.activeConnections.toLocaleString()}</td>
+                        <td className="px-4 py-2.5 text-right text-2xs text-text-faint">{expanded === record.id ? "▾" : "▸"}</td>
+                      </tr>
+                      {expanded === record.id && (
+                        <tr className="border-b border-border-subtle bg-bg">
+                          <td colSpan={8} className="px-4 py-3">
+                            <div className="grid grid-cols-2 gap-2 sm:grid-cols-4">
+                              {METRICS.map((metric) => (
+                                <div key={metric.key}>
+                                  <div className="text-2xs text-text-faint">{metric.label}</div>
+                                  <div className="text-sm tabular-nums">{record[metric.key].toLocaleString()}</div>
+                                </div>
+                              ))}
+                            </div>
+                            <div className="mt-3">
+                              <ProviderBreakdown byProvider={record.publicationsByProvider} deltas={null} previousMonth={record.month} />
+                            </div>
+                            <p className="mt-3 text-2xs text-text-faint">
+                              Generated {new Date(record.snapshotCompletedAt).toLocaleString()}
+                            </p>
+                          </td>
+                        </tr>
+                      )}
+                    </Fragment>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+            {historySource === "live" && cursor !== null && (
+              <div className="mt-3 flex justify-center">
+                <Button variant="outline" size="sm" disabled={loadingMore} onClick={() => void loadOlder()}>
+                  {loadingMore ? "Loading…" : "Load older months"}
+                </Button>
+              </div>
+            )}
+          </>
+        )}
+        <p className="mt-3 text-2xs text-text-faint">
+          Snapshots are recomputed per (workspace, month) from source tables — re-running a month overwrites it in place.
+        </p>
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/approvals/page.tsx b/apps/web/src/app/(main)/approvals/page.tsx
new file mode 100644
index 0000000..6f1b928
--- /dev/null
+++ b/apps/web/src/app/(main)/approvals/page.tsx
@@ -0,0 +1,5 @@
+import InboxPage from "../inbox/page";
+
+export default function ApprovalsPage(): React.ReactElement {
+  return <InboxPage defaultSegment="approvals" />;
+}
diff --git a/apps/web/src/app/(main)/archive/page.tsx b/apps/web/src/app/(main)/archive/page.tsx
new file mode 100644
index 0000000..2327468
--- /dev/null
+++ b/apps/web/src/app/(main)/archive/page.tsx
@@ -0,0 +1,139 @@
+"use client";
+
+import { useState } from "react";
+import { isBotConnection } from "../../../lib/connections-client";
+import { Badge, Button, Card } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { EmptyState } from "../../../components/brand/empty-state";
+import { api, errorMessage } from "../../../lib/api-client";
+import { useAuth } from "../../../lib/auth-store";
+import { useApiResource } from "../../../lib/use-api";
+import type { ConnectionSummary, DraftRecord, DraftState } from "../../../lib/api-types";
+
+interface MediaRef { fileId: string; status: string; thumbUrl: string | null; contentType: string }
+interface ArchiveItem {
+  id: string; remoteRef: string; text: string; media: MediaRef[];
+  attribution: { channelTitle?: string | null; channelUsername?: string | null; authorSignature?: string | null; forwardOrigin?: Record<string, unknown> | null };
+  protectedContent: boolean; postedAt: string; revision: number;
+}
+interface Page { items: ArchiveItem[]; nextCursor: string | null }
+const SAMPLE: Page = { items: [{
+  id: "sample", remoteRef: "-100123456789:42", text: "A new channel post appears here for review.",
+  media: [], attribution: { channelTitle: "Example channel", authorSignature: "Editor" },
+  protectedContent: false, postedAt: "2026-10-07T12:00:00.000Z", revision: 1,
+}], nextCursor: null };
+const identity = (page: Page): Page => page;
+const noConnections: ConnectionSummary[] = [];
+const same = (value: ConnectionSummary[]): ConnectionSummary[] => value;
+
+export default function ArchivePage(): React.ReactElement {
+  const { can } = useAuth();
+  const { data, source, error, reload } = useApiResource<Page, Page>("/archive/items", identity, SAMPLE);
+  const { data: connections } = useApiResource<ConnectionSummary[], ConnectionSummary[]>("/connections", same, noConnections);
+  const [more, setMore] = useState<ArchiveItem[]>([]);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [drafts, setDrafts] = useState<Record<string, string>>({});
+  const [draftStates, setDraftStates] = useState<Record<string, DraftState>>({});
+  const [connectionId, setConnectionId] = useState("");
+  const [attribution, setAttribution] = useState(true);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [actionError, setActionError] = useState<string | null>(null);
+  const [notice, setNotice] = useState<string | null>(null);
+  const telegramConnections = connections.filter(isBotConnection);
+  const nextCursor = cursor ?? data.nextCursor;
+  const items = [...data.items, ...more];
+
+  async function createDraft(item: ArchiveItem): Promise<void> {
+    setBusy(item.id); setActionError(null);
+    try {
+      const draft = await api.post<DraftRecord>(`/archive/items/${item.id}/drafts`, {});
+      setDrafts((current) => ({ ...current, [item.id]: draft.id }));
+      setDraftStates((current) => ({ ...current, [item.id]: draft.state }));
+      setNotice("Draft created. Submit it for review, then approve it before amplifying.");
+    } catch (err) { setActionError(errorMessage(err)); }
+    finally { setBusy(null); }
+  }
+  async function submitDraft(item: ArchiveItem): Promise<void> {
+    const draftId = drafts[item.id];
+    if (!draftId) return;
+    setBusy(item.id); setActionError(null);
+    try {
+      const draft = await api.post<DraftRecord>(`/publishing/drafts/${draftId}/submit`);
+      setDraftStates((current) => ({ ...current, [item.id]: draft.state }));
+      setNotice("Submitted for review.");
+    } catch (err) { setActionError(errorMessage(err)); }
+    finally { setBusy(null); }
+  }
+  async function approveDraft(item: ArchiveItem): Promise<void> {
+    const draftId = drafts[item.id];
+    if (!draftId) return;
+    setBusy(item.id); setActionError(null);
+    try {
+      const draft = await api.post<DraftRecord>(`/publishing/drafts/${draftId}/approve`);
+      setDraftStates((current) => ({ ...current, [item.id]: draft.state }));
+      setNotice("Draft approved — it can now be amplified.");
+    } catch (err) { setActionError(errorMessage(err)); }
+    finally { setBusy(null); }
+  }
+  async function amplify(item: ArchiveItem): Promise<void> {
+    const draftId = drafts[item.id];
+    if (!draftId || !connectionId) return;
+    setBusy(item.id); setActionError(null);
+    try {
+      await api.post(`/archive/items/${item.id}/amplify`, { draftId, connectionId, attribution });
+      setNotice("Amplified to Telegram.");
+    } catch (err) { setActionError(errorMessage(err)); }
+    finally { setBusy(null); }
+  }
+  async function loadMore(): Promise<void> {
+    if (!nextCursor) return;
+    setBusy("more");
+    try {
+      const page = await api.get<Page>("/archive/items", { cursor: nextCursor });
+      setMore((current) => [...current, ...page.items]); setCursor(page.nextCursor);
+    } catch (err) { setActionError(errorMessage(err)); }
+    finally { setBusy(null); }
+  }
+
+  return <div className="h-full overflow-y-auto p-4 pb-24 lg:p-6">
+    <div className="mb-5 flex items-center gap-3"><h1 className="text-lg font-semibold">Archive</h1><OfflineBadge source={source} /></div>
+    <p className="mb-4 text-sm text-text-dim">Posts from channels where your Telegram bot is an admin arrive here. Check that you have the right to reuse someone else&apos;s work before sharing it.</p>
+    {error && <p className="mb-3 text-sm text-danger">{error}</p>}
+    {actionError && <p role="alert" className="mb-3 text-sm text-danger">{actionError}</p>}
+    {notice && <p role="status" className="mb-3 text-sm text-live">{notice}</p>}
+    {items.length === 0 && <EmptyState title="No archived posts yet" hint="New channel posts appear after your bot joins a subscribed channel." />}
+    <div className="space-y-3">{items.map((item) => <Card key={item.id} className="p-4">
+      <div className="mb-2 flex flex-wrap items-center gap-2 text-xs text-text-faint">
+        <strong className="text-text">{item.attribution.channelTitle ?? item.attribution.channelUsername ?? item.remoteRef}</strong>
+        {item.attribution.authorSignature && <span>by {item.attribution.authorSignature}</span>}
+        <time dateTime={item.postedAt}>{new Date(item.postedAt).toLocaleString()}</time>
+        {item.revision > 1 && <Badge>edited</Badge>}
+        {item.protectedContent && <Badge tone="warn">amplify unavailable</Badge>}
+      </div>
+      {item.text && <p className="mb-3 whitespace-pre-wrap text-sm">{item.text}</p>}
+      {item.attribution.forwardOrigin && <p className="mb-2 text-xs text-text-faint">Forwarded origin retained in attribution.</p>}
+      {item.media.length > 0 && <div className="mb-3 flex flex-wrap gap-2">{item.media.map((media: MediaRef) => typeof media.thumbUrl === "string" && media.contentType.startsWith("image/")
+        ? <img key={media.fileId} src={media.thumbUrl} alt="Archived Telegram media" className="h-24 w-24 rounded object-cover" />
+        : <span key={media.fileId} className="rounded border border-border p-2 text-xs">{media.status}</span>)}</div>}
+      {source === "live" && <div className="flex flex-wrap items-center gap-2">
+        {can("draft.create") && <Button size="sm" onClick={() => void createDraft(item)} disabled={busy === item.id}>Create draft</Button>}
+        {drafts[item.id] && <>
+          <span className="text-xs text-text-faint">Draft {drafts[item.id]?.slice(0, 8)} · state: {draftStates[item.id] ?? "editing"}</span>
+          {(draftStates[item.id] === undefined || draftStates[item.id] === "editing" || draftStates[item.id] === "rejected") && (
+            <Button size="sm" variant="outline" disabled={busy === item.id} onClick={() => void submitDraft(item)}>Submit</Button>
+          )}
+          {draftStates[item.id] === "in_review" && can("approval.grant") && (
+            <Button size="sm" variant="outline" disabled={busy === item.id} onClick={() => void approveDraft(item)}>Approve</Button>
+          )}
+          <select aria-label="Telegram target" value={connectionId} onChange={(event) => setConnectionId(event.target.value)} className="rounded border border-border bg-surface p-2 text-xs">
+            <option value="">Choose target</option>{telegramConnections.map((c) => <option key={c.id} value={c.id}>{c.channelId}</option>)}
+          </select>
+          <label className="flex items-center gap-1 text-xs"><input type="checkbox" checked={attribution} onChange={(event) => setAttribution(event.target.checked)} /> Include attribution</label>
+          {can("publication.schedule") && <Button size="sm" disabled={item.protectedContent || !connectionId || busy === item.id || draftStates[item.id] !== "approved"} title={draftStates[item.id] !== "approved" ? "Submit and approve the draft first" : undefined} onClick={() => void amplify(item)}>Amplify approved draft</Button>}
+        </>}
+      </div>}
+    </Card>)}</div>
+    {nextCursor && source === "live" && <Button className="mt-4" disabled={busy === "more"} onClick={() => void loadMore()}>Load more</Button>}
+    {source === "live" && <button type="button" onClick={() => { setMore([]); setCursor(null); reload(); }} className="mt-4 block text-xs text-text-faint underline">Refresh archive</button>}
+  </div>;
+}
diff --git a/apps/web/src/app/(main)/audit/page.tsx b/apps/web/src/app/(main)/audit/page.tsx
new file mode 100644
index 0000000..2a7b486
--- /dev/null
+++ b/apps/web/src/app/(main)/audit/page.tsx
@@ -0,0 +1,267 @@
+"use client";
+
+import { Fragment, useEffect, useState } from "react";
+import { Badge, Button } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { AUDIT_ENTRIES, ageLabel } from "../../../lib/fixtures";
+import { api, ApiUnreachableError, errorMessage } from "../../../lib/api-client";
+import type { AuditEntryDto, AuditPage as AuditPageDto } from "../../../lib/api-types";
+import { useAuth } from "../../../lib/auth-store";
+import type { DataSource } from "../../../lib/use-api";
+import { Loading } from "../../../components/brand/loading";
+
+type DiffValue = string | number | boolean | null | unknown[] | Record<string, unknown>;
+
+function DiffCell({ label, value }: { label: string; value: DiffValue }): React.ReactElement {
+  return (
+    <div className="grid grid-cols-[110px_1fr] gap-2 text-xs">
+      <span className="text-text-faint">{label}</span>
+      <span className="font-mono text-text-dim">{JSON.stringify(value)}</span>
+    </div>
+  );
+}
+
+function DiffViewer({ diff }: { diff: Record<string, unknown> }): React.ReactElement {
+  return (
+    <div className="space-y-1.5 rounded-md border border-border-subtle bg-surface-2 p-3">
+      {Object.entries(diff).map(([key, value]) => {
+        if (Array.isArray(value) && value.length === 2 && typeof value[0] !== "object") {
+          return (
+            <div key={key} className="grid grid-cols-[110px_1fr] gap-2 text-xs">
+              <span className="text-text-faint">{key}</span>
+              <span className="font-mono">
+                <span className="text-removed line-through">{JSON.stringify(value[0])}</span>
+                <span className="mx-1 text-text-faint">→</span>
+                <span className="text-added">{JSON.stringify(value[1])}</span>
+              </span>
+            </div>
+          );
+        }
+        return <DiffCell key={key} label={key} value={value as DiffValue} />;
+      })}
+    </div>
+  );
+}
+
+interface AuditRow {
+  id: string;
+  actor: string;
+  action: string;
+  targetType: string;
+  target: string;
+  minutes: number;
+  diff: Record<string, unknown> | null;
+}
+
+interface FilterOption {
+  value: string;
+  label: string;
+}
+
+const PAGE_SIZE = 25;
+const ALL = "all";
+
+function fromApi(e: AuditEntryDto): AuditRow {
+  return {
+    id: e.id,
+    actor: e.actorEmail ?? (e.actorUserId === null ? "system" : e.actorUserId),
+    action: e.action,
+    targetType: e.targetType,
+    target: e.targetId,
+    minutes: Math.max(0, Math.floor((Date.now() - Date.parse(e.at)) / 60_000)),
+    diff: e.diff,
+  };
+}
+
+const SAMPLE_ROWS: AuditRow[] = AUDIT_ENTRIES.map((e) => ({ ...e, id: String(e.id) }));
+
+function csvCell(value: string | number | null): string {
+  const text = value === null ? "" : String(value);
+  return /[",\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
+}
+
+function toCsv(rows: AuditRow[]): string {
+  const header = ["id", "actor", "action", "target_type", "target", "minutes_ago", "diff"];
+  const lines = rows.map((e) =>
+    [e.id, e.actor, e.action, e.targetType, e.target, e.minutes, e.diff === null ? null : JSON.stringify(e.diff)].map(csvCell).join(","));
+  return [header.join(","), ...lines].join("\n");
+}
+
+function downloadCsv(rows: AuditRow[]): void {
+  const blob = new Blob([toCsv(rows)], { type: "text/csv;charset=utf-8" });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = `audit-${new Date().toISOString().slice(0, 10)}.csv`;
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  URL.revokeObjectURL(url);
+}
+
+export default function AuditPage(): React.ReactElement {
+  const { status } = useAuth();
+  const [actor, setActor] = useState(ALL);
+  const [action, setAction] = useState(ALL);
+  const [expanded, setExpanded] = useState<string | null>(null);
+  const [source, setSource] = useState<DataSource>("loading");
+  const [rows, setRows] = useState<AuditRow[]>([]);
+  const [cursor, setCursor] = useState<string | null>(null);
+  const [actorOptions, setActorOptions] = useState<FilterOption[]>([]);
+  const [actionOptions, setActionOptions] = useState<string[]>([]);
+  const [error, setError] = useState<string | null>(null);
+  const [loadingMore, setLoadingMore] = useState(false);
+
+  // Live: filters are applied server-side and pages are fetched by seq cursor.
+  useEffect(() => {
+    if (status === "loading") return;
+    if (status !== "authenticated") {
+      setSource("sample");
+      return;
+    }
+    const controller = new AbortController();
+    api
+      .get<AuditPageDto>("/audit", { action: action === ALL ? undefined : action, actor: actor === ALL ? undefined : actor, limit: PAGE_SIZE }, controller.signal)
+      .then((page) => {
+        setRows(page.entries.map(fromApi));
+        setCursor(page.nextCursor);
+        setActionOptions(page.facets.actions);
+        setActorOptions(page.facets.actors.map((a) => ({ value: a.id ?? "system", label: a.email ?? (a.id === null ? "system" : a.id) })));
+        setSource("live");
+        setError(null);
+      })
+      .catch((err: unknown) => {
+        if (controller.signal.aborted) return;
+        if (err instanceof ApiUnreachableError) setSource("sample");
+        else {
+          setSource("live");
+          setError(errorMessage(err));
+        }
+      });
+    return () => controller.abort();
+  }, [status, action, actor]);
+
+  async function loadMore(): Promise<void> {
+    if (cursor === null) return;
+    setLoadingMore(true);
+    try {
+      const page = await api.get<AuditPageDto>("/audit", {
+        action: action === ALL ? undefined : action,
+        actor: actor === ALL ? undefined : actor,
+        before: cursor,
+        limit: PAGE_SIZE,
+      });
+      setRows((current) => [...current, ...page.entries.map(fromApi)]);
+      setCursor(page.nextCursor);
+    } catch (err) {
+      setError(errorMessage(err));
+    } finally {
+      setLoadingMore(false);
+    }
+  }
+
+  const live = source === "live";
+  const actors: FilterOption[] = live
+    ? actorOptions
+    : [...new Set(SAMPLE_ROWS.map((e) => e.actor))].map((a) => ({ value: a, label: a }));
+  const actions = live ? actionOptions : [...new Set(SAMPLE_ROWS.map((e) => e.action))];
+  const visible = live
+    ? rows
+    : SAMPLE_ROWS.filter((e) => (actor === ALL || e.actor === actor) && (action === ALL || e.action === action));
+
+  return (
+    <div className="h-full overflow-y-auto p-6 scrollbar-thin">
+      <div className="mb-6 flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <h1 className="text-lg font-semibold">Audit trail</h1>
+          <OfflineBadge source={source} />
+        </div>
+        <button
+          type="button"
+          disabled={source === "loading" || visible.length === 0}
+          onClick={() => downloadCsv(visible)}
+          className="rounded-md border border-border px-3 py-1.5 text-xs text-text-dim transition-colors duration-150 hover:border-accent hover:text-accent disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:border-border disabled:hover:text-text-dim"
+        >
+          Export CSV
+        </button>
+      </div>
+
+      <div className="mb-4 flex flex-wrap gap-3">
+        <select value={actor} onChange={(e) => setActor(e.target.value)} className="rounded-md border border-border bg-surface-2 px-2 py-1.5 text-xs">
+          <option value={ALL}>All actors</option>
+          {actors.map((a) => (
+            <option key={a.value} value={a.value}>{a.label}</option>
+          ))}
+        </select>
+        <select value={action} onChange={(e) => setAction(e.target.value)} className="rounded-md border border-border bg-surface-2 px-2 py-1.5 text-xs">
+          <option value={ALL}>All actions</option>
+          {actions.map((a) => (
+            <option key={a} value={a}>{a}</option>
+          ))}
+        </select>
+        <span className="ml-auto self-center text-2xs text-text-faint">hash-chained · tamper-evident</span>
+      </div>
+
+      {error !== null && <p className="mb-3 text-xs text-danger">{error}</p>}
+
+      <div className="rounded-lg border border-border-subtle">
+        <table className="mobile-stack-table w-full text-sm">
+          <thead>
+            <tr className="border-b border-border-subtle text-left text-2xs text-text-faint">
+              <th className="px-4 py-2 font-medium">Actor</th>
+              <th className="px-4 py-2 font-medium">Action</th>
+              <th className="px-4 py-2 font-medium">Target</th>
+              <th className="px-4 py-2 font-medium">When</th>
+              <th className="px-4 py-2" />
+            </tr>
+          </thead>
+          <tbody>
+            {source === "loading" && (
+              <tr><td colSpan={5} className="px-4 py-3"><span className="inline-flex items-center gap-2 text-xs text-text-faint"><Loading size={14} label="Loading audit trail" /> Loading audit trail…</span></td></tr>
+            )}
+            {source !== "loading" && visible.length === 0 && (
+              error !== null
+                ? <tr><td colSpan={5} className="px-4 py-3 text-xs text-danger">Failed to load audit entries — {error}</td></tr>
+                : <tr><td colSpan={5} className="px-4 py-3 text-xs text-text-faint">No audit entries match.</td></tr>
+            )}
+            {source !== "loading" && visible.map((e) => (
+              <Fragment key={e.id}>
+                <tr
+                  className="cursor-pointer border-b border-border-subtle transition-colors duration-150 hover:bg-surface-2"
+                  onClick={() => setExpanded(expanded === e.id ? null : e.id)}
+                >
+                  <td className="px-4 py-2.5 text-xs">{e.actor}</td>
+                  <td className="px-4 py-2.5"><code className="text-xs text-accent">{e.action}</code></td>
+                  <td className="px-4 py-2.5 text-xs text-text-dim">{e.targetType}:{e.target}</td>
+                  <td className="px-4 py-2.5 text-2xs text-text-faint">{ageLabel(e.minutes)} ago</td>
+                  <td className="px-4 py-2.5 text-right text-2xs text-text-faint">{expanded === e.id ? "▾" : "▸"}</td>
+                </tr>
+                {expanded === e.id && (
+                  <tr className="border-b border-border-subtle bg-bg">
+                    <td colSpan={5} className="px-4 py-3">
+                      {e.diff === null ? (
+                        <span className="text-xs text-text-faint">no payload</span>
+                      ) : (
+                        <DiffViewer diff={e.diff} />
+                      )}
+                    </td>
+                  </tr>
+                )}
+              </Fragment>
+            ))}
+          </tbody>
+        </table>
+      </div>
+      {live && cursor !== null && (
+        <div className="mt-3 flex justify-center">
+          <Button variant="outline" size="sm" disabled={loadingMore} onClick={() => void loadMore()}>
+            {loadingMore ? "Loading…" : "Load older entries"}
+          </Button>
+        </div>
+      )}
+      <p className="mt-3 text-2xs text-text-faint">
+        Secret-shaped keys render as <Badge tone="danger">[REDACTED]</Badge> by construction — they never enter the chain.
+      </p>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/calendar/page.tsx b/apps/web/src/app/(main)/calendar/page.tsx
new file mode 100644
index 0000000..f27508b
--- /dev/null
+++ b/apps/web/src/app/(main)/calendar/page.tsx
@@ -0,0 +1,291 @@
+"use client";
+
+import { useEffect, useMemo, useState } from "react";
+import { Badge, Button } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { EmptyState } from "../../../components/brand/empty-state";
+import { LoadingPanel } from "../../../components/brand/loading";
+import { api, errorMessage } from "../../../lib/api-client";
+import { PLATFORMS } from "../../../lib/platforms";
+import { useAuth } from "../../../lib/auth-store";
+import { useApiResource } from "../../../lib/use-api";
+import type { ConnectionSummary, DraftRecord } from "../../../lib/api-types";
+
+/**
+ * Calendar = the scheduled slice of the publishing pipeline. There is no
+ * dedicated schedule-list endpoint, so this reads the same draft list the
+ * approvals queue uses (`GET /publishing/drafts?state=scheduled`) and joins
+ * each draft to its target connection for a readable label.
+ */
+
+interface ScheduledRow {
+  id: string;
+  text: string;
+  /** ISO — the queue's `post.scheduledAt` when recorded, else the draft's last update. */
+  publishAt: string;
+  fromScheduledAt: boolean;
+  targetLabel: string;
+}
+
+interface DayGroup {
+  key: number;
+  label: string;
+  rows: ScheduledRow[];
+}
+
+type Notice = { tone: "ok" | "error"; text: string };
+
+const identity = (drafts: DraftRecord[]): DraftRecord[] => drafts;
+const same = (connections: ConnectionSummary[]): ConnectionSummary[] => connections;
+const noConnections: ConnectionSummary[] = [];
+
+/** Offline / unauthenticated fallback — one future-dated row so the layout is visible. */
+const SAMPLE: DraftRecord[] = [
+  {
+    id: "sample-scheduled",
+    workspaceId: "sample",
+    authorUserId: "sample-author",
+    post: {
+      text: "Sample scheduled post — the weekly roundup goes out to every connected channel.",
+      mediaAssetIds: [],
+      visibility: "public",
+      providerMetadata: { connectionId: "sample-connection" },
+      scheduledAt: new Date(Date.now() + 3_600_000).toISOString(),
+    },
+    state: "scheduled",
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  },
+];
+
+function connectionIdOf(draft: DraftRecord): string | null {
+  const id = draft.post.providerMetadata.connectionId;
+  return typeof id === "string" && id !== "" ? id : null;
+}
+
+function labelFor(connection: ConnectionSummary | undefined, id: string): string {
+  if (connection === undefined) return `unknown connection ${id.slice(0, 8)}`;
+  const handle = typeof connection.fields.handle === "string" ? connection.fields.handle : connection.channelId;
+  return `${PLATFORMS[connection.provider]?.displayName ?? connection.provider} · ${handle}`;
+}
+
+function toRows(drafts: DraftRecord[], connections: ConnectionSummary[]): ScheduledRow[] {
+  return drafts
+    .map((draft): ScheduledRow => {
+      const connectionId = connectionIdOf(draft);
+      const connection = connectionId === null ? undefined : connections.find((c) => c.id === connectionId);
+      return {
+        id: draft.id,
+        text: draft.post.text,
+        publishAt: draft.post.scheduledAt ?? draft.updatedAt,
+        fromScheduledAt: draft.post.scheduledAt !== undefined,
+        targetLabel: connectionId === null ? "no target recorded" : labelFor(connection, connectionId),
+      };
+    })
+    .sort((a, b) => Date.parse(a.publishAt) - Date.parse(b.publishAt));
+}
+
+/** Group by the viewer's local calendar day — the list equivalent of a week view. */
+function groupByDay(rows: ScheduledRow[]): DayGroup[] {
+  const groups = new Map<number, ScheduledRow[]>();
+  for (const row of rows) {
+    const date = new Date(row.publishAt);
+    const key = new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+    const bucket = groups.get(key);
+    if (bucket === undefined) groups.set(key, [row]);
+    else bucket.push(row);
+  }
+  return [...groups.entries()].map(([key, dayRows]) => ({
+    key,
+    label: new Date(key).toLocaleDateString(undefined, { weekday: "long", month: "short", day: "numeric" }),
+    rows: dayRows,
+  }));
+}
+
+const localTime = (iso: string): string =>
+  new Date(iso).toLocaleTimeString(undefined, { hour: "2-digit", minute: "2-digit" });
+
+const utcTime = (iso: string): string => `${new Date(iso).toISOString().slice(0, 16).replace("T", " ")} UTC`;
+
+function relativeLabel(iso: string, now: number): { text: string; overdue: boolean } {
+  const delta = Date.parse(iso) - now;
+  const minutes = Math.max(0, Math.round(Math.abs(delta) / 60_000));
+  const span =
+    minutes < 60
+      ? `${minutes}m`
+      : minutes < 1_440
+        ? `${Math.floor(minutes / 60)}h ${minutes % 60}m`
+        : `${Math.floor(minutes / 1_440)}d ${Math.floor((minutes % 1_440) / 60)}h`;
+  return { text: delta >= 0 ? `in ${span}` : `${span} overdue`, overdue: delta < 0 };
+}
+
+export default function CalendarPage(): React.ReactElement {
+  const { can } = useAuth();
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, SAMPLE, {
+    state: "scheduled",
+    limit: 100,
+  });
+  const connections = useApiResource<ConnectionSummary[], ConnectionSummary[]>("/connections", same, noConnections);
+  const live = drafts.source === "live";
+  const canSchedule = can("publication.schedule");
+
+  const [cancelling, setCancelling] = useState<ScheduledRow | null>(null);
+  const [busyId, setBusyId] = useState<string | null>(null);
+  const [notice, setNotice] = useState<Notice | null>(null);
+  const [now, setNow] = useState<number>(Date.now());
+
+  // Same cadence as the streams wall: refresh on a 30s timer.
+  useEffect(() => {
+    const timer = setInterval(() => {
+      drafts.reload();
+      connections.reload();
+      setNow(Date.now());
+    }, 30_000);
+    return () => clearInterval(timer);
+  }, [drafts.reload, connections.reload]);
+
+  const rows = useMemo(() => toRows(drafts.data, connections.data), [drafts.data, connections.data]);
+  const groups = useMemo(() => groupByDay(rows), [rows]);
+
+  async function cancel(row: ScheduledRow): Promise<void> {
+    if (!live) {
+      setNotice({ tone: "error", text: "Offline — sample mode, nothing was sent." });
+      setCancelling(null);
+      return;
+    }
+    setBusyId(row.id);
+    setNotice(null);
+    try {
+      const draft = await api.del<DraftRecord>(`/publishing/drafts/${row.id}/schedule`);
+      drafts.setData((current) => current.filter((item) => item.id !== row.id));
+      setNotice({ tone: "ok", text: `Schedule cancelled — the draft is back to ${draft.state.replace("_", " ")}.` });
+      setCancelling(null);
+      drafts.reload();
+    } catch (err) {
+      setNotice({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setBusyId(null);
+    }
+  }
+
+  return (
+    <div className="h-full overflow-y-auto p-4 pb-24 lg:p-6">
+      <div className="mb-1 flex items-center gap-3">
+        <h1 className="text-lg font-semibold">Calendar</h1>
+        <OfflineBadge source={drafts.source} />
+        <span className="ml-auto text-2xs text-text-faint">
+          {rows.length} scheduled · refreshes every 30s
+        </span>
+        <Button size="sm" variant="ghost" onClick={() => { drafts.reload(); connections.reload(); setNow(Date.now()); }}>
+          Refresh
+        </Button>
+      </div>
+      <p className="mb-4 text-xs text-text-faint">
+        Publications queued by the publishing pipeline, grouped by your local day. Each row shows the local time with the
+        UTC time beside it; execution state lives in the audit log, not this list.
+      </p>
+
+      {notice !== null && (
+        <p role="status" className={`mb-3 text-xs ${notice.tone === "ok" ? "text-live" : "text-danger"}`}>
+          {notice.text}
+        </p>
+      )}
+      {drafts.error !== null && <p role="alert" className="mb-3 text-xs text-danger">{drafts.error}</p>}
+      {!live && drafts.error === null && (
+        <p className="mb-3 text-xs text-text-faint">Offline sample — connect to the API to see and cancel real schedules.</p>
+      )}
+
+      {drafts.source === "loading" && <LoadingPanel label="Loading scheduled publications…" />}
+      {drafts.source !== "loading" && rows.length === 0 && drafts.error === null && (
+        <EmptyState
+          title="Nothing scheduled"
+          hint="Queue a post from Compose (or approve one with a schedule time) and it appears here until it publishes or is cancelled."
+        />
+      )}
+      {drafts.source !== "loading" &&
+        groups.map((group) => (
+          <section key={group.key} className="mb-6">
+            <h2 className="mb-2 flex items-center gap-2 text-xs font-semibold uppercase tracking-wider text-text-faint">
+              {group.label}
+              <span className="rounded-full bg-surface-2 px-2 py-0.5 text-2xs font-medium normal-case tracking-normal text-text-dim">
+                {group.rows.length}
+              </span>
+            </h2>
+            <ul className="divide-y divide-border-subtle rounded-lg border border-border-subtle bg-surface">
+              {group.rows.map((row) => {
+                const relative = relativeLabel(row.publishAt, now);
+                return (
+                  <li key={row.id} className="flex flex-col gap-2 p-4 lg:flex-row lg:items-start lg:gap-4">
+                    <div className="flex w-44 shrink-0 flex-col gap-0.5">
+                      <span className="font-mono text-sm text-text">{localTime(row.publishAt)}</span>
+                      <span className="text-2xs text-text-faint">{utcTime(row.publishAt)}</span>
+                      <span className={`text-2xs ${relative.overdue ? "text-warn" : "text-text-faint"}`}>{relative.text}</span>
+                    </div>
+                    <div className="min-w-0 flex-1">
+                      <p className="line-clamp-2 whitespace-pre-wrap break-words text-sm text-text">{row.text}</p>
+                      <div className="mt-1.5 flex flex-wrap items-center gap-2 text-2xs text-text-faint">
+                        <Badge tone="accent">scheduled</Badge>
+                        <span>{row.targetLabel}</span>
+                        {!row.fromScheduledAt && (
+                          <span title="The queue keeps its own timestamp, but the API only exposes the draft — this is the draft's last update.">
+                            time from last draft update
+                          </span>
+                        )}
+                      </div>
+                    </div>
+                    <div className="flex shrink-0 items-center">
+                      {live && canSchedule && (
+                        <Button
+                          variant="danger"
+                          size="sm"
+                          disabled={busyId !== null}
+                          onClick={() => { setNotice(null); setCancelling(row); }}
+                        >
+                          Cancel
+                        </Button>
+                      )}
+                      {live && !canSchedule && (
+                        <span className="text-2xs text-text-faint" title="Cancelling a schedule requires the publication.schedule permission.">
+                          cancelling needs publication.schedule
+                        </span>
+                      )}
+                    </div>
+                  </li>
+                );
+              })}
+            </ul>
+          </section>
+        ))}
+
+      {cancelling !== null && (
+        <div
+          className="fixed inset-0 z-40 flex items-center justify-center bg-black/60"
+          onClick={() => { if (busyId === null) setCancelling(null); }}
+        >
+          <div
+            className="w-[480px] max-w-[90vw] rounded-lg border border-border bg-surface p-4 shadow-2xl"
+            onClick={(e: React.MouseEvent) => e.stopPropagation()}
+          >
+            <h3 className="text-sm font-semibold">Cancel this scheduled publication?</h3>
+            <p className="mt-1 text-2xs text-text-faint">
+              {utcTime(cancelling.publishAt)} · {cancelling.targetLabel}
+            </p>
+            <p className="mt-3 max-h-24 overflow-y-auto whitespace-pre-wrap break-words rounded-md border border-border-subtle bg-surface-2 p-2 text-xs leading-relaxed text-text-dim scrollbar-thin">
+              {cancelling.text}
+            </p>
+            <p className="mt-3 text-xs text-text-dim">
+              Nothing is published. The draft returns to editing so it can be rescheduled or changed, and the cancellation
+              is recorded in the audit log.
+            </p>
+            <div className="mt-4 flex justify-end gap-2">
+              <Button variant="ghost" disabled={busyId !== null} onClick={() => setCancelling(null)}>Keep it</Button>
+              <Button variant="danger" disabled={busyId !== null} onClick={() => void cancel(cancelling)}>
+                {busyId === cancelling.id ? "Cancelling…" : "Cancel publication"}
+              </Button>
+            </div>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/compose/page.tsx b/apps/web/src/app/(main)/compose/page.tsx
new file mode 100644
index 0000000..6904ebd
--- /dev/null
+++ b/apps/web/src/app/(main)/compose/page.tsx
@@ -0,0 +1,324 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import { useEditor, EditorContent } from "@tiptap/react";
+import StarterKit from "@tiptap/starter-kit";
+import Placeholder from "@tiptap/extension-placeholder";
+import CharacterCount from "@tiptap/extension-character-count";
+import { Badge, Button, Input } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { MOCK_TARGETS, PLATFORMS } from "../../../lib/platforms";
+import { api, errorMessage } from "../../../lib/api-client";
+import type { ConnectionSummary, DraftPost, DraftRecord, DraftState, ScheduledPublicationRecord, Visibility } from "../../../lib/api-types";
+import { useAuth } from "../../../lib/auth-store";
+import { useApiResource } from "../../../lib/use-api";
+import { Sheet } from "../../../components/mobile/sheet";
+
+/** A publish target: a real connection when live, a fixture platform when offline. */
+interface Target {
+  key: string;
+  provider: string;
+  label: string;
+}
+
+function connectionTargets(connections: ConnectionSummary[]): Target[] {
+  return connections.map((c) => {
+    const handle = typeof c.fields.handle === "string" ? c.fields.handle : c.channelId;
+    return { key: c.id, provider: c.provider, label: `${PLATFORMS[c.provider]?.displayName ?? c.provider} · ${handle}` };
+  });
+}
+
+const SAMPLE_TARGETS: Target[] = MOCK_TARGETS.map((t) => ({ key: t, provider: t, label: PLATFORMS[t]?.displayName ?? t }));
+
+const identity = <T,>(value: T): T => value;
+const NO_DRAFTS: DraftRecord[] = [];
+
+const STATE_TONE: Record<DraftState, "neutral" | "accent" | "live" | "warn" | "danger"> = {
+  editing: "neutral",
+  in_review: "warn",
+  approved: "accent",
+  rejected: "danger",
+  scheduled: "accent",
+  published: "live",
+};
+
+type Notice = { tone: "ok" | "error"; text: string };
+
+export default function ComposePage(): React.ReactElement {
+  const router = useRouter();
+  const { can } = useAuth();
+  const targetsResource = useApiResource<ConnectionSummary[], Target[]>("/connections", connectionTargets, SAMPLE_TARGETS);
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, NO_DRAFTS, { limit: 10 });
+  const live = targetsResource.source === "live";
+  const available = targetsResource.data;
+
+  const [picked, setPicked] = useState<string[] | null>(null);
+  const [scheduledAt, setScheduledAt] = useState("");
+  const [visibility, setVisibility] = useState<Visibility>("public");
+  const [approval, setApproval] = useState("draft");
+  const [busy, setBusy] = useState(false);
+  const [notice, setNotice] = useState<Notice | null>(null);
+  const [scheduleOpen, setScheduleOpen] = useState(false);
+  const [previewOpen, setPreviewOpen] = useState(false);
+  const [keyboardOffset, setKeyboardOffset] = useState(0);
+  const [media, setMedia] = useState<Array<{ name: string; url: string; alt: string }>>([]);
+  const mediaRef = useRef(media);
+  mediaRef.current = media;
+
+  // Default selection: the first available target, until the user picks.
+  const targets = (picked ?? available.slice(0, 1).map((t) => t.key)).filter((k) => available.some((t) => t.key === k));
+  const selected = available.filter((t) => targets.includes(t.key));
+  const limit = selected.length === 0 ? 500 : Math.min(...selected.map((t) => PLATFORMS[t.provider]?.charLimit ?? 500));
+
+  const editor = useEditor({
+    extensions: [
+      StarterKit,
+      Placeholder.configure({ placeholder: "What's shipping? (bold **so** / heading # supported)" }),
+      CharacterCount,
+    ],
+    content: "",
+    immediatelyRender: false,
+    // Tiptap v3 no longer re-renders per keystroke by default; the char counter,
+    // previews and button enablement all read editor state during render.
+    shouldRerenderOnTransaction: true,
+  });
+
+  const chars = editor?.storage.characterCount.characters() ?? 0;
+  const over = chars > limit;
+  const mediaBlocked = media.length > 0;
+  useEffect(() => {
+    const viewport = window.visualViewport;
+    if (!viewport) return;
+    const update = (): void => setKeyboardOffset(Math.max(0, Math.round(window.innerHeight - viewport.height - viewport.offsetTop)));
+    update();
+    viewport.addEventListener("resize", update);
+    viewport.addEventListener("scroll", update);
+    return () => { viewport.removeEventListener("resize", update); viewport.removeEventListener("scroll", update); };
+  }, []);
+  useEffect(() => {
+    if (!editor) return;
+    const params = new URLSearchParams(window.location.search);
+    const text = params.get("text");
+    if (text) editor.commands.setContent(text);
+    const requested = params.get("targets")?.split(",").filter(Boolean);
+    if (requested?.length) setPicked(requested);
+  }, [editor]);
+  useEffect(() => () => { mediaRef.current.forEach((item) => URL.revokeObjectURL(item.url)); }, []);
+
+  function postFor(providerMetadata: Record<string, unknown>): DraftPost {
+    return {
+      text: editor?.getText() ?? "",
+      mediaAssetIds: [],
+      visibility,
+      providerMetadata,
+      ...(scheduledAt !== "" ? { scheduledAt: new Date(scheduledAt).toISOString() } : {}),
+    };
+  }
+
+  async function run(action: () => Promise<string>): Promise<void> {
+    if (!live) {
+      setNotice({ tone: "error", text: "Offline — sample mode, nothing was sent." });
+      return;
+    }
+    setBusy(true);
+    setNotice(null);
+    try {
+      setNotice({ tone: "ok", text: await action() });
+      drafts.reload();
+    } catch (err) {
+      setNotice({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const saveDraft = (): Promise<void> =>
+    run(async () => {
+      await api.post<DraftRecord>("/publishing/drafts", { post: postFor({ targetConnectionIds: targets }) });
+      return "Draft saved.";
+    });
+
+  /**
+   * A scheduled publication binds one draft to one connection (UNIQUE draft_id),
+   * so multi-target posts become one draft per target. Each runs the pipeline as
+   * far as the caller's permissions allow: create → submit → approve → schedule.
+   */
+  const publish = (): Promise<void> =>
+    run(async () => {
+      const stopAtReview = approval === "review" || !can("approval.grant");
+      const canSchedule = can("publication.schedule");
+      const publishAt = scheduledAt !== "" ? new Date(scheduledAt).toISOString() : new Date().toISOString();
+      const outcomes: string[] = [];
+      for (const target of selected) {
+        const draft = await api.post<DraftRecord>("/publishing/drafts", { post: postFor({ connectionId: target.key }) });
+        await api.post<DraftRecord>(`/publishing/drafts/${draft.id}/submit`);
+        if (stopAtReview) {
+          outcomes.push(`${target.label}: submitted for review`);
+          continue;
+        }
+        await api.post<DraftRecord>(`/publishing/drafts/${draft.id}/approve`);
+        if (!canSchedule) {
+          outcomes.push(`${target.label}: approved (you lack publication.schedule)`);
+          continue;
+        }
+        await api.post<ScheduledPublicationRecord>(`/publishing/drafts/${draft.id}/schedule`, { connectionId: target.key, publishAt });
+        outcomes.push(`${target.label}: ${scheduledAt !== "" ? `scheduled for ${new Date(publishAt).toLocaleString()}` : "queued to publish now"}`);
+      }
+      return outcomes.join(" · ");
+    });
+
+  return (
+    <div className="flex min-h-full min-w-0 pb-40 lg:h-full lg:pb-0">
+      <div className="flex min-w-0 flex-1 flex-col p-4 lg:p-6">
+        <div className="mb-4 flex items-center gap-3">
+          <h1 className="text-lg font-semibold">Compose</h1>
+          <OfflineBadge source={targetsResource.source} />
+        </div>
+
+        <div className="mb-4 flex items-center gap-2 overflow-x-auto pb-2 lg:flex-wrap lg:overflow-visible">
+          {live && available.length === 0 && (
+            <span className="text-xs text-text-faint">No channels connected — add one under Channels to publish.</span>
+          )}
+          {available.map((t) => {
+            const active = targets.includes(t.key);
+            return (
+              <button
+                key={t.key}
+                onClick={() => setPicked(active ? targets.filter((x) => x !== t.key) : [...targets, t.key])}
+                className={`min-h-11 shrink-0 rounded-full border px-3 py-1 text-xs font-medium transition-colors duration-150 ${
+                  active ? "border-accent bg-accent-dim text-accent" : "border-border text-text-dim hover:border-text-faint"
+                }`}
+              >
+                {t.label} · {PLATFORMS[t.provider]?.charLimit ?? 500}
+              </button>
+            );
+          })}
+        </div>
+
+        <div className="min-h-[220px] flex-1 overflow-y-auto rounded-lg border border-border-subtle bg-surface p-4 scrollbar-thin">
+          <EditorContent editor={editor} className="prose-invert max-w-none text-sm [&_.ProseMirror]:min-h-[180px] [&_.ProseMirror]:outline-none [&_.ProseMirror_p.is-editor-empty:first-child::before]:content-[attr(data-placeholder)] [&_.ProseMirror_p.is-editor-empty:first-child::before]:text-text-faint [&_.ProseMirror_p.is-editor-empty:first-child::before]:float-left [&_.ProseMirror_p.is-editor-empty:first-child::before]:h-0 [&_.ProseMirror_p.is-editor-empty:first-child::before]:pointer-events-none" />
+        </div>
+
+        <div className="mt-3 lg:hidden">
+          <div className="flex items-center gap-3"><div className={`flex h-11 w-11 shrink-0 items-center justify-center rounded-full border-4 text-xs font-bold ${over ? "border-danger text-danger" : chars >= limit * 0.9 ? "border-warn text-warn" : "border-accent text-accent"}`}>{Math.max(0, limit - chars)}</div><div className="min-w-0 flex-1 overflow-x-auto"><div className="flex gap-2">{selected.map((target) => { const max = PLATFORMS[target.provider]?.charLimit ?? 500; return <button key={target.key} type="button" onClick={() => setPreviewOpen(true)} className={`min-h-11 shrink-0 rounded-md border px-3 text-xs ${chars > max ? "border-danger text-danger" : "border-border text-text-dim"}`}>{PLATFORMS[target.provider]?.displayName ?? target.provider} {chars}/{max}</button>; })}</div></div></div>
+          {media.length > 0 && <div className="mt-2 flex gap-2 overflow-x-auto">{media.map((item) => <div key={item.url} className="w-28 shrink-0 rounded-md border border-border p-2"><div className="h-16 overflow-hidden rounded bg-surface-2"><img src={item.url} alt={item.alt || item.name} className="h-full w-full object-cover" /></div><input aria-label={`Alt text for ${item.name}`} value={item.alt} onChange={(event) => setMedia((current) => current.map((value) => value.url === item.url ? { ...value, alt: event.target.value } : value))} placeholder="ALT text" className="mt-1 min-h-11 w-full bg-transparent text-2xs outline-none" /><span className={`text-2xs ${item.alt ? "text-live" : "text-warn"}`}>{item.alt ? "ALT ready" : "Add ALT"}</span><button type="button" className="min-h-11 w-full text-2xs text-danger" onClick={() => { URL.revokeObjectURL(item.url); setMedia((current) => current.filter((value) => value.url !== item.url)); }}>Remove</button></div>)}</div>}
+          {mediaBlocked && <p className="mt-2 text-xs text-warn">Media upload is not available in the publishing API yet. Remove previews to save or post text.</p>}
+          <button type="button" onClick={() => setScheduleOpen(true)} className="mt-3 flex min-h-12 w-full items-center justify-between border-b border-border-subtle text-left text-sm"><span>Schedule</span><span className="text-xs text-text-faint">{scheduledAt ? new Date(scheduledAt).toLocaleString() : "Post now"} ›</span></button>
+          <label className="flex min-h-12 items-center justify-between border-b border-border-subtle text-sm"><span>Request approval</span><input type="checkbox" className="h-6 w-6 accent-accent" checked={approval === "review" || !can("approval.grant")} disabled={!can("approval.grant")} onChange={(event) => setApproval(event.target.checked ? "review" : "draft")} /></label>
+          {!can("approval.grant") && <p className="mt-1 text-2xs text-text-faint">Your role submits posts for editor approval.</p>}
+        </div>
+
+        <div className="mt-3 hidden flex-wrap items-center gap-3 lg:flex">
+          <span className={`font-mono text-xs ${over ? "text-danger" : "text-text-faint"}`}>
+            {chars} / {limit}
+          </span>
+          <span className="flex items-center gap-2 text-xs text-text-dim">
+            <label htmlFor="visibility" className="text-text-faint">Visibility</label>
+            <select
+              id="visibility"
+              value={visibility}
+              onChange={(e) => setVisibility(e.target.value as Visibility)}
+              className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs"
+            >
+              <option value="public">public</option>
+              <option value="unlisted">unlisted</option>
+              <option value="followers">followers</option>
+              <option value="private">private</option>
+              <option value="provider_default">provider default</option>
+            </select>
+          </span>
+          <span className="flex items-center gap-2 text-xs text-text-dim">
+            <label htmlFor="approval" className="text-text-faint">Approval</label>
+            <select
+              id="approval"
+              value={approval}
+              onChange={(e) => setApproval(e.target.value)}
+              className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs"
+            >
+              <option value="draft">draft</option>
+              <option value="review">submit for review</option>
+              {can("approval.grant") && <option value="approved">approved</option>}
+            </select>
+          </span>
+          <span className="flex items-center gap-2 text-xs text-text-dim">
+            <label htmlFor="schedule" className="text-text-faint">Schedule</label>
+            <Input
+              id="schedule"
+              type="datetime-local"
+              value={scheduledAt}
+              onChange={(e) => setScheduledAt(e.target.value)}
+              className="w-52 py-1 text-xs"
+            />
+          </span>
+          <div className="ml-auto flex gap-2">
+            <Button variant="outline" disabled={busy || chars === 0} onClick={() => void saveDraft()}>Save draft</Button>
+            <Button variant="primary" disabled={busy || targets.length === 0 || chars === 0 || over} onClick={() => void publish()}>
+              {scheduledAt !== "" ? "Schedule" : approval === "review" ? "Submit" : "Publish"}
+            </Button>
+          </div>
+        </div>
+        {notice !== null && (
+          <p className={`mt-2 text-xs ${notice.tone === "ok" ? "text-live" : "text-danger"}`}>{notice.text}</p>
+        )}
+        <div className="fixed left-0 right-0 z-30 border-t border-border bg-surface px-4 py-2 lg:hidden" style={{ bottom: `calc(var(--mobile-tab-height) + var(--mobile-safe-bottom) + ${keyboardOffset}px)` }}>
+          <p className="mb-2 truncate text-2xs text-text-faint">{approval === "review" || !can("approval.grant") ? "→ Editors approve" : "→ Ready to publish"} · {scheduledAt ? `publishes ${new Date(scheduledAt).toLocaleString()}` : "post now"} · {selected.length} accounts</p>
+          <div className="flex gap-2"><Button variant="ghost" className="min-h-11" onClick={() => router.back()}>Cancel</Button><Button variant="outline" className="min-h-11 flex-1" disabled={busy || chars === 0 || mediaBlocked} onClick={() => void saveDraft()}>Draft</Button><Button variant="primary" className="min-h-11 flex-1" disabled={busy || selected.length === 0 || chars === 0 || over || mediaBlocked} onClick={() => void publish()}>{scheduledAt ? "Schedule" : approval === "review" || !can("approval.grant") ? "Submit" : "Post"}</Button></div>
+        </div>
+        <Sheet open={scheduleOpen} onClose={() => setScheduleOpen(false)} title="Schedule post" footer={<Button variant="primary" className="min-h-11 w-full justify-center" onClick={() => setScheduleOpen(false)}>Done</Button>}><label className="block text-xs text-text-faint" htmlFor="mobile-schedule">Date and time</label><Input id="mobile-schedule" type="datetime-local" value={scheduledAt} onChange={(event) => setScheduledAt(event.target.value)} className="mt-2 min-h-12" /><div className="mt-4 flex gap-2">{[1, 24, 48].map((hours) => <button key={hours} type="button" className="min-h-11 rounded-md border border-border px-3 text-xs" onClick={() => { const date = new Date(Date.now() + hours * 3600000); setScheduledAt(`${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}T${String(date.getHours()).padStart(2, "0")}:${String(date.getMinutes()).padStart(2, "0")}`); }}>{hours === 1 ? "In 1 hour" : hours === 24 ? "Tomorrow" : "In 2 days"}</button>)}</div><button type="button" onClick={() => setScheduledAt("")} className="mt-4 min-h-11 text-xs text-text-faint">Clear schedule</button></Sheet>
+        <Sheet open={previewOpen} onClose={() => setPreviewOpen(false)} title="Target previews">{selected.map((target) => <div key={target.key} className="mb-3 rounded-md border border-border p-3"><p className="text-xs text-text-faint">{target.label}</p><p className="mt-2 whitespace-pre-wrap text-sm">{editor?.getText() || "Your post preview appears here…"}</p></div>)}</Sheet>
+        {/* Anchor target for the mobile "Resume drafts" shortcut — rendered at every breakpoint. */}
+        {drafts.source === "live" && drafts.data.length > 0 && <section id="drafts" className="mt-6 scroll-mt-4">
+          <h2 className="mb-3 text-sm font-semibold">Recent drafts</h2>
+          {drafts.data.map((draft) => <button key={draft.id} onClick={() => editor?.commands.setContent(draft.post.text)} className="mb-2 block min-h-14 w-full rounded-md border border-border-subtle p-3 text-left text-xs">
+            <span className="mb-1 block text-text-faint">{draft.state.replace("_", " ")}</span>
+            <span className="line-clamp-2 text-text-dim">{draft.post.text}</span>
+          </button>)}
+        </section>}
+      </div>
+
+      <aside className="hidden w-80 shrink-0 overflow-y-auto border-l border-border-subtle p-6 scrollbar-thin lg:block">
+        <h2 className="mb-4 text-sm font-semibold">Previews</h2>
+        {targets.length === 0 && <p className="text-xs text-text-faint">Select target platforms to preview.</p>}
+        {selected.map((t) => {
+          const charLimit = PLATFORMS[t.provider]?.charLimit ?? 500;
+          return (
+            <div key={t.key} className="mb-4 rounded-lg border border-border-subtle bg-surface p-3">
+              <div className="mb-2 flex items-center justify-between">
+                <span className="truncate text-2xs font-medium text-text-faint">{t.label}</span>
+                <Badge tone={chars > charLimit ? "danger" : "neutral"}>
+                  {chars}/{charLimit}
+                </Badge>
+              </div>
+              <p className="line-clamp-6 text-xs leading-relaxed text-text-dim">
+                {editor?.getText() || "Your post preview appears here…"}
+              </p>
+            </div>
+          );
+        })}
+
+        {drafts.source === "live" && (
+          <>
+            <h2 className="mb-3 mt-6 text-sm font-semibold">Recent drafts</h2>
+            {drafts.error !== null && <p className="text-xs text-danger">{drafts.error}</p>}
+            {drafts.data.length === 0 && <p className="text-xs text-text-faint">No drafts yet.</p>}
+            {drafts.data.map((d) => (
+              <button
+                key={d.id}
+                onClick={() => editor?.commands.setContent(d.post.text)}
+                title="Load this text into the editor"
+                className="mb-2 block w-full rounded-md border border-border-subtle p-2 text-left transition-colors duration-150 hover:border-accent"
+              >
+                <div className="mb-1 flex items-center justify-between">
+                  <Badge tone={STATE_TONE[d.state]}>{d.state.replace("_", " ")}</Badge>
+                  <span className="text-2xs text-text-faint">{new Date(d.updatedAt).toLocaleString()}</span>
+                </div>
+                <p className="line-clamp-2 text-2xs text-text-dim">{d.post.text}</p>
+              </button>
+            ))}
+          </>
+        )}
+      </aside>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/connections/page.tsx b/apps/web/src/app/(main)/connections/page.tsx
new file mode 100644
index 0000000..d529478
--- /dev/null
+++ b/apps/web/src/app/(main)/connections/page.tsx
@@ -0,0 +1,236 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { capacitySnapshot, humanizeMs } from "@tactical-media-broadcast-hub/connector-sdk/rate-policy";
+import { Badge, Button, Card } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { CONNECTED_ACCOUNTS, CONNECTION_CAPACITIES, DOCUMENTED_RATES, PLATFORMS, type ConnectionCapacity } from "../../../lib/platforms";
+import { CapacityChip } from "../../../components/connections/capacity-chip";
+import { EmptyState } from "../../../components/brand/empty-state";
+import { Loading } from "../../../components/brand/loading";
+import type { ConnectionSummary } from "../../../lib/api-types";
+import { useApiResource } from "../../../lib/use-api";
+import { api, errorMessage } from "../../../lib/api-client";
+import { useAuth } from "../../../lib/auth-store";
+import { reissueSession } from "../../../lib/api-client";
+import { setSessionToken } from "../../../lib/session-token";
+import { linkBotToken, type ConnectProvider } from "../../../lib/connections-client";
+
+const NO_PROVIDERS: ConnectProvider[] = [];
+const providersFromApi = (providers: ConnectProvider[]): ConnectProvider[] => providers;
+
+interface AccountView {
+  key: string;
+  provider: string;
+  handle: string;
+  health: "healthy" | "expiring" | "needs_credentials" | "unavailable";
+  capabilities?: string[];
+  instanceUrl?: string;
+  capacity: ConnectionCapacity;
+}
+
+function handleOf(c: ConnectionSummary): string {
+  const fromFields = c.fields.handle ?? c.fields.displayName;
+  return typeof fromFields === "string" && fromFields !== "" ? fromFields : c.channelId;
+}
+
+function fromApi(connections: ConnectionSummary[]): AccountView[] {
+  return connections.map((c) => {
+    const handle = handleOf(c);
+    return {
+      key: c.id,
+      provider: c.provider,
+      handle,
+      health: c.health,
+      capabilities: c.capabilities,
+      instanceUrl: typeof c.fields.instanceUrl === "string" ? c.fields.instanceUrl : undefined,
+      capacity: {
+        handle,
+        platform: c.provider,
+        resolvedCap: DOCUMENTED_RATES[c.provider]?.dailyPostCap,
+        used: c.recentPublishes.length,
+        recentPublishes: c.recentPublishes,
+      },
+    };
+  });
+}
+
+const SAMPLE: AccountView[] = CONNECTED_ACCOUNTS.map((a) => ({
+  key: a.handle,
+  provider: a.platform,
+  handle: a.handle,
+  health: a.status,
+  capacity: CONNECTION_CAPACITIES.find((c) => c.handle === a.handle) ?? { handle: a.handle, platform: a.platform, used: 0, recentPublishes: [] },
+}));
+
+function HealthBadge({ health }: { health: AccountView["health"] }): React.ReactElement {
+  if (health === "unavailable") return <Badge tone="warn">provider unavailable</Badge>;
+  if (health === "expiring") return <Badge tone="warn">token expiring</Badge>;
+  if (health === "needs_credentials") return <Badge tone="warn">needs credentials</Badge>;
+  return <Badge tone="live">healthy</Badge>;
+}
+
+
+export default function ConnectionsPage(): React.ReactElement {
+  const { data: accounts, source, error, reload } = useApiResource<ConnectionSummary[], AccountView[]>("/connections", fromApi, SAMPLE);
+  const live = source === "live";
+  const { can } = useAuth();
+  const { data: providers } = useApiResource<ConnectProvider[], ConnectProvider[]>("/connections/providers", providersFromApi, NO_PROVIDERS);
+  const [selected, setSelected] = useState<ConnectProvider | null>(null);
+  const [reconnectId, setReconnectId] = useState<string | undefined>();
+  const [instanceUrl, setInstanceUrl] = useState("");
+  const [token, setToken] = useState("");
+  const [target, setTarget] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [notice, setNotice] = useState<string | null>(null);
+  const manageable = live && can("connection.manage") && !busy;
+
+  useEffect(() => {
+    const url = new URL(window.location.href);
+    const result = url.searchParams.get("connect");
+    if (result === null) return;
+    if (result === "success") void reissueSession().then(() => { reload(); }).catch(() => setNotice("Sign in again to refresh account access."));
+    setNotice(result === "success" ? "Account connected successfully." : "Account linking failed or expired. Please try again.");
+    url.searchParams.delete("connect");
+    window.history.replaceState(null, "", url);
+  }, []);
+
+  // Onboarding (and any deep link) opens the connect dialog via /connections?start=<providerId>.
+  useEffect(() => {
+    if (source !== "live") return;
+    const url = new URL(window.location.href);
+    const startId = url.searchParams.get("start");
+    if (startId === null) return;
+    const provider = providers.find((item) => item.id === startId);
+    url.searchParams.delete("start");
+    window.history.replaceState(null, "", url);
+    if (provider !== undefined) { setSelected(provider); setNotice(null); }
+  }, [source, providers]);
+
+  function openConnect(provider: ConnectProvider, account?: AccountView): void {
+    setSelected(provider); setReconnectId(account?.key); setInstanceUrl(account?.instanceUrl ?? ""); setToken(""); setTarget(""); setNotice(null);
+  }
+  async function submitConnect(event: React.FormEvent): Promise<void> {
+    event.preventDefault();
+    if (!selected || !manageable) return;
+    setBusy(true);
+    try {
+      if (selected.kind === "token") {
+        await linkBotToken(token, target, reconnectId);
+        setToken(""); setSelected(null); reload(); setNotice("Bot connected successfully.");
+      } else {
+        const result = reconnectId
+          ? await api.post<{ redirectUrl: string }>(`/connections/${reconnectId}/reconnect`)
+          : await api.post<{ redirectUrl: string }>("/connections/authorize", { provider: selected.id, instanceUrl });
+        window.location.assign(result.redirectUrl);
+      }
+    } catch (err) { setNotice(errorMessage(err)); }
+    finally { setBusy(false); }
+  }
+  function reconnect(account: AccountView): void {
+    const provider = providers.find((item) => item.id === account.provider);
+    if (provider) openConnect(provider, account);
+  }
+  async function remove(account: AccountView): Promise<void> {
+    if (!window.confirm(`Remove ${account.handle}? This removes local schedules and publication records for this account. Published posts stay on the provider.`)) return;
+    setBusy(true);
+    try { const result = await api.del<{ removed: true; token: string }>(`/connections/${account.key}`); setSessionToken(result.token); reload(); setNotice("Account removed."); }
+    catch (err) { setNotice(errorMessage(err)); }
+    finally { setBusy(false); }
+  }
+  const [filter, setFilter] = useState<"all" | "attention" | "capacity">("all");
+  const atCapacity = (account: AccountView): boolean => account.capacity.resolvedCap !== undefined && account.capacity.used >= account.capacity.resolvedCap;
+  const urgent = [...accounts].sort((a, b) => Number(b.health !== "healthy") - Number(a.health !== "healthy") || Number(atCapacity(b)) - Number(atCapacity(a)));
+  const filtered = urgent.filter((account) => filter === "all" || (filter === "attention" && account.health !== "healthy") || (filter === "capacity" && atCapacity(account)));
+
+  return (
+    <div className="h-full overflow-y-auto p-4 pb-24 scrollbar-thin lg:p-6">
+      <div className="mb-6 flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <h1 className="text-lg font-semibold">Channels</h1>
+          <OfflineBadge source={source} />
+        </div>
+        <Button variant="primary" size="sm" disabled={!manageable} onClick={() => { const provider = providers.find((item) => item.enabled); if (provider) openConnect(provider); }}>Connect account</Button>
+      </div>
+
+      {notice && <div role="status" className="mb-4 rounded-lg border border-accent p-3 text-sm">{notice}<button type="button" className="ml-4 text-xs underline" onClick={() => setNotice(null)}>Dismiss</button></div>}
+      {selected && <form onSubmit={(event) => void submitConnect(event)} className="mb-6 space-y-3 rounded-lg border border-accent bg-surface p-4">
+        <h2 className="font-semibold">{reconnectId ? "Reconnect" : "Connect"} {selected.displayName}</h2>
+        {!reconnectId && <label className="block text-sm">Provider<select className="ml-3 rounded border border-border bg-bg p-2" value={selected.id} disabled={busy} onChange={(event) => { const provider = providers.find((item) => item.id === event.target.value); if (provider) openConnect(provider); }}>{providers.map((provider) => <option key={provider.id} value={provider.id} disabled={!provider.enabled}>{provider.displayName}{!provider.enabled ? " (unavailable)" : ""}</option>)}</select></label>}
+        {selected.instanceRequired && <label className="block text-sm">Instance URL<input className="mt-1 block w-full rounded border border-border bg-bg p-2" value={instanceUrl} onChange={(event) => setInstanceUrl(event.target.value)} placeholder="https://your-instance.example" required disabled={Boolean(reconnectId) || busy} /></label>}
+        {selected.kind === "token" && <><label className="block text-sm">Bot token<input className="mt-1 block w-full rounded border border-border bg-bg p-2" type="password" autoComplete="off" value={token} onChange={(event) => setToken(event.target.value)} required disabled={busy} /></label><label className="block text-sm">Chat or channel ID (optional)<input className="mt-1 block w-full rounded border border-border bg-bg p-2" value={target} onChange={(event) => setTarget(event.target.value)} placeholder="@channel or numeric chat ID" disabled={busy} /></label></>}
+        {selected.note && <p className="text-xs text-text-faint">{selected.note}</p>}
+        <div className="flex gap-2"><Button type="submit" variant="primary" disabled={!manageable || !selected.enabled}>{busy ? "Connecting…" : selected.kind === "token" ? "Validate and connect" : "Continue to provider"}</Button><Button type="button" disabled={busy} onClick={() => { setSelected(null); setToken(""); }}>Cancel</Button></div>
+      </form>}
+      <div className="mb-4 grid grid-cols-3 gap-2 lg:hidden">{([
+        { id: "all", label: "Connected", count: accounts.length },
+        { id: "attention", label: "Need attention", count: accounts.filter((account) => account.health !== "healthy").length },
+        { id: "capacity", label: "At capacity", count: accounts.filter(atCapacity).length },
+      ] as const).map((tile) => <button key={tile.id} type="button" onClick={() => setFilter(tile.id)} className={`min-h-20 min-w-0 rounded-lg border p-2 text-left ${filter === tile.id ? "border-accent bg-accent-dim" : "border-border bg-surface"}`}><span className="block text-xl font-bold">{tile.count}</span><span className="text-2xs text-text-dim">{tile.label}</span></button>)}</div>
+      <div className="space-y-2 lg:hidden">{filtered.map((account) => {
+        const platform = PLATFORMS[account.provider];
+        const cap = account.capacity.resolvedCap;
+        const snapshot = capacitySnapshot({ used: account.capacity.used, cap, recentPublishes: account.capacity.recentPublishes }, { requestsPerSecond: DOCUMENTED_RATES[account.provider]?.requestsPerSecond ?? 1, dailyPostCap: cap });
+        return <article key={account.key} className="rounded-lg border border-border bg-surface p-4"><div className="flex items-start gap-3"><span className="flex h-11 w-11 shrink-0 items-center justify-center rounded-full border-2 border-accent bg-black text-lg font-bold text-accent">{(platform?.displayName ?? account.provider).slice(0, 1)}</span><div className="min-w-0 flex-1"><div className="flex items-center gap-2"><h2 className="truncate text-sm font-semibold">{platform?.displayName ?? account.provider}</h2><span className={`h-2 w-2 shrink-0 rounded-full ${account.health === "healthy" ? "bg-live" : "bg-warn"}`} aria-label={account.health} /></div><p className="truncate text-xs text-text-faint">{account.handle}</p></div>{account.health !== "healthy" && <button type="button" disabled={!manageable || !providers.find((item) => item.id === account.provider)?.enabled} onClick={() => reconnect(account)} className="min-h-11 rounded-md border border-warn px-3 text-xs text-warn">Fix</button>}</div>
+          <div className="mt-4 flex items-center justify-between text-xs"><span className="text-text-faint">{cap === undefined ? `${account.capacity.used} posts · no documented cap` : `${account.capacity.used}/${cap} posts in 24h`}</span>{snapshot.remaining === 0 && snapshot.nextSlotInMs !== undefined && <span className="text-accent">frees in {humanizeMs(snapshot.nextSlotInMs)}</span>}</div>
+          <div className="mt-3 flex gap-2"><Button size="sm" disabled={!manageable || !providers.find((item) => item.id === account.provider)?.enabled} onClick={() => reconnect(account)}>Reconnect</Button><Button size="sm" variant="danger" disabled={!manageable} onClick={() => void remove(account)}>Remove</Button></div>
+          <div className={`mt-2 h-2 overflow-hidden rounded-full ${cap === undefined ? "border border-dashed border-border" : "bg-surface-2"}`}>{cap !== undefined && <div className={`h-full ${snapshot.remaining === 0 ? "bg-accent" : "bg-live"}`} style={{ width: `${Math.min(100, Math.round((account.capacity.used / Math.max(1, cap)) * 100))}%` }} />}</div>
+        </article>;
+      })}{filtered.length === 0 && <p className="py-8 text-center text-xs text-text-faint">No accounts in this filter.</p>}</div>
+
+      {error !== null && <p className="mb-4 text-xs text-danger">{error}</p>}
+      {source === "loading" && (
+        <div className="mb-4 flex items-center gap-2 text-xs text-text-faint">
+          <Loading size={16} label="Loading channels" /> Loading channels…
+        </div>
+      )}
+      <div className="hidden grid-cols-1 gap-4 md:grid-cols-2 lg:grid">
+        {live && accounts.length === 0 && (
+          <div className="md:col-span-2">
+            <EmptyState
+              title="No channels connected yet"
+              hint="Connect an account below to start publishing. Account passwords never touch this system."
+            />
+          </div>
+        )}
+        {source !== "loading" && accounts.map((account) => {
+          const platform = PLATFORMS[account.provider];
+          const caps = account.capabilities ?? [];
+          return (
+            <Card key={account.key} className="p-4">
+              <div className="flex flex-wrap items-start justify-between gap-3">
+                <div>
+                  <div className="flex items-center gap-2">
+                    <span className="text-base font-semibold">{platform?.displayName ?? account.provider}</span>
+                    <HealthBadge health={account.health} />
+                  </div>
+                  <div className="mt-0.5 text-xs text-text-faint">{account.handle}</div>
+                </div>
+                <div className="flex flex-wrap items-center gap-2">
+                  <CapacityChip cap={account.capacity} />
+                  <Button size="sm" variant="outline" disabled={!manageable || !providers.find((item) => item.id === account.provider)?.enabled} onClick={() => reconnect(account)}>Reconnect</Button>
+                  <Button size="sm" variant="danger" disabled={!manageable} onClick={() => void remove(account)}>Remove</Button>
+                </div>
+              </div>
+              <div className="mt-3 flex flex-wrap gap-1.5">
+                {caps.map((cap) => (
+                  <Badge key={cap} tone="accent">{cap}</Badge>
+                ))}
+              </div>
+
+            </Card>
+          );
+        })}
+
+      </div>
+      <div className="mt-4 grid grid-cols-1 gap-3 md:grid-cols-2">
+        {providers.map((provider) => <Card key={provider.id} className="border-dashed p-4"><div className="flex items-center justify-between gap-3"><span className="font-semibold">{provider.displayName}</span><Button size="sm" variant="outline" disabled={!manageable || !provider.enabled} onClick={() => openConnect(provider)}>Connect</Button></div>{provider.note && <p className="mt-2 text-xs text-text-faint">{provider.note}</p>}</Card>)}
+      </div>
+
+      <p className="mt-6 text-2xs leading-relaxed text-text-faint">
+        Connections store OAuth tokens or bot tokens — passwords never transit this system. Tokens live in the
+        workspace vault (envelope-encrypted); rotate or revoke any time.
+      </p>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/control-room/control-room.css b/apps/web/src/app/(main)/control-room/control-room.css
new file mode 100644
index 0000000..265c367
--- /dev/null
+++ b/apps/web/src/app/(main)/control-room/control-room.css
@@ -0,0 +1,16 @@
+.control-room .cr-field {
+  display: block;
+  width: 100%;
+  max-width: 100%;
+  min-width: 44px;
+  min-height: 44px;
+  border: 1px solid var(--color-border, #444);
+  border-radius: 6px;
+  background: var(--color-surface-2, #222);
+  padding: 8px 10px;
+  color: inherit;
+  font-size: 14px;
+}
+.control-room label { max-width: 100%; }
+.control-room button { min-width: 44px; }
+.control-room :focus-visible { outline: 2px solid #ff1610; outline-offset: 3px; }
diff --git a/apps/web/src/app/(main)/control-room/page.tsx b/apps/web/src/app/(main)/control-room/page.tsx
new file mode 100644
index 0000000..ae50a63
--- /dev/null
+++ b/apps/web/src/app/(main)/control-room/page.tsx
@@ -0,0 +1,111 @@
+"use client";
+import { useEffect, useMemo, useState } from "react";
+import { useAuth } from "../../../lib/auth-store";
+import { API_URL, ApiError, ApiUnreachableError } from "../../../lib/api-client";
+import { getSessionToken } from "../../../lib/session-token";
+import { Badge, Button } from "../../../components/ui/primitives";
+import { AudioMonitor } from "../../../components/control-room/audio-monitor";
+import { MultiviewGrid, liveTapIds, type GridTier } from "../../../components/control-room/multiview-grid";
+import { OverlayEditor, type RenderInput } from "../../../components/control-room/overlay-editor";
+import { PstPreview } from "../../../components/control-room/pst-preview";
+import { SwitcherBar, type DirectorAction } from "../../../components/control-room/switcher-bar";
+import { controlRequest } from "../../../components/control-room/client";
+import { fixtureChannel } from "../../../components/control-room/fixtures";
+import { RealtimeClient } from "../../../components/control-room/state-store";
+import { initialTally, refetchTally, tallyReducer, type TallyState } from "../../../components/control-room/tally";
+import type { Receipt, Status } from "../../../components/control-room/types";
+import "./control-room.css";
+
+export default function ControlRoom(): React.ReactElement {
+  const { session, can, status: authStatus } = useAuth();
+  const [channels, setChannels] = useState<Status["channels"]>([]);
+  const [selected, setSelected] = useState("");
+  const [state, setState] = useState<TallyState | null>(null);
+  const [fixture, setFixture] = useState(false);
+  const [connection, setConnection] = useState("loading");
+  const [message, setMessage] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [mobile, setMobile] = useState(true);
+  const [tier, setTier] = useState<GridTier>("2x2");
+  const [focused, setFocused] = useState<string | null>(null);
+  const [upgrades, setUpgrades] = useState<string[]>([]);
+  const [reload, setReload] = useState(0);
+  useEffect(() => {
+    const query = matchMedia("(max-width: 1023px)"); const update = (): void => setMobile(query.matches);
+    update(); query.addEventListener("change", update); return () => query.removeEventListener("change", update);
+  }, []);
+  useEffect(() => {
+    if (authStatus === "loading") return;
+    let cancelled = false;
+    const abort = new AbortController();
+    setConnection("loading"); setState(null); setFixture(false); setMessage("");
+    void controlRequest<Status>("/media-control/status", undefined, abort.signal).then(result => {
+      if (cancelled) return;
+      setChannels(result.channels); setSelected(result.channels[0]?.channelId ?? ""); setConnection(result.channels.length ? "connecting" : "empty");
+    }).catch(error => {
+      if (cancelled) return;
+      if (error instanceof ApiUnreachableError || error instanceof ApiError && error.status >= 500) {
+        const sample = fixtureChannel(); setFixture(true); setChannels([sample]); setSelected(sample.channelId); setConnection("fixture");
+      } else { setChannels([]); setSelected(""); setConnection("error"); setMessage(error instanceof Error ? error.message : "Status unavailable"); }
+    });
+    return () => { cancelled = true; abort.abort(); };
+  }, [authStatus, session?.workspace.id, reload]);
+  useEffect(() => {
+    const channel = channels.find(item => item.channelId === selected);
+    setFocused(null); setUpgrades([]);
+    if (!channel) { setState(null); return; }
+    setState(initialTally(channel));
+    if (fixture || !session) return;
+    const url = new URL(`${API_URL}/realtime`); url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+    const client = new RealtimeClient({ url: url.href, token: getSessionToken, workspaceId: session.workspace.id, channelId: selected,
+      socket: address => new WebSocket(address), status: () => controlRequest<Status>("/media-control/status"),
+      onFrame: frame => setState(previous => previous ? tallyReducer(previous, frame) : previous),
+      onStatus: result => { const current = result.channels.find(item => item.channelId === selected); setState(previous => current ? refetchTally(current, previous) : null); },
+      onConnection: setConnection });
+    client.start(); return () => client.stop();
+  }, [channels, selected, fixture, session]);
+  const production = state?.channel.desired?.production;
+  const liveIds = useMemo(() => liveTapIds(production?.sources ?? [], tier, focused, upgrades, mobile), [production, tier, focused, upgrades, mobile]);
+  const action = async (operation: DirectorAction, body: object): Promise<void> => {
+    if (!state?.channel.desired) return;
+    setBusy(true); setMessage("");
+    try {
+      if (fixture) {
+        const desired = structuredClone(state.channel.desired);
+        if (desired.production) {
+          if (operation === "pst-select" && "sceneId" in body) desired.production.buses.preview = String(body.sceneId);
+          if (operation === "cut" || operation === "take") desired.production.buses.program = desired.production.buses.preview;
+          if (operation === "lock" && "enabled" in body && desired.director) desired.director.locked = Boolean(body.enabled);
+          if (operation === "override" && "mode" in body && desired.director) desired.director.override = body.mode === null ? null : { mode: body.mode as NonNullable<typeof desired.director.override>["mode"], expiresAt: null };
+        }
+        desired.desiredVersion += 1;
+        setState(previous => previous ? tallyReducer(previous, { type: "state", workspaceId: "fixture", channelId: selected, kind: "desired", seq: previous.lastSeq + 1, data: desired }) : previous);
+        setMessage("Fixture request recorded. Tally awaits a simulated observed frame.");
+      } else {
+        const receipt = await controlRequest<Receipt>(`/media-control/channels/${selected}/${operation}`, body);
+        setMessage(`Request accepted · version ${receipt.desiredVersion}. Waiting for observed state.`);
+      }
+    } catch (error) { setMessage(error instanceof Error ? error.message : "Command failed"); }
+    finally { setBusy(false); }
+  };
+  const render = async (id: string, input: RenderInput): Promise<void> => {
+    if (fixture) throw new Error("Fixture mode has no render service. Reconnect to render an overlay.");
+    await controlRequest<Receipt>(`/production/overlays/${id}`, input);
+  };
+  const simulate = (): void => setState(previous => previous ? tallyReducer(previous, { type: "state", workspaceId: "fixture", channelId: selected, kind: "observed", seq: previous.lastSeq + 1, data: { workspaceId: "fixture", channelId: selected, workerId: previous.channel.workerId, assignmentEpoch: previous.channel.assignmentEpoch, realizedVersion: previous.channel.desired?.desiredVersion ?? null, state: "RUNNING", reason: "Fixture simulation", updatedAt: new Date().toISOString() } }) : previous);
+  const offline = connection !== "live" && connection !== "polling" && !fixture;
+  return <div className="control-room h-full min-w-0 overflow-y-auto p-3 sm:p-5">
+    <header className="mb-4 flex flex-wrap items-center justify-between gap-3"><div><h1 className="text-xl font-semibold">Control Room</h1><p className="mt-1 text-xs text-text-faint">Preview taps · server composition · observed tally</p></div><div className="flex flex-wrap items-center gap-2"><Badge tone={fixture ? "warn" : connection === "live" ? "live" : "neutral"}>{connection === "fixture" ? "FIXTURE · sample data" : connection}</Badge><Button className="min-h-11" variant="outline" onClick={() => setReload(value => value + 1)}>Reconnect</Button></div></header>
+    {fixture && <div className="mb-4 rounded-lg border border-warn/40 bg-warn/10 p-3 text-sm"><p>API unavailable. This is a fixture rehearsal with sample scenes, no broadcast, and no actual program state. Actions stay local.</p><Button className="mt-2 min-h-11" variant="outline" onClick={simulate}>Simulate observed frame</Button></div>}
+    {message && <p role="status" className="mb-4 break-words rounded border border-border p-3 text-sm">{message}</p>}
+    {channels.length > 0 && <label className="mb-4 block max-w-lg text-xs">Production channel<select className="cr-field mt-1" value={selected} onChange={event => setSelected(event.target.value)}>{channels.map(channel => <option key={channel.channelId} value={channel.channelId}>{fixture ? "Sample channel" : channel.channelId}</option>)}</select></label>}
+    {!production || production.scenes.length === 0 ? <section className="rounded-lg border border-border-subtle bg-surface p-6"><h2 className="text-lg font-semibold">{connection === "loading" ? "Loading production status…" : connection === "error" ? "Production status unavailable" : "No production scenes configured"}</h2><p className="mt-3 max-w-xl text-sm text-text-dim">{connection === "error" ? "Reconnect or ask a workspace administrator to check your media.view permission. Production state cannot be determined from this response." : "Configure a virtual channel, assign a media worker, add ingest sources and production scenes, then select the preview bus. Program tally appears only after the worker confirms a realized version."}</p></section> : <>
+      <div className="mb-4 flex flex-wrap gap-3 text-xs text-text-dim"><span>Desired v{state?.channel.desired?.desiredVersion}</span><span>Observed {state?.channel.observed?.realizedVersion === null || !state?.channel.observed ? "unconfirmed" : `v${state.channel.observed.realizedVersion} · ${state.channel.observed.state}`}</span><span>{state?.observedProduction ? "Tally confirmed" : "Tally unknown · awaiting matching observed version"}</span></div>
+      <SwitcherBar desired={state?.channel.desired ?? { desiredVersion: 0, desiredStatus: "STOPPED" }} disabled={offline || !fixture && !can("director.take")} busy={busy} onAction={(operation, body) => { if (!fixture && !can(operation === "lock" ? "director.lock_program" : operation === "override" ? "director.override_auto" : "director.take")) { setMessage("Your role cannot perform this action."); return; } void action(operation, body); }} />
+      <div className="mt-4 grid min-w-0 gap-4 xl:grid-cols-[minmax(0,2fr)_minmax(260px,1fr)]">
+        <MultiviewGrid production={production} observed={state?.observedProduction ?? null} channelId={selected} fixture={fixture} mobile={mobile} liveIds={liveIds} focused={focused} onFocus={setFocused} tier={tier} onTier={value => { setTier(value); setUpgrades([]); }} upgrades={upgrades} onUpgrade={id => setUpgrades(previous => previous.includes(id) ? previous.filter(item => item !== id) : liveIds.length < 4 ? [...previous, id] : previous)} />
+        <div className="min-w-0 space-y-4"><PstPreview production={production} channelId={selected} fixture={fixture} /><AudioMonitor production={production} observed={state?.observedProduction ?? null} liveIds={liveIds} focused={focused} channelId={selected} fixture={fixture} mobile={mobile} /><OverlayEditor overlays={production.overlays} disabled={fixture || offline || !can("director.change_layout")} onRender={render} /></div>
+      </div>
+    </>}
+  </div>;
+}
diff --git a/apps/web/src/app/(main)/inbox/[conversationId]/conversation-view.tsx b/apps/web/src/app/(main)/inbox/[conversationId]/conversation-view.tsx
new file mode 100644
index 0000000..abc7741
--- /dev/null
+++ b/apps/web/src/app/(main)/inbox/[conversationId]/conversation-view.tsx
@@ -0,0 +1,18 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { CONVERSATIONS, THREADS, ageLabel } from "../../../../lib/fixtures";
+import { Avatar } from "../../../../components/ui/primitives";
+
+export function ConversationView({ conversationId }: { conversationId: string }): React.ReactElement {
+  const [reply, setReply] = useState("");
+  const id = Number(conversationId);
+  const conversation = CONVERSATIONS.find((item) => item.id === id);
+  const thread = THREADS[id] ?? [];
+  return <div className="flex min-h-full flex-col">
+    <header className="flex min-h-16 items-center gap-3 border-b border-border-subtle px-4"><Link href="/inbox" aria-label="Back to Inbox" className="flex h-11 w-11 items-center justify-center text-xl">←</Link>{conversation && <Avatar handle={conversation.handle} />}<div className="min-w-0"><h1 className="truncate text-sm font-semibold">{conversation?.participant ?? "Conversation unavailable"}</h1><p className="text-xs text-text-faint">{conversation?.handle}</p></div></header>
+    <div className="min-h-[40vh] flex-1 space-y-3 p-4">{thread.map((message) => <div key={message.id} className={`flex ${message.mine ? "justify-end" : "justify-start"}`}><div className={`max-w-[85%] rounded-lg p-3 text-sm ${message.mine ? "bg-accent-dim" : "border border-border-subtle bg-surface"}`}><span className="mb-1 block text-2xs text-text-faint">{message.from} · {ageLabel(message.minutes)} ago</span>{message.text}</div></div>)}</div>
+    <footer className="sticky bottom-0 border-t border-border-subtle bg-bg p-4"><div className="flex gap-2"><input value={reply} onChange={(event) => setReply(event.target.value)} placeholder={`Reply to ${conversation?.handle ?? "conversation"}`} className="min-h-11 min-w-0 flex-1 rounded-md border border-border bg-surface-2 px-3 text-sm" /><button type="button" disabled className="min-h-11 rounded-md bg-accent px-4 text-xs text-white opacity-40">Send</button></div><p className="mt-2 text-2xs text-text-faint">Sample thread · messaging API is not connected yet.</p></footer>
+  </div>;
+}
diff --git a/apps/web/src/app/(main)/inbox/[conversationId]/page.tsx b/apps/web/src/app/(main)/inbox/[conversationId]/page.tsx
new file mode 100644
index 0000000..497b30d
--- /dev/null
+++ b/apps/web/src/app/(main)/inbox/[conversationId]/page.tsx
@@ -0,0 +1,5 @@
+import { ConversationView } from "./conversation-view";
+
+export default function ConversationPage({ params }: { params: { conversationId: string } }): React.ReactElement {
+  return <ConversationView conversationId={params.conversationId} />;
+}
diff --git a/apps/web/src/app/(main)/inbox/page.tsx b/apps/web/src/app/(main)/inbox/page.tsx
new file mode 100644
index 0000000..7b6331d
--- /dev/null
+++ b/apps/web/src/app/(main)/inbox/page.tsx
@@ -0,0 +1,61 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { Avatar } from "../../../components/ui/primitives";
+import { CONVERSATIONS, THREADS, ageLabel, type Conversation, type FeedItem } from "../../../lib/fixtures";
+import { getPlatform, MOCK_COLUMN_DEFS, PLATFORMS } from "../../../lib/platforms";
+import { Segmented } from "../../../components/mobile/segmented";
+import { SwipeItem } from "../../../components/mobile/swipe-item";
+import { ApprovalsSegment } from "../../../components/mobile/approvals-segment";
+import { AmplifySheet } from "../../../components/mobile/amplify-sheet";
+import { useApiResource } from "../../../lib/use-api";
+import type { DraftRecord } from "../../../lib/api-types";
+
+type Segment = "all" | "mentions" | "approvals" | "dms";
+type Kind = "spike" | "mention" | "approval" | "reply" | "dm" | "health";
+interface NoticeRow { id: string; kind: Kind; text: string; conversation?: Conversation; unread: boolean; }
+const extra: NoticeRow[] = [
+  { id: "spike", kind: "spike", text: "Sample spike alert · a post is getting attention", unread: true },
+  { id: "approval-sample", kind: "approval", text: "Sample draft waiting for review", unread: true },
+  { id: "health", kind: "health", text: "Facebook connection needs attention", unread: true },
+];
+const initial: NoticeRow[] = [...extra, ...CONVERSATIONS.map((conversation, i) => ({ id: `conversation-${conversation.id}`, kind: (i === 0 ? "mention" : i === 1 ? "dm" : "reply") as Kind, text: conversation.preview, conversation, unread: conversation.unread > 0 }))];
+const identity = (value: DraftRecord[]): DraftRecord[] => value;
+const empty: DraftRecord[] = [];
+const spikePost: FeedItem = { id: -1, platform: MOCK_COLUMN_DEFS[0]?.platformId ?? "unknown", author: "Sample author", handle: "@sample", text: "Sample spike alert post", ageMinutes: 4, likes: 120, reposts: 30, replies: 12, hasMedia: false };
+
+export default function InboxPage({ defaultSegment = "all" }: { defaultSegment?: "all" | "approvals" }): React.ReactElement {
+  const router = useRouter();
+  const [segment, setSegment] = useState<Segment>(defaultSegment);
+  const [rows, setRows] = useState(initial);
+  const [backup, setBackup] = useState<NoticeRow[] | null>(null);
+  const [activeId, setActiveId] = useState(CONVERSATIONS[0]?.id ?? 1);
+  const [amplify, setAmplify] = useState(false);
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, empty, { state: "in_review", limit: 100 });
+  const approvals = drafts.data.length;
+  // Fixture rows are only shown while the API is unreachable (sample mode).
+  const sample = drafts.source === "sample";
+  useEffect(() => { const requested = new URLSearchParams(window.location.search).get("segment"); if (requested === "approvals" || requested === "mentions" || requested === "dms") setSegment(requested); }, []);
+  function change(value: Segment): void { setSegment(value); window.history.replaceState(window.history.state, "", value === "all" ? "/inbox" : `/inbox?segment=${value}`); }
+  function changeRows(update: (current: NoticeRow[]) => NoticeRow[]): void { setBackup(rows); setRows(update); }
+  const visible = sample ? rows.filter((row) => segment === "all" || (segment === "mentions" && row.kind === "mention") || (segment === "dms" && row.kind === "dm")) : [];
+  const selected = CONVERSATIONS.find((conversation) => conversation.id === activeId) ?? CONVERSATIONS[0];
+  return <div className="flex h-full min-w-0 flex-col lg:flex-row">
+    <div className="min-w-0 flex-1 lg:hidden">
+      <div className="flex items-center justify-between px-4 py-2"><h1 className="text-lg font-semibold">Inbox</h1>{sample && <button type="button" className="min-h-11 rounded-md px-3 text-xs text-accent" onClick={() => changeRows((current) => current.map((row) => ({ ...row, unread: false })))}>✓ Mark read</button>}</div>
+      {backup && <div role="status" className="flex min-h-11 items-center justify-between bg-surface-2 px-4 text-xs">Inbox updated<button type="button" className="min-h-11 min-w-11 text-accent" onClick={() => { setRows(backup); setBackup(null); }}>Undo</button></div>}
+      <div className="border-b border-border-subtle px-2 pb-2"><Segmented options={[{ value: "all", label: "All", count: visible.filter((row) => row.unread).length + approvals }, { value: "mentions", label: "Mentions", count: visible.filter((row) => row.unread && row.kind === "mention").length }, { value: "approvals", label: "Approvals", count: approvals }, { value: "dms", label: "DMs", count: visible.filter((row) => row.unread && row.kind === "dm").length }]} value={segment} onChange={change} /></div>
+      {segment === "approvals" ? <ApprovalsSegment /> : <div>{visible.map((row) => <SwipeItem key={row.id} leftActions={[{ label: "Dismiss", tone: "accent", onClick: () => changeRows((current) => current.filter((item) => item.id !== row.id)) }]} rightActions={row.kind === "mention" || row.kind === "dm" ? [{ label: "Reply", onClick: () => { if (row.conversation) router.push(`/inbox/${row.conversation.id}`); } }] : []}>
+        <div className={`flex min-h-20 items-start gap-3 border-b border-border-subtle px-4 py-3 ${row.kind === "spike" ? "border-l-4 border-l-accent" : row.kind === "health" ? "border-l-4 border-l-warn" : row.unread ? "border-l-4 border-l-accent/60" : ""}`}>
+          {row.conversation ? <Avatar handle={row.conversation.handle} /> : <span className={`flex h-8 w-8 shrink-0 items-center justify-center rounded-full ${row.kind === "spike" || row.kind === "approval" ? "bg-accent" : "bg-warn/20 text-warn"}`}>{row.kind === "spike" ? "↗" : "!"}</span>}
+          <div className="min-w-0 flex-1"><div className="flex items-center gap-2"><span className="text-xs font-semibold capitalize">{row.kind}</span><span className="rounded border border-border px-1 text-2xs uppercase tracking-wide text-text-faint">sample</span>{row.conversation && <span className="truncate text-xs text-text-faint">{row.conversation.participant}</span>}{row.conversation && <span className="ml-auto text-2xs text-text-faint">{ageLabel(row.conversation.lastMinutes)}</span>}</div><p className="mt-1 text-xs text-text-dim">{row.text}</p><div className="mt-2 flex gap-2">{row.conversation && <button type="button" className="min-h-11 rounded-md border border-border px-3 text-xs" onClick={() => router.push(`/inbox/${row.conversation?.id}`)}>Open thread</button>}{row.kind === "spike" && <button type="button" className="min-h-11 rounded-md bg-accent px-3 text-xs text-white" onClick={() => setAmplify(true)}>Crosspost to…</button>}{row.kind === "approval" && <button type="button" className="min-h-11 rounded-md border border-accent px-3 text-xs text-accent" onClick={() => router.push("/approvals")}>Review</button>}{row.kind === "health" && <button type="button" className="min-h-11 rounded-md border border-warn px-3 text-xs text-warn" onClick={() => router.push("/connections")}>View connection</button>}</div></div>
+        </div></SwipeItem>)}
+        {!sample && segment === "all" && <p className="px-4 py-6 text-xs text-text-faint">No messages yet — direct messages arrive when connector messaging support lands.</p>}
+      </div>}
+    </div>
+    {segment === "approvals" ? <div className="hidden min-w-0 flex-1 lg:flex"><ApprovalsSegment /></div> : sample ? <><aside className="hidden w-80 shrink-0 overflow-y-auto border-r border-border-subtle lg:block"><div className="border-b border-border-subtle p-4 text-sm font-semibold">Inbox · sample messages</div>{CONVERSATIONS.map((conversation) => <button key={conversation.id} type="button" onClick={() => setActiveId(conversation.id)} className={`flex min-h-16 w-full items-start gap-3 border-b border-border-subtle p-3 text-left ${conversation.id === activeId ? "bg-accent-dim" : ""}`}><Avatar handle={conversation.handle} /><span className="min-w-0"><span className="block truncate text-sm font-semibold">{conversation.participant}</span><span className="block truncate text-xs text-text-faint">{conversation.preview}</span></span></button>)}</aside>
+    <section className="hidden min-w-0 flex-1 flex-col lg:flex"><div className="border-b border-border-subtle p-4 text-sm font-semibold">{selected?.participant} · {PLATFORMS[selected?.platform ?? ""]?.displayName}</div><div className="flex-1 overflow-y-auto p-4">{(THREADS[selected?.id ?? 1] ?? []).map((message, index) => <div key={index} className={`mb-3 flex ${message.mine ? "justify-end" : "justify-start"}`}><p className="max-w-[70%] rounded-lg border border-border-subtle bg-surface p-3 text-sm">{message.text}</p></div>)}</div><p className="border-t border-border-subtle p-4 text-xs text-text-faint">Sample thread · replies await connector messaging support.</p></section></> : <section className="hidden min-w-0 flex-1 flex-col lg:flex"><div className="border-b border-border-subtle p-4 text-sm font-semibold">Inbox</div><div className="flex flex-1 items-center justify-center p-6 text-center text-xs text-text-faint">No messages yet — direct messages arrive when connector messaging support lands.</div></section>}
+    <AmplifySheet post={spikePost} platform={getPlatform(spikePost.platform)} open={amplify} onClose={() => setAmplify(false)} />
+  </div>;
+}
diff --git a/apps/web/src/app/(main)/layout.tsx b/apps/web/src/app/(main)/layout.tsx
new file mode 100644
index 0000000..c01602d
--- /dev/null
+++ b/apps/web/src/app/(main)/layout.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import { useEffect, useRef, type ReactNode } from "react";
+import { usePathname } from "next/navigation";
+import { Sidebar } from "../../components/shell/sidebar";
+import { CommandPalette } from "../../components/shell/command-palette";
+import { BottomNav } from "../../components/mobile/bottom-nav";
+import { MobileTopBar } from "../../components/mobile/top-bar";
+import { AuthProvider, useAuth } from "../../lib/auth-store";
+import { AuthGate, SessionStatus } from "../../components/auth/auth-gate";
+import { useApiResource } from "../../lib/use-api";
+import type { DraftRecord } from "../../lib/api-types";
+import { useIsMobile } from "../../hooks/use-is-mobile";
+
+const titles: Record<string, string> = {
+  streams: "Home", search: "Search", inbox: "Inbox", approvals: "Approvals", more: "More", compose: "New post",
+  calendar: "Calendar", video: "Video", analytics: "Analytics", connections: "Connections", team: "Team",
+  audit: "Audit log", onboarding: "Welcome", settings: "Settings", archive: "Archive",
+};
+const rootTabs = new Set(["/streams", "/search", "/inbox", "/more"]);
+const scrollPositions = new Map<string, { main: number; nested: number[] }>();
+const identity = (drafts: DraftRecord[]): DraftRecord[] => drafts;
+const emptyDrafts: DraftRecord[] = [];
+
+function scrollableChildren(main: HTMLElement): HTMLElement[] {
+  return Array.from(main.querySelectorAll<HTMLElement>("*")).filter((element) =>
+    element.scrollHeight > element.clientHeight && /auto|scroll/.test(getComputedStyle(element).overflowY));
+}
+
+function Shell({ children }: { children: ReactNode }): React.ReactElement {
+  const pathname = usePathname();
+  const mobile = useIsMobile();
+  const { can } = useAuth();
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, emptyDrafts, { state: "in_review", limit: 100 });
+  // Badge comes from live approvals-in-review only — 0 while loading/sample/forbidden, never fixture counts.
+  const approvals = can("approval.grant") && drafts.source === "live" ? drafts.data.length : 0;
+  const mainRef = useRef<HTMLElement>(null);
+  useEffect(() => {
+    const main = mainRef.current;
+    if (main === null || !mobile) return;
+    const saved = scrollPositions.get(pathname);
+    const restore = window.setTimeout(() => {
+      main.scrollTop = saved?.main ?? 0;
+      scrollableChildren(main).forEach((element, index) => { element.scrollTop = saved?.nested[index] ?? 0; });
+    }, 0);
+    return () => {
+      window.clearTimeout(restore);
+      scrollPositions.set(pathname, { main: main.scrollTop, nested: scrollableChildren(main).map((element) => element.scrollTop) });
+    };
+  }, [pathname, mobile]);
+  const title = titles[pathname.split("/")[1] ?? ""] ?? "Tactical Media Broadcast Hub";
+  return (
+    <div className="flex h-dvh min-w-0 overflow-hidden lg:h-screen">
+      <Sidebar />
+      <div className="flex min-w-0 flex-1 flex-col">
+        <div className="hidden h-11 shrink-0 items-center justify-between border-b border-border-subtle bg-surface/60 px-4 backdrop-blur lg:flex">
+          <div className="text-2xs text-text-faint">Press <kbd className="rounded border border-border bg-surface-2 px-1 py-0.5 font-mono">⌘K</kbd> for commands</div>
+          <div className="text-2xs text-text-faint"><SessionStatus /></div>
+        </div>
+        {mobile && <MobileTopBar title={title} back={!rootTabs.has(pathname)} />}
+        <main ref={mainRef} data-mobile-main className="min-h-0 min-w-0 flex-1 overflow-x-hidden overflow-y-auto bg-bg lg:overflow-hidden">
+          <AuthGate>{children}</AuthGate>
+        </main>
+        {mobile && <BottomNav badges={{ inbox: approvals }} />}
+      </div>
+      {!mobile && <CommandPalette />}
+    </div>
+  );
+}
+
+export default function MainLayout({ children }: { children: ReactNode }): React.ReactNode {
+  return <AuthProvider><Shell>{children}</Shell></AuthProvider>;
+}
diff --git a/apps/web/src/app/(main)/more/page.tsx b/apps/web/src/app/(main)/more/page.tsx
new file mode 100644
index 0000000..c7c25ea
--- /dev/null
+++ b/apps/web/src/app/(main)/more/page.tsx
@@ -0,0 +1,70 @@
+"use client";
+
+import Link from "next/link";
+import { useAuth } from "../../../lib/auth-store";
+import { useApiResource } from "../../../lib/use-api";
+import { Avatar } from "../../../components/ui/primitives";
+import type { DraftRecord } from "../../../lib/api-types";
+
+interface GroupSummary { id: string; name: string; }
+const identity = (groups: GroupSummary[]): GroupSummary[] => groups;
+const identityDrafts = (drafts: DraftRecord[]): DraftRecord[] => drafts;
+const emptyDrafts: DraftRecord[] = [];
+
+function Tile({ href, title, detail }: { href: string; title: string; detail: string }): React.ReactElement {
+  return <Link href={href} className="flex min-h-[92px] flex-col justify-between rounded-lg border border-border bg-surface p-3.5 hover:border-accent">
+    <span className="text-accent">✦</span><span><strong className="block text-sm">{title}</strong><span className="text-xs text-text-faint">{detail}</span></span>
+  </Link>;
+}
+
+function Row({ href, title, detail }: { href: string; title: string; detail?: string }): React.ReactElement {
+  return <Link href={href} className="flex min-h-[56px] items-center gap-3 border-b border-border-subtle px-4 py-2">
+    <span className="min-w-0 flex-1"><strong className="block text-sm font-medium">{title}</strong>{detail && <span className="text-xs text-text-faint">{detail}</span>}</span>
+    <span aria-hidden="true" className="text-text-faint">›</span>
+  </Link>;
+}
+
+export default function MorePage(): React.ReactElement {
+  const { session, can, logout } = useAuth();
+  const groups = useApiResource<GroupSummary[], GroupSummary[]>("/groups/mine", identity, []);
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identityDrafts, emptyDrafts, { limit: 100 });
+  const canApprove = can("approval.grant") || session?.role === "Editor";
+  const canManage = can("workspace.members.manage");
+  const canAudit = can("audit.view");
+  return <div className="mx-auto max-w-2xl pb-8">
+    <section className="flex items-center gap-4 px-5 py-5">
+      <div className="scale-125"><Avatar handle={session?.user.displayName || session?.user.username || "AP"} /></div>
+      <div className="min-w-0 flex-1 pl-2">
+        <h1 className="truncate text-xl font-bold">{session?.user.displayName || session?.user.username || "Tactical Media Broadcast Hub"}</h1>
+        <p className="truncate text-xs text-text-faint">@{session?.user.username || "offline"}{session?.user.email ? ` · ${session.user.email}` : ""}</p>
+        <div className="mt-2 flex items-center gap-2"><span className="rounded-full bg-accent px-2.5 py-1 text-[11px] font-bold uppercase text-white">{session?.role || "Preview"}</span><span className="truncate text-xs text-text-dim">{session?.workspace.name || "Studio"}</span></div>
+      </div>
+    </section>
+    <h2 className="px-4 pb-2 text-xs font-bold uppercase tracking-wider text-text-faint">Your groups</h2>
+    <div className="flex min-h-11 flex-wrap gap-2 px-4 pb-3">{groups.data.length ? groups.data.map((group) => <span key={group.id} className="flex min-h-11 items-center rounded-full border border-border px-3 text-xs">{group.name}</span>) : <span className="text-xs text-text-faint">No groups yet</span>}</div>
+    {(canApprove || canManage || canAudit) && <>
+      <h2 className="px-4 py-3 text-xs font-bold uppercase tracking-wider text-text-faint">Team</h2>
+      <div className="grid grid-cols-2 gap-2.5 px-4">
+        {canApprove && <Tile href="/approvals" title="Approvals" detail={`${drafts.data.filter((draft) => draft.state === "in_review").length} waiting`} />}
+        {canManage && <Tile href="/team" title="Invite member" detail="Manage invitations" />}
+        {canManage && <Tile href="/team" title="Roles" detail={`${groups.data.length} groups`} />}
+        {canAudit && <Tile href="/audit" title="Audit log" detail="Recent activity" />}
+      </div>
+    </>}
+    <h2 className="px-4 pt-6 pb-2 text-xs font-bold uppercase tracking-wider text-text-faint">Help</h2>
+    <div className="grid grid-cols-2 gap-2.5 px-4">
+      <Tile href="/wiki" title="Help & docs" detail="Manuals · EN / ES" />
+    </div>
+    <h2 className="px-4 pt-6 pb-2 text-xs font-bold uppercase tracking-wider text-text-faint">Settings</h2>
+    <div className="border-y border-border-subtle bg-surface">
+      <Row href="/connections" title="Connections" detail="Accounts and health" />
+      <Row href="/settings" title="Settings" />
+      <Row href="/settings" title="Security & sessions" />
+      <Row href="/calendar" title="Calendar" />
+      <Row href="/analytics" title="Analytics" />
+      <Row href="/video" title="Video library" />
+      <Row href="/onboarding" title="Onboarding" />
+      <button onClick={() => void logout()} className="flex min-h-[56px] w-full items-center px-4 text-left text-sm font-medium text-danger">Sign out</button>
+    </div>
+  </div>;
+}
diff --git a/apps/web/src/app/(main)/onboarding/page.tsx b/apps/web/src/app/(main)/onboarding/page.tsx
new file mode 100644
index 0000000..a5cc719
--- /dev/null
+++ b/apps/web/src/app/(main)/onboarding/page.tsx
@@ -0,0 +1,363 @@
+"use client";
+
+import { useEffect, useState, type FormEvent } from "react";
+import Link from "next/link";
+import { Badge, Button, Card, Input } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { ArrowGlyph } from "../../../components/brand/logo";
+import { PLATFORMS } from "../../../lib/platforms";
+import { useApiResource } from "../../../lib/use-api";
+import { api, errorMessage } from "../../../lib/api-client";
+import type { MemberMutationResult } from "../../../lib/api-types";
+import type { ConnectProvider } from "../../../lib/connections-client";
+import { useAuth } from "../../../lib/auth-store";
+
+const STEPS = ["Create workspace", "Invite team", "Connect accounts"];
+const MIN_PASSWORD = 10;
+const INVITE_ROLE_CHOICES = ["Owner", "Editor", "Viewer"] as const;
+const DEFAULT_INVITE_ROLE = "Editor";
+const NO_PROVIDERS: ConnectProvider[] = [];
+
+function platformName(id: string): string {
+  return PLATFORMS[id]?.displayName ?? id;
+}
+
+function SignInForm({ onSwitch }: { onSwitch: () => void }): React.ReactElement {
+  const { login } = useAuth();
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: FormEvent): Promise<void> {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    try {
+      await login(username.trim(), password);
+      window.location.assign("/streams");
+    } catch (err) {
+      setError(errorMessage(err));
+      setBusy(false);
+    }
+  }
+
+  return (
+    <form onSubmit={(e) => void submit(e)}>
+      <h2 className="mb-1 text-base font-semibold">Sign in</h2>
+      <p className="mb-4 text-xs text-text-faint">Use the username and password you registered with.</p>
+      <div className="space-y-2">
+        <Input type="text" value={username} onChange={(e) => setUsername(e.target.value)} placeholder="username" autoComplete="username" autoFocus />
+        <Input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" autoComplete="current-password" />
+      </div>
+      {error !== null && <p className="mt-2 text-xs text-danger">{error}</p>}
+      <div className="mt-6 flex items-center justify-between">
+        <Button type="button" variant="ghost" onClick={onSwitch}>Create a workspace instead</Button>
+        <Button type="submit" variant="primary" disabled={busy || username.trim() === "" || password === ""}>
+          {busy ? "Signing in…" : "Sign in"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+
+export default function OnboardingPage(): React.ReactElement {
+  const { status, session, register, adoptToken, logout } = useAuth();
+  const offline = status === "offline";
+  const [mode, setMode] = useState<"register" | "signin">("register");
+  const [step, setStep] = useState(0);
+  const [name, setName] = useState("");
+  const [displayName, setDisplayName] = useState("");
+  const [username, setUsername] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [emails, setEmails] = useState("");
+  const [inviteRole, setInviteRole] = useState<string>(DEFAULT_INVITE_ROLE);
+  const { data: providers, source: providerSource } = useApiResource<ConnectProvider[], ConnectProvider[]>("/connections/providers", (p) => p, NO_PROVIDERS);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [sessionExpired, setSessionExpired] = useState(false);
+
+  // The API client redirects here with ?reason=session on a 401: default to sign-in.
+  useEffect(() => {
+    if (new URLSearchParams(window.location.search).get("reason") === "session") {
+      setSessionExpired(true);
+      setMode("signin");
+    }
+  }, []);
+
+  async function createWorkspace(): Promise<void> {
+    if (offline) {
+      setStep(1);
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    try {
+      await register({
+        workspaceName: name.trim(),
+        username: username.trim(),
+        password,
+        ...(displayName.trim() === "" ? {} : { displayName: displayName.trim() }),
+        ...(email.trim() === "" ? {} : { email: email.trim() }),
+      });
+      setStep(1);
+    } catch (err) {
+      setError(errorMessage(err));
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  async function sendInvites(): Promise<void> {
+    const list = emails.split(/[\s,;]+/).map((e) => e.trim()).filter((e) => e.includes("@"));
+    if (offline || list.length === 0) {
+      setStep(2);
+      return;
+    }
+    setBusy(true);
+    setError(null);
+    const failures: string[] = [];
+    // Sequential: each invite bumps the authz epoch and returns the token the next call must use.
+    for (const invitee of list) {
+      try {
+        const result = await api.post<MemberMutationResult>("/team/members/invite", { email: invitee, role: inviteRole });
+        adoptToken(result.token);
+      } catch (err) {
+        failures.push(`${invitee}: ${errorMessage(err)}`);
+      }
+    }
+    setBusy(false);
+    if (failures.length > 0) setError(failures.join(" · "));
+    else setStep(2);
+  }
+
+  const usernameValid = /^[a-z0-9][a-z0-9_.-]{1,31}$/.test(username.trim());
+  const registerReady =
+    name.trim().length >= 2 && (offline || (usernameValid && password.length >= MIN_PASSWORD));
+
+  // Signed-in visitors who land here (e.g. from the sidebar) get a way out rather than a second registration form.
+  if (status === "authenticated" && session !== null && step === 0) {
+    return (
+      <div className="flex h-full items-center justify-center p-6">
+        <Card className="w-[520px] max-w-full p-6">
+          <h2 className="mb-1 text-base font-semibold">You&apos;re signed in</h2>
+          <p className="mb-6 text-xs text-text-faint">
+            @{session.user.username} · {session.role} of <span className="text-text">{session.workspace.name}</span>
+          </p>
+          <div className="flex justify-between">
+            <Button variant="ghost" onClick={() => void logout()}>Sign out</Button>
+            <Link href="/streams" className="rounded-md bg-accent px-3 py-1.5 text-xs font-medium text-white hover:bg-accent-hover">
+              Continue to Streams
+            </Link>
+          </div>
+        </Card>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex h-full items-center justify-center p-6">
+      <Card className="w-[520px] max-w-full p-6">
+        <div className="mb-4 flex items-center justify-end">
+          <Button
+            size="sm"
+            variant="outline"
+            onClick={() => { setMode(mode === "signin" ? "register" : "signin"); setStep(0); }}
+          >
+            {mode === "signin" ? "Create a workspace" : "Existing account? Log in"}
+          </Button>
+        </div>
+        {offline && (
+          <div className="mb-4 flex justify-end">
+            <OfflineBadge source="sample" />
+          </div>
+        )}
+        {sessionExpired && step === 0 && (
+          <p className="mb-4 rounded-md border border-warn/30 bg-warn/10 px-3 py-2 text-xs text-warn">
+            Your session ended (expired, or your role changed). Sign in again.
+          </p>
+        )}
+
+        {mode === "signin" && step === 0 && !offline ? (
+          <SignInForm onSwitch={() => setMode("register")} />
+        ) : (
+          <>
+            <div className="mb-6 flex items-center gap-2">
+              {STEPS.map((s, i) => (
+                <div key={s} className="flex flex-1 items-center gap-2">
+                  <span
+                    className={`flex h-6 w-6 items-center justify-center rounded-full text-2xs font-semibold ${
+                      i < step ? "bg-live/20 text-live" : i === step ? "bg-accent text-white" : "bg-surface-2 text-text-faint"
+                    }`}
+                  >
+                    {i < step ? "✓" : i + 1}
+                  </span>
+                  <span className={`text-xs ${i === step ? "text-text" : "text-text-faint"}`}>{s}</span>
+                  {i < STEPS.length - 1 && <span className="h-px flex-1 bg-border-subtle" />}
+                </div>
+              ))}
+            </div>
+
+            {step === 0 && (
+              <form
+                onSubmit={(e) => {
+                  e.preventDefault();
+                  void createWorkspace();
+                }}
+              >
+                <div className="mb-5">
+                  <div className="mb-4 overflow-hidden rounded-lg border border-border-subtle">
+                    <img
+                      src="/brand/hero.png"
+                      alt="Tactical Media Broadcast Hub — arrows from a circle, warm red on black"
+                      width={1024}
+                      height={1024}
+                      className="h-36 w-full object-cover"
+                    />
+                  </div>
+                  <div className="text-center">
+                    <h1 className="text-2xl font-semibold tracking-tight">Tactical Media Broadcast Hub</h1>
+                    <p className="mt-1 text-2xs text-text-faint">Your platform. Their feeds. No algorithm in between.</p>
+                  </div>
+                </div>
+                <h2 className="mb-1 text-base font-semibold">Name your workspace</h2>
+                <p className="mb-4 text-xs text-text-faint">The tenant boundary for accounts, drafts, and audit.</p>
+                <Input value={name} onChange={(e) => setName(e.target.value)} placeholder="Your collective, your studio…" autoFocus />
+                {!offline && (
+                  <div className="mt-4 space-y-2">
+                    <p className="text-xs text-text-faint">Your owner account</p>
+                    <Input value={displayName} onChange={(e) => setDisplayName(e.target.value)} placeholder="Your name (optional)" autoComplete="name" />
+                    <Input
+                      type="text"
+                      value={username}
+                      onChange={(e) => setUsername(e.target.value.toLowerCase())}
+                      placeholder="Username — this is how you sign in"
+                      autoComplete="username"
+                      pattern="[a-z0-9][a-z0-9_.-]{1,31}"
+                      title="2-32 characters: lowercase letters, digits, dot, underscore or hyphen"
+                    />
+                    <Input
+                      type="password"
+                      value={password}
+                      onChange={(e) => setPassword(e.target.value)}
+                      placeholder={`Password (min ${MIN_PASSWORD} characters)`}
+                      autoComplete="new-password"
+                    />
+                    <Input
+                      type="email"
+                      value={email}
+                      onChange={(e) => setEmail(e.target.value)}
+                      placeholder="Email (optional)"
+                      autoComplete="email"
+                    />
+                  </div>
+                )}
+                {error !== null && <p className="mt-2 text-xs text-danger">{error}</p>}
+                <div className="mt-6 flex items-center justify-between">
+                  {offline ? <span /> : (
+                    <Button type="button" variant="ghost" onClick={() => setMode("signin")}>I already have an account</Button>
+                  )}
+                  <Button type="submit" variant="primary" disabled={busy || !registerReady}>
+                    {busy ? "Creating…" : "Continue"}
+                  </Button>
+                </div>
+              </form>
+            )}
+
+            {step === 1 && (
+              <div>
+                <h2 className="mb-1 text-base font-semibold">Invite your team</h2>
+                <p className="mb-4 text-xs text-text-faint">
+                  Comma-separated emails. Invitees join at the chosen role; adjust roles on the Team page.
+                </p>
+                <textarea
+                  value={emails}
+                  onChange={(e) => setEmails(e.target.value)}
+                  rows={3}
+                  placeholder="priya@studio.io, yuki@studio.io"
+                  className="w-full resize-none rounded-md border border-border bg-surface-2 p-2 text-sm focus:border-accent focus:outline-none"
+                />
+                <label className="mt-3 flex items-center gap-2 text-xs text-text-faint">
+                  Invite role
+                  <select
+                    value={inviteRole}
+                    onChange={(e) => setInviteRole(e.target.value)}
+                    className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs"
+                  >
+                    {INVITE_ROLE_CHOICES.map((role) => (
+                      <option key={role} value={role}>{role}</option>
+                    ))}
+                  </select>
+                </label>
+                {error !== null && <p className="mt-2 text-xs text-danger">{error}</p>}
+                <div className="mt-6 flex justify-between">
+                  {/* The workspace already exists once step 0 succeeds; going back would re-register. */}
+                  <Button variant="ghost" onClick={() => setStep(2)}>Skip</Button>
+                  <Button variant="primary" disabled={busy} onClick={() => void sendInvites()}>
+                    {busy ? "Inviting…" : "Continue"}
+                  </Button>
+                </div>
+              </div>
+            )}
+
+            {step === 2 && (
+              <div>
+                <h2 className="mb-1 text-base font-semibold">Connect your first accounts</h2>
+                <p className="mb-4 text-xs text-text-faint">
+                  {providerSource === "live" && providers.length > 0
+                    ? `Available: ${providers.map((p) => platformName(p.id)).join(", ")}. Follow each linking flow — bot tokens where required, OAuth on your instance otherwise.`
+                    : "Connect at least one account so your workspace can publish."}
+                </p>
+                <div className="space-y-2">
+                  {providerSource === "live" && providers.length > 0 ? (
+                    providers.map((p) => (
+                      <div key={p.id} className="flex items-center justify-between rounded-md border border-border-subtle px-3 py-2.5">
+                        <div className="flex items-center gap-3">
+                          <ArrowGlyph size={11} className="text-accent" />
+                          <span className="text-sm font-medium">{platformName(p.id)}</span>
+                        </div>
+                        <Button
+                          size="sm"
+                          variant="outline"
+                          onClick={() => window.location.assign(`/connections?start=${p.id}`)}
+                        >
+                          Connect
+                        </Button>
+                      </div>
+                    ))
+                  ) : (
+                    <p className={`rounded-md border px-3 py-2.5 text-xs ${providerSource === "loading" || providerSource === "live" ? "border-border-subtle text-text-faint" : "border-danger text-danger"}`}>
+                      {providerSource === "loading"
+                        ? "Loading connectable platforms…"
+                        : providerSource === "live"
+                          ? "No connectable platforms are available yet."
+                          : "Could not load the platform list — check that the API is reachable, or continue and connect later from Connections."}
+                    </p>
+                  )}
+                </div>
+                <p className="mt-3 text-2xs text-text-faint">Connecting opens the account linking flow — you can also do this later from Connections.</p>
+                <div className="mt-6 flex justify-between">
+                  <Button variant="ghost" onClick={() => setStep(1)}>Back</Button>
+                  <Button variant="primary" onClick={() => setStep(3)}>Finish setup</Button>
+                </div>
+              </div>
+            )}
+
+            {step === 3 && (
+              <div className="py-8 text-center">
+                <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-live/20 text-lg text-live">✓</div>
+                <h2 className="text-base font-semibold">{session?.workspace.name ?? (name || "Workspace")} is ready</h2>
+                <p className="mt-1 text-xs text-text-faint">
+                  Link accounts any time from <Link href="/connections" className="text-accent hover:underline">Connections</Link> — or head to{" "}
+                  <Link href="/streams" className="text-accent hover:underline">Streams</Link> or{" "}
+                  <Link href="/compose" className="text-accent hover:underline">Compose</Link>
+                </p>
+              </div>
+            )}
+          </>
+        )}
+      </Card>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/search/page.tsx b/apps/web/src/app/(main)/search/page.tsx
new file mode 100644
index 0000000..72d3803
--- /dev/null
+++ b/apps/web/src/app/(main)/search/page.tsx
@@ -0,0 +1,58 @@
+"use client";
+
+import { useEffect, useMemo, useRef, useState } from "react";
+import { useRouter } from "next/navigation";
+import { generateFeed, type FeedItem } from "../../../lib/fixtures";
+import { getPlatform, MOCK_COLUMN_DEFS, PLATFORMS, type Platform } from "../../../lib/platforms";
+import { readSavedSearches, saveSearches } from "../../../lib/saved-searches";
+import { PostCard } from "../../../components/mobile/post-card";
+import { SourceChips } from "../../../components/mobile/source-chips";
+import { AmplifySheet } from "../../../components/mobile/amplify-sheet";
+import { useApiResource } from "../../../lib/use-api";
+import type { ConnectionSummary } from "../../../lib/api-types";
+
+const identity = (value: ConnectionSummary[]): ConnectionSummary[] => value;
+const empty: ConnectionSummary[] = [];
+const sample = MOCK_COLUMN_DEFS.flatMap((column, i) => generateFeed(column.platformId, 80, (i + 1) * 11));
+// Trending values are local fixtures until tenant-scoped aggregation exists.
+const trends = [{ label: "product", bars: [2, 3, 4, 3, 5, 8, 12] }, { label: "connector", bars: [3, 3, 5, 4, 6, 7, 8] }, { label: "audit", bars: [2, 2, 3, 3, 4, 4, 6] }];
+const RECENT_KEY = "tmbh.recent-searches";
+
+export default function SearchPage(): React.ReactElement {
+  const router = useRouter();
+  const connections = useApiResource<ConnectionSummary[], ConnectionSummary[]>("/connections", identity, empty);
+  const input = useRef<HTMLInputElement>(null);
+  const [query, setQuery] = useState("");
+  const [active, setActive] = useState("all");
+  const [saved, setSaved] = useState<string[]>([]);
+  const [recent, setRecent] = useState<string[]>([]);
+  const [amplify, setAmplify] = useState<{ item: FeedItem; platform: Platform } | null>(null);
+  useEffect(() => {
+    setSaved(readSavedSearches());
+    try { const value: unknown = JSON.parse(localStorage.getItem(RECENT_KEY) ?? "[]"); if (Array.isArray(value)) setRecent(value.filter((part): part is string => typeof part === "string")); } catch { /* corrupt local preference */ }
+    const focus = (): void => input.current?.focus();
+    window.addEventListener("mobile-search-focus", focus);
+    return () => window.removeEventListener("mobile-search-focus", focus);
+  }, []);
+  const results = useMemo(() => query.trim() === "" ? [] : sample.filter((item) => `${item.text} ${item.handle} ${item.author}`.toLowerCase().includes(query.trim().toLowerCase())), [query]);
+  const visible = active === "all" ? results : results.filter((item) => item.platform === active);
+  const localProviders = new Set(MOCK_COLUMN_DEFS.map((column) => column.platformId));
+  function remember(term: string): void { const values = [term.trim(), ...recent.filter((part) => part !== term.trim())].filter(Boolean).slice(0, 8); setRecent(values); localStorage.setItem(RECENT_KEY, JSON.stringify(values)); }
+  function save(term: string): void { saveSearches([...saved, term]); setSaved(readSavedSearches()); remember(term); }
+  return <div className="mx-auto min-h-full max-w-2xl pb-6">
+    <div className="sticky top-0 z-10 border-b border-border-subtle bg-bg px-4 py-3"><div className="flex items-center gap-2"><button type="button" className="min-h-11 min-w-11 text-xl" aria-label="Clear search" onClick={() => { setQuery(""); setActive("all"); }}>←</button><span className="shrink-0 rounded-full border border-border px-2 py-0.5 text-2xs text-text-faint">sample results</span><input ref={input} id="mobile-search" data-search-field value={query} onChange={(event) => setQuery(event.target.value)} onKeyDown={(event) => { if (event.key === "Enter") { remember(query); input.current?.blur(); } }} placeholder="Search posts and accounts" className="min-h-[54px] min-w-0 flex-1 rounded-lg border border-border bg-surface-2 px-4 text-sm outline-none focus:border-accent" /></div></div>
+    {query.trim() === "" ? <div className="space-y-6 p-4">
+      <p className="text-xs text-text-faint">Search and trends use sample feeds. Cross-platform search is not connected yet. {connections.source === "live" ? `${connections.data.length} accounts connected.` : ""}</p>
+      <section><h2 className="mb-2 text-sm font-semibold">Saved searches</h2><div className="flex flex-wrap gap-2">{saved.map((term) => <button key={term} type="button" onClick={() => setQuery(term)} className="min-h-11 rounded-full border border-border px-4 text-xs">{term} · pinned on Home</button>)}</div></section>
+      <section><h2 className="mb-2 text-sm font-semibold">Trending in sample feeds</h2>{trends.map((trend) => <button key={trend.label} type="button" onClick={() => { setQuery(trend.label); remember(trend.label); }} className="flex min-h-14 w-full items-center justify-between border-b border-border-subtle text-left text-sm"><span>#{trend.label}</span><span className="flex h-8 items-end gap-0.5" aria-hidden="true">{trend.bars.map((bar, i) => <span key={i} className={`w-1.5 ${bar > 9 ? "bg-accent" : "bg-text-faint"}`} style={{ height: `${bar * 2}px` }} />)}</span></button>)}</section>
+      <section><h2 className="mb-2 text-sm font-semibold">Recent</h2>{recent.map((term) => <div key={term} className="flex items-center"><button type="button" onClick={() => setQuery(term)} className="min-h-11 flex-1 text-left text-sm">{term}</button><button type="button" aria-label={`Clear ${term}`} className="min-h-11 min-w-11" onClick={() => { const values = recent.filter((part) => part !== term); setRecent(values); localStorage.setItem(RECENT_KEY, JSON.stringify(values)); }}>×</button></div>)}</section>
+    </div> : <div>
+      <div className="flex items-center justify-between px-4 py-2"><span className="text-xs text-text-faint">{results.length} posts</span><button type="button" className="min-h-11 rounded-md border border-accent px-3 text-xs text-accent" onClick={() => save(query)}>Save search</button></div>
+      <SourceChips sources={[{ id: "all", label: "All", count: results.length }, ...[...localProviders].map((id) => ({ id, label: PLATFORMS[id]?.displayName ?? id, dot: id, count: results.filter((item) => item.platform === id).length }))]} value={active} onChange={setActive} />
+      <div className="flex gap-2 overflow-x-auto px-4 pb-2">{Object.keys(PLATFORMS).filter((id) => !localProviders.has(id)).map((id) => <span key={id} className="rounded-full border border-border px-3 py-2 text-xs text-text-faint">{PLATFORMS[id]?.displayName} –</span>)}</div>
+      {visible.map((item) => <PostCard key={`${item.platform}-${item.id}`} item={item} platform={getPlatform(item.platform)} match={query} onAmplify={() => setAmplify({ item, platform: getPlatform(item.platform) })} onReply={() => router.push(`/compose?text=${encodeURIComponent(`@${item.handle.replace(/^@/, "")} `)}`)} />)}
+      {visible.length === 0 && <p className="p-6 text-center text-sm text-text-faint">No matches in the sample feeds.</p>}
+    </div>}
+    <AmplifySheet post={amplify?.item ?? null} platform={amplify?.platform ?? null} open={amplify !== null} onClose={() => setAmplify(null)} />
+  </div>;
+}
diff --git a/apps/web/src/app/(main)/settings/page.tsx b/apps/web/src/app/(main)/settings/page.tsx
new file mode 100644
index 0000000..13f5537
--- /dev/null
+++ b/apps/web/src/app/(main)/settings/page.tsx
@@ -0,0 +1,109 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import { Avatar, Button } from "../../../components/ui/primitives";
+import { errorMessage } from "../../../lib/api-client";
+import { useAuth } from "../../../lib/auth-store";
+
+/**
+ * Deliberately small: this page states exactly what the API knows about the
+ * current session and how to end it. There is no notifications/preferences
+ * endpoint in the API, so none of that is faked here — no toggles that
+ * pretend to persist.
+ */
+
+function Field({ label, value, mono = false }: { label: string; value: string; mono?: boolean }): React.ReactElement {
+  return (
+    <div className="flex items-start justify-between gap-4 px-4 py-3">
+      <span className="text-xs text-text-faint">{label}</span>
+      <span className={`min-w-0 break-all text-right text-xs text-text ${mono ? "font-mono" : ""}`}>{value}</span>
+    </div>
+  );
+}
+
+export default function SettingsPage(): React.ReactElement {
+  const router = useRouter();
+  const { session, status, offline, logout } = useAuth();
+  const [signingOut, setSigningOut] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function signOut(): Promise<void> {
+    setSigningOut(true);
+    setError(null);
+    try {
+      // The store's logout also clears the local token; a network failure must
+      // still sign you out of this device, hence the swallow-then-state reset.
+      await logout();
+      router.push("/");
+    } catch (err) {
+      setError(errorMessage(err));
+      setSigningOut(false);
+    }
+  }
+
+  const statusLine =
+    status === "authenticated" ? "signed in" : status === "loading" ? "checking session…" : offline ? "offline" : status;
+
+  return (
+    <div className="h-full overflow-y-auto p-4 pb-24 lg:p-6">
+      <div className="mx-auto max-w-2xl">
+        <h1 className="mb-1 text-lg font-semibold">Settings</h1>
+        <p className="mb-5 text-xs text-text-faint">
+          What the API knows about this session. Workspace-level configuration lives in Team and Connections; there is no
+          per-user preference store in the API, so none is shown here.
+        </p>
+
+        <section className="mb-6 rounded-lg border border-border-subtle bg-surface">
+          <div className="flex items-center gap-4 border-b border-border-subtle p-4">
+            <Avatar handle={session?.user.displayName || session?.user.username || "AP"} />
+            <div className="min-w-0 flex-1">
+              <p className="truncate text-sm font-semibold">
+                {session?.user.displayName || session?.user.username || "Not signed in"}
+              </p>
+              <p className="text-xs text-text-faint">
+                {session === null ? "No verified session on this device." : `@${session.user.username}`}
+              </p>
+            </div>
+            <span className="rounded-full bg-accent px-2.5 py-1 text-2xs font-bold uppercase text-white">
+              {session?.role ?? statusLine}
+            </span>
+          </div>
+          <div className="divide-y divide-border-subtle">
+            <Field label="Username" value={session?.user.username ?? "—"} />
+            <Field label="Workspace" value={session?.workspace.name ?? "—"} />
+            <Field label="Role" value={session?.role ?? "—"} />
+            <Field label="Workspace slug" value={session?.workspace.slug ?? "—"} mono />
+            <Field
+              label="Permissions"
+              value={session === null ? "—" : session.permissions.length > 0 ? session.permissions.join(", ") : "none"}
+              mono
+            />
+            <Field
+              label="Session expires"
+              value={
+                session === null
+                  ? "—"
+                  : `${new Date(session.expiresAt).toLocaleString()} (${Intl.DateTimeFormat().resolvedOptions().timeZone})`
+              }
+            />
+          </div>
+        </section>
+
+        {error !== null && <p role="alert" className="mb-3 text-xs text-danger">{error}</p>}
+        <Button
+          variant="danger"
+          disabled={signingOut || session === null}
+          onClick={() => void signOut()}
+          title={session === null ? "No session to end." : "Ends the workspace session on the API and clears this device's token."}
+        >
+          {signingOut ? "Signing out…" : "Sign out"}
+        </Button>
+        <p className="mt-2 text-2xs text-text-faint">
+          Signing out calls <code className="font-mono">POST /auth/logout</code> on the API, clears the token here, and
+          returns you to the landing page.
+        </p>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/streams/page.tsx b/apps/web/src/app/(main)/streams/page.tsx
new file mode 100644
index 0000000..fe89aa1
--- /dev/null
+++ b/apps/web/src/app/(main)/streams/page.tsx
@@ -0,0 +1,284 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { generateFeed } from "../../../lib/fixtures";
+import { MOCK_COLUMN_DEFS, type Platform } from "../../../lib/platforms";
+import { StreamColumn, type ColumnDef } from "../../../components/streams/column";
+import { Button } from "../../../components/ui/primitives";
+import { EmptyState } from "../../../components/brand/empty-state";
+import { PostCard } from "../../../components/mobile/post-card";
+import { SourceChips } from "../../../components/mobile/source-chips";
+import { PullToRefresh } from "../../../components/mobile/pull-to-refresh";
+import { AmplifySheet } from "../../../components/mobile/amplify-sheet";
+import { readSavedSearches, saveSearches } from "../../../lib/saved-searches";
+import { useApiResource } from "../../../lib/use-api";
+import { api, errorMessage } from "../../../lib/api-client";
+import { liveColumns, streamItemKey, streamPlatform, type FeedsResponse, type StreamItem as FeedItem } from "../../../lib/streams-data";
+import Link from "next/link";
+import { useRouter } from "next/navigation";
+
+interface Toast {
+  id: number;
+  text: string;
+}
+
+interface QuoteTarget {
+  item: FeedItem;
+  platform: Platform;
+}
+
+const COLUMN_SEEDS = [11, 22, 33];
+
+const COLUMNS: ColumnDef[] = MOCK_COLUMN_DEFS.map((def, i) => ({
+  ...def,
+  items: generateFeed(def.platformId, [500, 420, 380][i] ?? 400, COLUMN_SEEDS[i] ?? 1),
+}));
+
+const SAMPLE_RESPONSE: FeedsResponse = { items: [], nextCursor: null, meta: { configuredFeeds: 0, connections: [], excludedConnections: [] } };
+const toFeeds = (response: FeedsResponse): FeedsResponse => response;
+
+export default function StreamsPage(): React.ReactElement {
+  const router = useRouter();
+  const resource = useApiResource("/feeds", toFeeds, SAMPLE_RESPONSE, { limit: 200 });
+  // Mock columns only when the API is unreachable; a live workspace with zero
+  // configured feeds gets an honest empty state instead of sample data.
+  const mock = resource.source === "sample";
+  const noFeeds = resource.source === "live" && !resource.error && resource.data.meta.configuredFeeds === 0;
+  const columns = useMemo(() => mock ? COLUMNS : resource.error || noFeeds ? [] : liveColumns(resource.data), [mock, noFeeds, resource.data, resource.error]);
+  const statusLabel = resource.source === "loading" ? "Loading feeds…" : mock ? "Offline — sample feed" : noFeeds ? "No configured feeds" : resource.error ?? "Live feeds";
+  useEffect(() => {
+    const timer = setInterval(resource.reload, 30_000);
+    return () => clearInterval(timer);
+  }, [resource.reload]);
+  const [source, setSource] = useState("all");
+  const [refreshKey, setRefreshKey] = useState(0);
+  const [amplify, setAmplify] = useState<QuoteTarget | null>(null);
+  const [saved, setSaved] = useState<string[]>([]);
+  const [selectedFlat, setSelectedFlat] = useState(0);
+  const [toasts, setToasts] = useState<Toast[]>([]);
+  const [quote, setQuote] = useState<QuoteTarget | null>(null);
+  const [quoteText, setQuoteText] = useState("");
+
+  useEffect(() => {
+    const sync = (): void => setSaved(readSavedSearches());
+    sync();
+    window.addEventListener("saved-searches-change", sync);
+    return () => window.removeEventListener("saved-searches-change", sync);
+  }, []);
+  const feed = useMemo(() => columns.flatMap((column) => column.items).sort((a, b) => a.ageMinutes - b.ageMinutes), [columns]);
+  const extraColumns: ColumnDef[] = useMemo(() => saved.filter((term) => !MOCK_COLUMN_DEFS.some((column) => column.title === `Saved: ${term}`)).map((term) => {
+    const items = feed.filter((item) => item.text.toLowerCase().includes(term.toLowerCase()));
+    return { key: `saved:${term}`, title: `Saved: ${term}`, platformId: items[0]?.platform ?? MOCK_COLUMN_DEFS[0]?.platformId ?? "limited", staleness: mock ? "sample" : "live", platform: items[0] ? streamPlatform(items[0]) : undefined, items };
+  }), [feed, saved, mock]);
+  const shown = source === "all" || source === "columns" ? feed : source.startsWith("saved:") ? feed.filter((item) => item.text.toLowerCase().includes(source.slice(6).toLowerCase())) : columns.find((column) => column.key === source)?.items ?? [];
+  const allColumns = useMemo(() => source === "columns" ? [...columns, ...extraColumns] : [{ key: source, title: source === "all" ? "All feeds" : columns.find((column) => column.key === source)?.title ?? source.slice(6), platformId: shown[0]?.platform ?? MOCK_COLUMN_DEFS[0]?.platformId ?? "limited", platform: shown[0] ? streamPlatform(shown[0]) : undefined, staleness: mock ? "sample" : "live", items: shown }], [columns, extraColumns, shown, source, mock]);
+  useEffect(() => { setSelectedFlat(0); }, [source]);
+  const offsets = useMemo(() => allColumns.reduce<number[]>((acc, _column, index) => [...acc, (acc[index - 1] ?? 0) + (allColumns[index - 1]?.items.length ?? 0)], []), [allColumns]);
+  const flatMax = (offsets[offsets.length - 1] ?? 0) + (allColumns[allColumns.length - 1]?.items.length ?? 0) - 1;
+  useEffect(() => { setSelectedFlat((current) => Math.max(0, Math.min(current, flatMax))); }, [flatMax]);
+  useEffect(() => {
+    if (source !== "all" && source !== "columns" && !source.startsWith("saved:") && !columns.some((column) => column.key === source)) setSource("all");
+  }, [columns, source]);
+  const mobileItems = source === "columns" ? allColumns.flatMap((column) => column.items) : shown;
+  const sources = [{ id: "all", label: "All feeds", count: feed.length }, { id: "columns", label: "Columns" }, ...columns.map((column) => ({ id: column.key, label: column.title, dot: column.platformId, count: column.items.length })), ...saved.map((term) => ({ id: `saved:${term}`, label: `Saved: ${term}`, count: feed.filter((item) => item.text.toLowerCase().includes(term.toLowerCase())).length }))];
+  const refresh = async (): Promise<void> => {
+    try {
+      if (!mock) await api.post("/feeds/refresh");
+      resource.reload();
+      setRefreshKey((key) => key + 1);
+    } catch (error) { pushToast(errorMessage(error)); }
+  };
+
+  useEffect(() => {
+    if (window.matchMedia("(max-width: 1023px)").matches) document.querySelector('[data-stream-selected="true"]')?.scrollIntoView({ block: "nearest" });
+  }, [selectedFlat]);
+
+  const pushToast = useCallback((text: string) => {
+    const id = Date.now() + Math.random();
+    setToasts((t) => [...t, { id, text }]);
+    setTimeout(() => setToasts((t) => t.filter((x) => x.id !== id)), 2600);
+  }, []);
+
+  const locate = useCallback(
+    (flat: number): { column: ColumnDef; item: FeedItem; platform: Platform } | null => {
+      for (let i = allColumns.length - 1; i >= 0; i -= 1) {
+        const start = offsets[i] ?? 0;
+        if (flat >= start) {
+          const item = allColumns[i]?.items[flat - start];
+          const column = allColumns[i];
+          if (item === undefined || column === undefined) return null;
+          return { column, item, platform: streamPlatform(item) };
+        }
+      }
+      return null;
+  }, [allColumns, offsets]);
+
+  const notConnectedToast = useCallback(() => {
+    pushToast(mock ? "sample — connect an account to boost" : "Not connected — connect an account to boost");
+  }, [mock, pushToast]);
+
+  const doRepost = useCallback(
+    (item: FeedItem, platform: Platform) => {
+      // No connection id: there is nothing to amplify through — never fake success.
+      if (item.connectionId) { setAmplify({ item, platform }); return; }
+      notConnectedToast();
+    },
+    [notConnectedToast],
+  );
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent): void => {
+      if (quote !== null) {
+        if (e.key === "Escape") setQuote(null);
+        return;
+      }
+      const target = e.target as HTMLElement | null;
+      if (target !== null && (target.tagName === "INPUT" || target.tagName === "TEXTAREA" || target.isContentEditable)) return;
+      if (e.key === "j" || e.key === "ArrowDown") {
+        e.preventDefault();
+        setSelectedFlat((f) => Math.max(0, Math.min(f + 1, flatMax)));
+      } else if (e.key === "k" || e.key === "ArrowUp") {
+        e.preventDefault();
+        setSelectedFlat((f) => Math.max(f - 1, 0));
+      } else if (e.key === "r") {
+        const loc = locate(selectedFlat);
+        if (loc !== null && (loc.platform.capabilities.amplifyRepost || loc.platform.capabilities.amplifyShare)) {
+          doRepost(loc.item, loc.platform);
+        } else if (loc !== null) {
+          pushToast(`${loc.platform.displayName}: no repost capability — API exposes none`);
+        }
+      } else if (e.key === "q") {
+        const loc = locate(selectedFlat);
+        if (loc !== null && loc.item.connectionId === undefined) {
+          notConnectedToast();
+        } else if (loc !== null && (loc.platform.capabilities.amplifyQuote || loc.platform.capabilities.publishText)) {
+          setQuoteText("");
+          setQuote(loc);
+        } else if (loc !== null) {
+          pushToast(`${loc.platform.displayName}: no quote capability — API exposes none`);
+        }
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [locate, doRepost, notConnectedToast, pushToast, quote, selectedFlat, flatMax]);
+
+  const headerNote = "j/k move · r amplify · q quote";
+
+  return (
+    <div className="flex h-full min-w-0 flex-col">
+      <div className="flex items-center justify-between border-b border-border-subtle px-4 py-2"><span role="status" className="text-xs text-text-faint">{statusLabel}{!mock && resource.data.meta.excludedConnections.length > 0 ? ` · ${resource.data.meta.excludedConnections.length} accounts do not support feeds` : ""}</span><Button size="sm" variant="ghost" onClick={() => void refresh()}>Refresh</Button></div>
+      <SourceChips sources={sources} value={source} onChange={setSource} />
+      <div className="flex min-h-0 flex-1 flex-col lg:hidden">
+        <div className="flex items-center justify-end border-b border-border-subtle px-4 py-2"><button type="button" className="min-h-11 min-w-11 text-xl" aria-label="Search" onClick={() => router.push("/search")}>⌕</button></div>
+        {noFeeds ? (
+          <div className="p-6">
+            <EmptyState title="No configured feeds" hint="None of your connected accounts have feeds configured yet." />
+            <Link href="/connections" className="mt-3 flex min-h-11 items-center justify-center rounded-md bg-accent px-3 text-xs font-medium text-white hover:bg-accent-hover">Connect an account</Link>
+          </div>
+        ) : (
+        <PullToRefresh sourceCount={columns.length} onRefresh={refresh}>
+          <div key={refreshKey}>{mobileItems.map((item, index) => <PostCard key={`${streamItemKey(item)}:${index}`} item={item} selected={selectedFlat === index} onSelect={() => setSelectedFlat(index)} platform={streamPlatform(item)} onAmplify={() => doRepost(item, streamPlatform(item))} onReply={() => router.push(`/compose?text=${encodeURIComponent(`@${item.handle.replace(/^@/, "")} `)}`)} />)}</div>
+          {mobileItems.length === 0 && <EmptyState title="No posts in this source" hint="Choose another feed or saved search." />}
+        </PullToRefresh>
+        )}
+      </div>
+      <div className="hidden min-h-0 flex-1 flex-col lg:flex">
+      <div className="flex shrink-0 items-center justify-between border-b border-border-subtle bg-surface/60 px-4 py-1.5">
+        <span className="text-2xs text-text-faint">{headerNote}</span>
+        <div className="flex gap-1">
+          <Button size="sm" variant="ghost" onClick={() => { const term = window.prompt("Save a search as a column"); if (term?.trim()) saveSearches([...readSavedSearches(), term]); }}>+ Column</Button>
+        </div>
+      </div>
+      <div className="flex min-h-0 flex-1">
+        {noFeeds ? (
+          <div className="flex w-full flex-col items-center justify-center gap-3 self-center">
+            <EmptyState className="w-full self-center" title="No configured feeds" hint="None of your connected accounts have feeds configured yet." />
+            <Link href="/connections" className="rounded-md bg-accent px-3 py-1.5 text-xs font-medium text-white hover:bg-accent-hover">Connect an account</Link>
+          </div>
+        ) : allColumns.length === 0 && (
+          <EmptyState
+            className="w-full self-center"
+            title="No columns"
+            hint="Nothing on the wall yet — add a column to pull in a feed."
+          />
+        )}
+        {allColumns.map((column, i) => (
+          <StreamColumn
+            key={column.key}
+            column={column}
+            flatStartIndex={offsets[i] ?? 0}
+            selectedFlat={selectedFlat}
+            onSelectFlat={setSelectedFlat}
+            onRepost={doRepost}
+            onQuote={(item, platform) => {
+              // No connection id: nothing to quote through — say so instead of faking it.
+              if (item.connectionId === undefined) { notConnectedToast(); return; }
+              setQuoteText("");
+              setQuote({ item, platform });
+            }}
+          />
+        ))}
+      </div>
+      </div>
+      {!mock && !noFeeds && !resource.error && resource.data.nextCursor && <Button size="sm" variant="ghost" onClick={async () => {
+        try {
+          const next = await api.get<FeedsResponse>("/feeds", { limit: 200, cursor: resource.data.nextCursor ?? undefined });
+          resource.setData((current) => ({ ...next, items: [...new Map([...current.items, ...next.items].map((item) => [`${item.connectionId}:${item.id}`, item])).values()] }));
+        } catch (error) { pushToast(errorMessage(error)); }
+      }}>Load older posts</Button>}
+      <AmplifySheet post={amplify?.item ?? null} platform={amplify?.platform ?? null} open={amplify !== null} onClose={() => setAmplify(null)} />
+
+      {quote !== null && (
+        <div className="fixed inset-0 z-40 flex items-center justify-center bg-black/60" onClick={() => setQuote(null)}>
+          <div className="w-[520px] max-w-[90vw] rounded-lg border border-border bg-surface p-4 shadow-2xl" onClick={(e: React.MouseEvent) => e.stopPropagation()}>
+            <div className="mb-2 flex items-center justify-between">
+              <span className="text-sm font-medium">Quote {quote.item.handle}</span>
+              <span className="text-2xs text-text-faint">{quote.platform.displayName}</span>
+            </div>
+            <blockquote className="mb-3 max-h-24 overflow-y-auto rounded-md border border-border-subtle bg-surface-2 p-2 text-xs leading-relaxed text-text-dim scrollbar-thin">
+              {quote.item.text}
+            </blockquote>
+            <textarea
+              autoFocus
+              value={quoteText}
+              onChange={(e) => setQuoteText(e.target.value)}
+              rows={3}
+              placeholder="Add your commentary…"
+              className="w-full resize-none rounded-md border border-border bg-surface-2 p-2 text-sm text-text placeholder:text-text-faint focus:border-accent focus:outline-none"
+            />
+            <div className="mt-3 flex items-center justify-between">
+              <span className="text-2xs text-text-faint">{quoteText.length} / {quote.platform.charLimit}</span>
+              <div className="flex gap-2">
+                <Button variant="ghost" onClick={() => setQuote(null)}>Cancel</Button>
+                <Button
+                  variant="primary"
+                  disabled={quoteText.trim() === "" || quote.item.connectionId === undefined}
+                  title={quote.item.connectionId === undefined ? "not connected" : undefined}
+                  onClick={() => {
+                    if (quote.item.connectionId) {
+                      const params = new URLSearchParams({ text: `${quoteText}\n\n“${quote.item.text}”\nVia ${quote.item.handle}`, targets: quote.item.connectionId });
+                      router.push(`/compose?${params.toString()}`);
+                      setQuote(null);
+                    }
+                  }}
+                >
+                  {quote.item.connectionId ? "Open compose" : "Not connected"}
+                </Button>
+              </div>
+            </div>
+          </div>
+        </div>
+      )}
+
+      <div className="pointer-events-none fixed bottom-4 right-4 z-50 flex flex-col gap-2">
+        {toasts.map((t) => (
+          <div key={t.id} className="flex items-center gap-2 rounded-md border border-border bg-surface px-3 py-2 text-xs text-text shadow-lg">
+            <span className="h-3 w-0.5 shrink-0 rounded-full bg-accent" />
+            {t.text}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/team/page.tsx b/apps/web/src/app/(main)/team/page.tsx
new file mode 100644
index 0000000..12b52cb
--- /dev/null
+++ b/apps/web/src/app/(main)/team/page.tsx
@@ -0,0 +1,439 @@
+"use client";
+
+import { useState } from "react";
+import { Badge, Button, Card, Input } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { ASSETS, MEMBERS, ROLES } from "../../../lib/fixtures";
+import { ApiError, api, errorMessage } from "../../../lib/api-client";
+import type { InviteLink, InviteLinkStatus, Member, MemberMutationResult } from "../../../lib/api-types";
+import { useAuth } from "../../../lib/auth-store";
+import { useApiResource } from "../../../lib/use-api";
+import { Loading } from "../../../components/brand/loading";
+
+const OWNER = "Owner";
+
+const SAMPLE_MEMBERS: Member[] = MEMBERS.map((m) => ({
+  id: String(m.id),
+  userId: String(m.id),
+  username: m.email.split("@")[0] ?? "member",
+  email: m.email,
+  displayName: m.name,
+  role: m.role,
+  status: m.status,
+  createdAt: new Date(0).toISOString(),
+}));
+
+const memberLabel = (m: Member): string => m.email ?? `@${m.username}`;
+
+/** Invite-link lifetime choices, in hours. */
+const LINK_TTL_OPTIONS: Array<{ hours: number; label: string }> = [
+  { hours: 24, label: "24 hours" },
+  { hours: 168, label: "7 days" },
+  { hours: 720, label: "30 days" },
+];
+const DEFAULT_LINK_TTL = 168;
+const DEFAULT_LINK_ROLE = "Editor";
+
+const SAMPLE_LINKS: InviteLink[] = [
+  {
+    id: "sample-1", role: "Publisher", createdAt: "2024-05-01T09:00:00.000Z",
+    expiresAt: new Date(Date.now() + 86_400_000 * 3).toISOString(), maxUses: 50, useCount: 38,
+    revokedAt: null, status: "active", createdByUserId: "sample-owner",
+  },
+  {
+    id: "sample-2", role: "Editor", createdAt: "2024-04-01T09:00:00.000Z",
+    expiresAt: new Date(Date.now() - 86_400_000).toISOString(), maxUses: null, useCount: 12,
+    revokedAt: null, status: "expired", createdByUserId: "sample-owner",
+  },
+  {
+    id: "sample-3", role: "Approver", createdAt: "2024-03-01T09:00:00.000Z",
+    expiresAt: new Date(Date.now() + 86_400_000).toISOString(), maxUses: 10, useCount: 10,
+    revokedAt: null, status: "exhausted", createdByUserId: "sample-owner",
+  },
+  {
+    id: "sample-4", role: "Analyst", createdAt: "2024-02-01T09:00:00.000Z",
+    expiresAt: new Date(Date.now() + 86_400_000).toISOString(), maxUses: null, useCount: 3,
+    revokedAt: "2024-02-04T09:00:00.000Z", status: "revoked", createdByUserId: "sample-owner",
+  },
+];
+
+const linkStatusTone = (status: InviteLinkStatus): "live" | "warn" | "neutral" =>
+  status === "active" ? "live" : status === "revoked" ? "neutral" : "warn";
+
+const usesLabel = (link: InviteLink): string =>
+  link.maxUses === null ? "unlimited" : `${link.useCount} / ${link.maxUses}`;
+
+const identity = <T,>(value: T): T => value;
+
+export default function TeamPage(): React.ReactElement {
+  const { session, can, adoptToken, logout } = useAuth();
+  const members = useApiResource<Member[], Member[]>("/team/members", identity, SAMPLE_MEMBERS);
+  const roles = useApiResource<string[], string[]>("/team/roles", identity, ROLES);
+  const links = useApiResource<InviteLink[], InviteLink[]>("/team/invite-links", identity, SAMPLE_LINKS);
+  const [inviteEmail, setInviteEmail] = useState("");
+  const [inviteRole, setInviteRole] = useState("Editor");
+  const [confirmRemove, setConfirmRemove] = useState<string | null>(null);
+  const [linkRole, setLinkRole] = useState(DEFAULT_LINK_ROLE);
+  const [linkTtl, setLinkTtl] = useState(String(DEFAULT_LINK_TTL));
+  const [linkMaxUses, setLinkMaxUses] = useState("");
+  const [createdLink, setCreatedLink] = useState<InviteLink | null>(null);
+  const [inviteLink, setInviteLink] = useState<InviteLink | null>(null);
+  const [copied, setCopied] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [message, setMessage] = useState<{ tone: "ok" | "error"; text: string } | null>(null);
+
+  const live = members.source === "live";
+  // Either resource falling back to fixtures means the screen is showing sample data somewhere.
+  const sampleMode = members.source === "sample" || links.source === "sample";
+  const canManage = !live || can("workspace.members.manage");
+  const isOwner = !live || session?.role === OWNER;
+
+  async function mutate(run: () => Promise<MemberMutationResult>, apply: (result: MemberMutationResult) => void | Promise<void>, ok: string): Promise<void> {
+    if (!live) {
+      setMessage({ tone: "error", text: "Offline — sample data is read-only." });
+      return;
+    }
+    setBusy(true);
+    setMessage(null);
+    try {
+      const result = await run();
+      // Membership changes bump the authz epoch; without the re-issued token our next call would 401.
+      adoptToken(result.token);
+      await apply(result);
+      if (ok !== "") setMessage({ tone: "ok", text: ok });
+    } catch (err) {
+      setMessage({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const changeRole = (member: Member, role: string): Promise<void> =>
+    mutate(
+      () => api.patch<MemberMutationResult>(`/team/members/${member.id}/role`, { role }),
+      (result) => {
+        const updated = result.member;
+        if (updated !== null) members.setData((list) => list.map((m) => (m.id === updated.id ? updated : m)));
+      },
+      `${memberLabel(member)} is now ${role}.`,
+    );
+
+  const invite = (): Promise<void> =>
+    mutate(
+      () => api.post<MemberMutationResult>("/team/members/invite", { email: inviteEmail.trim(), role: inviteRole }),
+      async (result) => {
+        const added = result.member;
+        if (added !== null) members.setData((list) => [...list, added]);
+        setInviteEmail("");
+        // No mailer exists, so the invitee would never see anything. Create a
+        // join link for the same role and hand it to the inviter instead.
+        const link = await api.post<InviteLink>("/team/invite-links", { role: inviteRole, expiresInHours: DEFAULT_LINK_TTL });
+        links.setData((list) => [link, ...list.filter((l) => l.id !== link.id)]);
+        setInviteLink(link);
+        setCopied(false);
+      },
+      "",
+    );
+
+  const remove = (member: Member): Promise<void> =>
+    mutate(
+      () => api.del<MemberMutationResult>(`/team/members/${member.id}`),
+      (result) => {
+        members.setData((list) => list.filter((m) => m.id !== member.id));
+        setConfirmRemove(null);
+        // Removing yourself ends your membership: no replacement token.
+        if (result.token === null && member.userId === session?.user.id) void logout();
+      },
+      `Removed ${memberLabel(member)}.`,
+    );
+
+  // Invite links: no epoch bump on create, but the returned token is displayed exactly once.
+  async function createLink(): Promise<void> {
+    if (!live) {
+      setMessage({ tone: "error", text: "Offline — sample data is read-only." });
+      return;
+    }
+    const maxUsesRaw = linkMaxUses.trim();
+    const maxUses = maxUsesRaw === "" ? undefined : Number(maxUsesRaw);
+    if (maxUses !== undefined && (!Number.isInteger(maxUses) || maxUses < 1)) {
+      setMessage({ tone: "error", text: "Max uses must be a whole number of 1 or more." });
+      return;
+    }
+    setBusy(true);
+    setMessage(null);
+    try {
+      const created = await api.post<InviteLink>("/team/invite-links", {
+        role: linkRole,
+        expiresInHours: Number(linkTtl),
+        ...(maxUses === undefined ? {} : { maxUses }),
+      });
+      links.setData((list) => [created, ...list.filter((l) => l.id !== created.id)]);
+      setCreatedLink(created);
+      setCopied(false);
+      setLinkMaxUses("");
+      setMessage({ tone: "ok", text: `Invite link created — ${created.role} access, shown once below.` });
+    } catch (err) {
+      setMessage({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  // Revoke returns the updated link (no re-issued token), so it skips `mutate`'s MemberMutationResult shape.
+  async function revokeLink(link: InviteLink): Promise<void> {
+    if (!live) {
+      setMessage({ tone: "error", text: "Offline — sample data is read-only." });
+      return;
+    }
+    setBusy(true);
+    setMessage(null);
+    try {
+      const revoked = await api.del<InviteLink>(`/team/invite-links/${link.id}`);
+      links.setData((list) => list.map((l) => (l.id === revoked.id ? revoked : l)));
+      setCreatedLink((current) => (current !== null && current.id === revoked.id ? revoked : current));
+      setMessage({ tone: "ok", text: `Revoked the ${link.role} invite link.` });
+    } catch (err) {
+      setMessage({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  const assignable = (current: string): string[] => roles.data.filter((r) => r !== OWNER || isOwner || current === OWNER);
+
+  return (
+    <div className="h-full overflow-y-auto p-6 scrollbar-thin">
+      <div className="mb-6 flex items-center gap-3">
+        <h1 className="text-lg font-semibold">Team</h1>
+        <OfflineBadge source={sampleMode ? "sample" : members.source} />
+      </div>
+
+      <Card className="mb-6 p-4">
+        {members.error !== null && <p className="mb-3 text-xs text-danger">{members.error}</p>}
+        {/* On a live error (e.g. 403) the sample roster is stale, so the table is withheld rather than faked. */}
+        {members.source !== "loading" && members.error !== null ? null : (
+        <table className="mobile-stack-table w-full text-sm">
+          <thead>
+            <tr className="border-b border-border-subtle text-left text-2xs text-text-faint">
+              <th className="pb-2 font-medium">Member</th>
+              <th className="pb-2 font-medium">Role</th>
+              <th className="pb-2 font-medium">Status</th>
+              <th className="pb-2" />
+            </tr>
+          </thead>
+          <tbody>
+            {members.source === "loading" && (
+              <tr><td colSpan={4} className="py-3"><span className="inline-flex items-center gap-2 text-xs text-text-faint"><Loading size={14} label="Loading members" /> Loading members…</span></td></tr>
+            )}
+            {members.source !== "loading" && members.data.map((m) => {
+              const ownerLocked = m.role === OWNER && !isOwner;
+              return (
+                <tr key={m.id} className="border-b border-border-subtle last:border-b-0">
+                  <td className="py-2.5">
+                    <div className="font-medium">{m.displayName}</div>
+                    <div className="text-2xs text-text-faint">{memberLabel(m)}</div>
+                  </td>
+                  <td className="py-2.5">
+                    <select
+                      value={m.role}
+                      disabled={!canManage || ownerLocked || busy}
+                      onChange={(e) => void changeRole(m, e.target.value)}
+                      className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs disabled:opacity-40"
+                    >
+                      {assignable(m.role).map((r) => (
+                        <option key={r} value={r}>{r}</option>
+                      ))}
+                    </select>
+                  </td>
+                  <td className="py-2.5">
+                    {m.status === "active" ? <Badge tone="live">active</Badge> : <Badge tone="warn">invited</Badge>}
+                  </td>
+                  <td className="py-2.5 text-right">
+                    {confirmRemove === m.id ? (
+                      <span className="flex items-center justify-end gap-2">
+                        <Button size="sm" variant="ghost" onClick={() => setConfirmRemove(null)}>Cancel</Button>
+                        <Button size="sm" variant="danger" disabled={busy} onClick={() => void remove(m)}>Confirm remove</Button>
+                      </span>
+                    ) : (
+                      <Button size="sm" variant="ghost" disabled={!canManage || ownerLocked} onClick={() => setConfirmRemove(m.id)}>
+                        Remove
+                      </Button>
+                    )}
+                  </td>
+                </tr>
+              );
+            })}
+          </tbody>
+        </table>
+        )}
+        {canManage && (
+          <div className="mt-4 flex flex-wrap gap-2">
+            <Input
+              value={inviteEmail}
+              onChange={(e) => setInviteEmail(e.target.value)}
+              placeholder="teammate@studio.io"
+              className="max-w-xs"
+            />
+            <select
+              value={inviteRole}
+              onChange={(e) => setInviteRole(e.target.value)}
+              className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs"
+              aria-label="Role for the invitee"
+            >
+              {assignable("").map((r) => (
+                <option key={r} value={r}>{r}</option>
+              ))}
+            </select>
+            <Button variant="outline" disabled={!inviteEmail.includes("@") || busy} onClick={() => void invite()}>Send invite</Button>
+          </div>
+        )}
+        {message !== null && (
+          <p className={`mt-2 text-2xs ${message.tone === "ok" ? "text-live" : "text-danger"}`}>{message.text}</p>
+        )}
+        <p className="mt-1.5 text-2xs text-text-faint">
+          Role changes and removals bump the workspace authz epoch — live sessions re-check and fail closed.
+          No invite email is sent — after inviting, share the join link shown above so the member can activate.
+        </p>
+      </Card>
+
+      <Card className="mb-6 p-4">
+        <h2 className="mb-1 text-sm font-semibold">Invite links</h2>
+        <p className="mb-4 text-xs text-text-faint">
+          Anyone with the link joins this workspace at the chosen role — no email needed. Links expire and can be revoked.
+        </p>
+        {canManage && (
+          <div className="mb-4 flex flex-wrap items-center gap-2">
+            <select
+              value={linkRole}
+              onChange={(e) => setLinkRole(e.target.value)}
+              className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs"
+              aria-label="Role for the invite link"
+            >
+              {assignable("").map((r) => (
+                <option key={r} value={r}>{r}</option>
+              ))}
+            </select>
+            <select
+              value={linkTtl}
+              onChange={(e) => setLinkTtl(e.target.value)}
+              className="rounded-md border border-border bg-surface-2 px-2 py-1 text-xs"
+              aria-label="How long the invite link stays valid"
+            >
+              {LINK_TTL_OPTIONS.map((option) => (
+                <option key={option.hours} value={String(option.hours)}>{option.label}</option>
+              ))}
+            </select>
+            <Input
+              type="number"
+              min={1}
+              step={1}
+              value={linkMaxUses}
+              onChange={(e) => setLinkMaxUses(e.target.value)}
+              placeholder="Max uses (optional)"
+              className="max-w-[11rem]"
+            />
+            <Button variant="outline" disabled={busy || roles.data.length === 0} onClick={() => void createLink()}>Create link</Button>
+          </div>
+        )}
+        {canManage && inviteLink !== null && (
+          <p className="mb-3 rounded-md border border-accent bg-accent-dim px-3 py-2 text-xs text-accent">Member added — share this link to activate (shown below).</p>
+        )}
+        {(inviteLink !== null || (createdLink !== null && createdLink.token !== undefined)) && (() => {
+          const link = inviteLink ?? createdLink;
+          if (link === null || link.token === undefined) return null;
+          return (
+          <div className="mb-4 rounded-md border border-border-subtle bg-surface-2 p-3">
+            <div className="mb-2 flex items-center justify-between">
+              <span className="text-xs font-medium">
+                {inviteLink !== null ? "Member added — share this link to activate" : "Share this link — shown once"}
+              </span>
+              <Badge tone="accent">{link.role}</Badge>
+            </div>
+            <div className="flex items-center gap-2">
+              <code className="min-w-0 flex-1 truncate rounded-md border border-border bg-bg px-2 py-1.5 font-mono text-2xs text-text">
+                {`${window.location.origin}/join/${link.token}`}
+              </code>
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={() => {
+                  void navigator.clipboard?.writeText(`${window.location.origin}/join/${link.token}`).then(() => {
+                    setCopied(true);
+                  }).catch(() => setCopied(false));
+                }}
+              >
+                {copied ? "Copied" : "Copy"}
+              </Button>
+            </div>
+            <p className="mt-2 text-2xs text-text-faint">
+              {inviteLink !== null
+                ? "No invite email is sent — copy this link and give it to the member. The token is shown only once."
+                : "The token is never shown again — copy it now. Revoke the link below if it leaks."}
+            </p>
+          </div>
+          );
+        })()}
+        {links.error !== null && <p className="mb-3 text-xs text-danger">{links.error}</p>}
+        {/* On a live error (e.g. 403) the sample data is stale, so the list is withheld rather than faked. */}
+        {links.error === null && (
+        <table className="mobile-stack-table w-full text-sm">
+          <thead>
+            <tr className="border-b border-border-subtle text-left text-2xs text-text-faint">
+              <th className="pb-2 font-medium">Role</th>
+              <th className="pb-2 font-medium">Uses</th>
+              <th className="pb-2 font-medium">Status</th>
+              <th className="pb-2 font-medium">Expires</th>
+              <th className="pb-2" />
+            </tr>
+          </thead>
+          <tbody>
+            {links.source === "loading" && (
+              <tr><td colSpan={5} className="py-3"><span className="inline-flex items-center gap-2 text-xs text-text-faint"><Loading size={14} label="Loading invite links" /> Loading invite links…</span></td></tr>
+            )}
+            {links.source !== "loading" && links.data.length === 0 && (
+              <tr><td colSpan={5} className="py-3 text-xs text-text-faint">No invite links yet — create one above.</td></tr>
+            )}
+            {links.source !== "loading" && links.data.map((link) => (
+              <tr key={link.id} className="border-b border-border-subtle last:border-b-0">
+                <td className="py-2.5 font-medium">{link.role}</td>
+                <td className="py-2.5 text-2xs text-text-faint">{usesLabel(link)}</td>
+                <td className="py-2.5"><Badge tone={linkStatusTone(link.status)}>{link.status}</Badge></td>
+                <td className="py-2.5 text-2xs text-text-faint">{new Date(link.expiresAt).toLocaleDateString()}</td>
+                <td className="py-2.5 text-right">
+                  {link.status === "active" ? (
+                    <Button size="sm" variant="ghost" disabled={!canManage || busy} onClick={() => void revokeLink(link)}>Revoke</Button>
+                  ) : (
+                    <span className="text-2xs text-text-faint">{link.revokedAt !== null ? `revoked ${new Date(link.revokedAt).toLocaleDateString()}` : "—"}</span>
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+        )}
+        <p className="mt-1.5 text-2xs text-text-faint">
+          Tokens are returned once, at creation; the list never exposes them. Joining as <em>Owner</em> requires an Owner to have created the link.
+        </p>
+      </Card>
+
+      {/* Asset library stays on fixtures: the media library API is not part of this wiring pass. */}
+      <h2 className="mb-3 text-sm font-semibold">Asset library <Badge tone="neutral">sample</Badge></h2>
+      <div className="grid grid-cols-2 gap-3 md:grid-cols-3 lg:grid-cols-6">
+        {ASSETS.map((a) => (
+          <Card key={a.id} className="p-3">
+            <div className={`flex h-16 items-center justify-center rounded-md border font-mono text-2xs uppercase ${
+              a.locked ? "border-border-subtle bg-surface-2 text-text-faint" : "border-border-subtle text-text-dim"
+            }`}>
+              {a.name.split(".").pop()}
+            </div>
+            <div className="mt-2 flex items-center justify-between">
+              <span className="truncate text-2xs">{a.name}</span>
+              {a.locked && <Badge tone="neutral">group-locked</Badge>}
+            </div>
+            <div className="mt-1 text-2xs text-text-faint">{a.group}</div>
+          </Card>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/video/page.tsx b/apps/web/src/app/(main)/video/page.tsx
new file mode 100644
index 0000000..7da4dfc
--- /dev/null
+++ b/apps/web/src/app/(main)/video/page.tsx
@@ -0,0 +1,243 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { Button } from "../../../components/ui/primitives";
+import { OfflineBadge } from "../../../components/ui/offline-badge";
+import { EmptyState } from "../../../components/brand/empty-state";
+import { Loading } from "../../../components/brand/loading";
+import { api, ApiUnreachableError, errorMessage } from "../../../lib/api-client";
+import { useAuth } from "../../../lib/auth-store";
+import { SAMPLE_VIDEO_ENTRIES } from "../../../lib/video-fixtures";
+import type { VideoLibraryEntryDto, VideoLibraryPageDto, VideoStatusDto } from "../../../lib/video-types";
+import { VideoCard, UploadingCard } from "../../../components/video/video-card";
+import { UploadDropzone } from "../../../components/video/upload-dropzone";
+import { VideoDetailDrawer } from "../../../components/video/video-detail-drawer";
+import { DeleteVideoModal } from "../../../components/video/delete-video-modal";
+
+/**
+ * Video library + upload. Live mode pages through GET /video by cursor (audit
+ * page's load-more pattern); offline the screen renders the sample library
+ * read-only per useApiResource conventions. In-flight assets auto-refresh so
+ * queued → probing → ready advances without a manual reload.
+ */
+
+const PAGE_SIZE = 24;
+const IN_FLIGHT: VideoLibraryEntryDto["processingState"][] = ["queued", "probing", "transcoding"];
+const REFRESH_MS = 6_000;
+
+/** A pick in flight: shows as an "uploading…" card until the API answers. */
+interface UploadDraft {
+  key: string;
+  name: string;
+  detail: string;
+}
+
+export default function VideoPage(): React.ReactElement {
+  const { status: authStatus, can } = useAuth();
+  const [items, setItems] = useState<VideoLibraryEntryDto[] | null>(null);
+  const [source, setSource] = useState<"loading" | "live" | "sample">("loading");
+  const [error, setError] = useState<string | null>(null);
+  const [nextCursor, setNextCursor] = useState<string | undefined>(undefined);
+  const [loadingMore, setLoadingMore] = useState(false);
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const [confirmDelete, setConfirmDelete] = useState<VideoLibraryEntryDto | null>(null);
+  const [deleting, setDeleting] = useState(false);
+  const [optimistic, setOptimistic] = useState<UploadDraft[]>([]);
+  const [notice, setNotice] = useState<{ tone: "ok" | "error"; text: string } | null>(null);
+
+  const live = source === "live";
+  const canManage = !live || can("media.manage");
+
+  const loadFirstPage = useCallback((signal: AbortSignal): void => {
+    api
+      .get<VideoLibraryPageDto>("/video", { limit: PAGE_SIZE }, signal)
+      .then((page) => {
+        setItems(page.items);
+        setNextCursor(page.nextCursor);
+        setSource("live");
+        setError(null);
+      })
+      .catch((err: unknown) => {
+        if (signal.aborted) return;
+        if (err instanceof ApiUnreachableError) {
+          setSource("sample");
+          return;
+        }
+        setSource("live");
+        setError(errorMessage(err));
+      });
+  }, []);
+
+  useEffect(() => {
+    if (authStatus === "loading") return;
+    if (authStatus !== "authenticated") {
+      setSource("sample");
+      return;
+    }
+    const controller = new AbortController();
+    loadFirstPage(controller.signal);
+    return () => controller.abort();
+  }, [authStatus, loadFirstPage]);
+
+  const anyInFlight = useMemo(
+    () => (items ?? []).some((e) => IN_FLIGHT.includes(e.processingState)),
+    [items],
+  );
+
+  // Status refresh: keeps queued/probing/transcoding rows moving without a manual reload.
+  useEffect(() => {
+    if (!live || !anyInFlight) return;
+    const timer = setInterval(() => loadFirstPage(new AbortController().signal), REFRESH_MS);
+    return () => clearInterval(timer);
+  }, [live, anyInFlight, loadFirstPage]);
+
+  async function loadMore(): Promise<void> {
+    if (nextCursor === undefined) return;
+    setLoadingMore(true);
+    try {
+      const page = await api.get<VideoLibraryPageDto>("/video", { cursor: nextCursor, limit: PAGE_SIZE });
+      setItems((current) => {
+        const seen = new Set((current ?? []).map((e) => e.videoAsset.id));
+        return [...(current ?? []), ...page.items.filter((e) => !seen.has(e.videoAsset.id))];
+      });
+      setNextCursor(page.nextCursor);
+    } catch (err) {
+      setError(errorMessage(err));
+    } finally {
+      setLoadingMore(false);
+    }
+  }
+
+  const onUploadStarted = useCallback((draft: UploadDraft): void => {
+    setOptimistic((current) => [draft, ...current]);
+  }, []);
+
+  const onUploadSettled = useCallback((key: string): void => {
+    setOptimistic((current) => current.filter((d) => d.key !== key));
+  }, []);
+
+  const applyStatus = useCallback((status: VideoStatusDto): void => {
+    const entry: VideoLibraryEntryDto = {
+      videoAsset: status.videoAsset,
+      processingState: status.processingJob.state,
+      publications: [],
+    };
+    setItems((current) => [entry, ...(current ?? []).filter((e) => e.videoAsset.id !== entry.videoAsset.id)]);
+    setSelectedId(entry.videoAsset.id);
+  }, []);
+
+  async function remove(entry: VideoLibraryEntryDto): Promise<void> {
+    setDeleting(true);
+    try {
+      await api.del<void>(`/video/${entry.videoAsset.id}`);
+      setItems((current) => (current ?? []).filter((e) => e.videoAsset.id !== entry.videoAsset.id));
+      if (selectedId === entry.videoAsset.id) setSelectedId(null);
+      setConfirmDelete(null);
+      setNotice({ tone: "ok", text: "Video deleted." });
+    } catch (err) {
+      setNotice({ tone: "error", text: errorMessage(err) });
+    } finally {
+      setDeleting(false);
+    }
+  }
+
+  const visible = live ? (items ?? []) : SAMPLE_VIDEO_ENTRIES;
+  const drafts = live ? optimistic : [];
+  const selected = visible.find((e) => e.videoAsset.id === selectedId) ?? null;
+
+  return (
+    <div className="h-full overflow-y-auto p-6 scrollbar-thin">
+      <div className="mb-5 flex items-center justify-between">
+        <div className="flex items-center gap-3">
+          <h1 className="text-lg font-semibold">Video</h1>
+          <OfflineBadge source={source} />
+        </div>
+        <Button
+          size="sm"
+          variant="outline"
+          disabled={!live}
+          onClick={() => loadFirstPage(new AbortController().signal)}
+        >
+          Refresh
+        </Button>
+      </div>
+
+      {error !== null && <p className="mb-3 text-xs text-danger">{error}</p>}
+
+      <UploadDropzone
+        live={live}
+        canUpload={canManage}
+        onStarted={onUploadStarted}
+        onSettled={onUploadSettled}
+        onUploaded={applyStatus}
+      />
+
+      {source === "loading" && (
+        <div className="flex items-center gap-2 text-xs text-text-faint">
+          <Loading size={16} label="Loading video library" /> Loading video library…
+        </div>
+      )}
+
+      {source !== "loading" && visible.length === 0 && (
+        <EmptyState
+          title="No videos yet"
+          hint="Drop a file above to upload it to this workspace. Videos are stored encrypted and probed before they are ready to attach to posts."
+        />
+      )}
+
+      {source !== "loading" && (drafts.length > 0 || visible.length > 0) && (
+        <div className="grid grid-cols-2 gap-3 md:grid-cols-3 lg:grid-cols-4 xl:grid-cols-5">
+          {drafts.map((draft) => (
+            <UploadingCard key={draft.key} name={draft.name} detail={draft.detail} />
+          ))}
+          {visible.map((entry) => (
+            <VideoCard
+              key={entry.videoAsset.id}
+              entry={entry}
+              active={entry.videoAsset.id === selectedId}
+              onOpen={() => setSelectedId(entry.videoAsset.id)}
+              onDelete={() => {
+                if (!canManage) {
+                  setNotice({ tone: "error", text: "Deleting videos needs the media.manage permission." });
+                  return;
+                }
+                if (!live) {
+                  setNotice({ tone: "error", text: "Offline — sample data is read-only." });
+                  return;
+                }
+                setConfirmDelete(entry);
+              }}
+            />
+          ))}
+        </div>
+      )}
+
+      {live && nextCursor !== undefined && (
+        <div className="mt-4 flex justify-center">
+          <Button variant="outline" size="sm" disabled={loadingMore} onClick={() => void loadMore()}>
+            {loadingMore ? "Loading…" : "Load more"}
+          </Button>
+        </div>
+      )}
+
+      {notice !== null && (
+        <p className={`mt-3 text-xs ${notice.tone === "ok" ? "text-live" : "text-danger"}`}>{notice.text}</p>
+      )}
+
+      <p className="mt-6 text-2xs leading-relaxed text-text-faint">
+        Videos are stored encrypted and probed on upload. The original file is retained;
+        rendering and transcoding run separately in the media worker.
+      </p>
+
+      {selected !== null && <VideoDetailDrawer key={selected.videoAsset.id} entry={selected} onClose={() => setSelectedId(null)} />}
+      {confirmDelete !== null && (
+        <DeleteVideoModal
+          asset={confirmDelete.videoAsset}
+          busy={deleting}
+          onCancel={() => setConfirmDelete(null)}
+          onConfirm={() => void remove(confirmDelete)}
+        />
+      )}
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/wiki/[slug]/page.tsx b/apps/web/src/app/(main)/wiki/[slug]/page.tsx
new file mode 100644
index 0000000..44f74c8
--- /dev/null
+++ b/apps/web/src/app/(main)/wiki/[slug]/page.tsx
@@ -0,0 +1,88 @@
+"use client";
+
+import Link from "next/link";
+import { useWikiLang, useWikiPages } from "../lang-context";
+import { WikiBody } from "../body";
+
+interface WikiSlugPageProps {
+  params: { slug: string };
+}
+
+/**
+ * One manual: title, blurb, then every section in order, with prev/next
+ * navigation in reading order. Unknown slugs render a "not found" panel that
+ * links back to the table of contents.
+ */
+export default function WikiSlugPage({ params }: WikiSlugPageProps): React.ReactElement | null {
+  const pages = useWikiPages();
+  const { t } = useWikiLang();
+  const index = pages.findIndex((page) => page.slug === params.slug);
+  const page = index >= 0 ? pages[index] : undefined;
+
+  if (page === undefined) {
+    return (
+      <div className="rounded-lg border border-border-subtle bg-surface p-6">
+        <h1 className="mb-2 text-lg font-semibold">{t({ en: "Page not found", es: "Página no encontrada" })}</h1>
+        <p className="mb-4 text-sm text-text-dim">
+          {t({
+            en: "That manual does not exist. Head back to the table of contents and pick from the list.",
+            es: "Ese manual no existe. Vuelve al índice y elige de la lista.",
+          })}
+        </p>
+        <Link href="/wiki" className="text-sm font-medium text-accent hover:underline">
+          {t({ en: "← All manuals", es: "← Todos los manuales" })}
+        </Link>
+      </div>
+    );
+  }
+
+  const previous = index > 0 ? pages[index - 1] : undefined;
+  const next = index < pages.length - 1 ? pages[index + 1] : undefined;
+
+  return (
+    <article>
+      <Link href="/wiki" className="mb-3 inline-block text-2xs text-text-faint transition-colors duration-150 hover:text-accent">
+        {t({ en: "← Contents", es: "← Contenido" })}
+      </Link>
+      <p className="mb-1 font-mono text-2xs font-bold uppercase tracking-wider text-accent">
+        {t({ en: "Manual", es: "Manual" })} {String(index + 1).padStart(2, "0")} / {String(pages.length).padStart(2, "0")}
+      </p>
+      <h1 className="mb-2 text-2xl font-bold">{t(page.title)}</h1>
+      <p className="mb-6 border-l-2 border-accent pl-3 text-sm leading-relaxed text-text-dim">{t(page.blurb)}</p>
+      <div className="flex flex-col gap-7">
+        {page.sections.map((section, sectionIndex) => (
+          <section key={`${page.slug}-${sectionIndex}`}>
+            <h2 className="mb-2 text-base font-semibold text-text">{t(section.heading)}</h2>
+            <div className="text-sm text-text-dim">
+              <WikiBody text={t(section.body)} />
+            </div>
+          </section>
+        ))}
+      </div>
+      <nav className="mt-10 flex flex-col gap-2 border-t border-border-subtle pt-5 sm:flex-row">
+        {previous !== undefined ? (
+          <Link
+            href={`/wiki/${previous.slug}`}
+            className="min-w-0 flex-1 rounded-lg border border-border-subtle bg-surface p-3 transition-colors duration-150 hover:border-accent"
+          >
+            <span className="block text-2xs text-text-faint">{t({ en: "Previous", es: "Anterior" })}</span>
+            <span className="block truncate text-sm font-medium">{t(previous.title)}</span>
+          </Link>
+        ) : (
+          <span className="hidden min-w-0 flex-1 sm:block" />
+        )}
+        {next !== undefined ? (
+          <Link
+            href={`/wiki/${next.slug}`}
+            className="min-w-0 flex-1 rounded-lg border border-border-subtle bg-surface p-3 text-right transition-colors duration-150 hover:border-accent"
+          >
+            <span className="block text-2xs text-text-faint">{t({ en: "Next", es: "Siguiente" })}</span>
+            <span className="block truncate text-sm font-medium">{t(next.title)}</span>
+          </Link>
+        ) : (
+          <span className="hidden min-w-0 flex-1 sm:block" />
+        )}
+      </nav>
+    </article>
+  );
+}
diff --git a/apps/web/src/app/(main)/wiki/body.tsx b/apps/web/src/app/(main)/wiki/body.tsx
new file mode 100644
index 0000000..062f12a
--- /dev/null
+++ b/apps/web/src/app/(main)/wiki/body.tsx
@@ -0,0 +1,52 @@
+"use client";
+
+import { Fragment, type ReactNode } from "react";
+
+/**
+ * Minimal markup for the wiki bodies, matching what the content file promises:
+ * blank-line paragraphs, "- " bullets, numbered steps, and **bold** for
+ * on-screen labels. Kept deliberately small — no HTML from content is ever
+ * injected, so manuals stay safe to edit for non-technical contributors.
+ */
+
+function inline(text: string, keyPrefix: string): ReactNode[] {
+  return text.split(/(\*\*[^*]+\*\*)/g).filter(Boolean).map((part, index) =>
+    part.startsWith("**") && part.endsWith("**") && part.length > 4 ? (
+      <strong key={`${keyPrefix}-${index}`} className="font-semibold text-text">
+        {part.slice(2, -2)}
+      </strong>
+    ) : (
+      <Fragment key={`${keyPrefix}-${index}`}>{part}</Fragment>
+    ),
+  );
+}
+
+function renderBlock(block: string, key: string): ReactNode {
+  const lines = block.split("\n");
+  const isBullets = lines.every((line) => line.startsWith("- "));
+  const isSteps = lines.length > 0 && lines.every((line) => /^\d+\.\s/.test(line));
+  if (isBullets) {
+    return (
+      <ul key={key} className="my-3 list-disc space-y-1.5 pl-5 marker:text-accent">
+        {lines.map((line, index) => (
+          <li key={`${key}-${index}`}>{inline(line.slice(2), `${key}-${index}`)}</li>
+        ))}
+      </ul>
+    );
+  }
+  if (isSteps) {
+    return (
+      <ol key={key} className="my-3 list-decimal space-y-1.5 pl-5 marker:font-mono marker:text-text-faint">
+        {lines.map((line, index) => (
+          <li key={`${key}-${index}`}>{inline(line.replace(/^\d+\.\s/, ""), `${key}-${index}`)}</li>
+        ))}
+      </ol>
+    );
+  }
+  return <p key={key}>{inline(block, key)}</p>;
+}
+
+export function WikiBody({ text }: { text: string }): React.ReactElement {
+  const blocks = text.split(/\n{2,}/).filter((block) => block.trim().length > 0);
+  return <div className="space-y-1.5 leading-relaxed">{blocks.map((block, index) => renderBlock(block, `b${index}`))}</div>;
+}
diff --git a/apps/web/src/app/(main)/wiki/lang-context.tsx b/apps/web/src/app/(main)/wiki/lang-context.tsx
new file mode 100644
index 0000000..67fd143
--- /dev/null
+++ b/apps/web/src/app/(main)/wiki/lang-context.tsx
@@ -0,0 +1,65 @@
+"use client";
+
+import { createContext, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import { WIKI_PAGES, type LocalizedText } from "../../../lib/wiki-content";
+
+export type WikiLang = "en" | "es";
+
+interface WikiLangContextValue {
+  lang: WikiLang;
+  setLang: (lang: WikiLang) => void;
+  /** Pick the string for the current language — the one helper every wiki screen uses. */
+  t: (text: LocalizedText) => string;
+}
+
+const STORAGE_KEY = "tmbh.wiki.lang";
+const WikiLangContext = createContext<WikiLangContextValue | null>(null);
+
+function readStoredLang(): WikiLang {
+  if (typeof window === "undefined") return "en";
+  try {
+    const stored = window.localStorage.getItem(STORAGE_KEY);
+    return stored === "es" ? "es" : "en";
+  } catch {
+    return "en";
+  }
+}
+
+/**
+ * Language toggle for the wiki only. The choice is per-browser (localStorage)
+ * and never sent to the server: it is a reading preference, not an account
+ * setting, and the app has no per-user preference store to put it in.
+ */
+export function WikiLangProvider({ children }: { children: ReactNode }): React.ReactElement {
+  const [lang, setLangState] = useState<WikiLang>("en");
+
+  useEffect(() => {
+    setLangState(readStoredLang());
+  }, []);
+
+  const setLang = useCallback((next: WikiLang) => {
+    setLangState(next);
+    try {
+      window.localStorage.setItem(STORAGE_KEY, next);
+    } catch {
+      // Private-browsing modes can refuse storage; the choice still holds for
+      // this screen, it just will not survive a reload.
+    }
+  }, []);
+
+  const t = useCallback((text: LocalizedText) => text[lang], [lang]);
+
+  const value = useMemo<WikiLangContextValue>(() => ({ lang, setLang, t }), [lang, setLang, t]);
+  return <WikiLangContext.Provider value={value}>{children}</WikiLangContext.Provider>;
+}
+
+export function useWikiLang(): WikiLangContextValue {
+  const context = useContext(WikiLangContext);
+  if (context === null) throw new Error("useWikiLang must be used inside WikiLangProvider");
+  return context;
+}
+
+/** The page list in reading order — sidebar, table of contents and prev/next all share it. */
+export function useWikiPages() {
+  return WIKI_PAGES;
+}
diff --git a/apps/web/src/app/(main)/wiki/layout.tsx b/apps/web/src/app/(main)/wiki/layout.tsx
new file mode 100644
index 0000000..05f20d1
--- /dev/null
+++ b/apps/web/src/app/(main)/wiki/layout.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import type { ReactNode } from "react";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useWikiLang, useWikiPages } from "./lang-context";
+
+/**
+ * Wiki shell: page list on the left (collapses to a top strip on mobile) and
+ * the EN/ES toggle. The language lives in localStorage per browser — see
+ * lang-context for why it is not an account setting.
+ */
+export default function WikiLayout({ children }: { children: ReactNode }): React.ReactElement {
+  const pages = useWikiPages();
+  const { lang, setLang, t } = useWikiLang();
+  const pathname = usePathname();
+  const activeSlug = pathname.split("/")[2] ?? "";
+
+  return (
+    <div className="flex h-full min-h-0 flex-col lg:flex-row">
+      <aside className="flex min-h-0 shrink-0 flex-col border-b border-border-subtle bg-surface lg:w-64 lg:border-b-0 lg:border-r">
+        <div className="flex items-center gap-3 px-4 py-3">
+          <Link href="/wiki" className="min-w-0 flex-1">
+            <span className="block text-sm font-bold">
+              {t({ en: "Help & docs", es: "Ayuda y documentación" })}
+            </span>
+            <span className="block truncate text-2xs text-text-faint">
+              {t({ en: "TMBH manuals", es: "Manuales de TMBH" })}
+            </span>
+          </Link>
+          <div className="flex shrink-0 items-center rounded-md border border-border bg-surface-2 p-0.5" role="group" aria-label="Language">
+            {(["en", "es"] as const).map((code) => (
+              <button
+                key={code}
+                type="button"
+                onClick={() => setLang(code)}
+                aria-pressed={lang === code}
+                className={`min-h-8 rounded px-2.5 text-2xs font-bold uppercase transition-colors duration-150 ${
+                  lang === code ? "bg-accent text-white" : "text-text-dim hover:text-text"
+                }`}
+              >
+                {code}
+              </button>
+            ))}
+          </div>
+        </div>
+        <nav className="min-h-0 flex-1 overflow-y-auto px-2 pb-3 lg:pb-6">
+          <ul className="flex flex-col gap-0.5">
+            {pages.map((page, index) => {
+              const active = page.slug === activeSlug;
+              return (
+                <li key={page.slug}>
+                  <Link
+                    href={`/wiki/${page.slug}`}
+                    className={`flex min-h-9 items-center gap-2 rounded-md px-2.5 py-1.5 text-xs transition-colors duration-150 ${
+                      active ? "bg-accent-dim font-semibold text-accent" : "text-text-dim hover:bg-surface-2 hover:text-text"
+                    }`}
+                  >
+                    <span className="w-4 shrink-0 text-right font-mono text-2xs text-text-faint">{index + 1}</span>
+                    <span className="min-w-0 truncate">{t(page.title)}</span>
+                  </Link>
+                </li>
+              );
+            })}
+          </ul>
+        </nav>
+      </aside>
+      <div className="min-h-0 min-w-0 flex-1 overflow-y-auto">
+        <div className="mx-auto max-w-2xl px-4 py-6 pb-24 lg:px-8 lg:py-8">{children}</div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/(main)/wiki/page.tsx b/apps/web/src/app/(main)/wiki/page.tsx
new file mode 100644
index 0000000..f85ced1
--- /dev/null
+++ b/apps/web/src/app/(main)/wiki/page.tsx
@@ -0,0 +1,47 @@
+"use client";
+
+import Link from "next/link";
+import { useWikiLang, useWikiPages } from "./lang-context";
+
+/**
+ * Wiki home: table of contents with every manual title and a one-line summary.
+ * Numbered so a printed or shared copy reads as a course, not a link dump.
+ */
+export default function WikiHomePage(): React.ReactElement {
+  const pages = useWikiPages();
+  const { t } = useWikiLang();
+  return (
+    <div>
+      <p className="mb-1 text-2xs font-bold uppercase tracking-wider text-accent">
+        {t({ en: "Documentation", es: "Documentación" })}
+      </p>
+      <h1 className="mb-2 text-2xl font-bold">{t({ en: "TMBH manual", es: "Manual de TMBH" })}</h1>
+      <p className="mb-6 text-sm leading-relaxed text-text-dim">
+        {t({
+          en: "Step-by-step guides for every part of the newsroom, written for people who organise — not for developers. Switch language with the EN / ES buttons above; your choice is remembered on this device.",
+          es: "Guías paso a paso de cada parte de la redacción, escritas para gente que organiza, no para programadores. Cambia de idioma con los botones EN / ES de arriba; tu elección queda recordada en este dispositivo.",
+        })}
+      </p>
+      <h2 className="mb-3 text-xs font-bold uppercase tracking-wider text-text-faint">
+        {t({ en: "Contents", es: "Contenido" })}
+      </h2>
+      <ol className="flex flex-col gap-2.5">
+        {pages.map((page, index) => (
+          <li key={page.slug}>
+            <Link
+              href={`/wiki/${page.slug}`}
+              className="flex gap-3 rounded-lg border border-border-subtle bg-surface p-3.5 transition-colors duration-150 hover:border-accent"
+            >
+              <span className="shrink-0 font-mono text-xs font-bold text-accent">{String(index + 1).padStart(2, "0")}</span>
+              <span className="min-w-0">
+                <span className="block text-sm font-semibold">{t(page.title)}</span>
+                <span className="mt-0.5 block text-xs leading-relaxed text-text-faint">{t(page.blurb)}</span>
+              </span>
+              <span aria-hidden="true" className="ml-auto self-center text-text-faint">›</span>
+            </Link>
+          </li>
+        ))}
+      </ol>
+    </div>
+  );
+}
diff --git a/apps/web/src/app/globals.css b/apps/web/src/app/globals.css
new file mode 100644
index 0000000..c6d1267
--- /dev/null
+++ b/apps/web/src/app/globals.css
@@ -0,0 +1,102 @@
+@import "tailwindcss";
+
+@theme {
+  --color-bg: oklch(0.11 0.008 25);
+  --color-surface: oklch(0.15 0.01 25);
+  --color-surface-2: oklch(0.19 0.012 25);
+  --color-border: oklch(0.26 0.02 25);
+  --color-border-subtle: oklch(0.22 0.015 25);
+  --color-text: oklch(0.93 0.005 25);
+  --color-text-dim: oklch(0.62 0.02 25);
+  --color-text-faint: oklch(0.46 0.02 25);
+  --color-accent: #ff1610;
+  --color-accent-hover: #e3130e;
+  --color-accent-dim: rgb(255 22 16 / 0.15);
+  --color-live: oklch(0.72 0.19 145);
+  --color-warn: oklch(0.78 0.16 85);
+  --color-danger: oklch(0.55 0.24 15);
+  --color-added: oklch(0.72 0.16 145);
+  --color-removed: oklch(0.55 0.24 15);
+
+  --font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  --font-mono: ui-monospace, "SF Mono", Menlo, monospace;
+
+  --radius-sm: 0.375rem;
+  --radius-md: 0.5rem;
+  --radius-lg: 0.75rem;
+
+  --text-2xs: 0.6875rem;
+  --text-xs: 0.75rem;
+  --text-sm: 0.8125rem;
+  --text-base: 0.875rem;
+  --text-lg: 1rem;
+
+  --mobile-tab-height: 76px;
+  --mobile-fab-size: 64px;
+  --mobile-sheet-radius: 28px;
+  --mobile-safe-bottom: env(safe-area-inset-bottom, 0px);
+}
+
+@theme inline {
+  --color-brand: var(--color-accent);
+}
+
+html {
+  color-scheme: dark;
+}
+
+body {
+  background: var(--color-bg);
+  color: var(--color-text);
+  font-family: var(--font-sans);
+  font-size: var(--text-base);
+  -webkit-font-smoothing: antialiased;
+}
+
+html, body { max-width: 100%; }
+
+@media (max-width: 1023px) {
+  body { overflow-x: hidden; }
+  [data-mobile-main] :is(button, a[href], input, select, textarea, [role="tab"]) {
+    min-height: 44px;
+  }
+  [data-mobile-main] :is(button, a[href], [role="tab"]) {
+    min-width: 44px;
+  }
+  [data-mobile-main] p a[href] { display: inline-flex; align-items: center; }
+  [data-mobile-main] .mobile-stack-table,
+  [data-mobile-main] .mobile-stack-table tbody,
+  [data-mobile-main] .mobile-stack-table tr,
+  [data-mobile-main] .mobile-stack-table td { display: block; width: 100%; min-width: 0; }
+  [data-mobile-main] .mobile-stack-table thead { display: none; }
+  [data-mobile-main] .mobile-stack-table tr { padding: 8px 0; }
+  [data-mobile-main] .mobile-stack-table td { overflow-wrap: anywhere; }
+  [data-mobile-main] .mobile-stack-table td > * { max-width: 100%; }
+}
+
+::selection {
+  background: var(--color-accent-dim);
+}
+
+:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 1px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    transition-duration: 0.01ms !important;
+    animation-duration: 0.01ms !important;
+  }
+}
+
+.scrollbar-thin::-webkit-scrollbar {
+  width: 6px;
+  height: 6px;
+}
+.scrollbar-thin::-webkit-scrollbar-thumb {
+  background: var(--color-border);
+  border-radius: 3px;
+}
diff --git a/apps/web/src/app/join/[token]/page.tsx b/apps/web/src/app/join/[token]/page.tsx
new file mode 100644
index 0000000..5812039
--- /dev/null
+++ b/apps/web/src/app/join/[token]/page.tsx
@@ -0,0 +1,328 @@
+"use client";
+
+import { useEffect, useState, type FormEvent } from "react";
+import Link from "next/link";
+import { Badge, Button, Card, Input } from "../../../components/ui/primitives";
+import { LoadingPanel } from "../../../components/brand/loading";
+import { apiFetch, ApiError, ApiUnreachableError, errorMessage } from "../../../lib/api-client";
+import type { InviteInfo } from "../../../lib/api-types";
+import { useAuth } from "../../../lib/auth-store";
+
+const MIN_PASSWORD = 10;
+const USERNAME_PATTERN = /^[a-z0-9][a-z0-9_.-]{1,31}$/;
+const USERNAME_TITLE = "2-32 characters: lowercase letters, digits, dot, underscore or hyphen";
+const API_UNREACHABLE = "API unreachable — check that the API server is running.";
+
+type Phase = "loading" | "preview" | "dead" | "unreachable";
+/** Why the link no longer works — drives the copy on the dead-token card. */
+type DeadReason = "unknown" | "expired" | "exhausted";
+
+/** 404 (unknown/revoked) vs 410 (expired or exhausted, told apart by the message). Anything else reads as unknown. */
+function deadReasonFrom(err: unknown): DeadReason {
+  if (err instanceof ApiError && err.status === 410) {
+    const message = err.message.toLowerCase();
+    if (message.includes("expired")) return "expired";
+    if (message.includes("used up") || message.includes("no uses left")) return "exhausted";
+  }
+  return "unknown";
+}
+
+const isAlreadyMember = (err: unknown): boolean => err instanceof ApiError && err.status === 409;
+
+function usesLeftLine(info: InviteInfo): string {
+  const left = info.maxUses === null ? "unlimited uses" : `${Math.max(info.maxUses - info.usedCount, 0)} use${info.maxUses - info.usedCount === 1 ? "" : "s"} left`;
+  return `${left} · expires ${new Date(info.expiresAt).toLocaleDateString()}`;
+}
+
+/** Sign in with an existing account, then claim: login installs the account session, claimInvite swaps it for the workspace one. */
+function JoinSignInForm({
+  token,
+  onSwitch,
+  onAlreadyMember,
+}: {
+  token: string;
+  onSwitch: () => void;
+  onAlreadyMember: () => void;
+}): React.ReactElement {
+  const { login, claimInvite } = useAuth();
+  const [username, setUsername] = useState("");
+  const [password, setPassword] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: FormEvent): Promise<void> {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    try {
+      await login(username.trim(), password);
+      await claimInvite(token);
+      window.location.assign("/streams");
+    } catch (err) {
+      // Login worked but the workspace already holds this user: that is a success state.
+      if (isAlreadyMember(err)) {
+        setBusy(false);
+        onAlreadyMember();
+        return;
+      }
+      setError(errorMessage(err));
+      setBusy(false);
+    }
+  }
+
+  return (
+    <form onSubmit={(e) => void submit(e)}>
+      <h2 className="mb-1 text-base font-semibold">Sign in</h2>
+      <p className="mb-4 text-xs text-text-faint">Use the username and password you registered with.</p>
+      <div className="space-y-2">
+        <Input type="text" value={username} onChange={(e) => setUsername(e.target.value)} placeholder="username" autoComplete="username" autoFocus />
+        <Input type="password" value={password} onChange={(e) => setPassword(e.target.value)} placeholder="Password" autoComplete="current-password" />
+      </div>
+      {error !== null && <p className="mt-2 text-xs text-danger">{error}</p>}
+      <div className="mt-6 flex items-center justify-between">
+        <Button type="button" variant="ghost" onClick={onSwitch}>New here? Create an account</Button>
+        <Button type="submit" variant="primary" disabled={busy || username.trim() === "" || password === ""}>
+          {busy ? "Joining…" : "Sign in & join"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+
+/**
+ * Create-or-authenticate inline, then claim. Registering normally spins up a
+ * new workspace, so the claim endpoint takes the credentials itself and hands
+ * back a session issued in the invited workspace.
+ */
+function RegisterToJoinForm({
+  token,
+  onSwitch,
+  onAlreadyMember,
+}: {
+  token: string;
+  onSwitch: () => void;
+  onAlreadyMember: () => void;
+}): React.ReactElement {
+  const { claimInviteWithCredentials } = useAuth();
+  const [displayName, setDisplayName] = useState("");
+  const [username, setUsername] = useState("");
+  const [email, setEmail] = useState("");
+  const [password, setPassword] = useState("");
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function submit(e: FormEvent): Promise<void> {
+    e.preventDefault();
+    setBusy(true);
+    setError(null);
+    try {
+      await claimInviteWithCredentials(token, {
+        username: username.trim(),
+        password,
+        ...(displayName.trim() === "" ? {} : { displayName: displayName.trim() }),
+        ...(email.trim() === "" ? {} : { email: email.trim() }),
+      });
+      window.location.assign("/streams");
+    } catch (err) {
+      if (isAlreadyMember(err)) {
+        setBusy(false);
+        onAlreadyMember();
+        return;
+      }
+      setError(errorMessage(err));
+      setBusy(false);
+    }
+  }
+
+  const ready = USERNAME_PATTERN.test(username.trim()) && password.length >= MIN_PASSWORD;
+
+  return (
+    <form onSubmit={(e) => void submit(e)}>
+      <h2 className="mb-1 text-base font-semibold">Create your account</h2>
+      <p className="mb-4 text-xs text-text-faint">
+        Registering accepts the invite in one step — no workspace of your own is created.
+      </p>
+      <div className="space-y-2">
+        <Input value={displayName} onChange={(e) => setDisplayName(e.target.value)} placeholder="Your name (optional)" autoComplete="name" />
+        <Input
+          type="text"
+          value={username}
+          onChange={(e) => setUsername(e.target.value.toLowerCase())}
+          placeholder="Username — this is how you sign in"
+          autoComplete="username"
+          pattern="[a-z0-9][a-z0-9_.-]{1,31}"
+          title={USERNAME_TITLE}
+        />
+        <Input
+          type="password"
+          value={password}
+          onChange={(e) => setPassword(e.target.value)}
+          placeholder={`Password (min ${MIN_PASSWORD} characters)`}
+          autoComplete="new-password"
+        />
+        <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} placeholder="Email (optional — password recovery)" autoComplete="email" />
+      </div>
+      {error !== null && <p className="mt-2 text-xs text-danger">{error}</p>}
+      <div className="mt-6 flex items-center justify-between">
+        <Button type="button" variant="ghost" onClick={onSwitch}>I already have an account</Button>
+        <Button type="submit" variant="primary" disabled={busy || !ready}>
+          {busy ? "Joining…" : "Join workspace"}
+        </Button>
+      </div>
+    </form>
+  );
+}
+
+export default function JoinWorkspacePage({ params }: { params: { token: string } }): React.ReactElement {
+  const { status, session, isLoading, claimInvite } = useAuth();
+  const [phase, setPhase] = useState<Phase>("loading");
+  const [info, setInfo] = useState<InviteInfo | null>(null);
+  const [deadReason, setDeadReason] = useState<DeadReason>("unknown");
+  const [mode, setMode] = useState<"register" | "signin">("register");
+  const [claiming, setClaiming] = useState(false);
+  const [claimError, setClaimError] = useState<string | null>(null);
+  const [alreadyMember, setAlreadyMember] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+
+  // The preview is public: fetch it immediately rather than waiting for the session to settle.
+  useEffect(() => {
+    let cancelled = false;
+    setPhase("loading");
+    apiFetch<InviteInfo>(`/invites/${encodeURIComponent(params.token)}/info`, { redirectOn401: false })
+      .then((preview) => {
+        if (cancelled) return;
+        setInfo(preview);
+        setPhase("preview");
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        if (err instanceof ApiUnreachableError) setPhase("unreachable");
+        else {
+          setDeadReason(deadReasonFrom(err));
+          setPhase("dead");
+        }
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [params.token, attempt]);
+
+  const retry = (): void => setAttempt((n) => n + 1);
+
+  async function claim(): Promise<void> {
+    setClaiming(true);
+    setClaimError(null);
+    try {
+      await claimInvite(params.token);
+      // Full navigation so the (main) shell mounts with the freshly installed session.
+      window.location.assign("/streams");
+    } catch (err) {
+      if (isAlreadyMember(err)) {
+        setAlreadyMember(true);
+        setClaiming(false);
+        return;
+      }
+      setClaimError(errorMessage(err));
+      setClaiming(false);
+    }
+  }
+
+  if (phase === "loading" || isLoading) return <LoadingPanel label="Checking invite…" />;
+
+  if (phase === "unreachable") {
+    return (
+      <Card className="w-[520px] max-w-full p-6 text-center">
+        <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-warn/15 text-lg text-warn">!</div>
+        <h1 className="text-base font-semibold">Can&apos;t reach the server</h1>
+        <p className="mt-1 text-xs text-text-faint">
+          {API_UNREACHABLE} Your invite link is still fine — try again.
+        </p>
+        <Button variant="outline" className="mt-6" onClick={retry}>Retry</Button>
+      </Card>
+    );
+  }
+
+  if (phase === "dead") {
+    return (
+      <Card className="w-[520px] max-w-full p-6 text-center">
+        <div className="mx-auto mb-4 flex h-12 w-12 items-center justify-center rounded-full bg-danger/15 text-lg text-danger">✕</div>
+        <h1 className="text-base font-semibold">This invite link isn&apos;t valid</h1>
+        <p className="mt-1 text-xs text-text-faint">
+          {deadReason === "expired"
+            ? "It expired."
+            : deadReason === "exhausted"
+              ? "It has already been used up."
+              : "It was revoked or never existed."}{" "}
+          Ask a workspace owner for a fresh invite.
+        </p>
+        <Link href="/onboarding" className="mt-6 inline-block rounded-md bg-accent px-3 py-1.5 text-xs font-medium text-white hover:bg-accent-hover">
+          Start or sign in to your own workspace
+        </Link>
+      </Card>
+    );
+  }
+
+  if (info === null) return <LoadingPanel label="Checking invite…" />;
+
+  const memberCta = alreadyMember ? (
+    <div className="mt-6 flex items-center justify-between">
+      <span className="text-xs text-text-faint">You&apos;re already in this workspace.</span>
+      <Link href="/streams" className="rounded-md bg-accent px-3 py-1.5 text-xs font-medium text-white hover:bg-accent-hover">Go to Streams</Link>
+    </div>
+  ) : (
+    <div className="mt-6 flex items-center justify-between">
+      <span className="text-2xs text-text-faint">Signed in as @{session?.user.username}</span>
+      <Button variant="primary" disabled={claiming} onClick={() => void claim()}>
+        {claiming ? "Joining…" : "Join workspace"}
+      </Button>
+    </div>
+  );
+
+  // Signed in already: one click claims the invite with the current session.
+  if (status === "authenticated" && session !== null) {
+    return (
+      <Card className="w-[520px] max-w-full p-6">
+        <h1 className="text-xl font-semibold tracking-tight">Join {info.workspaceName}</h1>
+        <p className="mt-1 text-xs text-text-faint">
+          You&apos;ve been invited to join <span className="text-text">{info.workspaceName}</span> as{" "}
+          <Badge tone="accent">{info.role}</Badge>.
+        </p>
+        <p className="mt-2 text-2xs text-text-faint">{usesLeftLine(info)}</p>
+        {claimError !== null && <p className="mt-2 text-xs text-danger">{claimError}</p>}
+        {memberCta}
+      </Card>
+    );
+  }
+
+  // Anonymous (or the API dropped between mount and now): hero + register/sign-in forms.
+  return (
+    <Card className="w-[520px] max-w-full p-6">
+      <div className="mb-5 text-center">
+        <img
+          src="/brand/hero.png"
+          alt="Tactical Media Broadcast Hub — arrows from a circle, warm red on black"
+          width={1024}
+          height={1024}
+          className="mx-auto mb-3 h-20 w-20 rounded-lg object-cover"
+        />
+        <h1 className="text-xl font-semibold tracking-tight">Join {info.workspaceName}</h1>
+        <p className="mt-1 text-2xs text-text-faint">
+          You&apos;ve been invited as <Badge tone="accent">{info.role}</Badge> · {usesLeftLine(info)}
+        </p>
+      </div>
+      {mode === "signin" ? (
+        <JoinSignInForm token={params.token} onSwitch={() => setMode("register")} onAlreadyMember={() => setAlreadyMember(true)} />
+      ) : (
+        <RegisterToJoinForm token={params.token} onSwitch={() => setMode("signin")} onAlreadyMember={() => setAlreadyMember(true)} />
+      )}
+      {alreadyMember && (
+        <div className="mt-5 border-t border-border-subtle pt-4 text-center">
+          <p className="text-xs text-text-faint">You&apos;re already in this workspace.</p>
+          <Link href="/streams" className="mt-2 inline-block rounded-md bg-accent px-3 py-1.5 text-xs font-medium text-white hover:bg-accent-hover">
+            Go to Streams
+          </Link>
+        </div>
+      )}
+    </Card>
+  );
+}
diff --git a/apps/web/src/app/join/layout.tsx b/apps/web/src/app/join/layout.tsx
new file mode 100644
index 0000000..ebe186f
--- /dev/null
+++ b/apps/web/src/app/join/layout.tsx
@@ -0,0 +1,19 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { AuthProvider } from "../../lib/auth-store";
+
+/**
+ * Anonymous-safe layout for the invite claim flow. It deliberately lives
+ * outside the `(main)` group: that layout mounts the app Shell and wraps
+ * children in `AuthGate`, which bounces anonymous visitors to /onboarding —
+ * the opposite of what a shared invite link needs. Here we mount only
+ * `AuthProvider` so the page can branch on "already signed in" vs anonymous.
+ */
+export default function JoinLayout({ children }: { children: ReactNode }): React.ReactNode {
+  return (
+    <AuthProvider>
+      <div className="flex h-dvh items-center justify-center overflow-y-auto bg-bg p-6">{children}</div>
+    </AuthProvider>
+  );
+}
diff --git a/apps/web/src/app/layout.tsx b/apps/web/src/app/layout.tsx
new file mode 100644
index 0000000..4e436ad
--- /dev/null
+++ b/apps/web/src/app/layout.tsx
@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+import type { Metadata, Viewport } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: "Tactical Media Broadcast Hub",
+  description: "Tactical Media Broadcast Hub — post, schedule and amplify across every network you refuse to be owned by.",
+  icons: { icon: "/brand/favicon.svg" },
+};
+
+export const viewport: Viewport = {
+  width: "device-width",
+  initialScale: 1,
+  viewportFit: "cover",
+  interactiveWidget: "resizes-content",
+  themeColor: "#FF1610",
+};
+
+export default function RootLayout({ children }: { children: ReactNode }): React.ReactNode {
+  return (
+    <html lang="en">
+      <body className="min-h-screen antialiased">{children}</body>
+    </html>
+  );
+}
diff --git a/apps/web/src/app/page.tsx b/apps/web/src/app/page.tsx
new file mode 100644
index 0000000..abf70c7
--- /dev/null
+++ b/apps/web/src/app/page.tsx
@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default function RootPage(): never {
+  redirect("/streams");
+}
diff --git a/apps/web/src/components/auth/auth-gate.tsx b/apps/web/src/components/auth/auth-gate.tsx
new file mode 100644
index 0000000..5501b35
--- /dev/null
+++ b/apps/web/src/components/auth/auth-gate.tsx
@@ -0,0 +1,50 @@
+"use client";
+
+import { useEffect, type ReactNode } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import { useAuth } from "../../lib/auth-store";
+import { ONBOARDING_PATH } from "../../lib/api-client";
+import { LoadingPanel } from "../brand/loading";
+
+/** Sends visitors without a session to onboarding. Offline (API unreachable) renders sample-data screens instead. */
+export function AuthGate({ children }: { children: ReactNode }): React.ReactElement {
+  const { status } = useAuth();
+  const pathname = usePathname();
+  const router = useRouter();
+  const onOnboarding = pathname === ONBOARDING_PATH;
+
+  useEffect(() => {
+    if (status === "anonymous" && !onOnboarding) router.replace(ONBOARDING_PATH);
+  }, [status, onOnboarding, router]);
+
+  if (!onOnboarding && (status === "loading" || status === "anonymous")) {
+    return <LoadingPanel label="Checking session…" />;
+  }
+  return <>{children}</>;
+}
+
+export function SessionStatus(): React.ReactElement {
+  const { status, session, logout } = useAuth();
+  if (status === "offline") {
+    return (
+      <span className="flex items-center gap-2" title="API unreachable — screens show sample data">
+        <span className="h-1.5 w-1.5 rounded-full bg-warn" />
+        offline — sample data
+      </span>
+    );
+  }
+  if (status !== "authenticated" || session === null) {
+    return <span>{status === "loading" ? "connecting…" : "signed out"}</span>;
+  }
+  return (
+    <span className="flex items-center gap-3">
+      <span className="flex items-center gap-2">
+        <span className="h-1.5 w-1.5 rounded-full bg-live" />
+        @{session.user.username} · {session.role}
+      </span>
+      <button onClick={() => void logout()} className="text-text-dim transition-colors duration-150 hover:text-accent">
+        Sign out
+      </button>
+    </span>
+  );
+}
diff --git a/apps/web/src/components/brand/empty-state.tsx b/apps/web/src/components/brand/empty-state.tsx
new file mode 100644
index 0000000..0f646e2
--- /dev/null
+++ b/apps/web/src/components/brand/empty-state.tsx
@@ -0,0 +1,28 @@
+import type { ReactElement } from "react";
+import { CircleA } from "./logo";
+
+/**
+ * Branded empty state: the circle-A outline sitting low-contrast behind the
+ * message, the way a screen-printed mark sits behind text on a black tee.
+ */
+export function EmptyState({
+  title,
+  hint,
+  size = 64,
+  className = "",
+}: {
+  title: string;
+  hint?: string;
+  size?: number;
+  className?: string;
+}): ReactElement {
+  return (
+    <div className={`flex flex-col items-center justify-center gap-3 py-8 text-center ${className}`}>
+      <CircleA size={size} className="text-accent/30" />
+      <p className="text-sm font-medium text-text-dim">{title}</p>
+      {hint !== undefined && (
+        <p className="max-w-sm text-2xs leading-relaxed text-text-faint">{hint}</p>
+      )}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/brand/index.tsx b/apps/web/src/components/brand/index.tsx
new file mode 100644
index 0000000..a8ac97b
--- /dev/null
+++ b/apps/web/src/components/brand/index.tsx
@@ -0,0 +1,90 @@
+import type { ReactElement } from "react";
+
+interface LogoProps {
+  size?: number;
+  withText?: boolean;
+}
+
+export function Logo({ size = 32, withText = false }: LogoProps): ReactElement {
+  return (
+    <span className="flex items-center gap-2">
+      <svg width={size} height={size} viewBox="0 0 1200 1200" aria-label="Tactical Media Broadcast Hub">
+        <g fill="none" stroke="var(--color-accent)" strokeWidth="72" strokeLinecap="round" strokeLinejoin="round">
+          <circle cx="600" cy="610" r="330" />
+          <path d="M 365 915 L 600 250 L 835 915" strokeWidth="92" />
+          <path d="M 250 610 L 950 610" strokeWidth="82" />
+        </g>
+        <g fill="var(--color-accent)">
+          <polygon points="600.0,145.0 660.0,270.0 540.0,270.0" />
+          <polygon points="125.0,610.0 250.0,550.0 250.0,670.0" />
+          <polygon points="1075.0,610.0 950.0,670.0 950.0,550.0" />
+          <polygon points="285.0,1050.0 331.0,919.2 415.8,1004.0" />
+          <polygon points="915.0,1050.0 784.2,1004.0 869.0,919.2" />
+        </g>
+      </svg>
+      {withText && (
+        <span className="text-sm font-bold tracking-tight" style={{ color: "var(--color-accent)" }}>
+          Tactical Media Broadcast Hub
+        </span>
+      )}
+    </span>
+  );
+}
+
+export function Spinner({ size = 24 }: { size?: number }): ReactElement {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 1200 1200"
+      className="animate-spin"
+      style={{ animationDuration: "1.2s" }}
+      aria-label="Loading"
+    >
+      <path d="M 600 280 A 330 330 0 0 1 930 610" fill="none" stroke="var(--color-accent)" strokeWidth="90" strokeLinecap="round" />
+      <path d="M 930 610 A 330 330 0 0 1 600 940" fill="none" stroke="var(--color-accent)" strokeWidth="90" strokeLinecap="round" opacity="0.2" />
+      <path d="M 600 940 A 330 330 0 0 1 270 610" fill="none" stroke="var(--color-accent)" strokeWidth="90" strokeLinecap="round" opacity="0.2" />
+      <path d="M 270 610 A 330 330 0 0 1 600 280" fill="none" stroke="var(--color-accent)" strokeWidth="90" strokeLinecap="round" opacity="0.2" />
+    </svg>
+  );
+}
+
+export function EmptyState({ message, size = 120 }: { message: string; size?: number }): ReactElement {
+  return (
+    <div className="flex flex-col items-center justify-center gap-4 py-12">
+      <svg width={size} height={size} viewBox="0 0 1200 1200" opacity="0.25">
+        <g fill="none" stroke="var(--color-accent)" strokeWidth="80" strokeLinecap="round" strokeLinejoin="round">
+          <circle cx="600" cy="610" r="330" />
+          <path d="M 365 915 L 600 250 L 835 915" strokeWidth="100" />
+          <path d="M 250 610 L 950 610" strokeWidth="80" />
+        </g>
+      </svg>
+      <p className="text-xs text-text-faint">{message}</p>
+    </div>
+  );
+}
+
+export function PlatformIcon({ platform, size = 20 }: { platform: string; size?: number }): ReactElement {
+  return (
+    <img
+      src={`/brand/icon-${platform}.svg`}
+      alt={platform}
+      width={size}
+      height={size}
+      className="rounded-full"
+      loading="lazy"
+    />
+  );
+}
+
+export function NavIcon({ name, size = 18 }: { name: string; size?: number }): ReactElement {
+  return (
+    <img
+      src={`/brand/nav-${name}.svg`}
+      alt={name}
+      width={size}
+      height={size}
+      loading="lazy"
+    />
+  );
+}
diff --git a/apps/web/src/components/brand/loading.tsx b/apps/web/src/components/brand/loading.tsx
new file mode 100644
index 0000000..87f38ff
--- /dev/null
+++ b/apps/web/src/components/brand/loading.tsx
@@ -0,0 +1,62 @@
+import type { ReactElement } from "react";
+import { LogoMark } from "./logo";
+
+/**
+ * Branded loading state: the mark upright inside a spinning ring.
+ *
+ * The mark itself is radially asymmetric (the A's apex sits high in its
+ * bounding box), so rotating the mark would wobble instead of spin. The ring
+ * carries the rotation; the A stays plumb. `animation` rather than
+ * Tailwind's animate-spin so globals.css's prefers-reduced-motion override
+ * (0.01ms) still applies via the transition/animation shorthand.
+ */
+export function Loading({
+  size = 28,
+  label = "Loading…",
+  className = "",
+}: {
+  size?: number;
+  label?: string;
+  className?: string;
+}): ReactElement {
+  return (
+    <span
+      role="status"
+      aria-label={label}
+      className={`relative inline-flex items-center justify-center ${className}`}
+      style={{ width: size, height: size }}
+    >
+      <svg
+        width={size}
+        height={size}
+        viewBox="0 0 100 100"
+        aria-hidden="true"
+        className="absolute inset-0 text-accent"
+        style={{ animation: "anp-spin 0.9s linear infinite" }}
+      >
+        {/* Three-quarter arc: the gap becomes the motion cue. */}
+        <circle
+          cx="50"
+          cy="50"
+          r="44"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="6"
+          strokeLinecap="round"
+          strokeDasharray="207 276"
+        />
+      </svg>
+      <LogoMark size={Math.round(size * 0.5)} className="text-accent" title="" />
+    </span>
+  );
+}
+
+/** Full-panel variant for screens that are still fetching their first page. */
+export function LoadingPanel({ label }: { label?: string }): ReactElement {
+  return (
+    <div className="flex h-full flex-col items-center justify-center gap-3">
+      <Loading size={32} label={label ?? "Loading…"} />
+      {label !== undefined && <span className="text-2xs text-text-faint">{label}</span>}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/brand/logo.tsx b/apps/web/src/components/brand/logo.tsx
new file mode 100644
index 0000000..3487ef8
--- /dev/null
+++ b/apps/web/src/components/brand/logo.tsx
@@ -0,0 +1,122 @@
+import type { ReactElement } from "react";
+
+/**
+ * The Tactical Media Broadcast Hub mark, inline.
+ *
+ * Source of truth: `public/brand/tactical-media-broadcast-hub.svg` — the arrows-from-circle
+ * mark, tilted −17.5° counterclockwise so the top arrow points upper-left
+ * (nothing static; everything points outward). The strokes use `currentColor`
+ * so the mark always rides the workspace accent, which in the warm palette
+ * lands within a hair of the brand red (#FF1610 ≈ oklch(0.63 0.24 29) vs the
+ * token's oklch(0.62 0.22 30)). Geometry is copied 1:1 from the asset on its
+ * 1700×1700 grid, minus the black plate and the screen-print distress paths
+ * (those only read on pure black at full size).
+ */
+
+export function LogoMark({
+  size = 32,
+  className = "text-accent",
+  title = "Tactical Media Broadcast Hub",
+}: {
+  size?: number;
+  className?: string;
+  title?: string;
+}): ReactElement {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 1700 1700"
+      role="img"
+      aria-label={title}
+      className={className}
+    >
+      <g transform="rotate(-17.5 850 850)">
+        <g fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round">
+          <circle cx="850" cy="850" r="350" strokeWidth="74" />
+          <path d="M 850 405 L 464.77 1269.52" strokeWidth="88" />
+          <path d="M 850 405 L 1235.23 1269.52" strokeWidth="88" />
+          <path d="M 850 405 L 850 350" strokeWidth="88" />
+          <path d="M 345 850 L 1355 850" strokeWidth="88" />
+        </g>
+        <g fill="currentColor">
+          <polygon points="850,240 925,385 775,385" />
+          <polygon points="235,850 380,775 380,925" />
+          <polygon points="1465,850 1320,925 1320,775" />
+          <polygon points="420,1370 410.51,1207.03 547.52,1268.08" />
+          <polygon points="1280,1370 1152.48,1268.08 1289.49,1207.03" />
+        </g>
+      </g>
+    </svg>
+  );
+}
+
+/**
+ * The quiet version of the mark: just the circle-A outline, no arrowheads.
+ * Used wherever the brand needs to whisper — empty states, placeholders.
+ */
+export function CircleA({
+  size = 64,
+  className = "text-accent",
+}: {
+  size?: number;
+  className?: string;
+}): ReactElement {
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 1700 1700"
+      aria-hidden="true"
+      className={className}
+    >
+      <g transform="rotate(-17.5 850 850)">
+        <g fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round">
+          <circle cx="850" cy="850" r="350" strokeWidth="74" />
+          <path d="M 850 405 L 464.77 1269.52" strokeWidth="88" />
+          <path d="M 850 405 L 1235.23 1269.52" strokeWidth="88" />
+          <path d="M 850 405 L 850 350" strokeWidth="88" />
+          <path d="M 345 850 L 1355 850" strokeWidth="88" />
+        </g>
+      </g>
+    </svg>
+  );
+}
+
+/**
+ * A single arrowhead lifted from the mark — the brand's bullet point.
+ * Points the same way the right-hand barb of the circle-A does.
+ */
+export function ArrowGlyph({
+  size = 12,
+  className = "text-accent",
+}: {
+  size?: number;
+  className?: string;
+}): ReactElement {
+  return (
+    <svg width={size} height={size} viewBox="0 0 120 120" aria-hidden="true" className={className}>
+      <polygon points="120,60 30,14 30,106" fill="currentColor" />
+    </svg>
+  );
+}
+
+/**
+ * Mark + wordmark. Inline below ~96px (sidebar, palette); stacked above it
+ * (onboarding hero) so the wordmark never gets dwarfed by the mark.
+ */
+export function Logo({ size = 32, withText = true }: { size?: number; withText?: boolean }): ReactElement {
+  if (!withText) return <LogoMark size={size} />;
+  const stacked = size >= 96;
+  return (
+    <span className={`inline-flex ${stacked ? "flex-col items-center gap-3" : "items-center gap-2.5"}`}>
+      <LogoMark size={size} />
+      <span
+        className={`font-semibold tracking-tight text-text ${stacked ? "text-2xl" : ""}`}
+        style={stacked ? undefined : { fontSize: `${Math.max(13, Math.round(size * 0.45))}px` }}
+      >
+        Tactical Media Broadcast Hub
+      </span>
+    </span>
+  );
+}
diff --git a/apps/web/src/components/connections/capacity-chip.tsx b/apps/web/src/components/connections/capacity-chip.tsx
new file mode 100644
index 0000000..c081e6a
--- /dev/null
+++ b/apps/web/src/components/connections/capacity-chip.tsx
@@ -0,0 +1,93 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import { Badge, Button } from "../ui/primitives";
+import { DOCUMENTED_RATES, type ConnectionCapacity } from "../../lib/platforms";
+import { capacitySnapshot, humanizeMs } from "@tactical-media-broadcast-hub/connector-sdk/rate-policy";
+
+function snapshotFor(cap: ConnectionCapacity) {
+  const documented = DOCUMENTED_RATES[cap.platform] ?? {};
+  const policy = {
+    requestsPerSecond: documented.requestsPerSecond ?? 1,
+    dailyPostCap: cap.resolvedCap,
+  };
+  return capacitySnapshot({ used: cap.used, cap: cap.resolvedCap, recentPublishes: cap.recentPublishes }, policy);
+}
+
+export function CapacityChip({ cap }: { cap: ConnectionCapacity }): React.ReactElement {
+  const [open, setOpen] = useState(false);
+  const snap = useMemo(() => snapshotFor(cap), [cap]);
+  const documented = DOCUMENTED_RATES[cap.platform] ?? {};
+  const overDocumented =
+    cap.overrideCap !== undefined && documented.dailyPostCap !== undefined && cap.overrideCap > documented.dailyPostCap;
+
+  const tone = snap.remaining === 0 ? "danger" : snap.remaining !== undefined && snap.remaining <= 3 ? "warn" : "live";
+
+  return (
+    <span className="relative">
+      <button
+        onClick={() => setOpen((v) => !v)}
+        title="Post capacity — click for details"
+        className="inline-flex items-center gap-1.5 rounded-full bg-surface-2 px-2.5 py-1 font-mono text-2xs text-text-dim transition-colors duration-150 hover:border hover:border-accent hover:text-accent"
+      >
+        <span className={`h-1.5 w-1.5 rounded-full ${tone === "danger" ? "bg-danger" : tone === "warn" ? "bg-warn" : "bg-live"}`} />
+        {snap.remaining !== undefined ? `${snap.remaining}/${snap.cap} posts left` : `${snap.used} today · no cap`}
+      </button>
+
+      {open && (
+        <div className="absolute right-0 top-8 z-30 w-72 rounded-lg border border-border bg-surface p-3 shadow-xl">
+          <div className="mb-2 flex items-center justify-between">
+            <span className="text-xs font-semibold">Rolling 24h capacity</span>
+            <Button size="sm" variant="ghost" onClick={() => setOpen(false)}>×</Button>
+          </div>
+
+          {snap.remaining !== undefined ? (
+            <>
+              <div className="mb-2 h-2 overflow-hidden rounded-full bg-surface-2">
+                <div
+                  className={`h-full rounded-full transition-all duration-300 ${
+                    tone === "danger" ? "bg-danger" : tone === "warn" ? "bg-warn" : "bg-accent"
+                  }`}
+                  style={{ width: `${Math.round((snap.used / (snap.cap ?? 1)) * 100)}%` }}
+                />
+              </div>
+              <div className="grid grid-cols-2 gap-x-3 gap-y-1 text-2xs">
+                <span className="text-text-faint">used</span>
+                <span className="text-right font-mono">{snap.used}</span>
+                <span className="text-text-faint">cap</span>
+                <span className="text-right font-mono">{snap.cap}</span>
+                <span className="text-text-faint">remaining</span>
+                <span className="text-right font-mono">{snap.remaining}</span>
+              </div>
+              <div className="mt-2 border-t border-border-subtle pt-2 text-2xs leading-relaxed">
+                {snap.nextSlotInMs !== undefined ? (
+                  <>
+                    <span className="text-warn">next slot frees in {humanizeMs(snap.nextSlotInMs)}</span>
+                    <span className="text-text-faint"> — the oldest post exits the 24h window at that point, then continuously as others age out.</span>
+                  </>
+                ) : (
+                  <span className="text-live">slots available now — each post holds its slot for 24h, then frees it</span>
+                )}
+              </div>
+              {cap.tierNote !== undefined && (
+                <div className="mt-2 border-t border-border-subtle pt-2">
+                  <Badge tone="accent">{cap.tierNote}</Badge>
+                </div>
+              )}
+              {overDocumented && (
+                <div className="mt-1.5 text-2xs leading-relaxed text-warn">
+                  Cap exceeds documented standard ({documented.dailyPostCap}/24h). Your API tier must genuinely
+                  permit {cap.overrideCap} — the provider enforces its real limit server-side.
+                </div>
+              )}
+            </>
+          ) : (
+            <p className="text-2xs leading-relaxed text-text-faint">
+              {snap.used} posts today. This connection has no configured cap — pacing is request-rate only.
+            </p>
+          )}
+        </div>
+      )}
+    </span>
+  );
+}
diff --git a/apps/web/src/components/control-room/audio-monitor.tsx b/apps/web/src/components/control-room/audio-monitor.tsx
new file mode 100644
index 0000000..c83a3ad
--- /dev/null
+++ b/apps/web/src/components/control-room/audio-monitor.tsx
@@ -0,0 +1,69 @@
+"use client";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "../ui/primitives";
+import { usePreviewTap } from "./preview-tap";
+import type { Production } from "./types";
+
+function AudioTap({ channelId, id, fixture, context, master, gain }: { channelId: string; id: string; fixture: boolean; context: AudioContext | null; master: GainNode | null; gain: number }): React.ReactElement {
+  const audio = useRef<HTMLAudioElement>(null);
+  const node = useRef<GainNode | null>(null);
+  const mediaSource = useRef<MediaElementAudioSourceNode | null>(null);
+  const urls = usePreviewTap(channelId, id, fixture, 40000);
+  const [available, setAvailable] = useState(false);
+  useEffect(() => { setAvailable(Boolean(document.createElement("audio").canPlayType("application/vnd.apple.mpegurl"))); }, []);
+  useEffect(() => {
+    if (!context || !master || !audio.current) return;
+    const source = mediaSource.current ?? context.createMediaElementSource(audio.current);
+    mediaSource.current = source;
+    const volume = context.createGain(); node.current = volume; volume.gain.value = 0;
+    source.connect(volume); volume.connect(master);
+    const element = audio.current;
+    return () => { element.pause(); source.disconnect(); volume.disconnect(); node.current = null; };
+  }, [context, master]);
+  useEffect(() => {
+    if (node.current) node.current.gain.setTargetAtTime(gain, context?.currentTime ?? 0, 0.015);
+    if (context && gain > 0 && available) void audio.current?.play().catch(() => undefined);
+    else audio.current?.pause();
+  }, [gain, context, urls, available]);
+  return <audio ref={audio} data-audio-tap={id} src={available ? urls?.audio : undefined} preload="none" crossOrigin="anonymous" />;
+}
+export function AudioMonitor({ production, liveIds, channelId, fixture, mobile, focused, observed }: { production: Production; liveIds: string[]; channelId: string; fixture: boolean; mobile: boolean; focused: string | null; observed: Production | null }): React.ReactElement {
+  const [mode, setMode] = useState("program");
+  const [context, setContext] = useState<AudioContext | null>(null);
+  const [master, setMaster] = useState<GainNode | null>(null);
+  const graph = useRef<AudioContext | null>(null);
+  const [gains, setGains] = useState<Record<string, number>>({});
+  const [error, setError] = useState("");
+  const [native, setNative] = useState(false);
+  useEffect(() => {
+    setNative(Boolean(document.createElement("audio").canPlayType("application/vnd.apple.mpegurl")));
+    return () => { void graph.current?.close(); };
+  }, []);
+  const arm = useCallback(async (): Promise<void> => {
+    try {
+      let ctx = graph.current;
+      if (!ctx) {
+        ctx = new AudioContext(); graph.current = ctx;
+        const output = ctx.createGain(); output.gain.value = 1; output.connect(ctx.destination);
+        setContext(ctx); setMaster(output);
+      }
+      await ctx.resume(); setError("");
+    } catch { setError("Audio could not be armed on this device."); }
+  }, []);
+  const selection = mobile ? focused ?? "program" : mode;
+  const ids = mobile ? [selection] : [...new Set(["program", ...(selection !== "custom" && selection !== "program" ? [selection] : []), ...liveIds.filter(id => id !== "program")])].slice(0, 5);
+  const audible = (id: string): number => selection === "custom" ? gains[id] ?? 0 : id === selection ? 1 : 0;
+  const programScene = observed?.scenes.find(scene => scene.id === observed.buses.program);
+  return <section aria-label="Audio monitor" className="rounded-lg border border-border-subtle bg-surface p-3">
+    <h2 className="mb-3 text-sm font-semibold">Audio monitor</h2>
+    <div className="flex flex-wrap items-end gap-3">
+      <Button className="min-h-11" variant="outline" disabled={fixture || !native} onClick={() => { void arm(); }}>{context ? "Resume audio" : "Arm audio"}</Button>
+      {!mobile && <label className="min-w-0 flex-1 text-xs">Monitor select<select className="cr-field mt-1" value={mode} onChange={event => setMode(event.target.value)}><option value="program">Follow program</option><option value="custom">Custom monitor mix</option>{production.sources.map(source => <option key={source.id} value={source.id}>Solo · {source.label}</option>)}</select></label>}
+    </div>
+    {selection === "custom" && ids.filter(id => id !== "program").map(id => <label key={id} className="mt-3 block text-xs">{production.sources.find(source => source.id === id)?.label}<input aria-label={`Monitor gain ${id}`} className="mt-1 h-11 w-full" type="range" min={0} max={1} step={0.01} value={gains[id] ?? 0} onChange={event => setGains(previous => ({ ...previous, [id]: Number(event.target.value) }))} /></label>)}
+    {ids.map(id => <AudioTap key={id} channelId={channelId} id={id} fixture={fixture} context={context} master={master} gain={audible(id)} />)}
+    <p className="mt-3 text-xs text-text-dim" data-program-audio>Program audio: {programScene ? `${programScene.label} · ${programScene.slots.filter(slot => slot.audioMode !== "off").length} audible slots · master ${observed?.audio.masterGainDb ?? 0} dB` : "unconfirmed"}</p>
+    <p className="mt-2 text-xs text-text-faint">{mobile ? "Monitor follows the watched tile. " : "Monitor gains are private to this browser. "}Same-origin signed audio taps avoid Web Audio’s cross-origin silence constraint. {fixture ? "Fixture has no audio." : !native ? "Native HLS audio is unavailable in this browser." : ""}</p>
+    {error && <p role="alert" className="mt-2 text-xs text-danger">{error}</p>}
+  </section>;
+}
diff --git a/apps/web/src/components/control-room/client.ts b/apps/web/src/components/control-room/client.ts
new file mode 100644
index 0000000..19372e3
--- /dev/null
+++ b/apps/web/src/components/control-room/client.ts
@@ -0,0 +1,32 @@
+import { API_URL, ApiError, ApiUnreachableError } from "../../lib/api-client";
+import { getSessionToken } from "../../lib/session-token";
+
+export function idempotencyKey(): string {
+  if (typeof crypto.randomUUID === "function") return crypto.randomUUID();
+  // getRandomValues also works on HTTP development hosts where randomUUID is unavailable.
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  bytes[6] = ((bytes[6] ?? 0) & 0x0f) | 0x40;
+  bytes[8] = ((bytes[8] ?? 0) & 0x3f) | 0x80;
+  const hex = Array.from(bytes, byte => byte.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+// Kept local: the shared API client does not support custom request headers.
+export async function controlRequest<T>(path: string, body?: unknown, signal?: AbortSignal): Promise<T> {
+  const token = getSessionToken();
+  let response: Response;
+  try {
+    response = await fetch(`${API_URL}${path}`, { method: body === undefined ? "GET" : "POST", credentials: "include", signal,
+      headers: { ...(token ? { Authorization: `Bearer ${token}` } : {}), ...(body === undefined ? {} : { "Content-Type": "application/json", "Idempotency-Key": idempotencyKey() }) },
+      body: body === undefined ? undefined : JSON.stringify(body) });
+  } catch (error) { if (signal?.aborted) throw error; throw new ApiUnreachableError(error); }
+  const text = await response.text();
+  let result: unknown = null;
+  if (text) { try { result = JSON.parse(text); } catch { result = text; } }
+  if (!response.ok) throw new ApiError(response.status, typeof result === "object" && result && "message" in result ? String(result.message) : `HTTP ${response.status}`, result);
+  return result as T;
+}
+export function signedSameOrigin(raw: string): string {
+  const url = new URL(raw, window.location.origin);
+  if (url.origin !== window.location.origin || !url.pathname.startsWith("/media-control/preview/")) throw new Error("Preview must use signed same-origin media URLs");
+  return url.href;
+}
diff --git a/apps/web/src/components/control-room/control-room.test.ts b/apps/web/src/components/control-room/control-room.test.ts
new file mode 100644
index 0000000..558806f
--- /dev/null
+++ b/apps/web/src/components/control-room/control-room.test.ts
@@ -0,0 +1,152 @@
+import { strict as assert } from "node:assert";
+import { test } from "node:test";
+import { webcrypto } from "node:crypto";
+import { idempotencyKey, controlRequest } from "./client";
+import { fixtureChannel } from "./fixtures";
+import { initialTally, refetchTally, tallyReducer, tileTally } from "./tally";
+import { RealtimeClient, type SocketLike } from "./state-store";
+import { liveTapIds } from "./multiview-grid";
+import { slotRect } from "./pst-preview";
+import type { StateFrame, Observed } from "./types";
+
+if (!globalThis.crypto) Object.defineProperty(globalThis, "crypto", { value: webcrypto });
+
+function observed(channel = fixtureChannel(), version = 1): Observed {
+  return { workspaceId: "workspace", channelId: channel.channelId, workerId: channel.workerId, assignmentEpoch: 1, state: "RUNNING", realizedVersion: version, updatedAt: new Date().toISOString(), reason: "" };
+}
+test("PST and CUT desired changes never move tally; exact observed version does", () => {
+  const channel = fixtureChannel(); channel.observed = observed();
+  let state = initialTally(channel);
+  const first = channel.desired?.production?.sources[0]?.id ?? "";
+  const second = channel.desired?.production?.sources[1]?.id ?? "";
+  assert.equal(tileTally(state.observedProduction, first), "program");
+  const desired = structuredClone(channel.desired);
+  assert.ok(desired?.production);
+  desired.desiredVersion = 2; desired.production.buses.preview = desired.production.scenes[1]?.id ?? null;
+  state = tallyReducer(state, { type: "state", workspaceId: "workspace", channelId: channel.channelId, kind: "desired", seq: 1, data: desired });
+  assert.equal(tileTally(state.observedProduction, second), "none");
+  state = tallyReducer(state, { type: "state", workspaceId: "workspace", channelId: channel.channelId, kind: "observed", seq: 2, data: observed(channel, 2) });
+  assert.equal(tileTally(state.observedProduction, second), "preview");
+  const cut = structuredClone(desired); assert.ok(cut.production); cut.desiredVersion = 3; cut.production.buses.program = cut.production.buses.preview;
+  state = tallyReducer(state, { type: "state", workspaceId: "workspace", channelId: channel.channelId, kind: "desired", seq: 3, data: cut });
+  assert.equal(tileTally(state.observedProduction, first), "program");
+  assert.equal(tileTally(state.observedProduction, second), "preview");
+  state = tallyReducer(state, { type: "state", workspaceId: "workspace", channelId: channel.channelId, kind: "observed", seq: 4, data: observed(channel, 3) });
+  assert.equal(tileTally(state.observedProduction, first), "none");
+  assert.equal(tileTally(state.observedProduction, second), "program");
+});
+test("unknown version, missing observation and stale assignment cannot claim program", () => {
+  const channel = fixtureChannel();
+  assert.equal(initialTally(channel).observedProduction, null);
+  channel.observed = observed(channel, 99); assert.equal(initialTally(channel).observedProduction, null);
+  channel.observed = { ...observed(), assignmentEpoch: 2 }; assert.equal(initialTally(channel).observedProduction, null);
+  channel.observed = { ...observed(), workerId: "other" }; assert.equal(initialTally(channel).observedProduction, null);
+  channel.observed = { ...observed(), state: "STOPPED" }; assert.equal(initialTally(channel).observedProduction, null);
+});
+test("duplicate and wrong-channel frames are ignored", () => {
+  const channel = fixtureChannel(); const state = { ...initialTally(channel), lastSeq: 4 };
+  const frame: StateFrame = { type: "state", workspaceId: "workspace", channelId: channel.channelId, kind: "observed", seq: 4, data: observed() };
+  assert.equal(tallyReducer(state, frame), state);
+  assert.equal(tallyReducer(state, { ...frame, seq: 5, channelId: "other" }), state);
+});
+test("late desired snapshot cannot fabricate a tally update", () => {
+  const channel = fixtureChannel(); channel.observed = observed(channel, 2);
+  const state = initialTally(channel); const desired = structuredClone(channel.desired); assert.ok(desired); desired.desiredVersion = 2;
+  const next = tallyReducer(state, { type: "state", workspaceId: "workspace", channelId: channel.channelId, kind: "desired", seq: 1, data: desired });
+  assert.equal(next.observedProduction, null);
+});
+test("Idempotency-Key is a distinct printable UUID for every action", async () => {
+  const keys = Array.from({ length: 100 }, idempotencyKey);
+  assert.equal(new Set(keys).size, keys.length);
+  for (const key of keys) { assert.match(key, /^[\x20-\x7e]{1,128}$/); assert.match(key, /^[0-9a-f-]{36}$/); }
+  const original = globalThis.fetch; const headers: Headers[] = [];
+  globalThis.fetch = async (_url, options) => { headers.push(new Headers(options?.headers)); return Response.json({ desiredVersion: 1, commandId: "test" }); };
+  try { await controlRequest("/media-control/channels/test/cut", {}); await controlRequest("/production/overlays/test", { templateId: "logo", fields: {} }); }
+  finally { globalThis.fetch = original; }
+  assert.ok(headers[0]?.get("Idempotency-Key")); assert.notEqual(headers[0]?.get("Idempotency-Key"), headers[1]?.get("Idempotency-Key"));
+});
+class FakeSocket implements SocketLike {
+  onopen: SocketLike["onopen"] = null; onmessage: SocketLike["onmessage"] = null; onclose: SocketLike["onclose"] = null; onerror: SocketLike["onerror"] = null;
+  sent: Record<string, unknown>[] = [];
+  send(raw: string): void { this.sent.push(JSON.parse(raw) as Record<string, unknown>); }
+  close(): void {}
+}
+test("WS auth waits for ack, resume uses last consumed frame and resync fully refetches", async () => {
+  const sockets: FakeSocket[] = []; const frames: StateFrame[] = []; let refetches = 0;
+  const channel = fixtureChannel();
+  const client = new RealtimeClient({ url: "ws://test/realtime", workspaceId: "workspace", channelId: channel.channelId, token: () => "secret", retryMs: 1,
+    socket: () => { const socket = new FakeSocket(); sockets.push(socket); return socket; },
+    status: async () => { refetches += 1; return { channels: [channel] }; }, onStatus: () => undefined, onFrame: frame => frames.push(frame), onConnection: () => undefined });
+  try {
+    client.start(); sockets[0]?.onopen?.(new Event("open"));
+    assert.deepEqual(sockets[0]?.sent, [{ type: "auth", token: "secret", workspaceId: "workspace" }]);
+    await client.receive(JSON.stringify({ type: "auth_ack" }));
+    assert.deepEqual(sockets[0]?.sent[1], { type: "subscribe", channelId: channel.channelId });
+    await client.receive(JSON.stringify({ type: "subscribe_ack", seq: 99 })); assert.equal(client.lastSeq, undefined);
+    const frame = { type: "state", workspaceId: "workspace", channelId: channel.channelId, seq: 7, kind: "observed", data: observed() };
+    await client.receive(JSON.stringify(frame)); await client.receive(JSON.stringify(frame));
+    assert.equal(frames.length, 1); assert.equal(client.lastSeq, 7);
+    sockets[0]?.onclose?.({ code: 1006 } as CloseEvent);
+    await new Promise(resolve => setTimeout(resolve, 10));
+    await client.receive(JSON.stringify({ type: "auth_ack" }));
+    assert.deepEqual(sockets[1]?.sent[0], { type: "subscribe", channelId: channel.channelId, lastSeq: 7 });
+    await client.receive(JSON.stringify({ type: "RESYNC_REQUIRED", channelId: channel.channelId }));
+    assert.equal(refetches, 1); assert.equal(client.lastSeq, undefined);
+    assert.deepEqual(sockets[1]?.sent.at(-1), { type: "subscribe", channelId: channel.channelId });
+    await client.receive(JSON.stringify({ ...frame, seq: 1 })); assert.equal(client.lastSeq, 1);
+  } finally { client.stop(); }
+});
+test("live budgets enforce large tier defaults, promotions, and mobile cap", () => {
+  const sources = fixtureChannel().desired?.production?.sources ?? [];
+  assert.equal(liveTapIds(sources, "2x2", null, [], false).length, 4);
+  assert.equal(liveTapIds(sources, "3x3", null, [], false).length, 1);
+  assert.equal(liveTapIds(sources, "4x4", sources[1]?.id ?? null, [], false).length, 2);
+  assert.equal(liveTapIds(sources, "custom", sources[0]?.id ?? null, sources.map(source => source.id), false).length, 4);
+  assert.deepEqual(liveTapIds(sources, "4x4", sources[0]?.id ?? null, [], true), [sources[0]?.id]);
+});
+test("PST uses scene slot geometry rather than multiview geometry", () => {
+  const slot = fixtureChannel().desired?.production?.scenes[0]?.slots[0]; assert.ok(slot);
+  assert.deepEqual(slotRect("2x2", { ...slot, index: 3 }), { x: 0.5, y: 0.5, w: 0.5, h: 0.5 });
+  assert.deepEqual(slotRect("custom", { ...slot, rect: { x: 1000, y: 2000, w: 4000, h: 3000 } }), { x: 0.1, y: 0.2, w: 0.4, h: 0.3 });
+});
+
+test("authorization close clears retries and never reconnects a revoked socket", async () => {
+  const socket = new FakeSocket(); let connections = 0; const states: string[] = [];
+  const client = new RealtimeClient({ url: "ws://test/realtime", workspaceId: "workspace", channelId: fixtureChannel().channelId, token: () => "revoked", retryMs: 1,
+    socket: () => { connections += 1; return socket; }, status: async () => ({ channels: [] }), onStatus: () => undefined, onFrame: () => undefined, onConnection: state => states.push(state) });
+  client.start(); socket.onclose?.({ code: 1008 } as CloseEvent);
+  await new Promise(resolve => setTimeout(resolve, 10));
+  assert.equal(connections, 1); assert.equal(states.at(-1), "denied"); client.stop();
+});
+test("status refetch keeps the realized snapshot during version lag and clears it on reassignment", () => {
+  const channel = fixtureChannel(); channel.observed = observed();
+  const initial = initialTally(channel); const nextChannel = structuredClone(channel);
+  assert.ok(nextChannel.desired?.production);
+  nextChannel.desired.desiredVersion = 2;
+  nextChannel.desired.production.buses.program = nextChannel.desired.production.scenes[1]?.id ?? null;
+  const resynced = refetchTally(nextChannel, initial);
+  assert.equal(resynced.observedProduction?.buses.program, channel.desired?.production?.buses.program);
+  assert.equal(resynced.lastSeq, 0);
+  assert.equal(refetchTally({ ...nextChannel, assignmentEpoch: 2 }, initial).observedProduction, null);
+});
+test("RESYNC failure stays in labeled polling mode and successful full refetch resubscribes", async () => {
+  const socket = new FakeSocket(); let unavailable = true, refetches = 0; const connections: string[] = [];
+  const client = new RealtimeClient({ url: "ws://test/realtime", workspaceId: "workspace", channelId: fixtureChannel().channelId, token: () => "token",
+    socket: () => socket, status: async () => { refetches += 1; if (unavailable) throw new Error("offline"); return { channels: [fixtureChannel()] }; },
+    onStatus: () => undefined, onFrame: () => undefined, onConnection: state => connections.push(state) });
+  try {
+    client.start(); await client.receive(JSON.stringify({ type: "RESYNC_REQUIRED" }));
+    assert.equal(connections.at(-1), "polling"); assert.equal(socket.sent.length, 0);
+    unavailable = false; await client.receive(JSON.stringify({ type: "RESYNC_REQUIRED" }));
+    assert.equal(refetches, 2); assert.deepEqual(socket.sent.at(-1), { type: "subscribe", channelId: fixtureChannel().channelId });
+  } finally { client.stop(); }
+});
+test("UUID fallback supports non-secure development hosts with Web Crypto entropy", () => {
+  const descriptor = Object.getOwnPropertyDescriptor(crypto, "randomUUID");
+  Object.defineProperty(crypto, "randomUUID", { value: undefined, configurable: true });
+  try {
+    const keys = Array.from({ length: 100 }, idempotencyKey);
+    assert.equal(new Set(keys).size, 100);
+    for (const key of keys) assert.match(key, /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/);
+  } finally { if (descriptor) Object.defineProperty(crypto, "randomUUID", descriptor); else Reflect.deleteProperty(crypto, "randomUUID"); }
+});
diff --git a/apps/web/src/components/control-room/fixtures.ts b/apps/web/src/components/control-room/fixtures.ts
new file mode 100644
index 0000000..9caa587
--- /dev/null
+++ b/apps/web/src/components/control-room/fixtures.ts
@@ -0,0 +1,10 @@
+import type { Channel, Production } from "./types";
+export const fixtureChannelId = "10000000-0000-4000-8000-000000000001";
+export const fixtureProduction: Production = {
+  sources: Array.from({ length: 16 }, (_, i) => ({ id: `20000000-0000-4000-8000-${String(i + 1).padStart(12, "0")}`, label: `Sample source ${i + 1}`, kind: "hls" })),
+  scenes: [0, 1].map(i => ({ id: `30000000-0000-4000-8000-${String(i + 1).padStart(12, "0")}`, label: i === 0 ? "Sample studio" : "Sample field", layout: "single", slots: [{ index: 0, sourceId: `20000000-0000-4000-8000-${String(i + 1).padStart(12, "0")}`, rect: null, fit: "contain", audioMode: "primary", gainDb: 0 }] })),
+  buses: { program: "30000000-0000-4000-8000-000000000001", preview: "30000000-0000-4000-8000-000000000001" },
+  overlays: ["lower_third", "chyron", "logo"].map((kind, i) => ({ id: `40000000-0000-4000-8000-${String(i + 1).padStart(12, "0")}`, sceneId: "30000000-0000-4000-8000-000000000001", kind: kind as "lower_third" | "chyron" | "logo", enabled: true, layer: i, position: { x: 0, y: 8000 }, revisionId: null, assetId: null })),
+  audio: { masterGainDb: 0 },
+};
+export function fixtureChannel(): Channel { return { channelId: fixtureChannelId, workerId: "sample-worker", assignmentEpoch: 1, desired: { desiredVersion: 1, desiredStatus: "RUNNING", production: structuredClone(fixtureProduction), director: { locked: false, override: null } }, observed: null, converged: false, workerAlive: false }; }
diff --git a/apps/web/src/components/control-room/multiview-grid.tsx b/apps/web/src/components/control-room/multiview-grid.tsx
new file mode 100644
index 0000000..5413659
--- /dev/null
+++ b/apps/web/src/components/control-room/multiview-grid.tsx
@@ -0,0 +1,40 @@
+"use client";
+import { useState } from "react";
+import { Button } from "../ui/primitives";
+import { PreviewTap } from "./preview-tap";
+import { tileTally } from "./tally";
+import type { Production, Source } from "./types";
+export type GridTier = "2x1" | "2x2" | "3x3" | "4x4" | "custom";
+export function liveTapIds(sources: Source[], tier: GridTier, focused: string | null, upgrades: string[], mobile: boolean): string[] {
+  const ids = sources.map(source => source.id);
+  const valid = (id: string): boolean => id === "program" || ids.includes(id);
+  const candidates = mobile ? [focused ?? "program"] : tier === "2x1" || tier === "2x2" ? ["program", ...(focused ? [focused] : []), ...ids] : ["program", ...(focused ? [focused] : []), ...upgrades];
+  return [...new Set(candidates)].filter(valid).slice(0, mobile ? 1 : Math.min(4, tier === "2x1" ? 2 : 4));
+}
+export function MultiviewGrid({ production, observed, channelId, fixture, mobile, liveIds, focused, onFocus, tier, onTier, upgrades, onUpgrade }: { production: Production; observed: Production | null; channelId: string; fixture: boolean; mobile: boolean; liveIds: string[]; focused: string | null; onFocus: (id: string) => void; tier: GridTier; onTier: (tier: GridTier) => void; upgrades: string[]; onUpgrade: (id: string) => void }): React.ReactElement {
+  const [columns, setColumns] = useState(3);
+  const capacity = tier === "2x1" ? 2 : tier === "2x2" ? 4 : tier === "3x3" ? 9 : 16;
+  const tiles = [{ id: "program", label: "PGM · encoder output", kind: "hls" as const }, ...production.sources].slice(0, capacity);
+  const selectedSourceIds = production.scenes.find(scene => scene.id === production.buses.preview)?.slots.map(slot => slot.sourceId) ?? [];
+  return <section aria-label="Multiview" className="min-w-0 rounded-lg border border-border-subtle bg-surface p-3">
+    <div className="mb-3 flex flex-wrap items-end gap-3">
+      <label className="text-xs">Multiview layout<select className="cr-field mt-1" value={tier} onChange={event => onTier(event.target.value as GridTier)}>{["2x1", "2x2", "3x3", "4x4", "custom"].map(value => <option key={value}>{value}</option>)}</select></label>
+      {tier === "custom" && <label className="text-xs">Columns<input className="cr-field mt-1" type="number" min={1} max={4} value={columns} onChange={event => setColumns(Math.max(1, Math.min(4, Number(event.target.value) || 1)))} /></label>}
+      <span className="pb-3 text-xs text-text-faint">{liveIds.length}/{mobile ? 1 : 4} live slots · tap to focus</span>
+    </div>
+    <div className="grid gap-2" style={{ gridTemplateColumns: `repeat(${mobile ? (tier === "2x1" ? 1 : 2) : tier === "custom" ? columns : tier === "3x3" ? 3 : tier === "4x4" ? 4 : 2}, minmax(0, 1fr))` }}>
+      {tiles.map(source => {
+        const tally = source.id === "program" ? observed?.buses.program ? "program" : "none" : tileTally(observed, source.id);
+        return <div key={source.id} data-source={source.id} data-tally={tally} className={`min-w-0 rounded-md border-2 p-1 ${tally === "program" ? "border-red-500" : tally === "preview" ? "border-green-500" : "border-border"}`}>
+          <button className="min-h-11 w-full text-left" aria-label={`Focus ${source.label}`} aria-pressed={focused === source.id} onClick={() => onFocus(source.id)}>
+            <div className="mb-1 flex min-h-7 flex-wrap items-center justify-between gap-1 px-1 text-xs"><span className="break-words">{source.label}</span><span className="font-mono">{tally === "program" ? "PGM" : tally === "preview" ? "PST" : "—"}</span></div>
+            <PreviewTap channelId={channelId} tap={source.id} fixture={fixture} live={liveIds.includes(source.id)} selected={selectedSourceIds.includes(source.id)} label={source.label} />
+          </button>
+          <p className="px-1 py-1 text-[10px] text-text-faint">{fixture ? "SAMPLE" : "Health not reported"}</p>
+          {!mobile && (tier === "3x3" || tier === "4x4" || tier === "custom") && source.id !== "program" && source.id !== focused && <Button className="min-h-11 w-full justify-center" disabled={!upgrades.includes(source.id) && liveIds.length >= 4} onClick={() => onUpgrade(source.id)}>{upgrades.includes(source.id) ? "Remove live" : "Upgrade live"}</Button>}
+        </div>;
+      })}
+    </div>
+    <p className="mt-3 text-xs text-text-faint">Extra live tiles can strain the device. Red/green tally uses the worker’s realized version. Unknown versions have no tally.</p>
+  </section>;
+}
diff --git a/apps/web/src/components/control-room/overlay-editor.tsx b/apps/web/src/components/control-room/overlay-editor.tsx
new file mode 100644
index 0000000..917a49f
--- /dev/null
+++ b/apps/web/src/components/control-room/overlay-editor.tsx
@@ -0,0 +1,31 @@
+"use client";
+import { useState } from "react";
+import { Button } from "../ui/primitives";
+import type { Overlay } from "./types";
+export interface RenderInput { templateId: "lower_third" | "chyron" | "logo"; fields: { title?: string; subtitle?: string; style?: "dark" | "red"; svg?: string } }
+function Editor({ overlay, disabled, onRender }: { overlay: Overlay; disabled: boolean; onRender: (id: string, input: RenderInput) => Promise<void> }): React.ReactElement {
+  const [title, setTitle] = useState(""); const [subtitle, setSubtitle] = useState(""); const [style, setStyle] = useState<"dark" | "red">("dark"); const [svg, setSvg] = useState("");
+  const [busy, setBusy] = useState(false); const [message, setMessage] = useState("");
+  if (overlay.kind === "clock") return <p className="text-xs text-text-faint">Clock overlay is server-generated.</p>;
+  const templateId = overlay.kind;
+  return <form className="min-w-0 space-y-3" onSubmit={event => {
+    event.preventDefault(); setBusy(true); setMessage("");
+    const input: RenderInput = { templateId, fields: templateId === "logo" ? { svg } : { title, subtitle, style } };
+    void onRender(overlay.id, input).then(() => setMessage("Render accepted. Waiting for the current revision in status.")).catch(error => setMessage(error instanceof Error ? error.message : "Render failed")).finally(() => setBusy(false));
+  }}>
+    <p className="text-xs text-text-faint">Template · {templateId}</p>
+    {templateId === "logo" ? <label className="block text-xs">Logo SVG<textarea className="cr-field mt-1 min-h-28" required maxLength={64000} value={svg} onChange={event => setSvg(event.target.value)} placeholder="<svg>…</svg>" /><span className="mt-1 block text-text-faint">Geometric SVG only; no scripts, external assets, or text.</span></label> : <>
+      <label className="block text-xs">{templateId === "chyron" ? "Chyron text" : "Title"} · {title.length}/80<input className="cr-field mt-1" maxLength={80} value={title} onChange={event => setTitle(event.target.value)} /></label>
+      <label className="block text-xs">Subtitle · {subtitle.length}/120<input className="cr-field mt-1" maxLength={120} value={subtitle} onChange={event => setSubtitle(event.target.value)} /></label>
+      <label className="block text-xs">Style<select className="cr-field mt-1" value={style} onChange={event => setStyle(event.target.value as "dark" | "red")}><option value="dark">Dark</option><option value="red">Red</option></select></label>
+    </>}
+    <Button className="min-h-11" variant="outline" disabled={disabled || busy} type="submit">{busy ? "Rendering…" : "Render overlay"}</Button>
+    <p className="break-all text-xs text-text-faint">Current revision: {overlay.revisionId ?? "None"}</p>
+    {message && <p role="status" className="text-xs">{message}</p>}
+  </form>;
+}
+export function OverlayEditor({ overlays, disabled, onRender }: { overlays: Overlay[]; disabled: boolean; onRender: (id: string, input: RenderInput) => Promise<void> }): React.ReactElement {
+  const [selected, setSelected] = useState("");
+  const overlay = overlays.find(item => item.id === selected) ?? overlays[0];
+  return <section aria-label="Overlay editor" className="min-w-0 rounded-lg border border-border-subtle bg-surface p-3"><h2 className="mb-3 text-sm font-semibold">Overlay editor</h2>{overlay ? <><label className="mb-3 block text-xs">Overlay slot<select className="cr-field mt-1" value={overlay.id} onChange={event => setSelected(event.target.value)}>{overlays.map((item, index) => <option key={item.id} value={item.id}>{item.kind} · slot {index + 1}</option>)}</select></label><Editor key={overlay.id} overlay={overlay} disabled={disabled} onRender={onRender} /></> : <p className="text-xs text-text-faint">Configure an overlay slot on a production scene to render a lower third, chyron, or logo.</p>}</section>;
+}
diff --git a/apps/web/src/components/control-room/preview-tap.tsx b/apps/web/src/components/control-room/preview-tap.tsx
new file mode 100644
index 0000000..4381768
--- /dev/null
+++ b/apps/web/src/components/control-room/preview-tap.tsx
@@ -0,0 +1,62 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { controlRequest, signedSameOrigin } from "./client";
+import type { PreviewUrls } from "./types";
+
+export function usePreviewTap(channelId: string, tap: string, fixture: boolean, cadence = 2000): PreviewUrls | null {
+  const [urls, setUrls] = useState<PreviewUrls | null>(null);
+  useEffect(() => {
+    setUrls(null);
+    if (fixture) return;
+    let visible = true, busy = false;
+    const abort = new AbortController();
+    const update = async (): Promise<void> => {
+      if (!visible || document.hidden || busy) return;
+      busy = true;
+      try {
+        const result = await controlRequest<PreviewUrls>(`/media-control/channels/${channelId}/preview/${tap}`, undefined, abort.signal);
+        if (!abort.signal.aborted) setUrls({ thumbnail: `${signedSameOrigin(result.thumbnail)}&refresh=${Date.now()}`, video: signedSameOrigin(result.video), audio: signedSameOrigin(result.audio) });
+      } catch { if (!abort.signal.aborted) setUrls(null); }
+      finally { busy = false; }
+    };
+    const listener = (): void => { if (!document.hidden) void update(); };
+    document.addEventListener("visibilitychange", listener);
+    // Consumers pause their own polling through cadence=0 while off-screen.
+    if (cadence > 0) void update(); else visible = false;
+    const timer = cadence > 0 ? setInterval(() => { void update(); }, cadence) : null;
+    return () => { abort.abort(); if (timer) clearInterval(timer); document.removeEventListener("visibilitychange", listener); };
+  }, [channelId, tap, fixture, cadence]);
+  return urls;
+}
+
+export function PreviewTap({ channelId, tap, fixture, live, selected, label }: { channelId: string; tap: string; fixture: boolean; live: boolean; selected: boolean; label: string }): React.ReactElement {
+  const root = useRef<HTMLDivElement>(null);
+  const [visible, setVisible] = useState(true);
+  const [pageVisible, setPageVisible] = useState(true);
+  const [native, setNative] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const active = visible && pageVisible;
+  const urls = usePreviewTap(channelId, tap, fixture, active ? (selected ? 1000 : 2000) : 0);
+  useEffect(() => {
+    setNative(Boolean(document.createElement("video").canPlayType("application/vnd.apple.mpegurl")));
+    const observer = new IntersectionObserver(entries => setVisible(entries[0]?.isIntersecting ?? false));
+    const update = (): void => setPageVisible(!document.hidden);
+    update(); document.addEventListener("visibilitychange", update);
+    if (root.current) observer.observe(root.current);
+    return () => { observer.disconnect(); document.removeEventListener("visibilitychange", update); };
+  }, []);
+  useEffect(() => setFailed(false), [tap, live]);
+  // Refresh thumbnail signatures continuously, but keep a live manifest stable until its TTL nears expiry.
+  const [videoUrl, setVideoUrl] = useState<string>();
+  useEffect(() => {
+    if (!urls || !live || !active) { setVideoUrl(undefined); return; }
+    setVideoUrl(previous => !previous || Number(new URL(previous).searchParams.get("expires")) * 1000 < Date.now() + 10000 ? urls.video : previous);
+  }, [urls, live, active]);
+  const playing = live && active && native && !failed && Boolean(videoUrl);
+  return <div ref={root} className="relative flex aspect-video items-center justify-center overflow-hidden rounded bg-black/60">
+    {playing ? <video data-live-decode src={videoUrl} autoPlay muted playsInline preload="none" className="h-full w-full object-contain" onError={() => setFailed(true)} />
+      : urls ? <img src={urls.thumbnail} alt={`${label} preview tap`} className="h-full w-full object-contain" onLoad={event => { event.currentTarget.style.visibility = "visible"; }} onError={event => { event.currentTarget.style.visibility = "hidden"; }} />
+      : <span className="px-3 text-center text-xs text-text-faint">{fixture ? "Fixture · no media" : "Preview tap unavailable"}</span>}
+    <span className="absolute bottom-1 left-1 rounded bg-black/80 px-2 py-1 text-[10px] text-white">{playing ? "live preview" : `thumbnail · ${selected ? "1" : "2"} s`}{live && !native && !fixture ? " · native HLS unavailable" : ""}</span>
+  </div>;
+}
diff --git a/apps/web/src/components/control-room/pst-preview.tsx b/apps/web/src/components/control-room/pst-preview.tsx
new file mode 100644
index 0000000..2ffe224
--- /dev/null
+++ b/apps/web/src/components/control-room/pst-preview.tsx
@@ -0,0 +1,64 @@
+"use client";
+import { useEffect, useRef, useState } from "react";
+import { controlRequest, signedSameOrigin } from "./client";
+import type { Production, Slot } from "./types";
+export function slotRect(layout: string, slot: Slot): { x: number; y: number; w: number; h: number } {
+  if (slot.rect) return { x: slot.rect.x / 10000, y: slot.rect.y / 10000, w: slot.rect.w / 10000, h: slot.rect.h / 10000 };
+  const cols = layout === "3x3" ? 3 : layout === "4x4" ? 4 : layout === "2x1" || layout === "2x2" ? 2 : 1;
+  const rows = layout === "2x1" || cols === 1 ? 1 : cols;
+  return { x: (slot.index % cols) / cols, y: Math.floor(slot.index / cols) / rows, w: 1 / cols, h: 1 / rows };
+}
+export function PstPreview({ production, channelId, fixture }: { production: Production; channelId: string; fixture: boolean }): React.ReactElement {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const [visible, setVisible] = useState(true);
+  const scene = production.scenes.find(item => item.id === production.buses.preview);
+  useEffect(() => {
+    const observer = new IntersectionObserver(entries => setVisible(entries[0]?.isIntersecting ?? false));
+    if (canvas.current) observer.observe(canvas.current);
+    return () => observer.disconnect();
+  }, []);
+  useEffect(() => {
+    const element = canvas.current;
+    if (!element) return;
+    const buffer = document.createElement("canvas"); buffer.width = element.width; buffer.height = element.height;
+    const context = buffer.getContext("2d");
+    if (!context) return;
+    const abort = new AbortController();
+    let busy = false;
+    const draw = async (): Promise<void> => {
+      if (document.hidden || !visible || busy) return;
+      busy = true;
+      context.fillStyle = "#101010"; context.fillRect(0, 0, element.width, element.height);
+      try {
+        for (const slot of [...(scene?.slots ?? [])].sort((a, b) => a.index - b.index)) {
+          const rect = slotRect(scene?.layout ?? "single", slot);
+          const x = rect.x * element.width, y = rect.y * element.height, w = rect.w * element.width, h = rect.h * element.height;
+          context.save(); context.beginPath(); context.rect(x, y, w, h); context.clip();
+          context.fillStyle = "#222"; context.fillRect(x, y, w, h);
+          let painted = false;
+          if (!fixture && slot.sourceId) {
+            try {
+              const urls = await controlRequest<{ thumbnail: string }>(`/media-control/channels/${channelId}/preview/${slot.sourceId}`, undefined, abort.signal);
+              const response = await fetch(signedSameOrigin(urls.thumbnail), { signal: abort.signal });
+              if (!response.ok) throw new Error("Thumbnail unavailable");
+              const bitmap = await createImageBitmap(await response.blob());
+              if (!abort.signal.aborted) {
+                const scale = slot.fit === "contain" ? Math.min(w / bitmap.width, h / bitmap.height) : Math.max(w / bitmap.width, h / bitmap.height);
+                context.drawImage(bitmap, x + (w - bitmap.width * scale) / 2, y + (h - bitmap.height * scale) / 2, bitmap.width * scale, bitmap.height * scale);
+                painted = true;
+              }
+              bitmap.close();
+            } catch { /* Label unavailable taps. */ }
+          }
+          if (!painted && !abort.signal.aborted) { context.fillStyle = "#aaa"; context.font = "16px sans-serif"; context.fillText(fixture ? "Fixture · no media" : "Tap unavailable", x + 16, y + 30, Math.max(1, w - 32)); }
+          context.restore();
+        }
+        if (!abort.signal.aborted) element.getContext("2d")?.drawImage(buffer, 0, 0);
+      } finally { busy = false; }
+    };
+    void draw(); const timer = setInterval(() => { void draw(); }, 1000);
+    return () => { abort.abort(); clearInterval(timer); };
+  }, [scene, channelId, fixture, visible]);
+  const overlays = production.overlays.filter(overlay => overlay.enabled && overlay.sceneId === scene?.id);
+  return <section className="rounded-lg border border-border-subtle bg-surface p-3" aria-label="PST look-ahead"><h2 className="mb-2 text-sm font-semibold">PST · {scene?.label ?? "No scene selected"}</h2><canvas ref={canvas} width={640} height={360} className="aspect-video w-full rounded bg-black" aria-label={`Look-ahead of ${scene?.label ?? "empty preview"}`} /><p className="mt-2 text-xs text-text-faint">PST is a look-ahead; PGM is the truth.</p>{overlays.length > 0 && <p className="mt-2 text-xs text-text-faint">{overlays.length} overlay slots configured. Status provides revision IDs without render pixels; overlay appearance is unavailable in this look-ahead.</p>}</section>;
+}
diff --git a/apps/web/src/components/control-room/state-store.ts b/apps/web/src/components/control-room/state-store.ts
new file mode 100644
index 0000000..de92b08
--- /dev/null
+++ b/apps/web/src/components/control-room/state-store.ts
@@ -0,0 +1,90 @@
+import type { StateFrame, Status } from "./types";
+
+export interface SocketLike {
+  onopen: ((event: Event) => void) | null; onmessage: ((event: MessageEvent) => void) | null; onclose: ((event: CloseEvent) => void) | null; onerror: ((event: Event) => void) | null;
+  send(value: string): void; close(): void;
+}
+interface Options {
+  url: string; token: () => string | null; workspaceId: string; channelId: string;
+  socket: (url: string) => SocketLike; status: () => Promise<Status>;
+  onFrame: (frame: StateFrame) => void; onStatus: (status: Status) => void;
+  onConnection: (state: "connecting" | "live" | "polling" | "denied") => void;
+  retryMs?: number;
+}
+export class RealtimeClient {
+  private socket: SocketLike | null = null;
+  private retry: ReturnType<typeof setTimeout> | null = null;
+  private poll: ReturnType<typeof setInterval> | null = null;
+  private stopped = false;
+  private seq: number | undefined;
+  private backoff = 1000;
+  private resyncing = false;
+  private resyncPending = false;
+  private handshake: ReturnType<typeof setTimeout> | null = null;
+  private messages: Promise<void> = Promise.resolve();
+  constructor(private readonly options: Options) {}
+  get lastSeq(): number | undefined { return this.seq; }
+  start(): void { this.stopped = false; this.connect(); }
+  private connect(): void {
+    if (this.stopped) return;
+    this.options.onConnection("connecting");
+    const socket = this.options.socket(this.options.url); this.socket = socket;
+    socket.onopen = () => socket.send(JSON.stringify({ type: "auth", token: this.options.token(), workspaceId: this.options.workspaceId }));
+    socket.onmessage = event => { this.messages = this.messages.then(() => this.receive(String(event.data))).catch(() => socket.close()); };
+    this.handshake = setTimeout(() => socket.close(), 5000);
+    socket.onerror = () => socket.close();
+    socket.onclose = event => {
+      if (this.stopped) return;
+      if (this.handshake) clearTimeout(this.handshake);
+      if (event.code === 1008) { this.options.onConnection("denied"); this.stop(); return; }
+      this.options.onConnection("polling");
+      if (!this.poll) this.poll = setInterval(() => { void this.refresh(); }, 2000);
+      this.retry = setTimeout(() => this.connect(), this.options.retryMs ?? this.backoff);
+      this.backoff = Math.min(8000, this.backoff * 2);
+    };
+  }
+  async receive(raw: string): Promise<void> {
+    if (this.stopped) return;
+    let frame: Record<string, unknown>;
+    try { const value: unknown = JSON.parse(raw); if (!value || typeof value !== "object") return; frame = value as Record<string, unknown>; } catch { return; }
+    if (frame.type === "auth_ack") this.socket?.send(JSON.stringify({ type: "subscribe", channelId: this.options.channelId, ...(this.seq === undefined ? {} : { lastSeq: this.seq }) }));
+    if (frame.type === "subscribe_denied") { this.options.onConnection("denied"); this.stop(); }
+    if (frame.type === "subscribe_ack") {
+      if (this.handshake) clearTimeout(this.handshake);
+      this.backoff = 1000; if (this.poll) clearInterval(this.poll); this.poll = null;
+      // ACK advertises the ring head, NOT the last consumed frame. Do not advance seq.
+      this.options.onConnection("live");
+    }
+    if (frame.type === "RESYNC_REQUIRED" && (!frame.channelId || frame.channelId === this.options.channelId)) {
+      this.seq = undefined;
+      this.resyncPending = true;
+      this.options.onConnection("polling");
+      if (!this.poll) this.poll = setInterval(() => { void this.refresh(); }, 2000);
+      await this.refresh();
+    }
+    if (frame.type === "state" && frame.channelId === this.options.channelId && frame.workspaceId === this.options.workspaceId && (frame.kind === "desired" || frame.kind === "observed") && Number.isSafeInteger(frame.seq) && Number(frame.seq) > (this.seq ?? -1)) {
+      this.seq = Number(frame.seq); this.options.onFrame(frame as unknown as StateFrame);
+      this.socket?.send(JSON.stringify({ type: "ack", channelId: this.options.channelId, seq: this.seq }));
+    }
+  }
+  private async refresh(): Promise<boolean> {
+    if (this.resyncing) return false;
+    this.resyncing = true;
+    const startedSeq = this.seq;
+    try {
+      const status = await this.options.status();
+      // An old REST poll must not overwrite newer WS observations after reconnect.
+      if (!this.stopped && this.seq === startedSeq) {
+        this.options.onStatus(status);
+        if (this.resyncPending) {
+          this.seq = undefined; this.resyncPending = false;
+          this.socket?.send(JSON.stringify({ type: "subscribe", channelId: this.options.channelId }));
+        }
+      }
+      return !this.stopped;
+    }
+    catch { return false; }
+    finally { this.resyncing = false; }
+  }
+  stop(): void { this.stopped = true; if (this.retry) clearTimeout(this.retry); if (this.poll) clearInterval(this.poll); if (this.handshake) clearTimeout(this.handshake); this.socket?.close(); }
+}
diff --git a/apps/web/src/components/control-room/switcher-bar.tsx b/apps/web/src/components/control-room/switcher-bar.tsx
new file mode 100644
index 0000000..f8700eb
--- /dev/null
+++ b/apps/web/src/components/control-room/switcher-bar.tsx
@@ -0,0 +1,16 @@
+"use client";
+import { Button } from "../ui/primitives";
+import type { Desired, OverrideMode } from "./types";
+export type DirectorAction = "pst-select" | "take" | "cut" | "lock" | "override";
+export function SwitcherBar({ desired, disabled, busy, onAction }: { desired: Desired; disabled: boolean; busy: boolean; onAction: (action: DirectorAction, body: object) => void }): React.ReactElement {
+  const production = desired.production;
+  const locked = desired.director?.locked ?? false;
+  return <section aria-label="Switcher" className="flex flex-wrap items-end gap-3 rounded-lg border border-border-subtle bg-surface p-3">
+    <label className="min-w-0 flex-1 text-xs">PST scene<select aria-label="PST scene" className="cr-field mt-1" disabled={disabled || busy} value={production?.buses.preview ?? ""} onChange={event => onAction("pst-select", { sceneId: event.target.value })}><option value="">Select a scene</option>{production?.scenes.map(scene => <option key={scene.id} value={scene.id}>{scene.label}</option>)}</select></label>
+    <Button className="min-h-11 min-w-20 justify-center" variant="outline" disabled={disabled || busy || !production?.buses.preview} title="PST to PGM at the next ready frame boundary (CUT transition)" onClick={() => onAction("take", {})}>TAKE</Button>
+    <Button className="min-h-11 min-w-20 justify-center" variant="primary" disabled={disabled || busy || !production?.buses.preview} title="Request an immediate CUT; tally waits for worker observation" onClick={() => onAction("cut", {})}>CUT</Button>
+    <Button className="min-h-11 justify-center" variant="outline" disabled={disabled || busy} aria-pressed={locked} onClick={() => onAction("lock", { enabled: !locked })}>{locked ? "Unlock program" : "Lock program"}</Button>
+    <label className="text-xs">Operator override<select className="cr-field mt-1" disabled={disabled || busy} value={desired.director?.override?.mode ?? "auto"} onChange={event => onAction("override", { mode: event.target.value === "auto" ? null : event.target.value as OverrideMode })}><option value="auto">Return to auto</option><option value="until_released">Until released</option><option value="five_minutes">Five minutes</option><option value="until_source_offline">Until source offline</option><option value="until_next_event">Until next event</option></select></label>
+    <p className="w-full text-xs text-text-faint">{locked ? "LOCKED" : desired.director?.override ? "MANUAL" : "AUTO"} · TAKE uses the next ready frame boundary; CUT requests an immediate switch. Both wait for worker confirmation.</p>
+  </section>;
+}
diff --git a/apps/web/src/components/control-room/tally.tsx b/apps/web/src/components/control-room/tally.tsx
new file mode 100644
index 0000000..f0fd39a
--- /dev/null
+++ b/apps/web/src/components/control-room/tally.tsx
@@ -0,0 +1,43 @@
+import type { Channel, Desired, Observed, Production, StateFrame } from "./types";
+
+export interface TallyState { channel: Channel; snapshots: ReadonlyMap<number, Production>; observedProduction: Production | null; lastSeq: number }
+function boundSnapshots(snapshots: Map<number, Production>, realizedVersion: number | null | undefined): void {
+  while (snapshots.size > 256) {
+    const oldest = [...snapshots.keys()].find(key => key !== realizedVersion);
+    if (oldest === undefined) break;
+    snapshots.delete(oldest);
+  }
+}
+function realized(channel: Channel, snapshots: ReadonlyMap<number, Production>): Production | null {
+  const observed = channel.observed;
+  return observed && observed.state !== "STOPPED" && observed.state !== "FAILED" && observed.channelId === channel.channelId && observed.assignmentEpoch === channel.assignmentEpoch && observed.workerId === channel.workerId && observed.realizedVersion !== null
+    ? snapshots.get(observed.realizedVersion) ?? null : null;
+}
+export function initialTally(channel: Channel): TallyState {
+  const snapshots = new Map<number, Production>();
+  if (channel.desired?.production) snapshots.set(channel.desired.desiredVersion, channel.desired.production);
+  return { channel, snapshots, observedProduction: realized(channel, snapshots), lastSeq: 0 };
+}
+export function refetchTally(channel: Channel, previous: TallyState | null): TallyState {
+  const fresh = initialTally(channel);
+  if (!previous || previous.channel.channelId !== channel.channelId || previous.channel.workerId !== channel.workerId || previous.channel.assignmentEpoch !== channel.assignmentEpoch) return fresh;
+  const snapshots = new Map([...previous.snapshots, ...fresh.snapshots]);
+  boundSnapshots(snapshots, channel.observed?.realizedVersion);
+  return { ...fresh, snapshots, observedProduction: realized(channel, snapshots) };
+}
+export function tallyReducer(state: TallyState, frame: StateFrame): TallyState {
+  if (frame.channelId !== state.channel.channelId || frame.seq <= state.lastSeq) return state;
+  const channel = { ...state.channel };
+  const snapshots = new Map(state.snapshots);
+  if (frame.kind === "desired") {
+    channel.desired = frame.data as Desired | null;
+    if (channel.desired?.production) snapshots.set(channel.desired.desiredVersion, channel.desired.production);
+  } else channel.observed = frame.data as Observed | null;
+  // Keep the realized snapshot while bounding memory during long sessions.
+  boundSnapshots(snapshots, channel.observed?.realizedVersion);
+  return { channel, snapshots, observedProduction: frame.kind === "observed" ? realized(channel, snapshots) : state.observedProduction, lastSeq: frame.seq };
+}
+export function tileTally(production: Production | null, sourceId: string): "program" | "preview" | "none" {
+  const contains = (id: string | null | undefined): boolean => Boolean(production?.scenes.find(scene => scene.id === id)?.slots.some(slot => slot.sourceId === sourceId));
+  return contains(production?.buses.program) ? "program" : contains(production?.buses.preview) ? "preview" : "none";
+}
diff --git a/apps/web/src/components/control-room/types.ts b/apps/web/src/components/control-room/types.ts
new file mode 100644
index 0000000..ceb2c1b
--- /dev/null
+++ b/apps/web/src/components/control-room/types.ts
@@ -0,0 +1,14 @@
+// Web-facing subset of the live media-control contracts. No remote source URLs are consumed.
+export interface Slot { index: number; sourceId: string | null; rect: { x: number; y: number; w: number; h: number } | null; fit: "contain" | "cover" | "crop"; audioMode: "off" | "on" | "primary"; gainDb: number }
+export interface Scene { id: string; label: string; layout: "single" | "pip" | "2x1" | "2x2" | "3x3" | "4x4" | "custom"; slots: Slot[] }
+export interface Source { id: string; label: string; kind: "hls" | "playlist" }
+export interface Overlay { id: string; sceneId: string; kind: "lower_third" | "chyron" | "logo" | "clock"; enabled: boolean; layer: number; position: { x: number; y: number }; revisionId: string | null; assetId: string | null }
+export interface Production { scenes: Scene[]; sources: Source[]; buses: { preview: string | null; program: string | null }; overlays: Overlay[]; audio: { masterGainDb: number } }
+export type OverrideMode = "until_released" | "five_minutes" | "until_source_offline" | "until_next_event";
+export interface Desired { desiredVersion: number; desiredStatus: string; production?: Production; director?: { locked: boolean; override: { mode: OverrideMode; expiresAt: string | null } | null } }
+export interface Observed { workspaceId: string; channelId: string; workerId: string; assignmentEpoch: number; state: string; realizedVersion: number | null; updatedAt: string; reason: string }
+export interface Channel { channelId: string; workerId: string; assignmentEpoch: number; desired: Desired | null; observed: Observed | null; converged: boolean; workerAlive: boolean }
+export interface Status { channels: Channel[] }
+export interface StateFrame { type: "state"; workspaceId: string; channelId: string; kind: "desired" | "observed"; seq: number; data: Desired | Observed | null }
+export interface PreviewUrls { thumbnail: string; video: string; audio: string }
+export interface Receipt { desiredVersion: number; commandId: string }
diff --git a/apps/web/src/components/live-chat/chat-panel.tsx b/apps/web/src/components/live-chat/chat-panel.tsx
new file mode 100644
index 0000000..c4fa581
--- /dev/null
+++ b/apps/web/src/components/live-chat/chat-panel.tsx
@@ -0,0 +1,85 @@
+"use client";
+
+import { useState } from "react";
+import type { ChatMessage, Delivery, LiveChatCapability, ModerateChatBody, SendChatMessageBody } from "../../../../../packages/core/src/chat-contract";
+import { CHAT_CONTRACT_EXAMPLES } from "../../../../../packages/core/src/chat-contract.schema";
+
+export interface ChatPanelProps {
+  messages?: ChatMessage[];
+  capabilities?: LiveChatCapability[];
+  delivery?: Delivery[];
+  readOnlyEmbedUrl?: string;
+  onSend?: (body: SendChatMessageBody) => Promise<void>;
+  onModerate?: (messageId: string, body: ModerateChatBody) => Promise<void>;
+}
+const fixtures: ChatMessage[] = [CHAT_CONTRACT_EXAMPLES.chatMessage];
+const fixtureCapabilities: LiveChatCapability[] = [CHAT_CONTRACT_EXAMPLES.capability];
+
+/** Standalone surface. The Control Room supplies REST/WS state and callbacks. */
+export function ChatPanel({ messages = fixtures, capabilities = fixtureCapabilities, delivery = [], readOnlyEmbedUrl, onSend, onModerate }: ChatPanelProps) {
+  const [platform, setPlatform] = useState("all");
+  const [target, setTarget] = useState("all");
+  const [text, setText] = useState("");
+  const [replyTo, setReplyTo] = useState<string>();
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const [demoMessages, setDemoMessages] = useState<ChatMessage[]>([]);
+  const [hidden, setHidden] = useState<string[]>([]);
+  const rows = [...messages, ...demoMessages].filter(message => !message.isModerated && !hidden.includes(message.id) && (platform === "all" || message.provider === platform));
+  const canSend = capabilities.some(cap => cap.reply && (cap.state === "ok" || cap.state === "degraded") && (target === "all" || cap.connectionId === target));
+  const reply = async () => {
+    if (!text.trim() || busy || !canSend) return;
+    setBusy(true); setError("");
+    try {
+      const body: SendChatMessageBody = { text, targets: target === "all" ? "all" : [target], ...(replyTo ? { replyTo } : {}) };
+      if (onSend) await onSend(body);
+      else setDemoMessages(current => [...current, { ...CHAT_CONTRACT_EXAMPLES.chatMessage, id: crypto.randomUUID(), seq: messages.length + current.length + 1, text, author: { handle: "studio", color: "hsl(200 70% 62%)" }, sentAt: new Date().toISOString(), receivedAt: new Date().toISOString(), ...(replyTo ? { replyTo } : {}) }]);
+      setText(""); setReplyTo(undefined);
+    } catch (cause) { setError(cause instanceof Error ? cause.message : "Reply failed"); }
+    finally { setBusy(false); }
+  };
+  const moderate = async (message: ChatMessage, body: ModerateChatBody) => {
+    setBusy(true); setError("");
+    try {
+      if (onModerate) await onModerate(message.id, body);
+      else setHidden(current => [...current, message.id]);
+    } catch (cause) { setError(cause instanceof Error ? cause.message : "Moderation failed"); }
+    finally { setBusy(false); }
+  };
+  return <section aria-label="Live chat" className="flex min-h-80 flex-col gap-3 rounded-lg border border-white/10 bg-zinc-950 p-4 text-zinc-100">
+    <div className="flex items-center justify-between gap-2"><h2 className="font-semibold">Live chat</h2>
+      <label>Platform <select aria-label="Filter platform" value={platform} onChange={event => setPlatform(event.target.value)} className="rounded bg-zinc-800 p-1">
+        <option value="all">All platforms</option>{[...new Set(messages.map(message => message.provider))].map(provider => <option key={provider}>{provider}</option>)}
+      </select></label>
+    </div>
+    {!onSend && <p className="text-xs text-zinc-400">Fixture preview</p>}
+    {readOnlyEmbedUrl && readOnlyEmbedUrl.startsWith("https://") && <iframe title="Read-only live chat" src={readOnlyEmbedUrl} className="h-80 w-full rounded" sandbox="allow-scripts allow-same-origin" referrerPolicy="no-referrer" />}
+    {capabilities.filter(cap => cap.reason).map(cap => <p key={cap.connectionId} className="text-xs text-zinc-400">{cap.provider}: {cap.reason}</p>)}
+    <ol aria-live="polite" className="max-h-96 flex-1 space-y-3 overflow-auto">
+      {rows.map(message => <li key={message.id} className="rounded bg-zinc-900 p-2">
+        <div className="flex flex-wrap items-center gap-2 text-sm"><span className="rounded bg-zinc-800 px-2 text-xs">{message.provider}</span>
+          <strong style={{ color: message.author.color }}>{message.author.displayName ?? message.author.handle}</strong>
+          {message.author.badges?.map(badge => <span key={badge} className="text-xs text-zinc-400">{badge}</span>)}
+          <time className="text-xs text-zinc-500" dateTime={message.sentAt}>{new Date(message.sentAt).toLocaleTimeString()}</time>
+        </div><p className="whitespace-pre-wrap break-words">{message.text}</p>
+        <div className="mt-1 flex gap-3 text-xs"><button type="button" onClick={() => setReplyTo(message.id)}>Reply</button>
+          {capabilities.some(cap => cap.connectionId === message.connectionId && cap.moderate && (cap.state === "ok" || cap.state === "degraded")) && <>
+            <button type="button" disabled={busy} onClick={() => void moderate(message, { action: "delete" })}>Delete</button>
+            <button type="button" disabled={busy} onClick={() => void moderate(message, { action: "timeout", durationSeconds: 600 })}>Timeout 10 min</button>
+          </>}
+        </div>
+      </li>)}
+    </ol>
+    {rows.length === 0 && <p className="text-sm text-zinc-400">No messages yet.</p>}
+    <form className="space-y-2" onSubmit={event => { event.preventDefault(); void reply(); }}>
+      {replyTo && <p className="text-xs">Replying to a message <button type="button" onClick={() => setReplyTo(undefined)}>Cancel</button></p>}
+      <label className="block text-sm">Send to <select aria-label="Reply targets" className="rounded bg-zinc-800 p-1" value={target} onChange={event => setTarget(event.target.value)}>
+        <option value="all">All capable</option>{capabilities.map(cap => <option key={cap.connectionId} value={cap.connectionId} disabled={!cap.reply || (cap.state !== "ok" && cap.state !== "degraded")}>{cap.provider}{cap.reason ? ` — ${cap.reason}` : ""}</option>)}
+      </select></label>
+      <div className="flex gap-2"><input aria-label="Chat reply" value={text} onChange={event => setText(event.target.value)} maxLength={500} placeholder="Write a reply…" className="min-w-0 flex-1 rounded bg-zinc-800 p-2" />
+        <button disabled={busy || !text.trim() || !canSend} className="rounded bg-indigo-600 px-4 disabled:opacity-40">Send</button></div>
+      {delivery.map(row => <p key={row.connectionId} className="text-xs">{row.provider}: {row.status}{row.error ? ` — ${row.error}` : ""}</p>)}
+      {error && <p role="alert" className="text-sm text-red-400">{error}</p>}
+    </form>
+  </section>;
+}
diff --git a/apps/web/src/components/mobile/amplify-sheet.tsx b/apps/web/src/components/mobile/amplify-sheet.tsx
new file mode 100644
index 0000000..2624aaa
--- /dev/null
+++ b/apps/web/src/components/mobile/amplify-sheet.tsx
@@ -0,0 +1,49 @@
+"use client";
+
+import { useState } from "react";
+import { useRouter } from "next/navigation";
+import type { FeedItem } from "../../lib/fixtures";
+import { PLATFORMS, type Platform } from "../../lib/platforms";
+import type { ConnectionSummary } from "../../lib/api-types";
+import { useApiResource } from "../../lib/use-api";
+import { Sheet } from "./sheet";
+import { nativeAmplifyActions } from "../../lib/amplify";
+
+const identity = (value: ConnectionSummary[]): ConnectionSummary[] => value;
+const empty: ConnectionSummary[] = [];
+
+export function AmplifySheet({ post, platform, open, onClose }: { post: FeedItem | null; platform: Platform | null; open: boolean; onClose: () => void }): React.ReactElement {
+  const router = useRouter();
+  const connections = useApiResource<ConnectionSummary[], ConnectionSummary[]>("/connections", identity, empty);
+  const [picked, setPicked] = useState<string[]>([]);
+  const [notice, setNotice] = useState("");
+  const native = platform === null ? [] : nativeAmplifyActions(platform);
+  function compose(ids: string[]): void {
+    if (post === null) return;
+    const params = new URLSearchParams({ text: `${post.text}\n\nVia ${post.handle}`, targets: ids.join(",") });
+    onClose();
+    router.push(`/compose?${params.toString()}`);
+  }
+  async function share(): Promise<void> {
+    if (post === null) return;
+    const url = window.location.href;
+    if (navigator.share) await navigator.share({ title: `Post by ${post.handle}`, text: post.text, url }).catch(() => undefined);
+    else if (navigator.clipboard) { await navigator.clipboard.writeText(`${post.text}\n${url}`); setNotice("Post text copied"); }
+  }
+  return <Sheet open={open} onClose={onClose} title={post === null ? "Amplify" : `Amplify ${post.handle}`} footer={<div className="flex gap-2"><button type="button" className="min-h-11 min-w-11 rounded-md border border-border px-3" onClick={() => void share()}>Share</button><button type="button" className="min-h-11 flex-1 rounded-md bg-accent px-3 text-sm font-semibold text-white disabled:opacity-40" disabled={picked.length === 0} onClick={() => compose(picked)}>Crosspost to {picked.length}</button></div>}>
+    {platform !== null && <><h3 className="mt-2 text-xs font-semibold uppercase text-text-faint">Native on {platform.displayName}</h3>
+      {native.length === 0 ? <p className="mt-3 text-xs text-text-faint">This platform exposes no native amplify action.</p> : native.map((action) => <button key={action.kind} type="button" className="mt-2 flex min-h-12 w-full items-center rounded-md border border-border px-4 text-left text-sm" onClick={() => action.kind === "quote" ? compose([]) : setNotice(`${action.label} is available in the platform, but its connector action is not wired yet.`)}>{action.label}{action.kind === "quote" && <span className="ml-auto text-xs text-text-faint">Opens compose</span>}</button>)}
+    </>}
+    {notice && <p className="mt-2 text-xs text-warn" role="status">{notice}</p>}
+    <h3 className="mt-6 text-xs font-semibold uppercase text-text-faint">Crosspost to your other accounts</h3>
+    {connections.source !== "live" && <p className="mt-2 text-xs text-text-faint">Connect to the API to choose publishing accounts.</p>}
+    {connections.data.filter((connection) => connection.provider !== platform?.id).map((connection) => {
+      const target = PLATFORMS[connection.provider];
+      const reason = !target?.capabilities.publishText ? "Text publishing unavailable" : target.capabilities.requiresMediaForPublish && !post?.hasMedia ? `${target.displayName} needs media` : connection.health !== "healthy" ? "Reconnect account first" : "";
+      return <label key={connection.id} className={`mt-2 flex min-h-14 items-center gap-3 rounded-md border border-border px-3 ${reason ? "opacity-60" : ""}`}>
+        <input type="checkbox" className="h-5 w-5 accent-accent" disabled={reason !== ""} checked={picked.includes(connection.id)} onChange={(event) => setPicked((current) => event.target.checked ? [...current, connection.id] : current.filter((id) => id !== connection.id))} />
+        <span className="min-w-0 flex-1"><span className="block text-sm">{target?.displayName ?? connection.provider}</span><span className="block text-xs text-text-faint">{reason || "Creates a new attributed post in compose"}</span></span>
+      </label>;
+    })}
+  </Sheet>;
+}
diff --git a/apps/web/src/components/mobile/approvals-segment.tsx b/apps/web/src/components/mobile/approvals-segment.tsx
new file mode 100644
index 0000000..377944c
--- /dev/null
+++ b/apps/web/src/components/mobile/approvals-segment.tsx
@@ -0,0 +1,73 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { api, errorMessage } from "../../lib/api-client";
+import type { ConnectionSummary, DraftRecord, ScheduledPublicationRecord } from "../../lib/api-types";
+import { useApiResource } from "../../lib/use-api";
+import { useAuth } from "../../lib/auth-store";
+import { DOCUMENTED_RATES, MOCK_COLUMN_DEFS, PLATFORMS } from "../../lib/platforms";
+import { OfflineBadge } from "../ui/offline-badge";
+import { Sheet } from "./sheet";
+
+const sample: DraftRecord[] = [{ id: "sample-review", workspaceId: "sample", authorUserId: "sample-contributor", state: "in_review", createdAt: "2026-10-07T08:00:00Z", updatedAt: "2026-10-07T08:00:00Z", post: { text: "Draft launch update. Please review the target wording before it goes out.", mediaAssetIds: [], visibility: "public", providerMetadata: { targetConnectionIds: [MOCK_COLUMN_DEFS[0]?.platformId] } } }];
+const identity = (value: DraftRecord[]): DraftRecord[] => value;
+const connectionIdentity = (value: ConnectionSummary[]): ConnectionSummary[] => value;
+const noConnections: ConnectionSummary[] = [];
+const quickReasons = ["Needs edits", "Wrong target", "Please add context"];
+
+export function ApprovalsSegment(): React.ReactElement {
+  const { can } = useAuth();
+  const resource = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, sample, { state: "in_review", limit: 100 });
+  const connections = useApiResource<ConnectionSummary[], ConnectionSummary[]>("/connections", connectionIdentity, noConnections);
+  const [rejecting, setRejecting] = useState<DraftRecord | null>(null);
+  const [reason, setReason] = useState("");
+  const [busy, setBusy] = useState<string | null>(null);
+  const [notice, setNotice] = useState("");
+  const live = resource.source === "live";
+  async function decide(draft: DraftRecord, action: "approve" | "reject"): Promise<void> {
+    if (!live || !can("approval.grant")) return;
+    setBusy(draft.id);
+    setNotice("");
+    try {
+      await api.post<DraftRecord>(`/publishing/drafts/${draft.id}/${action}`, action === "reject" ? { reason } : {});
+      const connectionId = draft.post.providerMetadata.connectionId;
+      const queueScheduled = action === "approve" && draft.post.scheduledAt && typeof connectionId === "string" && can("publication.schedule");
+      if (queueScheduled) await api.post<ScheduledPublicationRecord>(`/publishing/drafts/${draft.id}/schedule`, { connectionId, publishAt: draft.post.scheduledAt });
+      resource.setData((current) => current.filter((item) => item.id !== draft.id));
+      setNotice(`${action === "approve" ? queueScheduled ? "Approved and queued" : "Approved" : "Rejected"} · decision recorded in audit log.`);
+      setRejecting(null);
+      setReason("");
+      resource.reload();
+    } catch (error) { setNotice(errorMessage(error)); }
+    finally { setBusy(null); }
+  }
+  return <section className="min-w-0 flex-1 overflow-y-auto p-4" aria-label="Approvals">
+    <div className="mb-4 flex items-center justify-between"><div><h2 className="text-lg font-semibold">Approvals</h2><p className="text-xs text-text-faint">{resource.data.length} waiting for review</p></div><OfflineBadge source={resource.source} /></div>
+    {resource.source !== "live" && <p className="mb-3 text-xs text-text-faint">Sample review only. Connect to the API to approve or reject.</p>}
+    {resource.error && <p className="mb-3 text-xs text-danger">{resource.error}</p>}
+    {notice && <div role="status" className="mb-3 flex min-h-11 items-center justify-between gap-2 rounded-md border border-border px-3 text-xs"><span>{notice}</span><Link href="/audit" className="shrink-0 text-accent">View audit</Link></div>}
+    {resource.data.length === 0 && <p className="py-8 text-center text-sm text-text-faint">No drafts waiting for review.</p>}
+    <div className="space-y-3">{resource.data.map((draft) => {
+      const ids = Array.isArray(draft.post.providerMetadata.targetConnectionIds) ? draft.post.providerMetadata.targetConnectionIds : [draft.post.providerMetadata.connectionId].filter(Boolean);
+      const targets = ids.filter((id): id is string => typeof id === "string");
+      const scheduled = draft.post.scheduledAt;
+      const targetConnections = targets.map((id) => connections.data.find((connection) => connection.id === id)).filter((connection): connection is ConnectionSummary => connection !== undefined);
+      const tooLong = targetConnections.length > 0 ? targetConnections.some((connection) => draft.post.text.length > (PLATFORMS[connection.provider]?.charLimit ?? 500)) : draft.post.text.length > 500;
+      const missingMedia = targetConnections.some((connection) => PLATFORMS[connection.provider]?.capabilities.requiresMediaForPublish && draft.post.mediaAssetIds.length === 0);
+      const atCapacity = targetConnections.some((connection) => { const cap = DOCUMENTED_RATES[connection.provider]?.dailyPostCap; return cap !== undefined && connection.recentPublishes.length >= cap; });
+      return <article key={draft.id} className="rounded-lg border border-border bg-surface p-4">
+        <div className="flex items-center justify-between gap-2"><span className="flex min-w-0 items-center gap-2"><span className="truncate text-sm font-semibold">{draft.authorUserId === "sample-contributor" ? "Sample contributor" : `Contributor ${draft.authorUserId.slice(0, 8)}`}</span>{!live && <span className="shrink-0 rounded-full border border-border px-2 py-0.5 text-2xs text-text-faint">sample</span>}</span><span className={`rounded-full px-2 py-1 text-2xs ${scheduled ? "bg-accent-dim text-accent" : "bg-surface-2 text-text-dim"}`}>{scheduled ? new Date(scheduled).toLocaleString() : "Post now"}</span></div>
+        <p className="mt-3 whitespace-pre-wrap break-words text-sm">{draft.post.text}</p>
+        <div className="mt-3 flex flex-wrap gap-1">{targets.map((id) => { const connection = connections.data.find((item) => item.id === id); return <span key={id} className="rounded-full border border-border px-2 py-1 text-2xs text-text-dim">{PLATFORMS[connection?.provider ?? id]?.displayName ?? id.slice(0, 8)}</span>; })}</div>
+        {(tooLong || missingMedia || atCapacity) && <p className="mt-3 text-xs text-warn">Preflight: {[tooLong && "over a target text limit", missingMedia && "target needs media", atCapacity && "target at capacity"].filter(Boolean).join(" · ")}. Review before approving.</p>}
+        {scheduled && <p className="mt-2 text-xs text-text-faint">{can("publication.schedule") && typeof draft.post.providerMetadata.connectionId === "string" ? "Approving queues this scheduled post; it does not publish now." : "Approval changes the draft state. A publisher must queue the scheduled post."}</p>}
+        <div className="mt-4 flex gap-2"><button type="button" disabled className="min-h-11 rounded-md border border-border px-3 text-xs opacity-40" title="Review comments are not available in the API">Reply</button><button type="button" disabled={!live || !can("approval.grant") || busy !== null} onClick={() => { setRejecting(draft); setReason(""); }} className="min-h-11 rounded-md border border-danger px-3 text-xs text-danger disabled:opacity-40">Reject</button><button type="button" disabled={!live || !can("approval.grant") || busy !== null} onClick={() => void decide(draft, "approve")} className="min-h-11 flex-1 rounded-md bg-accent px-3 text-xs font-semibold text-white disabled:opacity-40">Approve</button></div>
+        {tooLong && <p className="mt-2 text-2xs text-text-faint">Auto-trim requires an edit operation during review and is unavailable.</p>}
+      </article>;
+    })}</div>
+    <Sheet open={rejecting !== null} onClose={() => setRejecting(null)} title="Reject draft" footer={<button type="button" disabled={busy !== null || reason.trim() === ""} onClick={() => { if (rejecting) void decide(rejecting, "reject"); }} className="min-h-11 w-full rounded-md bg-danger px-3 text-sm font-semibold text-white disabled:opacity-40">Reject with reason</button>}>
+      <p className="mb-3 text-xs text-text-faint">Choose a reason or write your own.</p><div className="flex flex-wrap gap-2">{quickReasons.map((pick) => <button key={pick} type="button" onClick={() => setReason(pick)} className="min-h-11 rounded-full border border-border px-3 text-xs">{pick}</button>)}</div><textarea value={reason} onChange={(event) => setReason(event.target.value)} placeholder="Reason for rejection" className="mt-3 min-h-24 w-full rounded-md border border-border bg-bg p-3 text-sm" />
+    </Sheet>
+  </section>;
+}
diff --git a/apps/web/src/components/mobile/bottom-nav.tsx b/apps/web/src/components/mobile/bottom-nav.tsx
new file mode 100644
index 0000000..c53e60d
--- /dev/null
+++ b/apps/web/src/components/mobile/bottom-nav.tsx
@@ -0,0 +1,101 @@
+"use client";
+
+import Link from "next/link";
+import type { MouseEvent } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import { useState } from "react";
+import { CreateFab } from "./create-fab";
+import { SpeedDial } from "./speed-dial";
+import { useApiResource } from "../../lib/use-api";
+import type { DraftRecord } from "../../lib/api-types";
+import { NavIcon } from "../brand";
+
+const emptyDrafts: DraftRecord[] = [];
+const identity = (drafts: DraftRecord[]): DraftRecord[] => drafts;
+
+const tabs = [
+  { href: "/streams", label: "Home", icon: "home" },
+  { href: "/search", label: "Search", icon: "search" },
+  { href: "/inbox", label: "Inbox", icon: "inbox" },
+  { href: "/more", label: "More", icon: "more" },
+] as const;
+
+/** Exact-match-first tab ranking: a route that is a tab itself outranks one that
+ *  merely lives under it, and routes like /compose match nothing at all — so
+ *  /compose no longer highlights Home and More no longer swallows calendar/video. */
+function activeTab(pathname: string): string {
+  const candidates: Array<[string, number]> = [
+    ["/inbox", pathname === "/inbox" || pathname.startsWith("/inbox/") ? 5 : -1],
+    ["/approvals", pathname === "/approvals" ? 4 : -1],
+    ["/streams", pathname === "/streams" ? 3 : -1],
+    ["/search", pathname === "/search" ? 3 : -1],
+    ["/more", pathname === "/more" ? 3 : -1],
+    ["/team", pathname.startsWith("/team") ? 1 : -1],
+    ["/connections", pathname.startsWith("/connections") ? 1 : -1],
+    ["/audit", pathname.startsWith("/audit") ? 1 : -1],
+    ["/settings", pathname.startsWith("/settings") ? 1 : -1],
+    ["/onboarding", pathname.startsWith("/onboarding") ? 1 : -1],
+    ["/calendar", pathname.startsWith("/calendar") ? 1 : -1],
+    ["/analytics", pathname.startsWith("/analytics") ? 1 : -1],
+    ["/video", pathname.startsWith("/video") ? 1 : -1],
+  ];
+  let best = "";
+  let bestScore = 0;
+  for (const [href, score] of candidates) {
+    if (score > bestScore) { best = href; bestScore = score; }
+  }
+  return best;
+}
+
+export function BottomNav({ badges }: { badges: { inbox: number } }): React.ReactElement {
+  const pathname = usePathname();
+  const router = useRouter();
+  const [open, setOpen] = useState(false);
+  const [lastTap, setLastTap] = useState<{ href: string; time: number } | null>(null);
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, emptyDrafts, { limit: 100 });
+  // The unread badge is supplied by the shell from live approvals-in-review; keep
+  // this fetch only for draft counts (Speed dial / create button).
+  const actionable = badges.inbox;
+  const active = activeTab(pathname);
+  const activate = (href: string, event: MouseEvent<HTMLAnchorElement>): void => {
+    if (active !== href || pathname !== href) return;
+    event.preventDefault();
+    const now = Date.now();
+    const scroller = document.querySelector<HTMLElement>("[data-mobile-main]");
+    scroller?.scrollTo({ top: 0, behavior: "smooth" });
+    scroller?.querySelectorAll<HTMLElement>("*").forEach((element) => {
+      if (element.scrollTop > 0 && /auto|scroll/.test(getComputedStyle(element).overflowY)) element.scrollTo({ top: 0, behavior: "smooth" });
+    });
+    if (href === "/search") document.querySelector<HTMLInputElement>("[data-search-field]")?.focus();
+    if (lastTap?.href === href && now - lastTap.time < 750) router.refresh();
+    setLastTap({ href, time: now });
+  };
+  return (
+    <>
+      <SpeedDial open={open} onClose={() => setOpen(false)} onResumeDrafts={() => router.push("/compose#drafts")} draftCount={drafts.data.length} />
+      <nav aria-label="Primary navigation" className={`relative z-50 grid h-[calc(var(--mobile-tab-height)+var(--mobile-safe-bottom))] shrink-0 grid-cols-5 border-t border-border-subtle bg-surface pb-[var(--mobile-safe-bottom)] lg:hidden ${open ? "pointer-events-none" : ""}`}>
+        {tabs.slice(0, 2).map((tab) => <Tab key={tab.href} {...tab} active={active === tab.href} badge={0} onClick={(event) => activate(tab.href, event)} />)}
+        <div className="relative flex items-start justify-center">
+          <div className="pointer-events-auto absolute -top-6 z-10"><CreateFab draftCount={drafts.data.length} open={open} onCompose={() => router.push("/compose")} onLongPress={() => setOpen((value) => !value)} /></div>
+          <button type="button" aria-label="Post" onClick={() => router.push("/compose")} className="pointer-events-auto absolute bottom-0 flex min-h-11 min-w-11 items-end justify-center pb-1 text-[11px] text-text-dim">Post</button>
+        </div>
+        {tabs.slice(2).map((tab) => <Tab key={tab.href} {...tab} active={active === tab.href} badge={tab.href === "/inbox" ? actionable : 0} onClick={(event) => activate(tab.href, event)} />)}
+      </nav>
+    </>
+  );
+}
+
+function Tab({ href, label, icon, active, badge, onClick }: {
+  href: string; label: string; icon: string; active: boolean; badge: number; onClick: (event: MouseEvent<HTMLAnchorElement>) => void;
+}): React.ReactElement {
+  return (
+    <Link href={href} scroll={false} onClick={onClick} aria-current={active ? "page" : undefined}
+      className="relative flex min-h-11 flex-col items-center justify-center gap-0.5 text-[11px] font-semibold text-text-dim">
+      <span className={`relative flex h-8 w-[60px] items-center justify-center rounded-full text-[24px] leading-none ${active ? "bg-accent-dim text-accent" : ""}`}>
+        <NavIcon name={icon} size={24} />
+        {badge > 0 && <span aria-label={`${badge} unread`} className="absolute -right-1 -top-1 flex min-h-5 min-w-5 items-center justify-center rounded-full bg-accent px-1 text-[10px] text-white">{badge > 99 ? "99+" : badge}</span>}
+      </span>
+      <span className={active ? "text-accent" : ""}>{label}</span>
+    </Link>
+  );
+}
diff --git a/apps/web/src/components/mobile/create-fab.tsx b/apps/web/src/components/mobile/create-fab.tsx
new file mode 100644
index 0000000..44a8802
--- /dev/null
+++ b/apps/web/src/components/mobile/create-fab.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { useRef } from "react";
+
+export function CreateFab({ draftCount, onCompose, onLongPress, open = false }: {
+  draftCount: number;
+  onCompose: () => void;
+  onLongPress: () => void;
+  open?: boolean;
+}): React.ReactElement {
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const longPressed = useRef(false);
+  const clear = (): void => { if (timer.current !== null) clearTimeout(timer.current); timer.current = null; };
+  return (
+    <button type="button" aria-label={open ? "Close create menu" : `Create post${draftCount > 0 ? `, ${draftCount} drafts` : ""}`}
+      aria-expanded={open}
+      onPointerDown={() => { longPressed.current = false; clear(); timer.current = setTimeout(() => {
+        longPressed.current = true;
+        if ("vibrate" in navigator) navigator.vibrate(20);
+        onLongPress();
+      }, 450); }}
+      onPointerUp={clear} onPointerCancel={clear} onPointerLeave={clear}
+      onClick={() => { if (longPressed.current) { longPressed.current = false; return; } if (open) onLongPress(); else onCompose(); }}
+      className={`relative flex h-[var(--mobile-fab-size)] w-[var(--mobile-fab-size)] items-center justify-center rounded-full border-4 border-bg text-3xl font-light transition-transform ${open ? "rotate-45 bg-white text-bg" : "bg-accent text-white"}`}>
+      +
+    </button>
+  );
+}
diff --git a/apps/web/src/components/mobile/post-card.tsx b/apps/web/src/components/mobile/post-card.tsx
new file mode 100644
index 0000000..752940a
--- /dev/null
+++ b/apps/web/src/components/mobile/post-card.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { Avatar } from "../ui/primitives";
+import { ageLabel } from "../../lib/fixtures";
+import type { StreamItem as FeedItem } from "../../lib/streams-data";
+import type { Platform } from "../../lib/platforms";
+import { SwipeItem } from "./swipe-item";
+
+export function PostCard({ item, platform, onAmplify, onReply, match = "", selected = false, onSelect }: { item: FeedItem; platform: Platform; onAmplify: () => void; onReply: () => void; match?: string; selected?: boolean; onSelect?: () => void }): React.ReactElement {
+  const index = match.trim() === "" ? -1 : item.text.toLowerCase().indexOf(match.trim().toLowerCase());
+  const text = index < 0 ? item.text : <>{item.text.slice(0, index)}<strong className="font-bold text-accent">{item.text.slice(index, index + match.trim().length)}</strong>{item.text.slice(index + match.trim().length)}</>;
+  return <SwipeItem leftActions={[{ label: platform.amplifyLabels.repost ?? platform.amplifyLabels.share ?? "Amplify", onClick: onAmplify, tone: "accent" }, { label: "Quote", onClick: onAmplify }, { label: "Crosspost", onClick: onAmplify }]}>
+    <article onMouseEnter={onSelect} data-stream-selected={selected || undefined} className={`border-b border-border-subtle px-4 py-4 ${selected ? "bg-accent-dim" : ""}`} data-post-card>
+      <div className="flex gap-3"><Avatar handle={item.handle} /><div className="min-w-0 flex-1">
+        <div className="flex min-w-0 items-center gap-2"><span className="truncate text-sm font-semibold">{item.author}</span><span className="truncate text-xs text-text-faint">{item.handle}</span><span className="ml-auto shrink-0 text-xs text-text-faint">{ageLabel(item.ageMinutes)}</span></div>
+        <span className="mt-1 inline-flex rounded-full border border-border px-2 py-0.5 text-2xs text-text-dim"><span className="mr-1.5 h-2 w-2 self-center rounded-full bg-accent" />{item.sourceLabel ?? platform.displayName}</span>
+        <p className="mt-3 whitespace-pre-wrap break-words text-sm leading-relaxed">{text}</p>
+        {item.mediaUrls?.map((url) => <a key={url} href={url} target="_blank" rel="noreferrer" className="mr-2 text-xs text-accent">View media ↗</a>)}
+        {item.hasMedia && !item.mediaUrls && <div className="mt-3 flex min-h-28 items-center justify-center rounded-lg border border-border-subtle bg-surface-2 text-xs text-text-faint">Media preview · sample feed</div>}
+        <div className="mt-3 flex items-center justify-between text-xs text-text-faint">
+          <button type="button" className="min-h-11 min-w-11 text-left" onClick={onReply} aria-label={`Reply to ${item.handle}`}>↩ {item.replies}</button>
+          <button type="button" className={`min-h-11 min-w-11 ${item.connectionId === undefined ? "opacity-50" : ""}`} onClick={onAmplify} title={item.connectionId === undefined ? "not connected — connect an account to boost" : undefined} aria-label={`Amplify ${item.handle}`}>↻ {item.reposts}</button>
+          <span className="flex min-h-11 min-w-11 items-center justify-end" aria-label={`${item.likes} likes`}>♡ {item.likes}</span>
+        </div>
+      </div></div>
+    </article>
+  </SwipeItem>;
+}
diff --git a/apps/web/src/components/mobile/pull-to-refresh.tsx b/apps/web/src/components/mobile/pull-to-refresh.tsx
new file mode 100644
index 0000000..a3c19d4
--- /dev/null
+++ b/apps/web/src/components/mobile/pull-to-refresh.tsx
@@ -0,0 +1,28 @@
+"use client";
+
+import { useRef, useState, type ReactNode, type TouchEvent } from "react";
+import { Loading } from "../brand/loading";
+
+export function PullToRefresh({ onRefresh, sourceCount, children }: { onRefresh: () => Promise<void>; sourceCount: number; children: ReactNode }): React.ReactElement {
+  const start = useRef<number | null>(null);
+  const [distance, setDistance] = useState(0);
+  const [busy, setBusy] = useState(false);
+  function touchStart(event: TouchEvent<HTMLDivElement>): void {
+    if (event.currentTarget.scrollTop === 0) start.current = event.touches[0]?.clientY ?? null;
+  }
+  function touchMove(event: TouchEvent<HTMLDivElement>): void {
+    if (start.current === null || event.currentTarget.scrollTop > 0) return;
+    setDistance(Math.max(0, Math.min(90, ((event.touches[0]?.clientY ?? start.current) - start.current) * 0.55)));
+  }
+  function touchEnd(): void {
+    start.current = null;
+    if (distance >= 60 && !busy) {
+      setBusy(true);
+      void onRefresh().finally(() => { setBusy(false); setDistance(0); });
+    } else setDistance(0);
+  }
+  return <div className="min-h-0 flex-1 overflow-y-auto overscroll-y-contain" onTouchStart={touchStart} onTouchMove={touchMove} onTouchEnd={touchEnd} data-pull-to-refresh>
+    <div className="flex items-center justify-center gap-2 overflow-hidden text-xs text-text-faint" style={{ height: busy ? 48 : distance }} aria-live="polite">{(busy || distance > 16) && <><Loading size={18} label="Refreshing" />{busy ? "Refreshing" : "Pull to refresh"} · {sourceCount} sources</>}</div>
+    {children}
+  </div>;
+}
diff --git a/apps/web/src/components/mobile/segmented.tsx b/apps/web/src/components/mobile/segmented.tsx
new file mode 100644
index 0000000..6db4bcc
--- /dev/null
+++ b/apps/web/src/components/mobile/segmented.tsx
@@ -0,0 +1,25 @@
+"use client";
+
+export interface SegmentOption<T extends string> {
+  value: T;
+  label: string;
+  count?: number;
+}
+
+export function Segmented<T extends string>({ options, value, onChange }: {
+  options: SegmentOption<T>[];
+  value: T;
+  onChange: (value: T) => void;
+}): React.ReactElement {
+  return (
+    <div role="tablist" className="flex min-w-0 gap-1 overflow-x-auto rounded-lg bg-surface-2 p-1 scrollbar-thin">
+      {options.map((option) => (
+        <button key={option.value} role="tab" aria-selected={option.value === value}
+          onClick={() => onChange(option.value)}
+          className={`flex min-h-11 shrink-0 items-center justify-center gap-1 rounded-md px-3 text-xs font-semibold ${option.value === value ? "bg-accent-dim text-accent" : "text-text-dim"}`}>
+          {option.label}{option.count !== undefined && option.count > 0 && <span>{option.count > 99 ? "99+" : option.count}</span>}
+        </button>
+      ))}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/mobile/sheet.tsx b/apps/web/src/components/mobile/sheet.tsx
new file mode 100644
index 0000000..d2f109c
--- /dev/null
+++ b/apps/web/src/components/mobile/sheet.tsx
@@ -0,0 +1,53 @@
+"use client";
+
+import { useEffect, useRef, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+
+export function Sheet({ open, onClose, title, children, footer }: {
+  open: boolean;
+  onClose: () => void;
+  title: ReactNode;
+  children: ReactNode;
+  footer?: ReactNode;
+}): React.ReactElement | null {
+  const panel = useRef<HTMLDivElement>(null);
+  const startY = useRef<number | null>(null);
+  useEffect(() => {
+    if (!open) return;
+    const previous = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    panel.current?.focus();
+    const onKey = (event: KeyboardEvent): void => {
+      if (event.key === "Escape") onClose();
+      if (event.key !== "Tab" || panel.current === null) return;
+      const focusable = Array.from(panel.current.querySelectorAll<HTMLElement>("button:not(:disabled), a[href], input:not(:disabled), select:not(:disabled), textarea:not(:disabled), [tabindex]:not([tabindex='-1'])"));
+      if (focusable.length === 0) { event.preventDefault(); return; }
+      const first = focusable[0];
+      const last = focusable[focusable.length - 1];
+      if (event.shiftKey && document.activeElement === first) { event.preventDefault(); last?.focus(); }
+      else if (!event.shiftKey && document.activeElement === last) { event.preventDefault(); first?.focus(); }
+    };
+    document.addEventListener("keydown", onKey);
+    return () => { document.removeEventListener("keydown", onKey); previous?.focus(); };
+  }, [open, onClose]);
+  if (!open || typeof document === "undefined") return null;
+  return createPortal(
+    <div className="fixed inset-0 z-[70] flex items-end" role="presentation">
+      <button className="absolute inset-0 bg-black/70" aria-label="Close sheet" onClick={onClose} />
+      <div ref={panel} tabIndex={-1} role="dialog" aria-modal="true" aria-label={typeof title === "string" ? title : "Options"}
+        className="relative flex max-h-[90dvh] w-full flex-col overflow-hidden rounded-t-[var(--mobile-sheet-radius)] border-t border-border bg-surface-2 pb-[var(--mobile-safe-bottom)] outline-none">
+        <div role="button" tabIndex={0} aria-label="Drag down to close" className="flex h-11 shrink-0 items-start justify-center pt-2"
+          onKeyDown={(event) => { if (event.key === "Enter" || event.key === " ") onClose(); }}
+          onTouchStart={(event) => { startY.current = event.touches[0]?.clientY ?? null; }}
+          onTouchEnd={(event) => { if (startY.current !== null && (event.changedTouches[0]?.clientY ?? 0) - startY.current > 80) onClose(); startY.current = null; }}>
+          <span className="h-1 w-10 rounded-full bg-border" />
+        </div>
+        <header className="flex min-h-14 items-center justify-between gap-3 px-4">
+          <h2 className="text-base font-semibold">{title}</h2>
+          <button className="flex h-11 w-11 items-center justify-center text-xl" aria-label="Close" onClick={onClose}>×</button>
+        </header>
+        <div className="min-h-0 flex-1 overflow-y-auto px-4 pb-4">{children}</div>
+        {footer && <footer className="border-t border-border p-4">{footer}</footer>}
+      </div>
+    </div>, document.body,
+  );
+}
diff --git a/apps/web/src/components/mobile/source-chips.tsx b/apps/web/src/components/mobile/source-chips.tsx
new file mode 100644
index 0000000..f6f2b4b
--- /dev/null
+++ b/apps/web/src/components/mobile/source-chips.tsx
@@ -0,0 +1,24 @@
+"use client";
+
+import { useRef, type TouchEvent } from "react";
+
+export interface SourceChip { id: string; label: string; dot?: string; count?: number; }
+
+export function SourceChips({ sources, value, onChange }: { sources: SourceChip[]; value: string; onChange: (value: string) => void }): React.ReactElement {
+  const start = useRef<{ x: number; y: number } | null>(null);
+  function end(event: TouchEvent<HTMLDivElement>): void {
+    if (start.current === null) return;
+    const dx = (event.changedTouches[0]?.clientX ?? start.current.x) - start.current.x;
+    const dy = (event.changedTouches[0]?.clientY ?? start.current.y) - start.current.y;
+    start.current = null;
+    if (Math.abs(dx) < 50 || Math.abs(dx) < Math.abs(dy) * 1.5) return;
+    const index = sources.findIndex((source) => source.id === value);
+    const next = sources[Math.max(0, Math.min(sources.length - 1, index + (dx < 0 ? 1 : -1)))];
+    if (next) onChange(next.id);
+  }
+  return <div className="flex min-w-0 gap-2 overflow-x-auto px-4 py-2 scrollbar-thin" role="tablist" aria-label="Feed sources" onTouchStart={(event) => { start.current = { x: event.touches[0]?.clientX ?? 0, y: event.touches[0]?.clientY ?? 0 }; }} onTouchEnd={end}>
+    {sources.map((source) => <button key={source.id} type="button" role="tab" aria-selected={value === source.id} onClick={() => onChange(source.id)} className={`flex min-h-11 shrink-0 items-center gap-2 rounded-full border px-4 text-xs font-semibold ${value === source.id ? "border-accent bg-accent-dim text-accent" : "border-border text-text-dim"}`}>
+      {source.dot && <span className="h-2 w-2 rounded-full bg-accent" aria-hidden="true" />}{source.label}{source.count !== undefined && <span className="text-text-faint">{source.count}</span>}
+    </button>)}
+  </div>;
+}
diff --git a/apps/web/src/components/mobile/speed-dial.tsx b/apps/web/src/components/mobile/speed-dial.tsx
new file mode 100644
index 0000000..e0f699e
--- /dev/null
+++ b/apps/web/src/components/mobile/speed-dial.tsx
@@ -0,0 +1,44 @@
+"use client";
+
+import { useRouter } from "next/navigation";
+import { useEffect } from "react";
+
+// Photo/Link entries removed: compose has no ?media= handling yet, so those
+// actions dead-ended. Re-add them once media attach is wired.
+const items = [
+  { label: "Compose", href: "/compose", position: "bottom-[168px] left-1/2 -translate-x-1/2" },
+  { label: "Video", href: "/video", position: "bottom-[145px] right-[18%]" },
+];
+
+export function SpeedDial({ open, onClose, onResumeDrafts, draftCount = 0 }: {
+  open: boolean;
+  onClose: () => void;
+  onResumeDrafts: () => void;
+  draftCount?: number;
+}): React.ReactElement | null {
+  const router = useRouter();
+  useEffect(() => {
+    if (!open) return;
+    const onKey = (event: KeyboardEvent): void => { if (event.key === "Escape") onClose(); };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [open, onClose]);
+  if (!open) return null;
+  return (
+    <div className="fixed inset-0 z-40 lg:hidden" role="dialog" aria-modal="true" aria-label="Create options">
+      <button type="button" aria-label="Close create options" className="absolute inset-0 bg-black/65" onClick={onClose} />
+      <div className="pointer-events-none absolute inset-x-0 bottom-[calc(var(--mobile-tab-height)+var(--mobile-safe-bottom))] h-[250px]">
+        {items.map((item) => (
+          <button key={item.label} type="button" onClick={() => { onClose(); router.push(item.href); }}
+            className={`pointer-events-auto absolute ${item.position} flex h-[60px] min-w-[60px] flex-col items-center justify-center rounded-full border border-accent bg-surface-2 px-2 text-xs font-semibold text-text`}>
+            <span className="text-lg text-accent">+</span>{item.label}
+          </button>
+        ))}
+        {draftCount > 0 && <button type="button" onClick={() => { onClose(); onResumeDrafts(); }}
+          className="pointer-events-auto absolute bottom-[88px] left-[8%] flex min-h-11 items-center rounded-full border border-accent/50 bg-surface-2 px-3 text-xs text-accent">
+          Resume drafts · {draftCount}
+        </button>}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/mobile/swipe-item.tsx b/apps/web/src/components/mobile/swipe-item.tsx
new file mode 100644
index 0000000..862542b
--- /dev/null
+++ b/apps/web/src/components/mobile/swipe-item.tsx
@@ -0,0 +1,46 @@
+"use client";
+
+import { useRef, useState, type ReactNode, type PointerEvent } from "react";
+import { swipeIntent, swipeResult, type SwipeIntent } from "../../lib/gestures";
+
+export interface SwipeAction { label: string; onClick: () => void; tone?: "accent" | "neutral"; }
+
+export function SwipeItem({ leftActions, rightActions = [], children }: { leftActions: SwipeAction[]; rightActions?: SwipeAction[]; children: ReactNode }): React.ReactElement {
+  const [offset, setOffset] = useState(0);
+  const start = useRef<{ x: number; y: number; time: number; base: number; intent: SwipeIntent } | null>(null);
+  const leftWidth = leftActions.length * 68;
+  const rightWidth = rightActions.length * 68;
+
+  function down(event: PointerEvent<HTMLDivElement>): void {
+    if (event.pointerType === "mouse" && event.button !== 0) return;
+    start.current = { x: event.clientX, y: event.clientY, time: event.timeStamp, base: offset, intent: "pending" };
+  }
+  function move(event: PointerEvent<HTMLDivElement>): void {
+    const gesture = start.current;
+    if (gesture === null) return;
+    const dx = event.clientX - gesture.x;
+    const dy = event.clientY - gesture.y;
+    if (gesture.intent === "pending") gesture.intent = swipeIntent(dx, dy);
+    if (gesture.intent !== "horizontal") return;
+    setOffset(Math.max(-leftWidth, Math.min(rightWidth, gesture.base + dx)));
+  }
+  function end(event: PointerEvent<HTMLDivElement>): void {
+    const gesture = start.current;
+    start.current = null;
+    if (gesture?.intent !== "horizontal") return;
+    const dx = event.clientX - gesture.x;
+    const velocity = Math.abs(dx) / Math.max(1, event.timeStamp - gesture.time);
+    const direction = dx < 0 ? "left" : "right";
+    const actions = direction === "left" ? leftActions : rightActions;
+    const width = direction === "left" ? leftWidth : rightWidth;
+    if (actions.length === 0) { setOffset(0); return; }
+    const result = swipeResult(dx, velocity, direction, width);
+    if (result === "full") { setOffset(0); actions[0]?.onClick(); }
+    else setOffset(result === "open" ? (direction === "left" ? -width : width) : 0);
+  }
+  return <div className="relative overflow-hidden" data-swipe-item>
+    {rightActions.length > 0 && <div className="absolute inset-y-0 left-0 flex" style={{ width: rightWidth }}>{rightActions.map((action) => <button key={action.label} type="button" className="flex h-full min-w-[68px] flex-1 items-center justify-center bg-surface-2 px-1 text-xs" onClick={() => { setOffset(0); action.onClick(); }}>{action.label}</button>)}</div>}
+    {leftActions.length > 0 && <div className="absolute inset-y-0 right-0 flex" style={{ width: leftWidth }}>{leftActions.map((action) => <button key={action.label} type="button" className={`flex h-full min-w-[68px] flex-1 items-center justify-center px-1 text-xs ${action.tone === "accent" ? "bg-accent text-white" : "bg-surface-2"}`} onClick={() => { setOffset(0); action.onClick(); }}>{action.label}</button>)}</div>}
+    <div style={{ transform: `translateX(${offset}px)`, touchAction: "pan-y" }} onPointerDown={down} onPointerMove={move} onPointerUp={end} onPointerCancel={() => { start.current = null; setOffset(0); }} className="relative bg-bg">{children}</div>
+  </div>;
+}
diff --git a/apps/web/src/components/mobile/top-bar.tsx b/apps/web/src/components/mobile/top-bar.tsx
new file mode 100644
index 0000000..387f12e
--- /dev/null
+++ b/apps/web/src/components/mobile/top-bar.tsx
@@ -0,0 +1,22 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { usePathname, useRouter } from "next/navigation";
+import { LogoMark } from "../brand/logo";
+
+export function MobileTopBar({ title, actions, back = false }: { title: ReactNode; actions?: ReactNode; back?: boolean }): React.ReactElement {
+  const router = useRouter();
+  const pathname = usePathname();
+  return (
+    <header className="flex h-[60px] shrink-0 items-center gap-3 border-b border-border-subtle bg-surface px-4 lg:hidden">
+      {back ? (
+        <button type="button" aria-label="Go back" onClick={() => {
+          if (window.history.length > 1) router.back();
+          else router.push(pathname.startsWith("/inbox/") ? "/inbox" : "/more");
+        }} className="-ml-2 flex h-11 w-11 shrink-0 items-center justify-center rounded-full text-xl">←</button>
+      ) : <LogoMark size={32} />}
+      <div className="min-w-0 flex-1 truncate text-lg font-bold">{title}</div>
+      {actions}
+    </header>
+  );
+}
diff --git a/apps/web/src/components/shell/command-palette.tsx b/apps/web/src/components/shell/command-palette.tsx
new file mode 100644
index 0000000..dd1463e
--- /dev/null
+++ b/apps/web/src/components/shell/command-palette.tsx
@@ -0,0 +1,87 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { useRouter } from "next/navigation";
+import { Command } from "cmdk";
+import { LogoMark } from "../brand/logo";
+import { EmptyState } from "../brand/empty-state";
+
+const PAGES = [
+  { href: "/streams", label: "Go to Streams" },
+  { href: "/compose", label: "Go to Compose" },
+  { href: "/video", label: "Go to Video" },
+  { href: "/inbox", label: "Go to Inbox" },
+  { href: "/archive", label: "Go to Archive" },
+  { href: "/connections", label: "Go to Channels" },
+  { href: "/team", label: "Go to Team" },
+  { href: "/audit", label: "Go to Audit" },
+  { href: "/onboarding", label: "Go to Onboarding" },
+];
+
+export function CommandPalette(): React.ReactElement {
+  const [open, setOpen] = useState(false);
+  const router = useRouter();
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent): void => {
+      if ((e.metaKey || e.ctrlKey) && e.key === "k") {
+        e.preventDefault();
+        setOpen((v) => !v);
+      }
+      if (e.key === "Escape") setOpen(false);
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
+  if (!open) return <></>;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-start justify-center bg-black/60 pt-[15vh]" onClick={() => setOpen(false)}>
+      <Command
+        className="w-[480px] max-w-[90vw] overflow-hidden rounded-lg border border-border bg-surface shadow-2xl"
+        onClick={(e: React.MouseEvent) => e.stopPropagation()}
+      >
+        <div className="flex items-center gap-2.5 border-b border-border-subtle px-4">
+          <LogoMark size={16} title="Tactical Media Broadcast Hub" />
+          <Command.Input
+            autoFocus
+            placeholder="Type a command or search…"
+            className="w-full bg-transparent py-3 text-sm text-text placeholder:text-text-faint focus:outline-none"
+          />
+        </div>
+        <Command.List className="max-h-72 overflow-y-auto p-2 scrollbar-thin">
+          <Command.Empty>
+            <EmptyState
+              size={40}
+              title="Nothing here."
+              hint="No command matches — the circle-A keeps watch anyway."
+              className="py-4"
+            />
+          </Command.Empty>
+          <Command.Group heading="Navigate" className="text-2xs text-text-faint [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1">
+            {PAGES.map((p) => (
+              <Item key={p.href} onSelect={() => { setOpen(false); router.push(p.href); }}>
+                {p.label}
+              </Item>
+            ))}
+          </Command.Group>
+          <Command.Group heading="Actions" className="text-2xs text-text-faint [&_[cmdk-group-heading]]:px-2 [&_[cmdk-group-heading]]:py-1">
+            <Item onSelect={() => { setOpen(false); router.push("/compose"); }}>New post (Compose)</Item>
+          </Command.Group>
+        </Command.List>
+      </Command>
+    </div>
+  );
+}
+
+function Item({ children, onSelect }: { children: React.ReactNode; onSelect: () => void }): React.ReactElement {
+  return (
+    <Command.Item
+      onSelect={onSelect}
+      className="cursor-pointer rounded-md px-3 py-2 text-sm text-text-dim data-[selected=true]:bg-accent-dim data-[selected=true]:text-text"
+    >
+      {children}
+    </Command.Item>
+  );
+}
diff --git a/apps/web/src/components/shell/sidebar.tsx b/apps/web/src/components/shell/sidebar.tsx
new file mode 100644
index 0000000..091aa85
--- /dev/null
+++ b/apps/web/src/components/shell/sidebar.tsx
@@ -0,0 +1,77 @@
+"use client";
+
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+import { useAuth } from "../../lib/auth-store";
+import { useApiResource } from "../../lib/use-api";
+import type { DraftRecord } from "../../lib/api-types";
+import { LogoMark } from "../brand/logo";
+import { NavIcon } from "../brand";
+
+const NAV = [
+  { href: "/streams", label: "Streams" },
+  { href: "/compose", label: "Compose" },
+  { href: "/calendar", label: "Calendar" },
+  { href: "/video", label: "Video" },
+  { href: "/control-room", label: "Control Room" },
+  { href: "/inbox", label: "Inbox" },
+  { href: "/approvals", label: "Approvals" },
+  { href: "/archive", label: "Archive" },
+  { href: "/analytics", label: "Analytics" },
+  { href: "/connections", label: "Channels" },
+  { href: "/team", label: "Team" },
+  { href: "/audit", label: "Audit" },
+  { href: "/onboarding", label: "Onboarding" },
+  { href: "/settings", label: "Settings" },
+];
+
+const identity = (drafts: DraftRecord[]): DraftRecord[] => drafts;
+const emptyDrafts: DraftRecord[] = [];
+
+export function Sidebar(): React.ReactElement {
+  const pathname = usePathname();
+  const { session, can } = useAuth();
+  const drafts = useApiResource<DraftRecord[], DraftRecord[]>("/publishing/drafts", identity, emptyDrafts, { state: "in_review", limit: 100 });
+  // Real in-review count from the API; hidden while loading/offline and for non-approvers.
+  const approvals = can("approval.grant") && drafts.source === "live" ? drafts.data.length : 0;
+  const workspaceName = session?.workspace.name ?? "Studio";
+  return (
+    <aside className="hidden h-screen w-52 shrink-0 flex-col border-r border-border-subtle bg-surface lg:flex">
+      <div className="flex items-center gap-2.5 border-b border-border-subtle px-4 py-4">
+        <LogoMark size={30} title="Tactical Media Broadcast Hub" />
+        <div className="min-w-0">
+          <div className="truncate text-sm font-semibold tracking-tight">Tactical Media Broadcast Hub</div>
+          <div className="truncate text-2xs text-text-faint" title={workspaceName}>
+            {workspaceName} ▾
+          </div>
+        </div>
+      </div>
+      <nav className="flex-1 overflow-y-auto scrollbar-thin p-2">
+        {NAV.map((item) => {
+          const active = pathname.startsWith(item.href);
+          return (
+            <Link
+              key={item.href}
+              href={item.href}
+              className={`group flex items-center justify-between rounded-md px-3 py-1.5 text-sm transition-colors duration-150 ${item.href === "/control-room" ? "min-h-11" : ""} ${
+                active ? "bg-accent-dim text-accent" : "text-text-dim hover:bg-surface-2 hover:text-text"
+              }`}
+            >
+              <span className="flex items-center gap-2.5">
+                {item.href === "/video" || item.href === "/control-room" ? (
+                  <NavIcon name="video" size={14} />
+                ) : (
+                  <span className={`h-1.5 w-1.5 rounded-full ${active ? "bg-accent" : "bg-border group-hover:bg-text-faint"}`} />
+                )}
+                {item.label}
+              </span>
+              {item.href === "/approvals" && approvals > 0 && (
+                <span className="text-2xs text-text-faint">{approvals}</span>
+              )}
+            </Link>
+          );
+        })}
+      </nav>
+    </aside>
+  );
+}
diff --git a/apps/web/src/components/streams/card.tsx b/apps/web/src/components/streams/card.tsx
new file mode 100644
index 0000000..e8279f5
--- /dev/null
+++ b/apps/web/src/components/streams/card.tsx
@@ -0,0 +1,104 @@
+"use client";
+
+import { Badge } from "../ui/primitives";
+import type { StreamItem as FeedItem } from "../../lib/streams-data";
+import { ageLabel } from "../../lib/fixtures";
+import type { Platform } from "../../lib/platforms";
+
+export function FeedCard({
+  item,
+  platform,
+  selected,
+  onSelect,
+  onRepost,
+  onQuote,
+}: {
+  item: FeedItem;
+  platform: Platform;
+  selected: boolean;
+  onSelect: () => void;
+  onRepost: () => void;
+  onQuote: () => void;
+}): React.ReactElement {
+  const caps = platform.capabilities;
+  const canAmplify = caps.amplifyRepost || caps.amplifyQuote || caps.amplifyShare;
+  const fallbackQuote = !caps.amplifyQuote && caps.publishText;
+  // Sample/live items without a connection cannot actually be amplified.
+  const connected = item.connectionId !== undefined;
+  const notConnectedTitle = connected ? undefined : "not connected — connect an account to boost";
+  return (
+    <div
+      data-stream-selected={selected || undefined}
+      onMouseEnter={onSelect}
+      className={`group border-b border-border-subtle px-3 py-2.5 transition-colors duration-150 ${
+        selected ? "bg-accent-dim" : "hover:bg-surface-2"
+      }`}
+    >
+      <div className="flex items-start gap-2.5">
+        <div className="min-w-0 flex-1">
+          <div className="flex items-baseline gap-2">
+            <span className="truncate text-sm font-medium">{item.author}</span>
+            <span className="truncate text-2xs text-text-faint">{item.handle}</span>
+            <span className="ml-auto shrink-0 text-2xs text-text-faint">{ageLabel(item.ageMinutes)}</span>
+          </div>
+          {item.sourceLabel && <span className="text-2xs text-text-faint">{item.sourceLabel}</span>}
+          <p className="mt-1 line-clamp-4 text-sm leading-snug text-text-dim">{item.text}</p>
+          {item.mediaUrls?.map((url) => <a key={url} href={url} target="_blank" rel="noreferrer" className="mr-2 text-xs text-accent">View media ↗</a>)}
+          {item.hasMedia && !item.mediaUrls && <div className="mt-1.5 h-16 rounded-md border border-border-subtle bg-surface-2" />}
+          <div className="mt-1.5 flex items-center gap-3 text-2xs text-text-faint">
+            <span>♡ {item.likes}</span>
+            <span>⇆ {item.reposts}</span>
+            <span>↩ {item.replies}</span>
+            {selected && (canAmplify || fallbackQuote) && (
+              <span className="ml-auto flex items-center gap-1 opacity-100 transition-opacity duration-150">
+                {caps.amplifyRepost && (
+                  <button
+                    onClick={onRepost}
+                    disabled={!connected}
+                    title={notConnectedTitle}
+                    className="rounded border border-border px-1.5 py-0.5 font-medium text-text-dim transition-colors duration-150 hover:border-accent hover:text-accent disabled:cursor-not-allowed disabled:opacity-50"
+                  >
+                    {platform.amplifyLabels.repost ?? "Repost"}
+                  </button>
+                )}
+                {(caps.amplifyQuote || fallbackQuote) && (
+                  <button
+                    onClick={onQuote}
+                    disabled={!connected}
+                    title={notConnectedTitle ?? (caps.amplifyQuote ? "Native quote via API" : "Composes your own post quoting this item with attribution")}
+                    className={`rounded border px-1.5 py-0.5 font-medium transition-colors duration-150 disabled:cursor-not-allowed disabled:opacity-50 ${
+                      caps.amplifyQuote
+                        ? "border-border text-text-dim hover:border-accent hover:text-accent"
+                        : "border-dashed border-border text-text-faint hover:border-accent hover:text-accent"
+                    }`}
+                  >
+                    {caps.amplifyQuote ? (platform.amplifyLabels.quote ?? "Quote") : "Quote…"}
+                  </button>
+                )}
+                {caps.amplifyShare && !caps.amplifyRepost && !caps.amplifyQuote && (
+                  <button
+                    onClick={onRepost}
+                    disabled={!connected}
+                    title={notConnectedTitle}
+                    className="rounded border border-border px-1.5 py-0.5 font-medium text-text-dim transition-colors duration-150 hover:border-accent hover:text-accent disabled:cursor-not-allowed disabled:opacity-50"
+                  >
+                    {platform.amplifyLabels.share ?? "Share"}
+                  </button>
+                )}
+              </span>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+export function NoAmplifyNote(): React.ReactElement {
+  return (
+    <div className="flex items-center gap-2 border-b border-border-subtle px-3 py-2">
+      <Badge tone="neutral">no amplify</Badge>
+      <span className="text-2xs text-text-faint">this platform&apos;s API exposes no reshare action</span>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/streams/column.tsx b/apps/web/src/components/streams/column.tsx
new file mode 100644
index 0000000..6318a97
--- /dev/null
+++ b/apps/web/src/components/streams/column.tsx
@@ -0,0 +1,81 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+import { useVirtualizer } from "@tanstack/react-virtual";
+import { streamItemKey, streamPlatform, type StreamItem as FeedItem } from "../../lib/streams-data";
+import { getPlatform, type ColumnDef as BaseColumnDef } from "../../lib/platforms";
+import { FeedCard } from "./card";
+
+export type ColumnDef = BaseColumnDef & { items: FeedItem[]; platform?: import("../../lib/platforms").Platform };
+
+export function StreamColumn({
+  column,
+  flatStartIndex,
+  selectedFlat,
+  onSelectFlat,
+  onRepost,
+  onQuote,
+}: {
+  column: ColumnDef;
+  flatStartIndex: number;
+  selectedFlat: number;
+  onSelectFlat: (i: number) => void;
+  onRepost: (item: FeedItem, platform: import("../../lib/platforms").Platform) => void;
+  onQuote: (item: FeedItem, platform: import("../../lib/platforms").Platform) => void;
+}): React.ReactElement {
+  const parentRef = useRef<HTMLDivElement>(null);
+  const platform = column.platform ?? getPlatform(column.platformId);
+  const virtualizer = useVirtualizer({
+    count: column.items.length,
+    getScrollElement: () => parentRef.current,
+    estimateSize: () => 110,
+    overscan: 8,
+  });
+
+  useEffect(() => {
+    const local = selectedFlat - flatStartIndex;
+    if (local >= 0 && local < column.items.length) {
+      virtualizer.scrollToIndex(local, { align: "auto" });
+    }
+  }, [selectedFlat, flatStartIndex, column.items.length, virtualizer]);
+
+  return (
+    <section className="flex h-full min-w-0 flex-1 flex-col border-r border-border-subtle last:border-r-0">
+      <header className="flex shrink-0 items-center justify-between border-b border-border-subtle bg-surface px-3 py-2">
+        <div className="flex items-center gap-2">
+          <span className="text-sm font-medium">{column.title}</span>
+          <span className="rounded-full bg-surface-2 px-1.5 py-0.5 text-2xs text-text-faint">{column.key === "all" ? "All accounts" : platform.displayName}</span>
+        </div>
+        <span className="text-2xs text-text-faint">{column.staleness}</span>
+      </header>
+      {!platform.capabilities.amplifyRepost && !platform.capabilities.amplifyShare && <div className="border-b border-border-subtle px-3 py-1.5 text-2xs text-text-faint">Quote with attribution is available when this account can publish text.</div>}
+      {column.items.length === 0 && <p className="p-4 text-sm text-text-faint">{column.staleness === "Waiting for feed" ? "Waiting for the first successful poll." : "This feed has no posts yet."}</p>}
+      <div ref={parentRef} className="min-h-0 flex-1 overflow-y-auto scrollbar-thin">
+        <div style={{ height: `${virtualizer.getTotalSize()}px`, position: "relative" }}>
+          {virtualizer.getVirtualItems().map((virtualRow) => {
+            const item = column.items[virtualRow.index];
+            if (item === undefined) return null;
+            const flat = flatStartIndex + virtualRow.index;
+            return (
+              <div
+                key={streamItemKey(item)}
+                data-index={virtualRow.index}
+                ref={virtualizer.measureElement}
+                style={{ position: "absolute", top: 0, left: 0, width: "100%", transform: `translateY(${virtualRow.start}px)` }}
+              >
+                <FeedCard
+                  item={item}
+                  platform={streamPlatform(item)}
+                  selected={flat === selectedFlat}
+                  onSelect={() => onSelectFlat(flat)}
+                  onRepost={() => onRepost(item, streamPlatform(item))}
+                  onQuote={() => onQuote(item, streamPlatform(item))}
+                />
+              </div>
+            );
+          })}
+        </div>
+      </div>
+    </section>
+  );
+}
diff --git a/apps/web/src/components/ui/offline-badge.tsx b/apps/web/src/components/ui/offline-badge.tsx
new file mode 100644
index 0000000..7f21a63
--- /dev/null
+++ b/apps/web/src/components/ui/offline-badge.tsx
@@ -0,0 +1,15 @@
+import type { DataSource } from "../../lib/use-api";
+
+/** Subtle marker that a screen is rendering fixture data because the API is unreachable. */
+export function OfflineBadge({ source }: { source: DataSource }): React.ReactElement | null {
+  if (source !== "sample") return null;
+  return (
+    <span
+      title="The API is unreachable, so this screen shows built-in sample data. Nothing you do here is saved."
+      className="inline-flex items-center gap-1.5 rounded-full border border-border-subtle px-2 py-0.5 text-2xs text-text-faint"
+    >
+      <span className="h-1.5 w-1.5 rounded-full bg-warn" />
+      offline — showing sample data
+    </span>
+  );
+}
diff --git a/apps/web/src/components/ui/primitives.tsx b/apps/web/src/components/ui/primitives.tsx
new file mode 100644
index 0000000..36e6032
--- /dev/null
+++ b/apps/web/src/components/ui/primitives.tsx
@@ -0,0 +1,84 @@
+import type { ButtonHTMLAttributes, ReactNode } from "react";
+
+type Variant = "primary" | "ghost" | "outline" | "danger";
+
+const variants: Record<Variant, string> = {
+  primary: "bg-accent text-white hover:bg-accent-hover",
+  ghost: "text-text-dim hover:bg-surface-2 hover:text-text",
+  outline: "border border-border text-text hover:border-accent hover:text-accent",
+  danger: "bg-danger/10 text-danger border border-danger/30 hover:bg-danger/20",
+};
+
+export function Button({
+  variant = "ghost",
+  size = "md",
+  className = "",
+  children,
+  ...rest
+}: ButtonHTMLAttributes<HTMLButtonElement> & { variant?: Variant; size?: "sm" | "md" }): React.ReactElement {
+  const sizing = size === "sm" ? "px-2 py-1 text-2xs" : "px-3 py-1.5 text-xs";
+  return (
+    <button
+      className={`inline-flex items-center gap-1.5 rounded-md font-medium transition-colors duration-150 disabled:opacity-40 disabled:pointer-events-none ${variants[variant]} ${sizing} ${className}`}
+      {...rest}
+    >
+      {children}
+    </button>
+  );
+}
+
+export function Card({ className = "", children }: { className?: string; children: ReactNode }): React.ReactElement {
+  return <div className={`rounded-lg border border-border-subtle bg-surface ${className}`}>{children}</div>;
+}
+
+export function Badge({
+  tone = "neutral",
+  children,
+}: {
+  tone?: "neutral" | "accent" | "live" | "warn" | "danger";
+  children: ReactNode;
+}): React.ReactElement {
+  const tones: Record<string, string> = {
+    neutral: "bg-surface-2 text-text-dim",
+    accent: "border border-accent/30 bg-accent-dim text-accent",
+    live: "bg-live/15 text-live",
+    warn: "bg-warn/15 text-warn",
+    danger: "bg-danger/15 text-danger",
+  };
+  return (
+    <span className={`inline-flex items-center gap-1 rounded-full px-2 py-0.5 text-2xs font-medium ${tones[tone]}`}>
+      {children}
+    </span>
+  );
+}
+
+export function Input({ className = "", ...rest }: React.InputHTMLAttributes<HTMLInputElement>): React.ReactElement {
+  return (
+    <input
+      className={`w-full rounded-md border border-border bg-surface-2 px-3 py-1.5 text-sm text-text placeholder:text-text-faint focus:border-accent focus:outline-none transition-colors duration-150 ${className}`}
+      {...rest}
+    />
+  );
+}
+
+/**
+ * Initials avatar on a deterministic warm hue. The hash maps into the accent
+ * family (0–60° in oklch hue terms ≈ red → orange → amber) so every avatar
+ * reads as part of the palette; only lightness/chroma wobble per identity,
+ * which keeps distinct people distinguishable without breaking the scheme.
+ */
+export function Avatar({ handle }: { handle: string }): React.ReactElement {
+  const initials = handle.replace(/@.*/, "").slice(0, 2).toUpperCase();
+  const hash = [...handle].reduce((a, c) => a + c.charCodeAt(0), 0);
+  const hue = hash % 60; // 0–60: red through amber, matching the accent family
+  const lightness = 0.42 + ((hash % 7) * 0.025); // 0.42–0.57
+  const chroma = 0.13 + ((hash % 5) * 0.015); // 0.13–0.19
+  return (
+    <div
+      className="flex h-8 w-8 shrink-0 items-center justify-center rounded-full text-2xs font-semibold text-white"
+      style={{ background: `oklch(${lightness.toFixed(3)} ${chroma.toFixed(3)} ${hue})` }}
+    >
+      {initials}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/video/delete-video-modal.tsx b/apps/web/src/components/video/delete-video-modal.tsx
new file mode 100644
index 0000000..8a4ece5
--- /dev/null
+++ b/apps/web/src/components/video/delete-video-modal.tsx
@@ -0,0 +1,41 @@
+import { Button } from "../ui/primitives";
+import { formatBytes } from "./format";
+import type { VideoAssetDto } from "../../lib/video-types";
+
+/** Confirm modal before DELETE /video/:id (media.manage-gated upstream). */
+export function DeleteVideoModal({
+  asset,
+  busy,
+  onCancel,
+  onConfirm,
+}: {
+  asset: VideoAssetDto;
+  busy: boolean;
+  onCancel: () => void;
+  onConfirm: () => void;
+}): React.ReactElement {
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/60" onClick={onCancel}>
+      <div
+        className="w-[440px] max-w-[90vw] rounded-lg border border-border bg-surface p-4 shadow-2xl"
+        onClick={(e: React.MouseEvent) => e.stopPropagation()}
+      >
+        <h2 className="text-sm font-semibold">Delete video</h2>
+        <p className="mt-2 text-xs leading-relaxed text-text-dim">
+          This removes the asset, its processing jobs, and its probe metadata from the workspace library.
+          Published posts that reference it are not deleted.
+        </p>
+        <p className="mt-3 truncate font-mono text-2xs text-text-faint" title={asset.storageKey}>
+          {asset.storageKey}
+        </p>
+        <p className="mt-1 text-2xs text-text-faint">{formatBytes(asset.sizeBytes)}</p>
+        <div className="mt-4 flex justify-end gap-2">
+          <Button variant="ghost" onClick={onCancel}>Cancel</Button>
+          <Button variant="danger" disabled={busy} onClick={onConfirm}>
+            {busy ? "Deleting…" : "Delete video"}
+          </Button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/web/src/components/video/format.ts b/apps/web/src/components/video/format.ts
new file mode 100644
index 0000000..cb563ad
--- /dev/null
+++ b/apps/web/src/components/video/format.ts
@@ -0,0 +1,39 @@
+/** Display formatters for the video library — pure, no React. */
+
+export function formatDuration(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const hours = Math.floor(total / 3600);
+  const minutes = Math.floor((total % 3600) / 60);
+  const seconds = total % 60;
+  const mm = hours > 0 ? String(minutes).padStart(2, "0") : String(minutes);
+  const ss = String(seconds).padStart(2, "0");
+  return hours > 0 ? `${hours}:${mm}:${ss}` : `${mm}:${ss}`;
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  const text = value >= 100 ? String(Math.round(value)) : value.toFixed(1);
+  return `${text} ${units[unit] ?? "KB"}`;
+}
+
+export function formatBitrate(bitsPerSecond: number): string {
+  if (bitsPerSecond >= 1_000_000) return `${(bitsPerSecond / 1_000_000).toFixed(1)} Mbps`;
+  return `${Math.max(1, Math.round(bitsPerSecond / 1000))} kbps`;
+}
+
+export function fpsLabel(frameRate: number): string {
+  return `${Number.isInteger(frameRate) ? frameRate.toFixed(0) : frameRate.toFixed(2)} fps`;
+}
+
+/** The object-storage key's final path segment — the closest thing to a filename. */
+export function fileNameOf(storageKey: string): string {
+  const parts = storageKey.split("/");
+  return parts[parts.length - 1] ?? storageKey;
+}
diff --git a/apps/web/src/components/video/status-chip.tsx b/apps/web/src/components/video/status-chip.tsx
new file mode 100644
index 0000000..2916e70
--- /dev/null
+++ b/apps/web/src/components/video/status-chip.tsx
@@ -0,0 +1,26 @@
+import { Badge } from "../ui/primitives";
+import type { VideoProcessingState } from "../../lib/video-types";
+
+/**
+ * Chip for video_processing_jobs.state. Labels are the actual job states the
+ * API emits (queued/probing/transcoding/complete/failed) — never a friendlier
+ * invented word, so what the UI says always matches what the pipeline says.
+ */
+
+const TONES: Record<VideoProcessingState, "accent" | "live" | "warn" | "danger"> = {
+  queued: "warn",
+  probing: "accent",
+  transcoding: "accent",
+  complete: "live",
+  failed: "danger",
+};
+
+export function StatusChip({ state }: { state: VideoProcessingState }): React.ReactElement {
+  const inFlight = state === "queued" || state === "probing" || state === "transcoding";
+  return (
+    <Badge tone={TONES[state]}>
+      {inFlight && <span className="h-1.5 w-1.5 animate-pulse rounded-full bg-current" />}
+      {state}
+    </Badge>
+  );
+}
diff --git a/apps/web/src/components/video/upload-dropzone.tsx b/apps/web/src/components/video/upload-dropzone.tsx
new file mode 100644
index 0000000..f1fc688
--- /dev/null
+++ b/apps/web/src/components/video/upload-dropzone.tsx
@@ -0,0 +1,168 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Button } from "../ui/primitives";
+import { Loading } from "../brand/loading";
+import { apiUploadFile, errorMessage } from "../../lib/api-client";
+import type { VideoStatusDto } from "../../lib/video-types";
+import { formatBytes } from "./format";
+
+/**
+ * Drag-drop + file-picker target for POST /video/upload.
+ * The API stores encrypted bytes, mints the content-addressed key, and probes
+ * the stored object before responding. Progress measures the actual transfer.
+ */
+
+const MAX_UPLOAD_BYTES = 100 * 1024 * 1024;
+
+export interface UploadDraftInfo {
+  key: string;
+  name: string;
+  detail: string;
+}
+
+interface Props {
+  live: boolean;
+  canUpload: boolean;
+  onStarted: (draft: UploadDraftInfo) => void;
+  onSettled: (key: string) => void;
+  onUploaded: (status: VideoStatusDto) => void;
+}
+
+export function UploadDropzone({ live, canUpload, onStarted, onSettled, onUploaded }: Props): React.ReactElement {
+  const inputRef = useRef<HTMLInputElement>(null);
+  const busyRef = useRef(false);
+  const [dragging, setDragging] = useState(false);
+  const [uploading, setUploading] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [progress, setProgress] = useState(0);
+
+  const register = useCallback(
+    async (file: File): Promise<void> => {
+      if (!live || !canUpload || busyRef.current) return;
+      const draft: UploadDraftInfo = { key: `${file.name}:${file.size}:${file.lastModified}`, name: file.name, detail: formatBytes(file.size) };
+      if (!file.type.startsWith("video/")) {
+        setError(`${file.name}: not a video file (${file.type === "" ? "unknown type" : file.type})`);
+        return;
+      }
+      if (file.size === 0 || file.size > MAX_UPLOAD_BYTES) {
+        setError("Choose a non-empty video up to 100 MiB.");
+        return;
+      }
+      setError(null);
+      busyRef.current = true;
+      setProgress(0);
+      setUploading(`${file.name} (${formatBytes(file.size)})`);
+      onStarted(draft);
+      try {
+        const result = await apiUploadFile<VideoStatusDto>("/video/upload", file, setProgress);
+        onUploaded(result);
+        if (result.processingJob.state === "failed") setError(result.processingJob.error ?? "Video probing failed.");
+      } catch (err) {
+        setError(errorMessage(err));
+      } finally {
+        onSettled(draft.key);
+        setUploading(null);
+        busyRef.current = false;
+      }
+    },
+    [live, canUpload, onStarted, onSettled, onUploaded],
+  );
+
+  // Paste a video file straight into the library.
+  useEffect(() => {
+    if (!live) return;
+    const onPaste = (e: ClipboardEvent): void => {
+      const file = Array.from(e.clipboardData?.files ?? []).find((f) => f.type.startsWith("video/"));
+      if (file !== undefined) void register(file);
+    };
+    window.addEventListener("paste", onPaste);
+    return () => window.removeEventListener("paste", onPaste);
+  }, [live, register]);
+
+  const disabled = !live || !canUpload || uploading !== null;
+  const hint = !live
+    ? "Offline — connect to the API to upload."
+    : !canUpload
+      ? "Uploading needs the media.manage permission."
+      : "Drop a video file, paste one, or browse. Up to 100 MiB; stored encrypted and checked before it is ready.";
+
+  return (
+    <div className="mb-4">
+      <div
+        role="button"
+        tabIndex={disabled ? -1 : 0}
+        aria-disabled={disabled}
+        aria-label="Upload a video"
+        onClick={() => {
+          if (!disabled) inputRef.current?.click();
+        }}
+        onKeyDown={(e) => {
+          if (disabled) return;
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            inputRef.current?.click();
+          }
+        }}
+        onDragOver={(e) => {
+          e.preventDefault();
+          if (!disabled) setDragging(true);
+        }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={(e) => {
+          e.preventDefault();
+          setDragging(false);
+          if (disabled) return;
+          const file = e.dataTransfer.files[0];
+          if (file !== undefined) void register(file);
+        }}
+        className={`flex flex-col items-center justify-center gap-2 rounded-lg border border-dashed px-4 py-6 text-center transition-colors duration-150 ${
+          disabled
+            ? "cursor-not-allowed border-border-subtle opacity-50"
+            : dragging
+              ? "cursor-pointer border-accent bg-accent-dim"
+              : "cursor-pointer border-border hover:border-accent hover:bg-surface-2"
+        }`}
+      >
+        {uploading !== null ? (
+          <div className="w-full max-w-md space-y-2">
+            <span className="inline-flex items-center gap-2 text-xs text-text-dim">
+              <Loading size={14} label={progress < 100 ? "Uploading" : "Processing"} />
+              {progress < 100 ? `Uploading ${progress}%` : "Upload sent — storing and probing…"} {uploading}
+            </span>
+            <progress className="h-2 w-full" aria-label="File upload progress" value={progress} max={100} />
+          </div>
+        ) : (
+          <>
+            <span className="text-sm text-text">Drop a video here</span>
+            <span className="text-2xs leading-relaxed text-text-faint">{hint}</span>
+            {!disabled && (
+              <Button
+                size="sm"
+                variant="outline"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  inputRef.current?.click();
+                }}
+              >
+                Browse files
+              </Button>
+            )}
+          </>
+        )}
+        <input
+          ref={inputRef}
+          type="file"
+          accept="video/mp4,video/webm,video/quicktime"
+          className="hidden"
+          onChange={(e) => {
+            const file = e.target.files?.[0];
+            e.target.value = "";
+            if (file !== undefined) void register(file);
+          }}
+        />
+      </div>
+      {error !== null && <p className="mt-2 text-xs text-danger">{error}</p>}
+    </div>
+  );
+}
diff --git a/apps/web/src/components/video/video-card.tsx b/apps/web/src/components/video/video-card.tsx
new file mode 100644
index 0000000..b63a999
--- /dev/null
+++ b/apps/web/src/components/video/video-card.tsx
@@ -0,0 +1,96 @@
+import { Badge, Card } from "../ui/primitives";
+import { CircleA } from "../brand/logo";
+import { Loading } from "../brand/loading";
+import type { VideoLibraryEntryDto } from "../../lib/video-types";
+import { formatBytes, formatDuration, fileNameOf } from "./format";
+import { StatusChip } from "./status-chip";
+
+/**
+ * Library card. The poster area is the quiet circle-A mark (no thumbnail is
+ * stored yet — video_assets.thumbnail_key exists but nothing populates it);
+ * probe fields render when present and read as em-dashes before probing.
+ */
+
+export function VideoCard({
+  entry,
+  active,
+  onOpen,
+  onDelete,
+}: {
+  entry: VideoLibraryEntryDto;
+  active: boolean;
+  onOpen: () => void;
+  onDelete: () => void;
+}): React.ReactElement {
+  const { videoAsset: a, processingState, publications } = entry;
+  const dims = a.width !== undefined && a.height !== undefined ? `${a.width}×${a.height}` : "—";
+  return (
+    <Card
+      className={`cursor-pointer p-3 transition-colors duration-150 hover:border-accent/40 ${
+        active ? "border-accent/50 ring-1 ring-accent/30" : ""
+      }`}
+    >
+      <div
+        role="button"
+        tabIndex={0}
+        onClick={onOpen}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" || e.key === " ") {
+            e.preventDefault();
+            onOpen();
+          }
+        }}
+        className="relative flex h-24 cursor-pointer items-center justify-center rounded-md border border-border-subtle bg-bg transition-colors duration-150 hover:border-accent/40"
+      >
+        <CircleA size={44} className="text-accent/25" />
+        {a.durationMs !== undefined && (
+          <span className="absolute bottom-1.5 right-1.5 rounded bg-black/70 px-1.5 py-0.5 font-mono text-2xs text-white">
+            {formatDuration(a.durationMs)}
+          </span>
+        )}
+      </div>
+      <div className="mt-2 flex items-start justify-between gap-2">
+        <div className="min-w-0">
+          <div className="truncate text-xs font-medium" title={fileNameOf(a.storageKey)}>
+            {fileNameOf(a.storageKey)}
+          </div>
+          <div className="mt-0.5 text-2xs text-text-faint">
+            {dims} · {formatBytes(a.sizeBytes)} · {publications.length > 0 ? `${publications.length} publication${publications.length === 1 ? "" : "s"}` : "unpublished"}
+          </div>
+        </div>
+        <StatusChip state={processingState} />
+      </div>
+      <div className="mt-2 flex items-center justify-between border-t border-border-subtle pt-2">
+        <span className="truncate font-mono text-2xs text-text-faint">{a.mimeType}</span>
+        <button
+          type="button"
+          className="text-2xs text-text-faint transition-colors duration-150 hover:text-danger"
+          onClick={(e) => {
+            e.stopPropagation();
+            onDelete();
+          }}
+        >
+          Delete
+        </button>
+      </div>
+    </Card>
+  );
+}
+
+/** Optimistic card while a pick is being hashed and registered. */
+export function UploadingCard({ name, detail }: { name: string; detail: string }): React.ReactElement {
+  return (
+    <Card className="border-dashed p-3 opacity-70">
+      <div className="flex h-24 items-center justify-center rounded-md border border-border-subtle bg-bg">
+        <Loading size={22} label="Uploading" />
+      </div>
+      <div className="mt-2 flex items-start justify-between gap-2">
+        <div className="min-w-0">
+          <div className="truncate text-xs font-medium text-text-dim" title={name}>{name}</div>
+          <div className="mt-0.5 text-2xs text-text-faint">{detail}</div>
+        </div>
+        <Badge tone="warn">uploading…</Badge>
+      </div>
+    </Card>
+  );
+}
diff --git a/apps/web/src/components/video/video-detail-drawer.tsx b/apps/web/src/components/video/video-detail-drawer.tsx
new file mode 100644
index 0000000..af788c7
--- /dev/null
+++ b/apps/web/src/components/video/video-detail-drawer.tsx
@@ -0,0 +1,195 @@
+"use client";
+
+import { useEffect, useState } from "react";
+import { Badge, Button } from "../ui/primitives";
+import { api, errorMessage } from "../../lib/api-client";
+import type { VideoLibraryEntryDto, VideoProcessingState, VideoStatusDto } from "../../lib/video-types";
+import { fileNameOf, formatBitrate, formatBytes, formatDuration, fpsLabel } from "./format";
+import { StatusChip } from "./status-chip";
+
+/**
+ * Right-hand detail drawer: probe metadata, derived bitrate, the processing
+ * job timeline, and where the asset has been published. Live assets poll
+ * GET /video/:id/status while their job is still in flight.
+ */
+
+const PIPELINE: ReadonlyArray<{ state: VideoProcessingState; label: string }> = [
+  { state: "queued", label: "Queued" },
+  { state: "probing", label: "Probing (ffprobe)" },
+  { state: "transcoding", label: "Transcoding" },
+  { state: "complete", label: "Ready" },
+];
+
+const POLL_MS = 4_000;
+const IN_FLIGHT: VideoProcessingState[] = ["queued", "probing", "transcoding"];
+
+export function VideoDetailDrawer({
+  entry,
+  onClose,
+}: {
+  entry: VideoLibraryEntryDto;
+  onClose: () => void;
+}): React.ReactElement {
+  const [status, setStatus] = useState<VideoStatusDto | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const asset = entry.videoAsset;
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent): void => {
+      if (e.key === "Escape") onClose();
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [onClose]);
+
+  // Poll the job while it is in flight; the library page refreshes from this too.
+  const inFlight = IN_FLIGHT.includes(status?.processingJob.state ?? entry.processingState);
+  useEffect(() => {
+    let cancelled = false;
+    const fetchStatus = (): void => {
+      api
+        .get<VideoStatusDto>(`/video/${asset.id}/status`)
+        .then((next) => {
+          if (!cancelled) {
+            setStatus(next);
+            setError(null);
+          }
+        })
+        .catch((err: unknown) => {
+          if (!cancelled) setError(errorMessage(err));
+        });
+    };
+    fetchStatus();
+    const timer = inFlight ? setInterval(fetchStatus, POLL_MS) : undefined;
+    return () => {
+      cancelled = true;
+      if (timer !== undefined) clearInterval(timer);
+    };
+  }, [asset.id, inFlight]);
+
+  const job = status?.processingJob;
+  const state = job?.state ?? entry.processingState;
+  const duration = status?.videoAsset.durationMs ?? asset.durationMs;
+  const width = status?.videoAsset.width ?? asset.width;
+  const height = status?.videoAsset.height ?? asset.height;
+  const codec = status?.videoAsset.codec ?? asset.codec;
+  const audioCodec = status?.videoAsset.audioCodec ?? asset.audioCodec;
+  const frameRate = status?.videoAsset.frameRate ?? asset.frameRate;
+  const sizeBytes = status?.videoAsset.sizeBytes ?? asset.sizeBytes;
+  const bitrate = duration !== undefined && duration > 0 ? (sizeBytes * 8) / (duration / 1000) : undefined;
+  const reachedIndex = PIPELINE.findIndex((step) => step.state === state);
+
+  return (
+    <div className="fixed inset-0 z-40 flex justify-end bg-black/60" onClick={onClose}>
+      <aside
+        className="flex h-full w-[440px] max-w-[92vw] flex-col overflow-y-auto border-l border-border bg-surface scrollbar-thin"
+        onClick={(e: React.MouseEvent) => e.stopPropagation()}
+      >
+        <header className="sticky top-0 z-10 flex items-start justify-between gap-3 border-b border-border-subtle bg-surface px-4 py-3">
+          <div className="min-w-0">
+            <div className="flex items-center gap-2">
+              <h2 className="truncate text-sm font-semibold" title={fileNameOf(asset.storageKey)}>
+                {fileNameOf(asset.storageKey)}
+              </h2>
+              <StatusChip state={state} />
+            </div>
+            <p className="mt-1 truncate font-mono text-2xs text-text-faint" title={asset.storageKey}>
+              {asset.storageKey}
+            </p>
+          </div>
+          <Button size="sm" variant="ghost" onClick={onClose}>Close (esc)</Button>
+        </header>
+
+        <div className="space-y-4 p-4">
+          {error !== null && <p className="text-xs text-danger">{error}</p>}
+
+          {job !== undefined && (
+            <section>
+              <h3 className="mb-2 text-2xs font-medium uppercase tracking-wide text-text-faint">Processing</h3>
+              <ol className="space-y-1.5">
+                {PIPELINE.map((step, i) => {
+                  const done = state === "complete" || i < reachedIndex;
+                  const current = step.state === state;
+                  return (
+                    <li
+                      key={step.state}
+                      className={`flex items-center gap-2 rounded-md border px-2.5 py-1.5 text-xs ${
+                        current
+                          ? "border-accent/40 bg-accent-dim text-accent"
+                          : done
+                            ? "border-border-subtle bg-surface-2 text-text-dim"
+                            : "border-border-subtle text-text-faint"
+                      }`}
+                    >
+                      <span className={`h-1.5 w-1.5 shrink-0 rounded-full ${done || current ? "bg-current" : "bg-border"}`} />
+                      {step.label}
+                      {current && job.progressPercent !== undefined && (
+                        <span className="ml-auto font-mono text-2xs">{job.progressPercent}%</span>
+                      )}
+                    </li>
+                  );
+                })}
+                {state === "failed" && (
+                  <li className="rounded-md border border-danger/30 bg-danger/10 px-2.5 py-1.5 text-xs text-danger">
+                    <span className="font-medium">failed</span>
+                    {job.error !== undefined && <span className="ml-1 font-mono text-2xs">{job.error}</span>}
+                  </li>
+                )}
+              </ol>
+              {job.processingNote !== undefined && <p className="mt-2 text-2xs text-text-faint">{job.processingNote}</p>}
+            </section>
+          )}
+
+          <section>
+            <h3 className="mb-2 text-2xs font-medium uppercase tracking-wide text-text-faint">Probe metadata</h3>
+            <dl className="space-y-1 text-xs">
+              <Row label="MIME type" value={asset.mimeType} />
+              <Row label="Size" value={formatBytes(sizeBytes)} />
+              <Row label="Duration" value={duration !== undefined ? formatDuration(duration) : "—"} />
+              <Row label="Resolution" value={width !== undefined && height !== undefined ? `${width} × ${height}` : "—"} />
+              <Row label="Frame rate" value={frameRate !== undefined ? fpsLabel(frameRate) : "—"} />
+              <Row label="Video codec" value={codec ?? "—"} />
+              <Row label="Audio codec" value={audioCodec ?? "—"} />
+              <Row label="Bitrate (derived)" value={bitrate !== undefined ? formatBitrate(bitrate) : "—"} />
+            </dl>
+            {duration === undefined && (
+              <p className="mt-2 text-2xs leading-relaxed text-text-faint">
+                {state === "failed" ? "The probe failed; see the processing error above." : "Metadata fills in after the stored video is probed."}
+              </p>
+            )}
+          </section>
+
+          <section>
+            <h3 className="mb-2 text-2xs font-medium uppercase tracking-wide text-text-faint">Publications</h3>
+            {entry.publications.length === 0 ? (
+              <p className="text-xs text-text-faint">Not published anywhere yet.</p>
+            ) : (
+              <ul className="space-y-1.5">
+                {entry.publications.map((p) => (
+                  <li key={`${p.connectionId}:${p.remoteId}`} className="flex items-center gap-2 rounded-md border border-border-subtle bg-surface-2 px-2.5 py-1.5 text-xs">
+                    <Badge tone="accent">{p.platform}</Badge>
+                    <span className="font-mono text-2xs text-text-faint">{p.remoteId}</span>
+                    <span className="ml-auto text-2xs text-text-faint">{new Date(p.publishedAt).toLocaleString()}</span>
+                  </li>
+                ))}
+              </ul>
+            )}
+          </section>
+
+          <p className="text-2xs leading-relaxed text-text-faint">
+            Asset <span className="font-mono">{asset.id}</span>
+          </p>
+        </div>
+      </aside>
+    </div>
+  );
+}
+
+function Row({ label, value }: { label: string; value: string }): React.ReactElement {
+  return (
+    <div className="flex items-baseline justify-between gap-3">
+      <dt className="text-text-faint">{label}</dt>
+      <dd className="truncate font-mono text-text-dim">{value}</dd>
+    </div>
+  );
+}
diff --git a/apps/web/src/hooks/use-is-mobile.ts b/apps/web/src/hooks/use-is-mobile.ts
new file mode 100644
index 0000000..ce5dc02
--- /dev/null
+++ b/apps/web/src/hooks/use-is-mobile.ts
@@ -0,0 +1,15 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+
+const QUERY = "(max-width: 1023px)";
+
+function subscribe(onChange: () => void): () => void {
+  const media = window.matchMedia(QUERY);
+  media.addEventListener("change", onChange);
+  return () => media.removeEventListener("change", onChange);
+}
+
+export function useIsMobile(): boolean {
+  return useSyncExternalStore(subscribe, () => window.matchMedia(QUERY).matches, () => false);
+}
diff --git a/apps/web/src/lib/amplify.ts b/apps/web/src/lib/amplify.ts
new file mode 100644
index 0000000..9339e7d
--- /dev/null
+++ b/apps/web/src/lib/amplify.ts
@@ -0,0 +1,11 @@
+import type { Platform } from "./platforms";
+
+export interface NativeAmplifyAction { kind: "repost" | "quote" | "share"; label: string; }
+
+export function nativeAmplifyActions(platform: Platform): NativeAmplifyAction[] {
+  return [
+    ...(platform.capabilities.amplifyRepost ? [{ kind: "repost" as const, label: platform.amplifyLabels.repost ?? "Repost" }] : []),
+    ...(platform.capabilities.amplifyQuote ? [{ kind: "quote" as const, label: platform.amplifyLabels.quote ?? "Quote" }] : []),
+    ...(platform.capabilities.amplifyShare ? [{ kind: "share" as const, label: platform.amplifyLabels.share ?? "Share" }] : []),
+  ];
+}
diff --git a/apps/web/src/lib/api-client.ts b/apps/web/src/lib/api-client.ts
new file mode 100644
index 0000000..599557f
--- /dev/null
+++ b/apps/web/src/lib/api-client.ts
@@ -0,0 +1,188 @@
+import { getSessionToken, setSessionToken } from "./session-token";
+
+/**
+ * The single path from the web app to the API. Every call goes through
+ * `apiFetch` so auth, error shape, and the offline signal stay uniform.
+ */
+
+export const API_URL = (process.env.NEXT_PUBLIC_API_URL ?? "http://localhost:3000").replace(/\/$/, "");
+
+/** The API answered with a non-2xx status. */
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+    readonly body: unknown,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+/** The API could not be reached at all (server down, DNS, CORS). Screens fall back to sample data. */
+export class ApiUnreachableError extends Error {
+  constructor(override readonly cause: unknown) {
+    super("API unreachable");
+    this.name = "ApiUnreachableError";
+  }
+}
+
+type QueryValue = string | number | undefined | null;
+
+export interface ApiRequestOptions {
+  method?: "GET" | "POST" | "PATCH" | "DELETE";
+  body?: unknown;
+  query?: Record<string, QueryValue>;
+  signal?: AbortSignal;
+  /** Default true. Auth endpoints turn this off so a bad password shows an error instead of navigating away. */
+  redirectOn401?: boolean;
+}
+
+export const ONBOARDING_PATH = "/onboarding";
+let reissuePromise: Promise<string> | null = null;
+
+function buildUrl(path: string, query: Record<string, QueryValue> | undefined): string {
+  const url = new URL(`${API_URL}${path.startsWith("/") ? path : `/${path}`}`);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== undefined && value !== null && value !== "") url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
+function messageFrom(body: unknown, fallback: string): string {
+  if (typeof body === "object" && body !== null && "message" in body) {
+    const message = (body as { message: unknown }).message;
+    if (typeof message === "string") return message;
+    if (Array.isArray(message)) return message.filter((m): m is string => typeof m === "string").join("; ");
+  }
+  return fallback;
+}
+
+/** Multipart bytes with browser upload progress; shares the API's auth/error rules. */
+export async function apiUploadFile<T>(path: string, file: File, onProgress: (percent: number) => void): Promise<T> {
+  const send = async (retried: boolean): Promise<T> => {
+    const token = getSessionToken();
+    const response = await new Promise<{ status: number; text: string }>((resolve, reject) => {
+      const xhr = new XMLHttpRequest();
+      xhr.open("POST", buildUrl(path, undefined));
+      xhr.withCredentials = true;
+      xhr.timeout = 120_000;
+      if (token !== null) xhr.setRequestHeader("Authorization", `Bearer ${token}`);
+      xhr.upload.onprogress = (event) => {
+        if (event.lengthComputable) onProgress(Math.floor((event.loaded / event.total) * 100));
+      };
+      xhr.upload.onload = () => onProgress(100);
+      xhr.onload = () => resolve({ status: xhr.status, text: xhr.responseText });
+      xhr.onerror = () => reject(new ApiUnreachableError(new Error("Upload network error")));
+      xhr.ontimeout = () => reject(new Error("Upload timed out; check the video library before retrying."));
+      xhr.onabort = () => reject(new Error("Upload cancelled"));
+      const form = new FormData();
+      form.append("file", file);
+      xhr.send(form);
+    });
+    let body: unknown = null;
+    if (response.text !== "") {
+      try { body = JSON.parse(response.text) as unknown; } catch { body = response.text; }
+    }
+    if (response.status >= 200 && response.status < 300) return body as T;
+    if (response.status === 401 && !retried && token !== null && messageFrom(body, "").includes("authorization epoch stale")) {
+      let reissued = false;
+      try {
+        await reissueSession();
+        reissued = true;
+      } catch { /* Ordinary 401 handling below. */ }
+      if (reissued) { onProgress(0); return send(true); }
+    }
+    if (response.status === 401) redirectToSession();
+    throw new ApiError(response.status, messageFrom(body, `HTTP ${response.status}`), body);
+  };
+  return send(false);
+}
+
+export function reissueSession(): Promise<string> {
+  if (reissuePromise === null) {
+    reissuePromise = apiFetch<{ token: string }>("/auth/reissue", { method: "POST", redirectOn401: false })
+      .then((result) => {
+        setSessionToken(result.token);
+        return result.token;
+      }).finally(() => { reissuePromise = null; });
+  }
+  return reissuePromise;
+}
+
+function redirectToSession(): void {
+  setSessionToken(null);
+  if (typeof window !== "undefined" && window.location.pathname !== ONBOARDING_PATH) {
+    window.location.assign(`${ONBOARDING_PATH}?reason=session`);
+  }
+}
+
+export async function apiFetch<T>(path: string, options: ApiRequestOptions = {}): Promise<T> {
+  return fetchWithEpochRetry<T>(path, options, false);
+}
+
+async function fetchWithEpochRetry<T>(path: string, options: ApiRequestOptions, retried: boolean): Promise<T> {
+  const headers: Record<string, string> = {};
+  const token = getSessionToken();
+  if (token !== null) headers.Authorization = `Bearer ${token}`;
+  if (options.body !== undefined) headers["Content-Type"] = "application/json";
+
+  let response: Response;
+  try {
+    response = await fetch(buildUrl(path, options.query), {
+      method: options.method ?? "GET",
+      credentials: "include",
+      headers,
+      body: options.body === undefined ? undefined : JSON.stringify(options.body),
+      signal: options.signal,
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === "AbortError") throw err;
+    throw new ApiUnreachableError(err);
+  }
+
+  const text = await response.text();
+  let body: unknown = null;
+  if (text !== "") {
+    try {
+      body = JSON.parse(text);
+    } catch {
+      body = text;
+    }
+  }
+
+  if (!response.ok) {
+    if (response.status === 401 && !retried && token !== null && path !== "/auth/reissue" &&
+        messageFrom(body, "").includes("authorization epoch stale")) {
+      let reissued = false;
+      try {
+        await reissueSession();
+        reissued = true;
+      } catch {
+        // A revoked or expired session follows the ordinary 401 path below.
+      }
+      if (reissued) return fetchWithEpochRetry<T>(path, options, true);
+    }
+    if (response.status === 401 && (options.redirectOn401 ?? true)) {
+      redirectToSession();
+    }
+    throw new ApiError(response.status, messageFrom(body, `HTTP ${response.status}`), body);
+  }
+  return body as T;
+}
+
+export const api = {
+  get: <T>(path: string, query?: Record<string, QueryValue>, signal?: AbortSignal): Promise<T> =>
+    apiFetch<T>(path, { query, signal }),
+  post: <T>(path: string, body?: unknown, options: Omit<ApiRequestOptions, "method" | "body"> = {}): Promise<T> =>
+    apiFetch<T>(path, { ...options, method: "POST", body: body ?? {} }),
+  patch: <T>(path: string, body: unknown): Promise<T> => apiFetch<T>(path, { method: "PATCH", body }),
+  del: <T>(path: string): Promise<T> => apiFetch<T>(path, { method: "DELETE" }),
+};
+
+export function errorMessage(err: unknown): string {
+  if (err instanceof ApiUnreachableError) return "API unreachable — check that the API server is running.";
+  if (err instanceof ApiError) return err.message;
+  if (err instanceof Error) return err.message;
+  return "Unexpected error";
+}
diff --git a/apps/web/src/lib/api-types.ts b/apps/web/src/lib/api-types.ts
new file mode 100644
index 0000000..0c782fa
--- /dev/null
+++ b/apps/web/src/lib/api-types.ts
@@ -0,0 +1,140 @@
+/** Response shapes of apps/api — kept in sync by hand with the controllers. */
+
+export interface MeResponse {
+  user: { id: string; username: string; email: string | null; displayName: string };
+  workspace: { id: string; name: string; slug: string };
+  role: string;
+  permissions: string[];
+  expiresAt: number;
+}
+
+export interface AuthResult {
+  token: string;
+  me: MeResponse;
+}
+
+export interface ConnectionSummary {
+  id: string;
+  provider: string;
+  channelId: string;
+  fields: Record<string, unknown>;
+  health: "healthy" | "needs_credentials" | "unavailable";
+  capabilities?: string[];
+  credentialRotatedAt: string | null;
+  recentPublishes: string[];
+  createdAt: string;
+}
+
+export type MemberStatus = "active" | "invited";
+
+export interface Member {
+  id: string;
+  userId: string;
+  username: string;
+  email: string | null;
+  displayName: string;
+  role: string;
+  status: MemberStatus;
+  createdAt: string;
+}
+
+/** Membership mutations bump the workspace authz epoch; `token` is the caller's re-issued session. */
+export interface MemberMutationResult {
+  member: Member | null;
+  token: string | null;
+}
+
+/** Public, unauthenticated preview of a workspace invite link — GET /invites/:token/info. */
+export interface InviteInfo {
+  workspaceName: string;
+  role: string;
+  /** ISO timestamp; the link is dead after this. */
+  expiresAt: string;
+  /** null = unlimited uses. */
+  maxUses: number | null;
+  usedCount: number;
+}
+
+/** Claiming installs a fresh workspace session — same envelope as POST /auth/login. */
+export type InviteClaimResult = AuthResult;
+
+/** Anonymous claimant credentials; ignored when the request carries a valid session. */
+export interface InviteClaimInput {
+  username: string;
+  password: string;
+  displayName?: string;
+  email?: string;
+}
+
+export type InviteLinkStatus = "active" | "expired" | "revoked" | "exhausted";
+
+/** Admin view of a workspace invite link. `token`/`url` are present only on the 201 create response. */
+export interface InviteLink {
+  id: string;
+  role: string;
+  createdAt: string;
+  expiresAt: string;
+  maxUses: number | null;
+  useCount: number;
+  revokedAt: string | null;
+  status: InviteLinkStatus;
+  createdByUserId: string;
+  token?: string;
+  url?: string;
+}
+
+export interface InviteLinkCreateInput {
+  role: string;
+  expiresInHours: number;
+  maxUses?: number;
+}
+
+
+export interface AuditEntryDto {
+  id: string;
+  seq: string;
+  at: string;
+  actorUserId: string | null;
+  actorEmail: string | null;
+  actorRole: string | null;
+  action: string;
+  targetType: string;
+  targetId: string;
+  diff: Record<string, unknown> | null;
+}
+
+export interface AuditPage {
+  entries: AuditEntryDto[];
+  nextCursor: string | null;
+  facets: { actions: string[]; actors: Array<{ id: string | null; email: string | null }> };
+}
+
+export type DraftState = "editing" | "in_review" | "approved" | "rejected" | "scheduled" | "published";
+export type Visibility = "public" | "unlisted" | "private" | "followers" | "provider_default";
+
+export interface DraftPost {
+  text: string;
+  mediaAssetIds: string[];
+  visibility: Visibility;
+  scheduledAt?: string;
+  providerMetadata: Record<string, unknown>;
+}
+
+export interface DraftRecord {
+  id: string;
+  workspaceId: string;
+  authorUserId: string;
+  post: DraftPost;
+  state: DraftState;
+  reviewerUserId?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface ScheduledPublicationRecord {
+  id: string;
+  draftId: string;
+  connectionId: string;
+  publishAt: string;
+  state: "pending" | "in_flight" | "done" | "failed";
+}
diff --git a/apps/web/src/lib/auth-store.ts b/apps/web/src/lib/auth-store.ts
new file mode 100644
index 0000000..964ad8e
--- /dev/null
+++ b/apps/web/src/lib/auth-store.ts
@@ -0,0 +1,168 @@
+"use client";
+
+import { createContext, createElement, useCallback, useContext, useEffect, useMemo, useState, type ReactNode } from "react";
+import { api, apiFetch, ApiError, ApiUnreachableError } from "./api-client";
+import type { AuthResult, InviteClaimInput, InviteClaimResult, MeResponse } from "./api-types";
+import { getSessionToken, onSessionTokenChange, setSessionToken } from "./session-token";
+
+/**
+ * - loading:       verifying a stored token / probing the API
+ * - authenticated: token verified via GET /auth/me
+ * - anonymous:     API reachable, no valid session → the gate sends you to /onboarding
+ * - offline:       API unreachable → dev convenience: screens render sample data
+ */
+export type AuthStatus = "loading" | "authenticated" | "anonymous" | "offline";
+
+export interface RegisterInput {
+  workspaceName: string;
+  username: string;
+  password: string;
+  displayName?: string;
+  email?: string;
+}
+
+export interface AuthContextValue {
+  session: MeResponse | null;
+  status: AuthStatus;
+  isLoading: boolean;
+  offline: boolean;
+  login: (username: string, password: string) => Promise<MeResponse>;
+  register: (input: RegisterInput) => Promise<MeResponse>;
+  /** Claim an invite link with the current session; installs the returned workspace token. */
+  claimInvite: (inviteToken: string) => Promise<MeResponse>;
+  /** Register-or-authenticate inline, then claim; installs the returned workspace token. */
+  claimInviteWithCredentials: (inviteToken: string, input: InviteClaimInput) => Promise<MeResponse>;
+  logout: () => Promise<void>;
+  /** Install a re-issued token (membership mutations bump the authz epoch and return one). */
+  adoptToken: (token: string | null) => void;
+  can: (permission: string) => boolean;
+  /** Re-run session verification (e.g. after the API comes back). */
+  refresh: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+async function probeReachable(): Promise<boolean> {
+  try {
+    await apiFetch<unknown>("/healthz", { redirectOn401: false });
+    return true;
+  } catch (err) {
+    return !(err instanceof ApiUnreachableError);
+  }
+}
+
+export function AuthProvider({ children }: { children: ReactNode }): React.ReactElement {
+  const [session, setSession] = useState<MeResponse | null>(null);
+  const [status, setStatus] = useState<AuthStatus>("loading");
+
+  const verify = useCallback(async (): Promise<void> => {
+    const token = getSessionToken();
+    if (token === null) {
+      setSession(null);
+      setStatus((await probeReachable()) ? "anonymous" : "offline");
+      return;
+    }
+    try {
+      const me = await apiFetch<MeResponse>("/auth/me", { redirectOn401: false });
+      setSession(me);
+      setStatus("authenticated");
+    } catch (err) {
+      if (err instanceof ApiUnreachableError) {
+        setStatus("offline");
+      } else if (err instanceof ApiError && err.status === 401) {
+        setSessionToken(null);
+        setSession(null);
+        setStatus("anonymous");
+      } else {
+        setStatus("offline");
+      }
+    }
+  }, []);
+
+  useEffect(() => {
+    void verify();
+  }, [verify]);
+
+  // The API client clears the token on 401; mirror that into React state.
+  useEffect(
+    () =>
+      onSessionTokenChange((token) => {
+        if (token === null) {
+          setSession(null);
+          setStatus((s) => (s === "offline" ? s : "anonymous"));
+        }
+      }),
+    [],
+  );
+
+  const accept = useCallback((result: AuthResult): MeResponse => {
+    setSessionToken(result.token);
+    setSession(result.me);
+    setStatus("authenticated");
+    return result.me;
+  }, []);
+
+  const login = useCallback(
+    async (username: string, password: string) =>
+      accept(await api.post<AuthResult>("/auth/login", { username, password }, { redirectOn401: false })),
+    [accept],
+  );
+
+  const register = useCallback(
+    async (input: RegisterInput) => accept(await api.post<AuthResult>("/auth/register", input, { redirectOn401: false })),
+    [accept],
+  );
+
+  // Both claim paths return an AuthResult issued in the invite's workspace, so `accept`
+  // installs token + session + status atomically, exactly like login/register.
+  const claimInvite = useCallback(
+    async (inviteToken: string) =>
+      accept(await api.post<InviteClaimResult>(`/invites/${encodeURIComponent(inviteToken)}/claim`, {}, { redirectOn401: false })),
+    [accept],
+  );
+
+  const claimInviteWithCredentials = useCallback(
+    async (inviteToken: string, input: InviteClaimInput) =>
+      accept(await api.post<InviteClaimResult>(`/invites/${encodeURIComponent(inviteToken)}/claim`, input, { redirectOn401: false })),
+    [accept],
+  );
+
+  const logout = useCallback(async () => {
+    await api.post<unknown>("/auth/logout", {}, { redirectOn401: false }).catch(() => undefined);
+    setSessionToken(null);
+    setSession(null);
+    setStatus("anonymous");
+  }, []);
+
+  const adoptToken = useCallback((token: string | null) => {
+    if (token !== null) setSessionToken(token);
+  }, []);
+
+  const can = useCallback((permission: string) => session?.permissions.includes(permission) ?? false, [session]);
+
+  const value = useMemo<AuthContextValue>(
+    () => ({
+      session,
+      status,
+      isLoading: status === "loading",
+      offline: status === "offline",
+      login,
+      register,
+      claimInvite,
+      claimInviteWithCredentials,
+      logout,
+      adoptToken,
+      can,
+      refresh: verify,
+    }),
+    [session, status, login, register, claimInvite, claimInviteWithCredentials, logout, adoptToken, can, verify],
+  );
+
+  return createElement(AuthContext.Provider, { value }, children);
+}
+
+export function useAuth(): AuthContextValue {
+  const ctx = useContext(AuthContext);
+  if (ctx === null) throw new Error("useAuth must be used inside <AuthProvider>");
+  return ctx;
+}
diff --git a/apps/web/src/lib/connections-client.ts b/apps/web/src/lib/connections-client.ts
new file mode 100644
index 0000000..06dd94b
--- /dev/null
+++ b/apps/web/src/lib/connections-client.ts
@@ -0,0 +1,22 @@
+import { setSessionToken } from "./session-token";
+import { api } from "./api-client";
+
+export interface ConnectProvider {
+  id: string;
+  displayName: string;
+  kind: "oauth2-redirect" | "per-instance-oauth2" | "token";
+  enabled: boolean;
+  note?: string;
+  instanceRequired: boolean;
+  targetField?: string;
+  capabilities: string[];
+}
+
+export async function linkBotToken(token: string, channelId: string, connectionId?: string): Promise<{ connected: true }> {
+  const result = await api.post<{ connected: true; token: string }>("/connections/telegram/bot-token", { token, channelId: channelId || undefined, connectionId });
+  setSessionToken(result.token);
+  return result;
+}
+
+/** Shared provider boundary for the bot archive view. */
+export const isBotConnection = (connection: { provider: string }): boolean => connection.provider === "telegram";
diff --git a/apps/web/src/lib/fixtures.ts b/apps/web/src/lib/fixtures.ts
new file mode 100644
index 0000000..13dbe8d
--- /dev/null
+++ b/apps/web/src/lib/fixtures.ts
@@ -0,0 +1,173 @@
+export interface FeedItem {
+  id: number;
+  platform: string;
+  author: string;
+  handle: string;
+  text: string;
+  ageMinutes: number;
+  likes: number;
+  reposts: number;
+  replies: number;
+  hasMedia: boolean;
+}
+
+const AUTHORS: ReadonlyArray<readonly [string, string]> = [
+  ["Ada Lovelace", "@ada"],
+  ["Grace Hopper", "@amazing.grace"],
+  ["Alan Turing", "@turingtest"],
+  ["Katherine Johnson", "@kjohnson"],
+  ["Edsger Dijkstra", "@goesto"],
+  ["Barbara Liskov", "@abl"],
+  ["Donald Knuth", "@taocp"],
+  ["Radia Perlman", "@spanning"],
+  ["Linus Torvalds", "@torvalds"],
+  ["Margaret Hamilton", "@apollo"],
+];
+
+const TEXTS = [
+  "Shipped the tenant isolation suite today — RLS catches what code review misses.",
+  "Hot take: your audit log should be hash-chained from day one, not after the breach.",
+  "The connector manifest pattern is paying off: new platform, zero core changes.",
+  "Reminder: capability-driven UI means no grayed-out lies. If the API can't do it, the button isn't there.",
+  "Spent the morning fighting a trigger that referenced OLD on INSERT. COALESCE(NEW, OLD), friends.",
+  "Our streaming budget math finally balances. Per-host token buckets for the win.",
+  "Quote-posting this because the thread below is exactly why we deferred X.",
+  "The compositor held 8 hours without dropping a frame. Soak test verdict: green.",
+  "Anyone else maintaining three different rate-limit spreadsheets? There has to be a better way.",
+  "FFmpeg filter graphs are write-only code unless you diagram them first. Lesson learned.",
+  "Just watched the auto-director fail over mid-stream and nobody in chat noticed. Perfect.",
+  "OAuth tokens in the vault, passwords never touched. The only sane architecture.",
+  "Drafts → approvals → schedule → publish. The pipeline is boring and I love it.",
+  "New rule: every migration ships with its rollback tested, not just written.",
+  "The mock connectors now drive the entire E2E suite offline. Deterministic tests or bust.",
+  "Every ping of the source monitor is adaptive now. The instances stop noticing us.",
+];
+
+function mulberry32(seed: number): () => number {
+  let a = seed;
+  return () => {
+    a |= 0;
+    a = (a + 0x6d2b79f5) | 0;
+    let t = Math.imul(a ^ (a >>> 15), 1 | a);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function generateFeed(platform: string, count: number, seed: number): FeedItem[] {
+  const rand = mulberry32(seed);
+  const items: FeedItem[] = [];
+  for (let i = 0; i < count; i += 1) {
+    const pair = AUTHORS[Math.floor(rand() * AUTHORS.length)] ?? ["unknown", "@unknown"];
+    const [author, handle] = pair;
+    items.push({
+      id: i,
+      platform,
+      author,
+      handle,
+      text: TEXTS[Math.floor(rand() * TEXTS.length)] ?? "",
+      ageMinutes: Math.floor(rand() * 1440),
+      likes: Math.floor(rand() * 500),
+      reposts: Math.floor(rand() * 120),
+      replies: Math.floor(rand() * 60),
+      hasMedia: rand() > 0.75,
+    });
+  }
+  return items;
+}
+
+export function ageLabel(minutes: number): string {
+  if (minutes < 60) return `${minutes}m`;
+  if (minutes < 1440) return `${Math.floor(minutes / 60)}h`;
+  return `${Math.floor(minutes / 1440)}d`;
+}
+
+export interface Conversation {
+  id: number;
+  platform: string;
+  participant: string;
+  handle: string;
+  preview: string;
+  unread: number;
+  assignee: string | null;
+  lastMinutes: number;
+}
+
+export const CONVERSATIONS: Conversation[] = [
+  { id: 1, platform: "mastodon", participant: "Ada Lovelace", handle: "@ada", preview: "Is the boost button capability-gated per column?", unread: 2, assignee: "GH", lastMinutes: 4 },
+  { id: 2, platform: "instagram", participant: "Grace Hopper", handle: "@amazing.grace", preview: "Story scheduling would be huge for us", unread: 0, assignee: null, lastMinutes: 22 },
+  { id: 3, platform: "facebook", participant: "Alan Turing", handle: "@turingtest", preview: "The page token expires tomorrow — can we rotate?", unread: 1, assignee: "MC", lastMinutes: 65 },
+  { id: 4, platform: "mastodon", participant: "Katherine Johnson", handle: "@kjohnson", preview: "Trajectories confirmed. Launch window 0400.", unread: 0, assignee: null, lastMinutes: 190 },
+];
+
+export interface ThreadMessage {
+  id: number;
+  from: string;
+  mine: boolean;
+  text: string;
+  minutes: number;
+}
+
+export const THREADS: Record<number, ThreadMessage[]> = {
+  1: [
+    { id: 1, from: "@ada", mine: false, text: "Is the boost button capability-gated per column?", minutes: 30 },
+    { id: 2, from: "you", mine: true, text: "Yes — the column renders only what its platform manifest declares.", minutes: 25 },
+    { id: 3, from: "@ada", mine: false, text: "Beautiful. No grayed-out lies?", minutes: 4 },
+  ],
+  2: [
+    { id: 1, from: "@amazing.grace", mine: false, text: "Story scheduling would be huge for us", minutes: 22 },
+  ],
+  3: [
+    { id: 1, from: "@turingtest", mine: false, text: "The page token expires tomorrow — can we rotate?", minutes: 65 },
+  ],
+  4: [
+    { id: 1, from: "@kjohnson", mine: false, text: "Trajectories confirmed. Launch window 0400.", minutes: 190 },
+  ],
+};
+
+export const ROLES = [
+  "Owner", "Admin", "Publisher", "Editor", "Approver", "Analyst", "Moderator", "VideoPublisher", "StreamOperator", "BroadcastOperator",
+];
+
+export interface Member {
+  id: number;
+  name: string;
+  email: string;
+  role: string;
+  status: "active" | "invited";
+}
+
+export const MEMBERS: Member[] = [
+  { id: 1, name: "Marcus Chen", email: "marcus@studio.io", role: "Owner", status: "active" },
+  { id: 2, name: "Priya Sharma", email: "priya@studio.io", role: "Publisher", status: "active" },
+  { id: 3, name: "Yuki Tanaka", email: "yuki@studio.io", role: "BroadcastOperator", status: "active" },
+  { id: 4, name: "Sofia Rossi", email: "sofia@studio.io", role: "Approver", status: "invited" },
+];
+
+export const ASSETS = [
+  { id: 1, name: "logo-dark.svg", group: "Brand", locked: false },
+  { id: 2, name: "launch-banner.png", group: "Launch", locked: false },
+  { id: 3, name: "q4-roadmap.pdf", group: "Internal", locked: true },
+  { id: 4, name: "team-photo.jpg", group: "Brand", locked: false },
+  { id: 5, name: "keynote-clip.mp4", group: "Launch", locked: true },
+  { id: 6, name: "press-kit.zip", group: "PR", locked: false },
+];
+
+export interface AuditEntry {
+  id: number;
+  actor: string;
+  action: string;
+  targetType: string;
+  target: string;
+  minutes: number;
+  diff: Record<string, unknown> | null;
+}
+
+export const AUDIT_ENTRIES: AuditEntry[] = [
+  { id: 1, actor: "marcus@studio.io", action: "connection.created", targetType: "connection", target: "mastodon/@studio", minutes: 12, diff: { provider: "mastodon", scopes: ["read", "write"] } },
+  { id: 2, actor: "priya@studio.io", action: "publication.scheduled", targetType: "publication", target: "draft-8821", minutes: 34, diff: { scheduledAt: "2026-10-07T09:00Z", targets: 3 } },
+  { id: 3, actor: "yuki@studio.io", action: "membership.role_changed", targetType: "membership", target: "sofia@studio.io", minutes: 58, diff: { role: ["Editor", "Approver"] } },
+  { id: 4, actor: "system", action: "credential.rotated", targetType: "credential", target: "cred-117", minutes: 90, diff: { keyVersion: [1, 2], accessToken: "[REDACTED]" } },
+  { id: 5, actor: "marcus@studio.io", action: "publication.published", targetType: "publication", target: "pub-3390", minutes: 140, diff: { remoteUrl: "https://fosstodon.org/@studio/1099", streamKey: "[REDACTED]" } },
+  { id: 6, actor: "sofia@studio.io", action: "approval.granted", targetType: "draft", target: "draft-8819", minutes: 210, diff: null },
+];
diff --git a/apps/web/src/lib/gestures.ts b/apps/web/src/lib/gestures.ts
new file mode 100644
index 0000000..0067cb6
--- /dev/null
+++ b/apps/web/src/lib/gestures.ts
@@ -0,0 +1,14 @@
+export type SwipeIntent = "pending" | "horizontal" | "vertical";
+
+/** Lock a gesture only after it has moved far enough to distinguish scrolling. */
+export function swipeIntent(dx: number, dy: number, threshold = 12): SwipeIntent {
+  if (Math.hypot(dx, dy) < threshold) return "pending";
+  return Math.abs(dx) > Math.abs(dy) * 1.5 ? "horizontal" : "vertical";
+}
+
+export function swipeResult(dx: number, velocity: number, direction: "left" | "right", width = 204): "closed" | "open" | "full" {
+  const travel = direction === "left" ? -dx : dx;
+  if (travel <= 0) return "closed";
+  if (travel >= width * 0.82 || (travel > width * 0.45 && velocity > 0.75)) return "full";
+  return travel >= width * 0.25 ? "open" : "closed";
+}
diff --git a/apps/web/src/lib/platforms.ts b/apps/web/src/lib/platforms.ts
new file mode 100644
index 0000000..4ea76ab
--- /dev/null
+++ b/apps/web/src/lib/platforms.ts
@@ -0,0 +1,122 @@
+export interface PlatformCapabilities {
+  publishText: boolean;
+  requiresMediaForPublish?: boolean;
+  amplifyRepost: boolean;
+  amplifyQuote: boolean;
+  amplifyShare: boolean;
+  feed: boolean;
+  directMessages: boolean;
+  comments: boolean;
+}
+
+export interface Platform {
+  id: string;
+  displayName: string;
+  charLimit: number;
+  capabilities: PlatformCapabilities;
+  amplifyLabels: { repost?: string; quote?: string; share?: string };
+}
+
+export const PLATFORMS: Record<string, Platform> = {
+  mastodon: {
+    id: "mastodon",
+    displayName: "Mastodon",
+    charLimit: 500,
+    capabilities: { publishText: true, amplifyRepost: true, amplifyQuote: true, amplifyShare: false, feed: true, directMessages: true, comments: true },
+    amplifyLabels: { repost: "Boost", quote: "Quote" },
+  },
+  telegram: {
+    id: "telegram",
+    displayName: "Telegram",
+    charLimit: 4096,
+    capabilities: { publishText: true, amplifyRepost: false, amplifyQuote: false, amplifyShare: true, feed: true, directMessages: false, comments: false },
+    amplifyLabels: { share: "Forward" },
+  },
+  limited: {
+    id: "limited",
+    displayName: "Limited API",
+    charLimit: 2200,
+    capabilities: { publishText: true, amplifyRepost: false, amplifyQuote: false, amplifyShare: false, feed: true, directMessages: false, comments: true },
+    amplifyLabels: {},
+  },
+  facebook: {
+    id: "facebook",
+    displayName: "Facebook",
+    charLimit: 63206,
+    capabilities: { publishText: true, amplifyRepost: false, amplifyQuote: false, amplifyShare: true, feed: true, directMessages: true, comments: true },
+    amplifyLabels: { share: "Share link" },
+  },
+  instagram: {
+    id: "instagram",
+    displayName: "Instagram",
+    charLimit: 2200,
+    capabilities: { publishText: true, requiresMediaForPublish: true, amplifyRepost: false, amplifyQuote: false, amplifyShare: false, feed: true, directMessages: true, comments: true },
+    amplifyLabels: {},
+  },
+};
+
+export const CONNECTED_ACCOUNTS = [
+  { platform: "mastodon", handle: "@studio@fosstodon.org", status: "healthy" as const },
+  { platform: "telegram", handle: "@studiochannel", status: "healthy" as const },
+  { platform: "limited", handle: "@studio", status: "healthy" as const },
+  { platform: "facebook", handle: "Studio Page", status: "expiring" as const },
+];
+
+export function getPlatform(id: string): Platform {
+  const platform = PLATFORMS[id];
+  if (platform === undefined) throw new Error(`unknown platform: ${id}`);
+  return platform;
+}
+
+export interface DocumentedRate {
+  dailyPostCap?: number;
+  requestsPerSecond?: number;
+  commentsPerHour?: number;
+  tierNote?: string;
+}
+
+export const DOCUMENTED_RATES: Record<string, DocumentedRate> = {
+  instagram: { dailyPostCap: 25, requestsPerSecond: 0.5, commentsPerHour: 200 },
+  threads: { dailyPostCap: 250, requestsPerSecond: 0.5 },
+  mastodon: { requestsPerSecond: 0.5, dailyPostCap: 300 },
+  telegram: { requestsPerSecond: 1 },
+  facebook: { requestsPerSecond: 2 },
+  bluesky: { requestsPerSecond: 1 },
+  limited: {},
+};
+
+export interface ConnectionCapacity {
+  handle: string;
+  platform: string;
+  resolvedCap?: number;
+  used: number;
+  recentPublishes: string[];
+  tierNote?: string;
+  overrideCap?: number;
+}
+
+const HOUR = 3600_000;
+const now = Date.now();
+const ago = (h: number): string => new Date(now - h * HOUR).toISOString();
+
+export const CONNECTION_CAPACITIES: ConnectionCapacity[] = [
+  { handle: "@studio@fosstodon.org", platform: "mastodon", resolvedCap: 300, used: 42, recentPublishes: Array.from({ length: 42 }, (_, i) => ago(0.5 + i * 0.4)) },
+  { handle: "@studiochannel", platform: "telegram", resolvedCap: undefined, used: 15, recentPublishes: Array.from({ length: 15 }, (_, i) => ago(1 + i * 0.8)) },
+  { handle: "Studio News", platform: "instagram", resolvedCap: 100, used: 100, recentPublishes: Array.from({ length: 100 }, (_, i) => ago(0.2 + i * 0.22)), tierNote: "news-publisher advanced access", overrideCap: 100 },
+  { handle: "Studio Page", platform: "facebook", resolvedCap: undefined, used: 8, recentPublishes: Array.from({ length: 8 }, (_, i) => ago(2 + i)) },
+];
+
+export interface ColumnDef {
+  key: string;
+  title: string;
+  platformId: string;
+  staleness: string;
+}
+
+export const MOCK_COLUMN_DEFS: ColumnDef[] = [
+  { key: "home", title: "Home", platformId: "mastodon", staleness: "live" },
+  { key: "mentions", title: "Mentions", platformId: "telegram", staleness: "live" },
+  { key: "search", title: "Saved: product", platformId: "limited", staleness: "12s old" },
+];
+
+export const MOCK_TARGETS = ["mastodon", "telegram", "facebook", "instagram"];
diff --git a/apps/web/src/lib/saved-searches.ts b/apps/web/src/lib/saved-searches.ts
new file mode 100644
index 0000000..2a46792
--- /dev/null
+++ b/apps/web/src/lib/saved-searches.ts
@@ -0,0 +1,16 @@
+export const SAVED_SEARCHES_KEY = "tmbh.saved-searches";
+export const DEFAULT_SAVED_SEARCHES = ["product"];
+
+export function readSavedSearches(): string[] {
+  if (typeof window === "undefined") return DEFAULT_SAVED_SEARCHES;
+  try {
+    const raw = window.localStorage.getItem(SAVED_SEARCHES_KEY);
+    const parsed: unknown = raw === null ? DEFAULT_SAVED_SEARCHES : JSON.parse(raw);
+    return Array.isArray(parsed) ? parsed.filter((value): value is string => typeof value === "string") : DEFAULT_SAVED_SEARCHES;
+  } catch { return DEFAULT_SAVED_SEARCHES; }
+}
+
+export function saveSearches(values: string[]): void {
+  window.localStorage.setItem(SAVED_SEARCHES_KEY, JSON.stringify([...new Set(values.map((value) => value.trim()).filter(Boolean))]));
+  window.dispatchEvent(new Event("saved-searches-change"));
+}
diff --git a/apps/web/src/lib/session-token.ts b/apps/web/src/lib/session-token.ts
new file mode 100644
index 0000000..44a51db
--- /dev/null
+++ b/apps/web/src/lib/session-token.ts
@@ -0,0 +1,31 @@
+/**
+ * Session token holder: memory first, mirrored to localStorage so a reload
+ * keeps the session. Listeners let the auth store react when the API client
+ * clears a token (401) or a mutation hands back a re-issued one.
+ */
+
+const STORAGE_KEY = "tmbh.session";
+
+let memory: string | null | undefined;
+const listeners = new Set<(token: string | null) => void>();
+
+export function getSessionToken(): string | null {
+  if (memory !== undefined) return memory;
+  if (typeof window === "undefined") return null;
+  memory = window.localStorage.getItem(STORAGE_KEY);
+  return memory;
+}
+
+export function setSessionToken(token: string | null): void {
+  memory = token;
+  if (typeof window !== "undefined") {
+    if (token === null) window.localStorage.removeItem(STORAGE_KEY);
+    else window.localStorage.setItem(STORAGE_KEY, token);
+  }
+  for (const listener of listeners) listener(token);
+}
+
+export function onSessionTokenChange(listener: (token: string | null) => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
diff --git a/apps/web/src/lib/streams-data.ts b/apps/web/src/lib/streams-data.ts
new file mode 100644
index 0000000..eedf4b3
--- /dev/null
+++ b/apps/web/src/lib/streams-data.ts
@@ -0,0 +1,49 @@
+import type { FeedItem } from "./fixtures";
+import { getPlatform, PLATFORMS, type Platform } from "./platforms";
+import type { ColumnDef } from "../components/streams/column";
+
+export interface StreamItem extends FeedItem {
+  connectionId?: string;
+  remoteId?: string;
+  feedId?: string;
+  mediaUrls?: string[];
+  sourceLabel?: string;
+  livePlatform?: Platform;
+}
+export interface FeedsResponse {
+  items: Array<{ id: string; remoteId: string; connectionId: string; provider: string; authorHandle: string; text: string; mediaUrls: string[]; createdAt: string; metrics: Record<string, number> }>;
+  nextCursor: string | null;
+  meta: {
+    configuredFeeds: number;
+    connections: Array<{ id: string; provider: string; handle: string; displayName: string; capabilities: string[]; fetchedAt: string | null; status: "ready" | "pending" }>;
+    excludedConnections: Array<{ id: string; provider: string; reason: string }>;
+  };
+}
+export const streamItemKey = (item: StreamItem): string => `${item.connectionId ?? item.platform}:${item.feedId ?? item.remoteId ?? item.id}`;
+export const streamPlatform = (item: StreamItem): Platform => item.livePlatform ?? getPlatform(item.platform);
+export function liveColumns(response: FeedsResponse): ColumnDef[] {
+  return response.meta.connections.map((connection) => {
+    const enabled = (key: string): boolean => connection.capabilities.includes(key);
+    const known = PLATFORMS[connection.provider];
+    const platform: Platform = {
+      id: connection.provider, displayName: known?.displayName ?? connection.provider,
+      charLimit: known?.charLimit ?? 500, amplifyLabels: known?.amplifyLabels ?? { repost: "Repost", quote: "Quote" },
+      capabilities: { publishText: enabled("publishText"), amplifyRepost: enabled("amplifyRepost"), amplifyQuote: enabled("amplifyQuote"), amplifyShare: enabled("amplifyShare"), feed: true, directMessages: enabled("directMessages"), comments: enabled("comments") },
+    };
+    const items: StreamItem[] = response.items.filter((item) => item.connectionId === connection.id).map((item) => ({
+      // Existing mobile cards use numeric IDs; selection and React keys use the
+      // actual (connection, feed item) identity instead of this presentation ID.
+      id: Array.from(`${connection.id}:${item.id}`).reduce((hash, char) => (hash * 31 + char.charCodeAt(0)) >>> 0, 0),
+      platform: connection.provider, author: item.authorHandle, handle: item.authorHandle,
+      text: item.text, ageMinutes: Math.max(0, (Date.now() - Date.parse(item.createdAt)) / 60_000),
+      likes: item.metrics.likes ?? item.metrics.favourites ?? 0, reposts: item.metrics.reposts ?? item.metrics.reblogs ?? 0,
+      replies: item.metrics.replies ?? 0, hasMedia: item.mediaUrls.length > 0,
+      connectionId: connection.id, remoteId: item.remoteId, feedId: item.id, mediaUrls: item.mediaUrls,
+      sourceLabel: `${connection.displayName} (${connection.handle})`, livePlatform: platform,
+    }));
+    return {
+      key: connection.id, title: `${connection.displayName} · ${connection.handle}`, platformId: connection.provider,
+      platform, staleness: connection.fetchedAt ? `Updated ${new Date(connection.fetchedAt).toLocaleTimeString()}` : "Waiting for feed", items,
+    };
+  });
+}
diff --git a/apps/web/src/lib/use-api.ts b/apps/web/src/lib/use-api.ts
new file mode 100644
index 0000000..f34dabf
--- /dev/null
+++ b/apps/web/src/lib/use-api.ts
@@ -0,0 +1,68 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import { api, ApiUnreachableError, errorMessage } from "./api-client";
+import { useAuth } from "./auth-store";
+
+export type DataSource = "loading" | "live" | "sample";
+
+export interface ApiResource<T> {
+  data: T;
+  source: DataSource;
+  error: string | null;
+  reload: () => void;
+  setData: (update: (current: T) => T) => void;
+}
+
+/**
+ * GET a resource once the session is verified. When the API is unreachable
+ * the screen gets `sample` (its fixture data) so local UI work never blocks
+ * on a running backend — pages show an "offline — sample data" indicator.
+ */
+export function useApiResource<Live, View>(
+  path: string,
+  toView: (live: Live) => View,
+  sample: View,
+  query?: Record<string, string | number | undefined>,
+): ApiResource<View> {
+  const { status } = useAuth();
+  const [data, setDataState] = useState<View>(sample);
+  const [source, setSource] = useState<DataSource>("loading");
+  const [error, setError] = useState<string | null>(null);
+  const [nonce, setNonce] = useState(0);
+  const queryKey = JSON.stringify(query ?? {});
+
+  useEffect(() => {
+    if (status === "loading") return;
+    if (status !== "authenticated") {
+      setDataState(sample);
+      setSource("sample");
+      return;
+    }
+    const controller = new AbortController();
+    const parsedQuery = JSON.parse(queryKey) as Record<string, string | number | undefined>;
+    api
+      .get<Live>(path, parsedQuery, controller.signal)
+      .then((live) => {
+        setDataState(toView(live));
+        setSource("live");
+        setError(null);
+      })
+      .catch((err: unknown) => {
+        if (controller.signal.aborted) return;
+        if (err instanceof ApiUnreachableError) {
+          setDataState(sample);
+          setSource("sample");
+          return;
+        }
+        setError(errorMessage(err));
+        setSource("live");
+      });
+    return () => controller.abort();
+    // `toView` / `sample` must be stable (module-level); keying on them would refetch every render.
+  }, [status, path, queryKey, nonce]);
+
+  const reload = useCallback(() => setNonce((n) => n + 1), []);
+  const setData = useCallback((update: (current: View) => View) => setDataState(update), []);
+  return { data, source, error, reload, setData };
+}
diff --git a/apps/web/src/lib/video-fixtures.ts b/apps/web/src/lib/video-fixtures.ts
new file mode 100644
index 0000000..279a1ad
--- /dev/null
+++ b/apps/web/src/lib/video-fixtures.ts
@@ -0,0 +1,90 @@
+import type { VideoLibraryEntryDto } from "./video-types";
+
+/**
+ * Offline sample library for the video screen (useApiResource conventions: when
+ * the API is unreachable the screen renders these read-only). Lives under
+ * src/lib so provider literals stay inside the mock-registry boundary.
+ */
+
+export const SAMPLE_VIDEO_ENTRIES: VideoLibraryEntryDto[] = [
+  {
+    videoAsset: {
+      id: "1f0a2b3c-4d5e-6f70-8192-a3b4c5d6e7f8",
+      workspaceId: "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
+      storageKey: "sha256/9f2c7ab41d06e5b38c0f4a71d295e6b83c10d47a9e52f68b14c3d2e1f0a9b8c7.mp4",
+      mimeType: "video/mp4",
+      sizeBytes: 851_738_112,
+      width: 1920,
+      height: 1080,
+      durationMs: 362_400,
+      frameRate: 29.97,
+      codec: "h264",
+      audioCodec: "aac",
+    },
+    processingState: "complete",
+    publications: [
+      {
+        connectionId: "3c4d5e6f-7081-9293-a4b5-c6d7e8f90a1b",
+        remoteId: "981",
+        platform: "peertube",
+        publishedAt: "2026-10-05T09:12:00.000Z",
+      },
+      {
+        connectionId: "4d5e6f70-8192-93a4-b5c6-d7e8f90a1b2c",
+        remoteId: "dQw4w9WgXcQ",
+        platform: "youtube",
+        publishedAt: "2026-10-04T18:40:00.000Z",
+      },
+    ],
+  },
+  {
+    videoAsset: {
+      id: "2a1b3c4d-5e6f-7081-9293-b4c5d6e7f8a9",
+      workspaceId: "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
+      storageKey: "sha256/1c8d3e9f2a6b4d08e7c5a19f3b6d2e8c4a7f1b9e3d6c2a8f4e1b7d3c9a5e2f0.webm",
+      mimeType: "video/webm",
+      sizeBytes: 218_103_808,
+      width: 1280,
+      height: 720,
+      durationMs: 95_200,
+      frameRate: 30,
+      codec: "vp9",
+      audioCodec: "opus",
+    },
+    processingState: "transcoding",
+    publications: [],
+  },
+  {
+    videoAsset: {
+      id: "3b2c4d5e-6f70-8192-93a4-c5d6e7f8a9b0",
+      workspaceId: "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
+      storageKey: "sha256/6e1f0a2b3c4d5e6f70819293a4b5c6d7e8f90a1b2c3d4e5f6071829384a5b.mov",
+      mimeType: "video/quicktime",
+      sizeBytes: 41_943_040,
+    },
+    processingState: "probing",
+    publications: [],
+  },
+  {
+    videoAsset: {
+      id: "4c3d5e6f-7081-9293-a4b5-d6e7f8a9b0c1",
+      workspaceId: "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
+      storageKey: "sha256/2d9e4a1f7c3b5d08e6a19f4b7d2e8c3a5f1b9e6d3c2a8f4e0b7d3c9a5e2f1a8.mp4",
+      mimeType: "video/mp4",
+      sizeBytes: 12_582_912,
+    },
+    processingState: "queued",
+    publications: [],
+  },
+  {
+    videoAsset: {
+      id: "5d4e6f70-8192-93a4-b5c6-e7f8a9b0c1d2",
+      workspaceId: "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
+      storageKey: "sha256/8c7d6e5f4a3b2c1d0e9f8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b8.mp4",
+      mimeType: "video/mp4",
+      sizeBytes: 68_157_440,
+    },
+    processingState: "failed",
+    publications: [],
+  },
+];
diff --git a/apps/web/src/lib/video-types.ts b/apps/web/src/lib/video-types.ts
new file mode 100644
index 0000000..a518b12
--- /dev/null
+++ b/apps/web/src/lib/video-types.ts
@@ -0,0 +1,57 @@
+/**
+ * Response shapes of the /video routes — kept in sync by hand with
+ * apps/api VideoController/VideoService (same standing as api-types.ts;
+ * declared here because api-client.ts is owned by another worker right now).
+ */
+
+/** video_processing_jobs.state — the processing pipeline a video walks. */
+export type VideoProcessingState = "queued" | "probing" | "transcoding" | "complete" | "failed";
+
+export interface VideoAssetDto {
+  id: string;
+  workspaceId: string;
+  storageKey: string;
+  mimeType: string;
+  sizeBytes: number;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  frameRate?: number;
+  codec?: string;
+  audioCodec?: string;
+  thumbnailKey?: string;
+}
+
+export interface VideoProcessingJobDto {
+  id: string;
+  workspaceId: string;
+  videoAssetId: string;
+  state: VideoProcessingState;
+  progressPercent?: number;
+  outputKey?: string;
+  error?: string;
+  processingNote?: string;
+}
+
+export interface VideoPublicationDto {
+  connectionId: string;
+  remoteId: string;
+  platform: string;
+  publishedAt: string;
+}
+
+export interface VideoLibraryEntryDto {
+  videoAsset: VideoAssetDto;
+  processingState: VideoProcessingState;
+  publications: VideoPublicationDto[];
+}
+
+export interface VideoLibraryPageDto {
+  items: VideoLibraryEntryDto[];
+  nextCursor?: string;
+}
+
+export interface VideoStatusDto {
+  videoAsset: VideoAssetDto;
+  processingJob: VideoProcessingJobDto;
+}
diff --git a/apps/web/src/lib/wiki-content.ts b/apps/web/src/lib/wiki-content.ts
new file mode 100644
index 0000000..9f4bb42
--- /dev/null
+++ b/apps/web/src/lib/wiki-content.ts
@@ -0,0 +1,886 @@
+/**
+ * Bilingual (EN/ES) wiki content for the in-app documentation section.
+ *
+ * Every manual is written for a non-technical activist: plain language, no
+ * unexplained jargon, and concrete "click this, then that" steps. Spanish is
+ * written in the register activist collectives actually use (tú form, assembly
+ * vocabulary), not machine translation.
+ *
+ * Body text conventions understood by the wiki renderer:
+ *   - paragraphs are separated by a blank line ("\n\n")
+ *   - lines starting with "- " render as a bullet list
+ *   - lines starting with "1. " (any number) render as an ordered list
+ *   - **text** renders as bold — use it for on-screen button and field labels
+ */
+
+export interface LocalizedText {
+  readonly en: string;
+  readonly es: string;
+}
+
+export interface WikiSection {
+  readonly heading: LocalizedText;
+  readonly body: LocalizedText;
+}
+
+export interface WikiPage {
+  readonly slug: string;
+  readonly title: LocalizedText;
+  readonly blurb: LocalizedText;
+  readonly sections: readonly WikiSection[];
+}
+
+export const WIKI_PAGES: readonly WikiPage[] = [
+  {
+    slug: "getting-started",
+    title: { en: "Getting started", es: "Primeros pasos" },
+    blurb: {
+      en: "Create your account, join your collective's workspace, and learn what each role can do.",
+      es: "Crea tu cuenta, únete al espacio de trabajo de tu colectivo y aprende qué puede hacer cada rol.",
+    },
+    sections: [
+      {
+        heading: { en: "What TMBH is", es: "Qué es TMBH" },
+        body: {
+          en: "TMBH is a broadcast newsroom your collective runs itself: one place to write, review, schedule and publish to many platforms at once. It also watches live feeds, bridges your chats, runs votes, and keeps an archive that survives takedowns. You do not need to install anything — everything happens in your browser at app.occupymedia.cc.\n\nThis wiki explains every feature step by step. If a word is new to you, it is explained the first time it appears.",
+          es: "TMBH es una sala de redacción que tu colectivo administra por su cuenta: un solo lugar para escribir, revisar, programar y publicar en muchas plataformas a la vez. También vigila fuentes en vivo, une tus chats, hace votaciones y mantiene un archivo que sobrevive a los borradones. No hay que instalar nada: todo ocurre en tu navegador, en app.occupymedia.cc.\n\nEsta wiki explica cada función paso a paso. Si una palabra es nueva, se explica la primera vez que aparece.",
+        },
+      },
+      {
+        heading: { en: "Creating your account", es: "Crear tu cuenta" },
+        body: {
+          en: "Open app.occupymedia.cc. The first screen shows **Sign in** and **Create account** — choose **Create account**.\n\n1. Pick a username (no spaces, no @) and a display name others in the collective will recognise.\n2. Enter your email so invites and recovery can reach you.\n3. Choose a password of at least 10 characters. A long phrase you can remember is stronger than a short messy one.\n4. Press **Create account**. You land in your new, empty workspace as its **Owner**.",
+          es: "Abre app.occupymedia.cc. La primera pantalla muestra **Sign in** y **Create account** — elige **Create account**.\n\n1. Elige un nombre de usuario (sin espacios y sin @) y un nombre visible que el colectivo reconozca.\n2. Escribe tu correo para que te lleguen invitaciones y recuperación.\n3. Elige una contraseña de al menos 10 caracteres. Una frase larga que recuerdes es más fuerte que una corta y enredada.\n4. Pulsa **Create account**. Entrarás en tu espacio de trabajo nuevo y vacío como su **Owner** (propietario).",
+        },
+      },
+      {
+        heading: { en: "Joining an existing workspace", es: "Unirte a un espacio de trabajo existente" },
+        body: {
+          en: "Most people do not create a workspace — they join their collective's. Ask a team admin for an **invite link** and open it in your browser.\n\nThe link shows the workspace name, the role you will get, and how many times the link can still be used. Press **Join** and you are in; the link stops working once it hits its use limit or its expiry date. If the link has expired, ask for a fresh one — that expiry is a safety feature, not a bug.",
+          es: "La mayoría no crea un espacio de trabajo: se une al de su colectivo. Pide a quien administra el equipo un **enlace de invitación** y ábrelo en tu navegador.\n\nEl enlace muestra el nombre del espacio, el rol que recibirás y cuántos usos le quedan. Pulsa **Join** y ya estarás dentro; el enlace deja de funcionar al agotar sus usos o al llegar a su fecha de caducidad. Si el enlace caducó, pide uno nuevo: esa caducidad es una medida de seguridad, no un fallo.",
+        },
+      },
+      {
+        heading: { en: "Signing in and out", es: "Iniciar y cerrar sesión" },
+        body: {
+          en: "To sign in later, open the app, enter your username and password, and press **Sign in**. Your session is remembered on that device until you sign out.\n\nOn a shared or borrowed computer always sign out when you finish: open **More** (bottom right on mobile, or the sidebar) and press **Sign out**. On your own laptop or phone, staying signed in is fine and saves time.",
+          es: "Para entrar más tarde, abre la app, escribe tu usuario y contraseña y pulsa **Sign in**. La sesión queda recordada en ese dispositivo hasta que la cierres.\n\nEn un equipo compartido o prestado, cierra siempre la sesión al terminar: abre **More** (abajo a la derecha en el móvil, o en la barra lateral) y pulsa **Sign out**. En tu propio portátil o móvil puedes quedarte con la sesión abierta y ahorrar tiempo.",
+        },
+      },
+      {
+        heading: { en: "Understanding roles", es: "Entender los roles" },
+        body: {
+          en: "A role is the set of things a person is allowed to do. Roles keep the newsroom honest: no single person can publish, moderate and audit at the same time without anyone noticing.\n\n- **Owner** — runs the workspace, can do everything, including deleting it.\n- **Admin** — manages members, connections and settings.\n- **Editor** — writes and edits drafts, requests approval.\n- **Approver** — votes on drafts in review; can block with a reason.\n- **Publisher** — dispatches approved posts and manages schedules.\n- **Moderator** — handles the bridged chats: deletes, times out, resolves flags.\n- **BroadcastOperator** — drives the live Control Room and stream destinations.\n- **Viewer** — read-only: watches streams, calendar and archive, changes nothing.\n\nOne person can hold more than one role in small collectives, but splitting writing from approving is the cheapest safety you can buy. See the Team management manual for how to assign them.",
+          es: "Un rol es el conjunto de cosas que una persona puede hacer. Los roles mantienen la redacción honesta: nadie puede publicar, moderar y auditar a la vez sin que se note.\n\n- **Owner** — administra el espacio, puede hacer todo, incluso borrarlo.\n- **Admin** — gestiona miembros, conexiones y ajustes.\n- **Editor** — escribe y edita borradores, pide aprobación.\n- **Approver** — vota los borradores en revisión; puede bloquear con un motivo.\n- **Publisher** — despacha las publicaciones aprobadas y gestiona la programación.\n- **Moderator** — cuida los chats unidos: borra, expulsa temporalmente, resuelve avisos.\n- **BroadcastOperator** — maneja la sala de control en vivo y los destinos de transmisión.\n- **Viewer** — solo lectura: mira streams, calendario y archivo, no cambia nada.\n\nEn colectivos pequeños una persona puede tener más de un rol, pero separar quien escribe de quien aprueba es la seguridad más barata que existe. Mira el manual de Gestión del equipo para asignarlos.",
+        },
+      },
+      {
+        heading: { en: "Finding your way around", es: "Orientarte en la app" },
+        body: {
+          en: "On a laptop the sidebar on the left lists every section: **Streams**, **Search**, **Inbox**, **Calendar**, **Video**, **Analytics**, **Connections**, **Control Room**, **Team**, **Audit** and more. On a phone the same sections live in the bottom bar and under **More**.\n\nThe fastest way anywhere is the keyboard: press **⌘K** (or **Ctrl-K**) to open the command palette and type where you want to go. This wiki is always reachable from **More → Help & docs**.",
+          es: "En un portátil, la barra lateral izquierda lista todas las secciones: **Streams**, **Search**, **Inbox**, **Calendar**, **Video**, **Analytics**, **Connections**, **Control Room**, **Team**, **Audit** y más. En el móvil las mismas secciones están en la barra inferior y dentro de **More**.\n\nLa forma más rápida de moverse es el teclado: pulsa **⌘K** (o **Ctrl-K**) para abrir la paleta de comandos y escribe a dónde quieres ir. Esta wiki siempre está en **More → Ayuda y documentación**.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "composing-posts",
+    title: { en: "Composing posts", es: "Redactar publicaciones" },
+    blurb: {
+      en: "Write a draft, pick the platforms it goes to, preview each version, and send it for group review.",
+      es: "Escribe un borrador, elige a qué plataformas va, previsualiza cada versión y envíalo a revisión del grupo.",
+    },
+    sections: [
+      {
+        heading: { en: "Where composing happens", es: "Dónde se redacta" },
+        body: {
+          en: "Open **Compose** from the sidebar, the bottom bar, or by pressing **⌘K** and typing compose. The same editor opens from the pencil button on the streams wall, so you can write while watching the feeds.\n\nEverything you write starts as a **draft**. A draft is private to the workspace and cannot reach the outside world until the group approves it — that is the whole point of the pipeline.",
+          es: "Abre **Compose** desde la barra lateral, la barra inferior, o pulsando **⌘K** y escribiendo compose. El mismo editor se abre desde el botón de lápiz en el muro de streams, así que puedes escribir mientras miras las fuentes.\n\nTodo lo que escribes empieza como **borrador**. Un borrador es privado del espacio de trabajo y no puede salir al exterior hasta que el grupo lo apruebe: esa es la gracia de todo el circuito.",
+        },
+      },
+      {
+        heading: { en: "Writing the draft", es: "Escribir el borrador" },
+        body: {
+          en: "Type your text in the main editor box. Links, hashtags and line breaks are kept as you write them. If the text runs long, the editor shows a character counter per platform so you know what still fits.\n\nA few habits that save rework later: put the call to action in the first line (platforms truncate), write out dates and places instead of \"tomorrow\", and avoid thread-dependent meaning, because each platform gets one post.",
+          es: "Escribe tu texto en el cuadro principal del editor. Los enlaces, hashtags y saltos de línea se conservan tal cual. Si el texto se alarga, el editor muestra un contador de caracteres por plataforma para que sepas qué cabe todavía.\n\nAlgunos hábitos que ahorran retrabajo: pon la llamada a la acción en la primera línea (las plataformas cortan el texto), escribe fechas y lugares completos en vez de \"mañana\", y evita sentidos que dependan de un hilo, porque cada plataforma recibe una sola publicación.",
+        },
+      },
+      {
+        heading: { en: "Choosing target platforms", es: "Elegir las plataformas destino" },
+        body: {
+          en: "Below the editor, tick every platform this post should reach: Mastodon, Telegram, Bluesky, PeerTube, Facebook, Instagram, Threads, LinkedIn, Reddit, Twitch, Discord or Slack. Only the accounts your collective has connected appear as choices — see the Connections manual if one is missing.\n\nPick several at once; that is the fan-out. One approval covers all the boxes you tick, and each platform gets its own copy sized to its rules.",
+          es: "Debajo del editor, marca todas las plataformas a las que debe llegar esta publicación: Mastodon, Telegram, Bluesky, PeerTube, Facebook, Instagram, Threads, LinkedIn, Reddit, Twitch, Discord o Slack. Solo aparecen como opciones las cuentas que tu colectivo conectó; si falta alguna, mira el manual de Conexiones.\n\nMarca varias a la vez: eso es la difusión múltiple. Una sola aprobación cubre todas las casillas que marques, y cada plataforma recibe su propia copia ajustada a sus reglas.",
+        },
+      },
+      {
+        heading: { en: "Previews: seeing what each platform gets", es: "Previsualizaciones: ver qué recibe cada plataforma" },
+        body: {
+          en: "The **Previews** panel renders your draft exactly as each ticked platform will show it, including truncation and media layout. Check it before submitting — a post that looks fine for one network can look broken on another.\n\nIf the preview shows a warning (for example, a platform that requires media), fix the draft or untick that platform rather than hoping for the best.",
+          es: "El panel **Previews** muestra tu borrador exactamente como lo presentará cada plataforma marcada, incluidos los cortes y la disposición de los medios. Revísalo antes de enviar: una publicación que se ve bien en una red puede verse rota en otra.\n\nSi la vista previa muestra un aviso (por ejemplo, una plataforma que exige medios), corrige el borrador o desmarca esa plataforma en vez de cruzar los dedos.",
+        },
+      },
+      {
+        heading: { en: "Visibility and media", es: "Visibilidad y medios" },
+        body: {
+          en: "Use **Visibility** to set who can see the post where the platform supports it — public, followers-only, or unlisted. Followers-only is the right choice for internal callouts you do not want screenshotted to fascists.\n\nAttach photos or video with the media button before you submit; attached media travels with the draft through review and archive. Video you upload here is transcoded automatically — see the Video upload manual.",
+          es: "Usa **Visibility** para definir quién puede ver la publicación donde la plataforma lo permita: pública, solo seguidores o no listada. \"Solo seguidores\" es la opción correcta para convocatorias internas que no quieres que capten por captura de pantalla.\n\nAdjunta fotos o video con el botón de medios antes de enviar; los medios acompañan al borrador durante la revisión y quedan en el archivo. El video que subas aquí se transcodifica solo: mira el manual de Subida de video.",
+        },
+      },
+      {
+        heading: { en: "Saving a draft to finish later", es: "Guardar un borrador para terminarlo después" },
+        body: {
+          en: "Press **Save draft** at any moment. Nothing is sent anywhere, and the draft waits for you under **Recent drafts** on the same page. Reopen it by tapping its title and keep writing.\n\nDrafts also serve as a parking lot during actions: sketch the text while it is fresh, then finish and submit once the assembly has decided the line.",
+          es: "Pulsa **Save draft** en cualquier momento. No se envía nada a ninguna parte y el borrador queda esperando en **Recent drafts**, en la misma página. Vuélvelo a abrir tocando su título y sigue escribiendo.\n\nLos borradores también sirven de estacionamiento durante las acciones: esboza el texto mientras esté fresco y termínalo y envíalo cuando la asamblea haya decidido la línea.",
+        },
+      },
+      {
+        heading: { en: "Submitting for review", es: "Enviar a revisión" },
+        body: {
+          en: "When the draft is ready, press **Request approval**. The draft moves to state **in review** and appears in the queue of everyone who can approve (Approvers, and Editors depending on your setup). You cannot publish it yourself from here — that separation is deliberate.\n\nIf you also set **Date and time** before requesting approval, the post is scheduled the moment it is approved, and you can skip the scheduling step. Full details are in the Approval workflow and Scheduling posts manuals.",
+          es: "Cuando el borrador esté listo, pulsa **Request approval**. El borrador pasa al estado **in review** y aparece en la cola de quien pueda aprobar (Approver y, según la configuración, Editor). Desde aquí no puedes publicarlo tú: esa separación es deliberada.\n\nSi además fijaste **Date and time** antes de pedir aprobación, la publicación queda programada en cuanto se apruebe y te saltas el paso de programación. Los detalles están en los manuales de Flujo de aprobación y de Programar publicaciones.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "approval-workflow",
+    title: { en: "Approval workflow", es: "Flujo de aprobación" },
+    blurb: {
+      en: "How group review works: the review queue, quorum rules, voting from chat, blocking with reason codes, and the pre-dispatch gate.",
+      es: "Cómo funciona la revisión en grupo: la cola de revisión, las reglas de quórum, votar desde el chat, bloquear con códigos de motivo y la compuerta previa al despacho.",
+    },
+    sections: [
+      {
+        heading: { en: "Why group approval exists", es: "Por qué existe la aprobación en grupo" },
+        body: {
+          en: "Anything published in the collective's name is a risk the whole collective carries: legal heat, doxxing, burn of a hard-won account. Group approval spreads that decision across several people instead of leaving it to whoever typed fastest.\n\nThe pipeline is strict on purpose: draft → review → approved → scheduled → dispatched → receipt. A post cannot skip a stage, and every stage leaves a mark in the audit log.",
+          es: "Todo lo que se publica en nombre del colectivo es un riesgo que carga todo el colectivo: presión legal, doxxing, quemar una cuenta costosa de conseguir. La aprobación en grupo reparte esa decisión entre varias personas en vez de dejarla en manos de quien escribió más rápido.\n\nEl circuito es estricto a propósito: borrador → revisión → aprobado → programado → despachado → acuse. Una publicación no puede saltarse una etapa, y cada etapa deja marca en el registro de auditoría.",
+        },
+      },
+      {
+        heading: { en: "Where reviews wait", es: "Dónde esperan las revisiones" },
+        body: {
+          en: "Open **Inbox** and switch to the **Approvals** segment (or press **Approvals** directly in the sidebar). Every draft in state **in review** is listed there, newest first, with its author, target platforms and any deadline.\n\nThe badge on the Inbox tab counts drafts waiting in review right now, so nobody can claim they did not see it.",
+          es: "Abre **Inbox** y cambia al segmento **Approvals** (o pulsa **Approvals** directamente en la barra lateral). Ahí se listan todos los borradores en estado **in review**, los más nuevos primero, con su autor, plataformas destino y fecha límite si la hay.\n\nEl contador en la pestaña del Inbox indica cuántos borradores esperan revisión ahora mismo, así que nadie puede decir que no lo vio.",
+        },
+      },
+      {
+        heading: { en: "Reviewing a draft (the E1 gate)", es: "Revisar un borrador (la compuerta E1)" },
+        body: {
+          en: "Open a draft from the queue. You see the full text, the per-platform previews and the history of votes so far. Read it as an outsider would: is it true, is it safe, does it name anyone who did not consent?\n\nThen choose **Approve** to add your yes, or **Block** to stop it. Approval here is the E1 gate — the first checkpoint a draft must pass on its way out of the building.",
+          es: "Abre un borrador desde la cola. Verás el texto completo, las vistas previas por plataforma y el historial de votos hasta ahora. Léelo como lo leería alguien de afuera: ¿es cierto, es seguro, nombra a alguien que no consintió?\n\nLuego elige **Approve** para sumar tu sí, o **Block** para frenarlo. La aprobación aquí es la compuerta E1: el primer control que un borrador debe pasar antes de salir del edificio.",
+        },
+      },
+      {
+        heading: { en: "Quorum rules, in plain words", es: "Las reglas de quórum, en palabras simples" },
+        body: {
+          en: "A quorum is the number of votes needed before the draft counts as approved. Your collective configures it, typically as x out of y: 3 of 5 approvers, or half of the editors, and so on.\n\nThe queue always shows the gap to quorum — how many more yes votes are needed. Until that gap closes, the draft simply waits; it is never approved by silence. If the collective set a mixed rule (for example, 1 of 2 admins AND 2 of 5 participants), both arms must be satisfied.",
+          es: "Un quórum es la cantidad de votos necesaria para que el borrador cuente como aprobado. Tu colectivo lo configura, normalmente como x de y: 3 de 5 aprobadores, o la mitad de quienes editan, etc.\n\nLa cola siempre muestra lo que falta para el quórum: cuántos sí más se necesitan. Hasta cerrar esa brecha, el borrador simplemente espera; nunca se aprueba por silencio. Si el colectivo fijó una regla mixta (por ejemplo, 1 de 2 admins Y 2 de 5 participantes), deben cumplirse los dos brazos.",
+        },
+      },
+      {
+        heading: { en: "Blocking and reason codes", es: "Bloquear y códigos de motivo" },
+        body: {
+          en: "**Block** stops the draft immediately, no matter how many approvals it had. A block is not a veto war: you must attach a **reason code**, a short machine-readable tag saying why — for example unsafe-claim, legal-risk, wrong-target, needs-source, tone.\n\nCodes matter because they are counted. After a month you can see whether blocks cluster on \"needs-source\" and fix the writing process, instead of arguing about personalities. The blocked item sits in the blocked queue with the gap to quorum spelled out, so the author knows exactly what to change and resubmit.",
+          es: "**Block** frena el borrador de inmediato, sin importar cuántas aprobaciones tuviera. Un bloqueo no es una guerra de vetos: debes adjuntar un **código de motivo**, una etiqueta corta y legible por máquinas que diga por qué — por ejemplo afirmación-insegura, riesgo-legal, destino-equivocado, falta-fuente, tono.\n\nLos códigos importan porque se cuentan. Tras un mes puedes ver si los bloqueos se concentran en \"falta-fuente\" y arreglar el proceso de escritura, en vez de discutir personalidades. El ítem bloqueado queda en la cola de bloqueados con la brecha hasta el quórum a la vista, así quien escribió sabe exactamente qué cambiar y reenviar.",
+        },
+      },
+      {
+        heading: { en: "Voting from chat", es: "Votar desde el chat" },
+        body: {
+          en: "You do not have to be at a laptop. The collective can vote from the bridged chats — Telegram, Twitch or Discord — with a short command under the draft the bot posts. The web and the chat see the same tally, because it is the same vote.\n\nThis is the difference between deciding in the street and deciding in the meeting: people who are kettled can still approve the statement. See the Chat bridge manual for how the overlay works.",
+          es: "No hace falta estar frente a un portátil. El colectivo puede votar desde los chats unidos — Telegram, Twitch o Discord — con un comando corto bajo el borrador que publica el bot. La web y el chat ven el mismo recuento, porque es la misma votación.\n\nEsta es la diferencia entre decidir en la calle y decidir en la reunión: quien está rodeado por la policía puede igualmente aprobar el comunicado. Mira el manual de Puente de chat para entender la superposición.",
+        },
+      },
+      {
+        heading: { en: "The pre-dispatch gate (E3)", es: "La compuerta previa al despacho (E3)" },
+        body: {
+          en: "Approval is not the last look. At the moment of dispatch there is a second, smaller gate (E3) that re-checks the post against the platforms it is about to hit — token still valid, media ready, schedule still in the future.\n\nIf anything fails the gate, the dispatch is fenced: nothing half-published goes out, and the failure is recorded with a reason instead of silently retrying into the void.",
+          es: "La aprobación no es la última mirada. En el momento del despacho hay una segunda compuerta, más chica (E3), que vuelve a revisar la publicación contra las plataformas que va a tocar: token vigente, medios listos, programación todavía en el futuro.\n\nSi algo no pasa la compuerta, el despacho queda cercado: no sale nada publicado a medias, y el fallo queda registrado con su motivo en vez de reintentarse en silencio hacia la nada.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "scheduling-posts",
+    title: { en: "Scheduling posts", es: "Programar publicaciones" },
+    blurb: {
+      en: "Publish at the right hour in any timezone, read the calendar, trust the daylight-saving handling, and cancel safely.",
+      es: "Publica a la hora correcta en cualquier zona horaria, lee el calendario, confía en el manejo del horario de verano y cancela con seguridad.",
+    },
+    sections: [
+      {
+        heading: { en: "Why schedule instead of posting now", es: "Por qué programar en vez de publicar ya" },
+        body: {
+          en: "Timing decides reach. A callout posted at 3 a.m. local time dies quietly; the same text at 8 a.m. rides the morning scroll. Scheduling also lets the group approve tonight what goes out before tomorrow's march, without anyone waking up early to press a button.\n\nScheduling in TMBH is timezone-correct and daylight-saving-proof, so an action at a fixed local hour stays at that local hour all year.",
+          es: "El momento decide el alcance. Una convocatoria publicada a las 3 de la madrugada muere en silencio; el mismo texto a las 8 cabalga el scroll matinal. Programar también permite que el grupo apruebe esta noche lo que saldrá antes de la marcha de mañana, sin que nadie madrugue a apretar un botón.\n\nLa programación en TMBH respeta zonas horarias y el cambio de horario, así que una acción a una hora local fija se mantiene en esa hora local todo el año.",
+        },
+      },
+      {
+        heading: { en: "Setting date and time", es: "Fijar fecha y hora" },
+        body: {
+          en: "In **Compose**, fill **Date and time** under the editor. The time you enter is interpreted in your own timezone and shown back to you with the timezone spelled out — check that suffix before saving, especially if you coordinate across continents.\n\nThen press **Schedule** (or **Request approval** with the time already set, so the post schedules itself once approved). The draft leaves your hands and appears on the calendar.",
+          es: "En **Compose**, completa **Date and time** debajo del editor. La hora que escribas se interpreta en tu propia zona horaria y se te muestra de vuelta con la zona explícita: revisa ese sufijo antes de guardar, sobre todo si coordinas entre continentes.\n\nLuego pulsa **Schedule** (o **Request approval** con la hora ya fijada, para que la publicación se programe sola al aprobarse). El borrador sale de tus manos y aparece en el calendario.",
+        },
+      },
+      {
+        heading: { en: "Reading the calendar", es: "Leer el calendario" },
+        body: {
+          en: "Open **Calendar** to see every scheduled publication on a timeline: what goes out, to which platforms, and when in your local time. Scheduled items are fenced, which means the text is frozen — editing it would need a new approval round.\n\nUse the calendar as the newsroom's shared clock: before proposing a new time, look for collisions with actions, streams or other posts in the same window.",
+          es: "Abre **Calendar** para ver todas las publicaciones programadas en una línea de tiempo: qué sale, a qué plataformas y cuándo en tu hora local. Los ítems programados están cercados, lo que significa que el texto queda congelado; editarlo exigiría una nueva ronda de aprobación.\n\nUsa el calendario como el reloj compartido de la redacción: antes de proponer una hora nueva, mira choques con acciones, transmisiones u otras publicaciones en la misma ventana.",
+        },
+      },
+      {
+        heading: { en: "Daylight saving, handled", es: "El horario de verano, resuelto" },
+        body: {
+          en: "Clocks change twice a year and they change on different dates in different countries. TMBH stores each schedule as an exact instant, computed from the timezone rules in force on that date — not as \"9 a.m.\" floating free.\n\nIn practice: a post scheduled for 9 a.m. Madrid time lands at 9 a.m. Madrid time, whether Spain is on winter or summer clock, and colleagues in Buenos Aires see the correct local equivalent. You never need to reschedule around a clock change.",
+          es: "Los relojes cambian dos veces al año y cambian en fechas distintas según el país. TMBH guarda cada programación como un instante exacto, calculado con las reglas de zona horaria vigentes en esa fecha, no como un \"9:00\" flotando en el aire.\n\nEn la práctica: una publicación programada para las 9:00 de Madrid sale a las 9:00 de Madrid, esté España en horario de invierno o de verano, y quien esté en Buenos Aires ve el equivalente local correcto. Nunca hay que reprogramar por un cambio de hora.",
+        },
+      },
+      {
+        heading: { en: "Cancelling or changing a scheduled post", es: "Cancelar o cambiar una publicación programada" },
+        body: {
+          en: "Open the item on the calendar and press **Cancel**. You will be asked **Cancel this scheduled publication?** — confirm with the cancel button or back out with **Keep it**. Cancelling is safe at any point before dispatch, and the cancellation is written to the audit log with who did it.\n\nTo change the text rather than the time, cancel and compose a new draft: the old one stays archived, so you can copy from it. To move only the time, cancel and reschedule the same approved content if your role allows it.",
+          es: "Abre el ítem en el calendario y pulsa **Cancel**. Te preguntarán **Cancel this scheduled publication?** — confirma con el botón de cancelar o vuelve atrás con **Keep it**. Cancelar es seguro en cualquier momento antes del despacho, y la cancelación queda escrita en el registro de auditoría con quién la hizo.\n\nPara cambiar el texto y no la hora, cancela y redacta un borrador nuevo: el viejo queda archivado y puedes copiar de él. Para mover solo la hora, cancela y reprograma el mismo contenido aprobado si tu rol lo permite.",
+        },
+      },
+      {
+        heading: { en: "What happens at dispatch time", es: "Qué pasa en el momento del despacho" },
+        body: {
+          en: "When the moment arrives, the dispatcher fans the post out to every target platform through the pre-dispatch gate. Each platform gets its own attempt, its own retry with backoff, and its own outcome.\n\nYou do not have to watch it happen, but you can: the receipts arrive in the Inbox and each platform's result is recorded, so a partial failure (three platforms ok, one refused) is visible instead of guessed.",
+          es: "Cuando llega el momento, el despachador reparte la publicación a todas las plataformas destino a través de la compuerta previa al despacho. Cada plataforma recibe su propio intento, su propio reintento con espera progresiva y su propio resultado.\n\nNo hace falta que lo mires, pero puedes: los acuses llegan al Inbox y el resultado de cada plataforma queda registrado, así que un fallo parcial (tres plataformas bien, una rechazada) se ve en vez de adivinarse.",
+        },
+      },
+      {
+        heading: { en: "Receipts", es: "Acuses de recibo" },
+        body: {
+          en: "A receipt is the proof of what actually went out: the text as published, the platform, the timestamp, and the remote reference — the ID the platform assigned. Receipts land in the **Inbox** and are kept in the archive.\n\nKeep them. When a platform throttles, deletes or \"loses\" a post, the receipt plus the archived copy is what lets your collective show what was said and when.",
+          es: "Un acuse es la prueba de lo que realmente salió: el texto tal como se publicó, la plataforma, la marca de tiempo y la referencia remota, el ID que asignó la plataforma. Los acuses llegan al **Inbox** y se guardan en el archivo.\n\nConsérvalos. Cuando una plataforma limita, borra o \"pierde\" una publicación, el acuse más la copia archivada son lo que permite a tu colectivo demostrar qué se dijo y cuándo.",
+        },
+      },
+    ],
+  },
+
+  {
+    slug: "streams",
+    title: { en: "Streams — the column wall", es: "Streams — el muro de columnas" },
+    blurb: {
+      en: "Watch many platforms at once, add columns, trust that hostile content is rendered safely, and understand cooldowns.",
+      es: "Mira muchas plataformas a la vez, añade columnas, confía en que el contenido hostil se muestra de forma segura y entiende los tiempos de espera.",
+    },
+    sections: [
+      {
+        heading: { en: "What the wall is", es: "Qué es el muro" },
+        body: {
+          en: "**Streams** is the home screen: a wall of live columns side by side, in the style of the old TweetDeck. Each column is one feed — a Mastodon timeline, a Telegram channel, a Bluesky feed, a saved search — scrolling as new posts arrive.\n\nThe point is situational awareness during an action: instead of switching apps, you see the street, the press, the trolls and your own channels in one glance.",
+          es: "**Streams** es la pantalla de inicio: un muro de columnas en vivo una al lado de la otra, al estilo del viejo TweetDeck. Cada columna es una fuente — una línea de tiempo de Mastodon, un canal de Telegram, un feed de Bluesky, una búsqueda guardada — que se desplaza cuando llegan publicaciones nuevas.\n\nLa idea es tener lectura de situación durante una acción: en vez de saltar entre apps, ves la calle, la prensa, los trolls y tus propios canales de un vistazo.",
+        },
+      },
+      {
+        heading: { en: "Adding a column", es: "Añadir una columna" },
+        body: {
+          en: "Press **Columns** at the top of the streams page (on mobile it is the columns button in the top bar). Pick a feed from the list of connected accounts, or choose **All feeds** to watch everything at once. The column opens immediately at the right edge of your wall.\n\nTo watch a search instead of a feed, run the search from **Search** and use **Save a search as a column** — then the column shows every new post matching those words, on every platform you follow.",
+          es: "Pulsa **Columns** en la parte superior de la página de streams (en el móvil es el botón de columnas en la barra de arriba). Elige una fuente de la lista de cuentas conectadas, o marca **All feeds** para verlo todo junto. La columna se abre de inmediato en el borde derecho de tu muro.\n\nPara vigilar una búsqueda y no una fuente, hazla desde **Search** y usa **Save a search as a column**: la columna mostrará cada publicación nueva que coincida con esas palabras, en todas las plataformas que sigues.",
+        },
+      },
+      {
+        heading: { en: "Moving around the wall", es: "Moverse por el muro" },
+        body: {
+          en: "Columns scroll independently: drag within one column to read its history, and scroll the page sideways to reach the next. With a keyboard, **j** and **k** move between posts, **r** reposts and **q** quotes — the shortcut hints are printed under the wall.\n\n**Load older posts** at the bottom of a column pages further back in time. Loading older content never disturbs the live top of the column, so you cannot lose the newest post by reading history.",
+          es: "Las columnas se desplazan de forma independiente: arrastra dentro de una columna para leer su historial y desplázate de lado en la página para llegar a la siguiente. Con teclado, **j** y **k** mueven entre publicaciones, **r** repite y **q** cita — las pistas de atajos están impresas bajo el muro.\n\n**Load older posts** al pie de una columna avanza más atrás en el tiempo. Cargar contenido viejo nunca molesta la parte superior en vivo de la columna, así que no puedes perder la publicación más nueva por leer el historial.",
+        },
+      },
+      {
+        heading: { en: "Acting on a post", es: "Actuar sobre una publicación" },
+        body: {
+          en: "Hover or tap a post to get its actions: **Repost** (or **Boost** on Mastodon), **Quote** with your own commentary, and **Share** where the platform supports forwarding. **Open compose** takes the text into a new draft when you want to answer at length.\n\nActions only appear for platforms that truly allow them — there is no \"no amplify\" dead button. If an account is read-only, the column still shows the feed; the buttons simply do not offer what the platform forbids.",
+          es: "Pasa el cursor o toca una publicación para ver sus acciones: **Repost** (o **Boost** en Mastodon), **Quote** con tu propio comentario y **Share** donde la plataforma permita reenviar. **Open compose** lleva el texto a un borrador nuevo cuando quieres responder con calma.\n\nLas acciones solo aparecen en plataformas que de verdad las permiten: no hay botones muertos. Si una cuenta es de solo lectura, la columna muestra la fuente igual, pero los botones no ofrecen lo que la plataforma prohíbe.",
+        },
+      },
+      {
+        heading: { en: "Safe rendering: why a nasty post cannot hurt you", es: "Renderizado seguro: por qué una publicación maliciosa no puede dañarte" },
+        body: {
+          en: "Columns show content written by strangers, some of them hostile. TMBH never runs that content as-is: it is sanitised and rendered inside a locked frame, so hidden scripts, tracking pixels and auto-loading junk are stripped before anything reaches your browser.\n\nThis has been tested against deliberately hostile HTML. Practically: you can leave the wall open all day without a post executing anything on your machine. Media you do see is proxied through the server, so platforms do not learn your members' IP addresses.",
+          es: "Las columnas muestran contenido escrito por desconocidos, algunos hostiles. TMBH nunca ejecuta ese contenido tal cual: se limpia y se renderiza dentro de un marco cerrado, de modo que scripts ocultos, píxeles rastreadores y basura de carga automática se eliminan antes de llegar a tu navegador.\n\nEsto se probó contra HTML deliberadamente hostil. En la práctica: puedes dejar el muro abierto todo el día sin que una publicación ejecute nada en tu máquina. Los medios que sí ves pasan por el proxy del servidor, así las plataformas no conocen las IP de tu gente.",
+        },
+      },
+      {
+        heading: { en: "Cooldowns and refresh: why columns pause", es: "Enfriamientos y refresco: por qué las columnas se pausan" },
+        body: {
+          en: "Each source has a cooldown — a minimum pause between fetches. When a platform is slow, refuses, or rate-limits us, the source backs off progressively (the pause grows) instead of hammering it and burning the account. The column shows this state instead of pretending to be fresh.\n\nSo a paused or slow column is the system protecting your account, not a bug. **Refresh** forces one immediate fetch, but it cannot override the platform's limits; if a source stays degraded for long, check the Connections page, where health is tracked per account.",
+          es: "Cada fuente tiene un enfriamiento: una pausa mínima entre consultas. Cuando una plataforma va lenta, se niega o nos limita, la fuente retrocede de forma progresiva (la pausa crece) en vez de golpearla y quemar la cuenta. La columna muestra ese estado en vez de fingir frescura.\n\nAsí que una columna pausada o lenta es el sistema protegiendo tu cuenta, no un fallo. **Refresh** fuerza una consulta inmediata, pero no puede saltarse los límites de la plataforma; si una fuente queda degradada mucho tiempo, revisa la página de Connections, donde se sigue la salud por cuenta.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "connections",
+    title: { en: "Connections", es: "Conexiones" },
+    blurb: {
+      en: "Connect platform accounts, read their health, set per-account rules, and keep several accounts per platform.",
+      es: "Conecta cuentas de plataformas, lee su salud, define reglas por cuenta y mantén varias cuentas por plataforma.",
+    },
+    sections: [
+      {
+        heading: { en: "What a connection is", es: "Qué es una conexión" },
+        body: {
+          en: "A connection is one account of one platform, linked to the workspace: your collective's Mastodon account, its Telegram channel, its Twitch channel, and so on. Nothing can be published, watched or bridged until the connection exists.\n\nCredentials never sit in the browser. They are handed to the encrypted vault (see Settings & security) and only an opaque handle is stored with the connection, so a stolen laptop leaks nothing.",
+          es: "Una conexión es una cuenta de una plataforma, vinculada al espacio de trabajo: la cuenta de Mastodon del colectivo, su canal de Telegram, su canal de Twitch, etc. Nada puede publicarse, vigilarse ni unirse hasta que exista la conexión.\n\nLas credenciales nunca quedan en el navegador. Se entregan a la bóveda cifrada (mira Ajustes y seguridad) y con la conexión solo se guarda un identificador opaco, así que un portátil robado no filtra nada.",
+        },
+      },
+      {
+        heading: { en: "Connecting an account", es: "Conectar una cuenta" },
+        body: {
+          en: "Open **Connections** and press **Connect account**. Choose the **Provider** (the platform), then fill what it asks: for Mastodon the **Instance URL** like https://your-instance.example and the OAuth login; for a Telegram bot the **Bot token**; for other providers the equivalent fields, one step at a time.\n\nFinish with **Connect**. The new account appears in the list with a health indicator. If the platform refuses, the error is shown in full — wrong instance, expired token, missing permission — so you can fix it instead of guessing.",
+          es: "Abre **Connections** y pulsa **Connect account**. Elige el **Provider** (la plataforma) y completa lo que pida: para Mastodon la **Instance URL** tipo https://tu-instancia.ejemplo y el login por OAuth; para un bot de Telegram el **Bot token**; para otras plataformas sus campos equivalentes, un paso por vez.\n\nTermina con **Connect**. La cuenta nueva aparece en la lista con su indicador de salud. Si la plataforma se niega, el error se muestra completo — instancia equivocada, token vencido, permiso faltante — para que lo arregles en vez de adivinar.",
+        },
+      },
+      {
+        heading: { en: "Reading health", es: "Leer la salud" },
+        body: {
+          en: "Every connection shows a state: live (working), degraded (slow or partially limited), or failing. Degraded usually means the platform is rate-limiting us and the system has backed off — the account recovers by itself once the pause expires.\n\nA failing connection needs a human: press **Reconnect** to renew the credential. Channels you can act on are grouped under **Channels**; the page also lists per-account capacity so you can see which account is close to its posting limits before you schedule a fan-out.",
+          es: "Cada conexión muestra un estado: en vivo (funcionando), degradada (lenta o parcialmente limitada) o fallando. Degradada suele significar que la plataforma nos está limitando y el sistema retrocedió; la cuenta se recupera sola cuando expira la pausa.\n\nUna conexión fallida necesita persona: pulsa **Reconnect** para renovar la credencial. Los canales sobre los que puedes actuar se agrupan bajo **Channels**; la página también lista la capacidad por cuenta, para ver cuál está cerca de sus límites de publicación antes de programar una difusión múltiple.",
+        },
+      },
+      {
+        heading: { en: "Several accounts per platform", es: "Varias cuentas por plataforma" },
+        body: {
+          en: "You can connect more than one account on the same platform — the neighbourhood Mastodon plus the press-account Mastodon, two Telegram channels, and so on. Use the **All accounts** filter at the top of the page to see every account at once, or filter by platform.\n\nWhen composing, each connected account is a separate target you can tick or leave out, so a post can go to one Telegram channel and not the other. Keeping accounts separate like this is what lets a burned account be removed without touching the rest.",
+          es: "Puedes conectar más de una cuenta en la misma plataforma: el Mastodon del barrio más el Mastodon de prensa, dos canales de Telegram, etc. Usa el filtro **All accounts** arriba en la página para ver todas las cuentas juntas, o filtra por plataforma.\n\nAl redactar, cada cuenta conectada es un destino aparte que puedes marcar o dejar fuera, así una publicación puede ir a un canal de Telegram y no al otro. Mantener las cuentas separadas así permite retirar una cuenta quemada sin tocar las demás.",
+        },
+      },
+      {
+        heading: { en: "Per-account rules", es: "Reglas por cuenta" },
+        body: {
+          en: "Each connection carries its own rules: posting cadence, cooldown, whether its feed feeds the wall, whether it joins the chat bridge. Set these when you connect or edit them later — they live with the account, not globally, because one platform's limits are not another's.\n\nUse rules to protect scarce accounts: a hard-won press account can be limited to a couple of posts a day while the throwaway accounts carry the volume.",
+          es: "Cada conexión lleva sus propias reglas: cadencia de publicación, enfriamiento, si su fuente alimenta el muro, si se une al puente de chat. Se definen al conectar o se editan después; viven con la cuenta, no de forma global, porque los límites de una plataforma no son los de otra.\n\nUsa las reglas para proteger las cuentas escasas: una cuenta de prensa costosa de conseguir puede limitarse a un par de publicaciones diarias mientras las cuentas desechables cargan el volumen.",
+        },
+      },
+      {
+        heading: { en: "Removing a connection", es: "Quitar una conexión" },
+        body: {
+          en: "Open the account and press **Remove**, then confirm. Removing a connection stops all publishing and watching for that account, and revokes its credential handle from the vault.\n\nDo this as soon as an account is compromised or seized — a removed connection cannot be used to post in your name. History (posts, receipts, archived copies) is not deleted; it stays in the archive as evidence.",
+          es: "Abre la cuenta y pulsa **Remove**, luego confirma. Quitar una conexión detiene toda publicación y vigilancia de esa cuenta y revoca su credencial en la bóveda.\n\nHazlo apenas una cuenta esté comprometida o intervenida: una conexión quitada no puede usarse para publicar en tu nombre. El historial (publicaciones, acuses, copias archivadas) no se borra; queda en el archivo como evidencia.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "live-control-room",
+    title: { en: "Live control room", es: "Sala de control en vivo" },
+    blurb: {
+      en: "Open the multiview, put a source on preview, TAKE it to program, build scenes, add overlays, and mix audio.",
+      es: "Abre la multivista, pon una fuente en previsualización, haz TAKE a programa, arma escenas, añade sobreimpresos y mezcla el audio.",
+    },
+    sections: [
+      {
+        heading: { en: "What the control room is for", es: "Para qué sirve la sala de control" },
+        body: {
+          en: "The **Control Room** is the web version of a TV gallery: you watch every live source at once in a grid, choose what the audience sees, and dress it with titles and tickers. It exists so a collective with laptops and a phone camera can produce a broadcast that looks deliberate.\n\nEverything runs in the browser — no OBS install, no capture cards. Output goes to a PeerTube channel or any generic RTMP/RTMPS destination.",
+          es: "La **Sala de control** es la versión web de una cabina de TV: ves todas las fuentes en vivo a la vez en una cuadrícula, eliges lo que ve la audiencia y lo vistes con títulos y cintillos. Existe para que un colectivo con portátiles y la cámara del móvil produzca una transmisión con pinta de intencional.\n\nTodo corre en el navegador: sin instalar OBS y sin capturadoras. La salida va a un canal de PeerTube o a cualquier destino genérico RTMP/RTMPS.",
+        },
+      },
+      {
+        heading: { en: "Opening it and reading the grid", es: "Abrirla y leer la cuadrícula" },
+        body: {
+          en: "Open **Control Room** from the sidebar. The **multiview layout** selector lets you switch between grid shapes and a columns view, so you can fit four sources on a laptop or a dozen on a big screen. Each tile shows the source name and its state.\n\nTiles are labelled: **PGM** is what is on air right now, **PST** is the preview, and sources that are only samples show **SAMPLE** until the real feed connects. If the production channel is missing, pick it from **Production channel** and press **Reconnect**.",
+          es: "Abre **Control Room** desde la barra lateral. El selector de **multiview layout** permite cambiar entre formas de cuadrícula y una vista de columnas, para meter cuatro fuentes en un portátil o una docena en una pantalla grande. Cada recuadro muestra el nombre de la fuente y su estado.\n\nLos recuadros están rotulados: **PGM** es lo que está al aire ahora, **PST** es la previsualización, y las fuentes que son muestra dicen **SAMPLE** hasta que se conecte la señal real. Si falta el canal de producción, elígelo en **Production channel** y pulsa **Reconnect**.",
+        },
+      },
+      {
+        heading: { en: "Preview, program, TAKE and CUT", es: "Previsualización, programa, TAKE y CUT" },
+        body: {
+          en: "The professional habit is: never switch blind. Tap a source to send it to **PST** (preview) and check it — is the frame right, is the audio up? The audience still sees the old source the whole time.\n\nWhen preview looks good, press **TAKE** to move it to program with a transition, or **CUT** for an instant hard change. Use CUT when something must stop now (a dox attempt on a guest), TAKE the rest of the time so the broadcast breathes. **Lock program** freezes the output so not even Auto-Director can change it — the switcher then shows **LOCKED** until you unlock.",
+          es: "El hábito profesional es: nunca cambiar a ciegas. Toca una fuente para mandarla a **PST** (previsualización) y revísala: ¿el encuadre está bien, el audio subió? La audiencia sigue viendo la fuente vieja todo ese tiempo.\n\nCuando la previsualización luzca bien, pulsa **TAKE** para pasarla a programa con transición, o **CUT** para un cambio seco e inmediato. Usa CUT cuando algo deba parar ya (un intento de doxx sobre una persona invitada), y TAKE el resto del tiempo para que la transmisión respire. **Lock program** congela la salida de modo que ni el Autodirector pueda cambiarla: el conmutador muestra **LOCKED** hasta que la liberes.",
+        },
+      },
+      {
+        heading: { en: "Scenes and layouts", es: "Escenas y composiciones" },
+        body: {
+          en: "A scene is a saved arrangement: one source full screen, picture-in-picture, split screens, and so on. Build a layout once — speaker big, slide small, camera corner — and reuse it all night instead of dragging tiles by hand.\n\nUse the **PST scene** selector on the switcher bar to choose the next scene, then TAKE it. **Select a scene** lists what exists; scenes are part of the production configuration, so an operator change mid-stream does not lose the rundown.",
+          es: "Una escena es una composición guardada: una fuente a pantalla completa, imagen dentro de imagen, pantallas divididas, etc. Arma la composición una vez — oradora grande, cartel chico, cámara en la esquina — y reusala toda la noche en vez de arrastrar recuadros a mano.\n\nUsa el selector **PST scene** en la barra del conmutador para elegir la próxima escena y luego haz TAKE. **Select a scene** lista las existentes; las escenas son parte de la configuración de producción, así que un cambio de operador en mitad de la transmisión no pierde el guion.",
+        },
+      },
+      {
+        heading: { en: "Overlays: lower thirds, chyrons, clocks, logos", es: "Sobreimpresos: tercios inferiores, cintillos, relojes y logotipos" },
+        body: {
+          en: "Overlays are the graphics laid on top of the program: **lower_third** (name and role under a speaker), **chyron** (the scrolling ticker along the bottom), **clock**, and **logo**. Open the **Overlay editor**, pick the type, and fill its fields — **Title** for the name line and **Chyron text** for the ticker.\n\nChoose a variant and colour (dark/red/outline read best on busy footage), then **Render overlay** to see it composited before anyone else does. If the render shows **Render failed**, the text is usually too long for the box — shorten it rather than fighting the layout.",
+          es: "Los sobreimpresos son los gráficos colocados encima del programa: **lower_third** (nombre y rol bajo quien habla), **chyron** (el cintillo que corre abajo), **clock** y **logo**. Abre el **Overlay editor**, elige el tipo y completa sus campos: **Title** para la línea de nombre y **Chyron text** para el cintillo.\n\nElige variante y color (dark/red/outline se leen mejor sobre imágenes movidas) y pulsa **Render overlay** para verlo compuesto antes que nadie. Si el render muestra **Render failed**, casi siempre el texto es demasiado largo para la caja: acórtalo en vez de pelear con la composición.",
+        },
+      },
+      {
+        heading: { en: "Audio mixing", es: "Mezcla de audio" },
+        body: {
+          en: "Open the **Audio monitor** panel. Each source has its own fader, so you can keep the translation feed low while the street mic carries. **Monitor select** chooses what you hear in your headphones; **Follow program** automatically listens to whatever is on air, and **Custom monitor mix** lets you build your own.\n\nMix with your ears, not your eyes: set levels before the stream starts, during silence, and write the fader positions down — the next operator will thank you. Remember the mix you monitor and the mix the audience gets are controlled separately on purpose.",
+          es: "Abre el panel **Audio monitor**. Cada fuente tiene su fader, así que puedes dejar baja la traducción mientras manda el micrófono de la calle. **Monitor select** elige lo que escuchas en tus auriculares; **Follow program** escucha automáticamente lo que está al aire, y **Custom monitor mix** te deja armar tu propia mezcla.\n\nMezcla con los oídos, no con los ojos: fija los niveles antes de empezar, durante el silencio, y anota las posiciones de los faders: quien opere después te lo agradecerá. Recuerda que la mezcla que vigilas y la que recibe la audiencia se controlan por separado, a propósito.",
+        },
+      },
+      {
+        heading: { en: "Going live", es: "Salir al aire" },
+        body: {
+          en: "Output is defined as destinations: a PeerTube channel or a generic RTMP/RTMPS address, one at a time — a destination is either an address or a vault credential handle, never both at once. When you go live, the credential is redeemed from the vault for the session, so the stream key is never pasted by hand.\n\nThe tally lights on each source confirm what is on program, in green, from the switcher's own state rather than a promise. When the stream ends, stop the destination and the credential handle is released.",
+          es: "La salida se define como destinos: un canal de PeerTube o una dirección RTMP/RTMPS genérica, de a uno — un destino es o una dirección o una credencial de la bóveda, nunca ambas a la vez. Al salir al aire, la credencial se canje de la bóveda para esa sesión, así la clave de transmisión nunca se pega a mano.\n\nLas luces de tally en cada fuente confirman qué está en programa, en verde, según el estado real del conmutador y no una promesa. Al terminar la transmisión, detén el destino y la credencial se libera.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "auto-director",
+    title: { en: "Auto-Director", es: "Autodirector" },
+    blurb: {
+      en: "Teach the switcher which source wins, how long a source must be live before it can be cut, and what happens when everything falls over.",
+      es: "Enseña al conmutador qué fuente gana, cuánto debe estar viva una fuente antes de poder cortarla y qué pasa cuando todo se cae.",
+    },
+    sections: [
+      {
+        heading: { en: "What Auto-Director does", es: "Qué hace el Autodirector" },
+        body: {
+          en: "Auto-Director is the switcher driving itself. When a higher-priority source comes online, it is previewed and taken to program automatically, following the rules your collective wrote. It exists for the nights when one person is handling chat, audio and three cameras at once.\n\nIt is a colleague with perfect attention and no taste: it follows your rules exactly, so write rules that encode your collective's judgement about what matters.",
+          es: "El Autodirector es el conmutador manejándose solo. Cuando aparece en línea una fuente de mayor prioridad, la previsualiza y la pasa a programa automáticamente, siguiendo las reglas que tu colectivo escribió. Existe para las noches en que una sola persona atiende chat, audio y tres cámaras a la vez.\n\nEs un colega con atención perfecta y sin criterio propio: sigue tus reglas al pie de la letra, así que escribe reglas que codifiquen el juicio de tu colectivo sobre qué importa.",
+        },
+      },
+      {
+        heading: { en: "Setting priority rules", es: "Definir las reglas de prioridad" },
+        body: {
+          en: "Priorities are an ordered list of sources: first in the list wins when it is live. Put the breaking street feed first, the speaker second, the slide deck third, and so on. A source not in the list is never auto-taken — that is how you keep the ambient camera from stealing program.\n\nRules are part of the production configuration, so they survive page reloads and operator changes. Change them in rehearsal, not during the action; a mid-stream rule change takes effect on the next switch, which surprises everyone but you.",
+          es: "Las prioridades son una lista ordenada de fuentes: la primera de la lista gana cuando está en vivo. Pon el corte de calle primero, a quien oradora segundo, las diapositivas tercero, y así. Una fuente fuera de la lista nunca se toma automáticamente: así evitas que la cámara ambiente robe el programa.\n\nLas reglas son parte de la configuración de producción, así que sobreviven a recargas de página y cambios de operador. Cámbialas en el ensayo, no durante la acción: un cambio de reglas en plena transmisión surte efecto en el próximo cambio y sorprende a todos menos a ti.",
+        },
+      },
+      {
+        heading: { en: "Dwell: no strobe broadcasts", es: "Permanencia: nada de transmisiones estroboscópicas" },
+        body: {
+          en: "A minimum dwell is the shortest time a source must stay on program before anything else can replace it. Without it, two flapping feeds would cut back and forth every second and the audience would get seasick.\n\nSet dwell longer than the typical burst: five minutes for a march, shorter for a press conference. The switcher queues the pending switch and takes it when the dwell expires, so nothing is lost — it just waits its turn.",
+          es: "La permanencia mínima es el tiempo más corto que una fuente debe quedarse en programa antes de que otra la reemplace. Sin ella, dos señales intermitentes cortarían de un lado a otro cada segundo y la audiencia marearía.\n\nDefine una permanencia mayor que la ráfaga típica: cinco minutos para una marcha, menos para una rueda de prensa. El conmutador deja el cambio en cola y lo ejecuta al expirar, así no se pierde nada: solo espera su turno.",
+        },
+      },
+      {
+        heading: { en: "Manual, auto, and the override window", es: "Manual, auto y la ventana de anulación" },
+        body: {
+          en: "The switcher bar shows the current mode: **MANUAL** means every change is yours; **AUTO** means Auto-Director is driving; **LOCKED** means program is frozen and nothing moves. While in AUTO you can still grab a source manually — that opens an **override** window where your hand beats the rules.\n\nChoose how long the override lasts: **until_released** (until you let go), **five_minutes**, **until_next_event**, or **until_source_offline**. After it expires, Auto-Director resumes command without needing to be re-armed.",
+          es: "La barra del conmutador muestra el modo actual: **MANUAL** significa que cada cambio es tuyo; **AUTO**, que el Autodirector conduce; **LOCKED**, que el programa está congelado y nada se mueve. En AUTO igual puedes tomar una fuente a mano: eso abre una ventana de **override** donde tu mano vence a las reglas.\n\nElige cuánto dura la anulación: **until_released** (hasta que la sueltes), **five_minutes**, **until_next_event** o **until_source_offline**. Al expirar, el Autodirector retoma el mando sin necesidad de reactivarlo.",
+        },
+      },
+      {
+        heading: { en: "Fallback behaviour", es: "Comportamiento de respaldo" },
+        body: {
+          en: "When the program source goes offline mid-stream, Auto-Director does not freeze on a dead frame: it falls to the next live source in priority order, and if nothing is live it goes to the designated hold state rather than black.\n\nThis is why the last entry in your priority list should be something that is always available — a logo card or a looped clip. The fallback is the difference between a glitch and a broadcast that looks like it meant to do that.",
+          es: "Cuando la fuente de programa se cae en plena transmisión, el Autodirector no se congela en un cuadro muerto: cae a la siguiente fuente viva según el orden de prioridad, y si no hay nada vivo pasa al estado de espera designado en vez de a negro.\n\nPor eso la última entrada de tu lista debería ser algo siempre disponible: una tarjeta con el logotipo o un clip en bucle. El respaldo es la diferencia entre una falla y una transmisión que parece planeada.",
+        },
+      },
+    ],
+  },
+
+  {
+    slug: "chat-bridge",
+    title: { en: "Chat bridge", es: "Puente de chat" },
+    blurb: {
+      en: "Bring Telegram, Twitch and Discord into one overlay, moderate from one place, and let flood governors absorb raids.",
+      es: "Reúne Telegram, Twitch y Discord en una sola superposición, modera desde un lugar y deja que los gobernadores de flujo absorban los raids.",
+    },
+    sections: [
+      {
+        heading: { en: "What bridging means", es: "Qué significa unir los chats" },
+        body: {
+          en: "During a stream your audience is split: some on Telegram, some in Twitch chat, some in Discord. The chat bridge pulls all of them into one **Live chat** overlay, with each message labelled by its platform, so moderators read one conversation instead of three windows.\n\nBridging is read-and-reply, not teleportation: people stay on their platform, and your replies go back out to the right one. Reply targets are explicit, so you never answer a Twitch message into the wrong channel.",
+          es: "Durante una transmisión tu audiencia está repartida: parte en Telegram, parte en el chat de Twitch, parte en Discord. El puente de chat junta todo en una superposición de **Live chat**, con cada mensaje etiquetado por plataforma, así quien modera lee una sola conversación en vez de tres ventanas.\n\nUnir no es teletransportar: la gente se queda en su plataforma y tus respuestas salen a la correcta. Los destinos de respuesta son explícitos, así que nunca contestas un mensaje de Twitch en el canal equivocado.",
+        },
+      },
+      {
+        heading: { en: "Opening the overlay", es: "Abrir la superposición" },
+        body: {
+          en: "The **Live chat** panel opens over the streams wall or the control room, wherever the action is. Use **Filter platform** to focus — all, or a single platform — when one room is on fire and the rest can wait.\n\nIf a platform shows as read-only (the **Read-only live chat** marker), your collective has not connected write access for it: you can still see everything, you just cannot post back yet. Ask an Admin to connect the account.",
+          es: "El panel de **Live chat** se abre sobre el muro de streams o la sala de control, donde esté la acción. Usa **Filter platform** para concentrarte — todas, o una sola — cuando una sala se incendia y el resto puede esperar.\n\nSi una plataforma aparece como de solo lectura (la marca **Read-only live chat**), tu colectivo no conectó permiso de escritura: puedes verlo todo, pero todavía no responder. Pide a un Admin que conecte la cuenta.",
+        },
+      },
+      {
+        heading: { en: "Replying and crossposting", es: "Responder y republicar en cruz" },
+        body: {
+          en: "Pick the reply target, type in **Write a reply…** and **Send**. A single answer can go to several platforms at once when it makes sense — a correction, for example, belongs everywhere the mistake travelled.\n\n**Crosspost to…** pushes a message you choose to other connected rooms, clearly framed as coming from the collective. Use it for announcements (\"stream moving, new link in bio\"), not for arguing: crossposted arguments read as panic.",
+          es: "Elige el destino de la respuesta, escribe en **Write a reply…** y **Send**. Una sola respuesta puede ir a varias plataformas a la vez cuando tiene sentido: una corrección, por ejemplo, pertenece a todos lados donde viajó el error.\n\n**Crosspost to…** lleva un mensaje que elijas a otras salas conectadas, claramente enmarcado como del colectivo. Úsalo para anuncios (\"la transmisión se muda, enlace nuevo en la bio\"), no para discutir: las discusiones republicadas en cruz se leen como pánico.",
+        },
+      },
+      {
+        heading: { en: "Moderation tools", es: "Herramientas de moderación" },
+        body: {
+          en: "Moderators get per-message actions: **Delete** removes a message from the overlay, and a timeout removes its author for ten minutes (**Timeout 10 min**). Actions apply on the originating platform too, so a deleted message is deleted where it was written.\n\nIf a moderation action fails — the bot lacks rights in that room — the panel says **Moderation failed** instead of pretending it worked. Fix by giving the bot the moderation permission it needs on that platform, then retry.",
+          es: "Quien modera tiene acciones por mensaje: **Delete** quita un mensaje de la superposición, y un tiempo de espera expulsa a su autor por diez minutos (**Timeout 10 min**). Las acciones se aplican también en la plataforma de origen, así que un mensaje borrado queda borrado donde fue escrito.\n\nSi una acción de moderación falla — al bot le faltan permisos en esa sala — el panel dice **Moderation failed** en vez de fingir que funcionó. Se arregla dándole al bot el permiso de moderación que necesita en esa plataforma, y reintenta.",
+        },
+      },
+      {
+        heading: { en: "Flood governors and raids", es: "Gobernadores de flujo y raids" },
+        body: {
+          en: "A flood governor is a valve on how many messages per second are let through from each room. When a room is raided — hundreds of identical messages at once — the governor drops the excess before it reaches your moderators, and the overlay keeps working instead of melting.\n\nGovernors are per-room, so a flood on Twitch does not silence Telegram. Legitimate heavy traffic still gets through; only the machine-gun rate is cut. If a raid is sustained, the connection's backoff also widens, exactly like on the streams wall.",
+          es: "Un gobernador de flujo es una válvula sobre cuántos mensajes por segundo se dejan pasar de cada sala. Cuando un raid golpea — cientos de mensajes idénticos a la vez — el gobernador descarta el exceso antes de que llegue a quien modera, y la superposición sigue funcionando en vez de derretirse.\n\nLos gobernadores son por sala, así que un flood en Twitch no silencia a Telegram. El tráfico legítimo intenso pasa igual; solo se corta la cadencia de ametralladora. Si el raid se sostiene, la espera de la conexión también se amplía, igual que en el muro de streams.",
+        },
+      },
+      {
+        heading: { en: "Moderation culture, briefly", es: "Cultura de moderación, en breve" },
+        body: {
+          en: "Agree your moderation line before the stream, not during: what gets deleted, what gets timed out, what gets answered. Write it down where every moderator can see it — the wiki is a fine place.\n\nDelete doxx and slurs instantly, time out sealions, answer good-faith questions once and in public so a hundred people read the answer. Nobody should be moderating alone: two short shifts beat one heroic one.",
+          es: "Acuerden la línea de moderación antes de la transmisión, no durante: qué se borra, qué recibe tiempo de espera, qué se responde. Escríbanla donde toda la moderación pueda verla; esta wiki sirve.\n\nBorra doxx e insultos al instante, expulsa temporalmente a quien acosa con falsa buena fe, responde las preguntas honestas una vez y en público para que cien personas lean la respuesta. Nadie debería moderar solo: dos turnos cortos valen más que uno heroico.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "polls-and-voting",
+    title: { en: "Polls and voting", es: "Encuestas y votaciones" },
+    blurb: {
+      en: "Run a vote in the bridged chats, configure quorum arms, vote from Telegram or the web, and let the result post itself.",
+      es: "Haz una votación en los chats unidos, configura los brazos del quórum, vota desde Telegram o la web y deja que el resultado se publique solo.",
+    },
+    sections: [
+      {
+        heading: { en: "What polls are for", es: "Para qué sirven las encuestas" },
+        body: {
+          en: "A poll turns a scattered chat into a decision with a record. It is the tool for the questions that used to be settled by whoever shouted loudest: do we publish the statement, which frame leads the video, do we name the company.\n\nEvery poll has a configuration, a live tally both places can see, and a written outcome that lands in the audit log — so the decision can be revisited without relitigating what was decided.",
+          es: "Una encuesta convierte un chat disperso en una decisión con registro. Es la herramienta para las preguntas que antes resolvía quien gritaba más fuerte: publicamos el comunicado, qué plano abre el video, nombramos a la empresa.\n\nCada encuesta tiene una configuración, un recuento en vivo visible en ambos lados y un resultado escrito que cae en el registro de auditoría, así la decisión puede revisarse sin reabrir lo ya decidido.",
+        },
+      },
+      {
+        heading: { en: "Creating a poll", es: "Crear una encuesta" },
+        body: {
+          en: "Open the chat overlay and create a poll from the poll action. Write the question in plain language, one readable sentence, and give each option a short label — long options get truncated on Telegram.\n\nSet the **timebox**, the hard end of the vote, so it cannot drag forever, and choose whether the vote is anonymous. Anonymous is right for anything where a public position could expose a member.",
+          es: "Abre la superposición de chat y crea una encuesta desde la acción de encuesta. Escribe la pregunta en lenguaje claro, una frase legible, y da a cada opción una etiqueta corta: las opciones largas se cortan en Telegram.\n\nFija el **timebox**, el fin duro de la votación, para que no se arrastre eternamente, y elige si el voto es anónimo. Anónimo es lo correcto para todo lo que una posición pública pueda exponer a alguien.",
+        },
+      },
+      {
+        heading: { en: "Configuring quorum", es: "Configurar el quórum" },
+        body: {
+          en: "Quorum is how you say what a valid decision looks like. There are two kinds of arms: **x of y admins** (a role count) and **x of y participants** (whoever actually voted), and they can be joined with **AND** (both must be satisfied) or **OR** (either is enough).\n\nExample: 1 of 2 admins AND 3 of 5 participants means the vote passes only with an admin's yes and broader support — a guard against a single admin deciding alone, and against a flash mob deciding without any steward. A **veto** arm can also be enabled so one named role can stop a result outright, and **min-dwell** requires a voter to have been present for some time before their vote counts.",
+          es: "El quórum es cómo dices qué aspecto tiene una decisión válida. Hay dos tipos de brazos: **x de y admins** (un conteo por rol) y **x de y participantes** (quienes efectivamente votaron), y se pueden unir con **AND** (ambos deben cumplirse) o **OR** (basta uno).\n\nEjemplo: 1 de 2 admins Y 3 de 5 participantes significa que la votación pasa solo con un sí de un admin y apoyo más amplio: una guarda contra un admin decidiendo solo y contra una turba decidiendo sin ninguna mayordomía. También puede activarse un brazo de **veto** para que un rol nombrado frene el resultado de raíz, y una **permanencia mínima** que exige haber estado presente un tiempo antes de que el voto cuente.",
+        },
+      },
+      {
+        heading: { en: "Voting from Telegram or the web", es: "Votar desde Telegram o la web" },
+        body: {
+          en: "The bot posts the poll into each bridged chat with tappable options, and the same poll is on the web with buttons. Vote wherever you are: a tap on the phone in the street counts exactly the same as a click on a laptop.\n\nThe tally is shared — the bot's message updates as votes arrive, and the web shows the same numbers. Because it is one vote, not a recount, nobody can vote twice on two platforms.",
+          es: "El bot publica la encuesta en cada chat unido con opciones tocables, y la misma encuesta está en la web con botones. Vota donde estés: un toque en el móvil en la calle cuenta exactamente lo mismo que un clic en un portátil.\n\nEl recuento es compartido: el mensaje del bot se actualiza conforme llegan votos y la web muestra los mismos números. Como es una sola votación y no un recuento doble, nadie puede votar dos veces en dos plataformas.",
+        },
+      },
+      {
+        heading: { en: "When quorum passes", es: "Cuando se alcanza el quórum" },
+        body: {
+          en: "The moment quorum is met — inside the timebox — the poll closes and the outcome is recorded with the exact tally. If the poll is bound to a draft, the result flows straight into the approval pipeline: an approved poll can authorise the pending post, which then schedules and dispatches on its own.\n\nIf quorum is not met by the end of the timebox, the poll is recorded as not passed. That is a valid outcome, not a failure: it means the group did not decide, and the draft stays where it was.",
+          es: "En el momento en que se alcanza el quórum — dentro del tiempo límite — la encuesta se cierra y el resultado queda registrado con el recuento exacto. Si la encuesta está ligada a un borrador, el resultado entra directo al circuito de aprobación: una encuesta aprobada puede autorizar la publicación pendiente, que luego se programa y despacha sola.\n\nSi el quórum no se alcanza al terminar el tiempo, la encuesta queda registrada como no aprobada. Es un resultado válido, no un fracaso: significa que el grupo no decidió, y el borrador se queda donde estaba.",
+        },
+      },
+      {
+        heading: { en: "Reading the blocked queue", es: "Leer la cola de bloqueados" },
+        body: {
+          en: "Polls and approvals share the blocked queue: anything stopped shows there with the gap to quorum spelled out — which arm is missing, how many votes short, whose veto landed. That turns \"it didn't pass\" into actionable information.\n\nReopen by addressing the named gap, not by rerunning the vote louder. A poll re-run without changes is how collectives burn out their own voters.",
+          es: "Las encuestas y las aprobaciones comparten la cola de bloqueados: todo lo frenado aparece ahí con la brecha hasta el quórum explicada — qué brazo falta, cuántos votos faltan, de quién fue el veto. Eso convierte \"no pasó\" en información accionable.\n\nReabre atendiendo la brecha nombrada, no repitiendo la votación más fuerte. Repetir una encuesta sin cambios es como los colectivos agotan a su propia gente votante.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "archive",
+    title: { en: "Archive", es: "Archivo" },
+    blurb: {
+      en: "How content-addressed encrypted storage works, how to search it, how to export, and why deleted posts survive here.",
+      es: "Cómo funciona el almacenamiento cifrado por contenido, cómo buscarlo, cómo exportarlo y por qué lo borrado sobrevive aquí.",
+    },
+    sections: [
+      {
+        heading: { en: "What the archive is", es: "Qué es el archivo" },
+        body: {
+          en: "The **Archive** keeps a copy of everything that flowed through the workspace: posts published, posts received from followed sources, their media, and their receipts. Storage is content-addressed and encrypted on S3-compatible storage your collective controls.\n\n\"Content-addressed\" means each item is filed under a fingerprint of its own content rather than a chosen name. Two consequences matter to you: nothing can be silently swapped (a different file has a different address), and identical items are stored once no matter how many times they arrive.",
+          es: "El **Archivo** guarda una copia de todo lo que pasó por el espacio de trabajo: lo publicado, lo recibido de las fuentes seguidas, sus medios y sus acuses. El almacenamiento es por contenido, cifrado y en un S3 compatible que tu colectivo controla.\n\n\"Por contenido\" significa que cada ítem se archiva bajo la huella de su propio contenido y no bajo un nombre elegido. Dos consecuencias te importan: nada puede cambiarse en silencio (un archivo distinto tiene dirección distinta) y los ítems idénticos se guardan una sola vez, lleguen cuantas veces lleguen.",
+        },
+      },
+      {
+        heading: { en: "Why deleted platform content survives here", es: "Por qué lo borrado en las plataformas sobrevive aquí" },
+        body: {
+          en: "When a platform deletes a post — by moderation, by government request, or by \"accident\" — it deletes its copy. Your archive's copy was taken at publish time, addressed by its own fingerprint, and encrypted on your storage. The platform has no lever to reach it.\n\nThis is the archive's political job: the record of what your collective said and what was done to it cannot be edited by the party being documented. Keep the archive storage in hands your assembly trusts; that is now the primary copy of your history.",
+          es: "Cuando una plataforma borra una publicación — por moderación, por pedido gubernamental o por \"accidente\" — borra su copia. La copia de tu archivo se tomó al publicar, quedó identificada por su propia huella y cifrada en tu almacenamiento. La plataforma no tiene palanca para alcanzarla.\n\nEsa es la tarea política del archivo: el registro de lo que dijo tu colectivo y de lo que se le hizo no puede editarlo la parte documentada. Mantén el almacenamiento del archivo en manos que tu asamblea confíe; esa es ahora la copia primaria de tu historia.",
+        },
+      },
+      {
+        heading: { en: "Browsing and searching", es: "Navegar y buscar" },
+        body: {
+          en: "Open **Archive** to browse items newest first, or use **Search**, which runs full-text search across the archive: every word of every stored post is indexed. Search results carry their attribution — channel, author signature, forward origin — so you can tell who said it before you amplify it.\n\nSearch also reaches the same index from the streams wall, so a phrase you half-remember from a march can be found months later. Saved searches can be pinned as columns to watch a topic continuously.",
+          es: "Abre **Archive** para navegar los ítems más nuevos primero, o usa **Search**, que hace búsqueda de texto completo sobre el archivo: cada palabra de cada publicación guardada está indexada. Los resultados traen su atribución — canal, firma de autor, origen del reenvío — así sabes quién lo dijo antes de amplificarlo.\n\nLa búsqueda también llega al mismo índice desde el muro de streams, así que una frase que recuerdas a medias de una marcha aparece meses después. Las búsquedas guardadas pueden fijarse como columnas para vigilar un tema de continuo.",
+        },
+      },
+      {
+        heading: { en: "Turning an archived item back into a post", es: "Convertir un ítem archivado en publicación" },
+        body: {
+          en: "Archived items are not read-only tombstones. From an item you can create a draft — the text and media come along, and attribution can be kept or dropped with the toggle. The draft then enters the normal approval pipeline like any other.\n\nThis is the repost workflow that respects the process: nothing leaves the archive straight to the public; it passes the same review as fresh writing. Keep attribution on unless the source asked otherwise — naming sources is how networks stay trustworthy.",
+          es: "Los ítems archivados no son lápidas de solo lectura. Desde un ítem puedes crear un borrador: el texto y los medios vienen con él, y la atribución puede conservarse o quitarse con el interruptor. El borrador entra luego al circuito de aprobación normal, como cualquier otro.\n\nEste es el flujo de republicación que respeta el proceso: nada sale del archivo directo al público; pasa la misma revisión que lo recién escrito. Conserva la atribución salvo que la fuente pidiera lo contrario: nombrar las fuentes es como las redes se mantienen confiables.",
+        },
+      },
+      {
+        heading: { en: "Exporting", es: "Exportar" },
+        body: {
+          en: "The archive exports to **CSV** (open in any spreadsheet) and **JSON** (for tools and scripts). Export is how the record leaves the building: hand a copy to lawyers, journalists, or another collective that will carry it if your server is seized.\n\nDo exports on a schedule, not on the worst day. A monthly JSON export stored somewhere separate from the server is cheap insurance; the audit log's own export (see that manual) documents who exported what.",
+          es: "El archivo exporta a **CSV** (se abre en cualquier hoja de cálculo) y **JSON** (para herramientas y scripts). Exportar es cómo el registro sale del edificio: entrega una copia a abogacía, prensa u otro colectivo que la cargue si tu servidor es intervenido.\n\nHaz exportaciones con calendario, no el peor día. Un JSON mensual guardado en un lugar separado del servidor es un seguro barato; la exportación del propio registro de auditoría (mira ese manual) documenta quién exportó qué.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "video-transcoding",
+    title: { en: "Video upload and transcoding", es: "Subida y transcodificación de video" },
+    blurb: {
+      en: "Upload footage, watch it move through the transcode queue, and understand the jailed workers that do the heavy lifting.",
+      es: "Sube material, mira cómo avanza por la cola de transcodificación y entiende a los trabajadores enjaulados que hacen el esfuerzo.",
+    },
+    sections: [
+      {
+        heading: { en: "Why transcoding exists", es: "Por qué existe la transcodificación" },
+        body: {
+          en: "A phone records huge files that most platforms and most viewers' connections cannot handle. Transcoding converts your upload into the sizes and formats needed for web playback, thumbnails and live use — without you owning editing software.\n\nYou upload once; the system produces the variants. Upload the highest quality your camera gives, because every later copy is made from that master.",
+          es: "Un móvil graba archivos enormes que ni las plataformas ni las conexiones de la mayoría pueden manejar. La transcodificación convierte lo que subes en los tamaños y formatos necesarios para reproducir en la web, miniaturas y uso en vivo, sin que tengas software de edición.\n\nTú subes una vez; el sistema produce las variantes. Sube con la máxima calidad que dé tu cámara, porque cada copia posterior se hace desde ese máster.",
+        },
+      },
+      {
+        heading: { en: "Uploading", es: "Subir" },
+        body: {
+          en: "Open **Video** and drop your file on **Drop a video here**, or tap to choose it from the device. Large files upload in the background — you can leave the page, the upload continues and the library shows its progress.\n\nName uploads something findable (date-place-what), because in three months \"IMG_4472.mp4\" is a rumour. Once the upload lands, the item appears in the video library with a status chip showing where it is in the pipeline.",
+          es: "Abre **Video** y suelta tu archivo en **Drop a video here**, o tócalo para elegirlo desde el dispositivo. Los archivos grandes se suben en segundo plano: puedes salir de la página, la subida sigue y la biblioteca muestra su progreso.\n\nNombra las subidas de forma localizable (fecha-lugar-qué), porque en tres meses \"IMG_4472.mp4\" es un rumor. Al llegar la subida, el ítem aparece en la biblioteca de video con un chip de estado que indica dónde está en el circuito.",
+        },
+      },
+      {
+        heading: { en: "The pipeline and its states", es: "El circuito y sus estados" },
+        body: {
+          en: "An upload moves through states: uploaded, probing, queued, transcoding, then ready. **Probe metadata** in the detail drawer shows what was found in the file — duration, resolution, codecs — which is how you check a suspicious clip before using it.\n\nIf a job fails, the item says so with the reason; fix what it names (usually a corrupt file or an unsupported codec) and re-upload. Failed jobs never block the rest of the queue.",
+          es: "Una subida pasa por estados: subida, sondeo, en cola, transcodificando y lista. **Probe metadata** en el cajón de detalles muestra qué se encontró en el archivo — duración, resolución, códecs — y así revisas un clip sospechoso antes de usarlo.\n\nSi un trabajo falla, el ítem lo dice con el motivo; corrige lo que señale (casi siempre un archivo corrupto o un códec no soportado) y vuelve a subirlo. Los trabajos fallidos nunca bloquean el resto de la cola.",
+        },
+      },
+      {
+        heading: { en: "Distributed workers", es: "Trabajadores distribuidos" },
+        body: {
+          en: "Transcoding runs on worker machines — literally the GPUs and laptops of collective members — linked over Tailscale, a private network that makes them reachable without exposing anything to the public internet. Jobs are handed to whichever worker is free, and a capacity queue holds the excess until a worker can take it.\n\nSo a long queue does not mean broken; it means busy. If your collective needs faster turns, the fix is another machine running the worker, not faster clicking.",
+          es: "La transcodificación corre en máquinas trabajadoras — literalmente las GPU y portátiles de gente del colectivo — enlazadas por Tailscale, una red privada que las hace alcanzables sin exponer nada al internet público. Los trabajos se entregan a la máquina libre, y una cola de capacidad retiene el exceso hasta que alguna pueda tomarlo.\n\nUna cola larga no significa roto: significa ocupado. Si tu colectivo necesita respuestas más rápidas, la solución es otra máquina corriendo el trabajador, no clickear más rápido.",
+        },
+      },
+      {
+        heading: { en: "Hardware encoding", es: "Codificación por hardware" },
+        body: {
+          en: "Workers use NVENC, the encoder chip built into NVIDIA cards, when one is present. Hardware encoding turns minutes of CPU grinding into seconds — a graphics card from the RTX 3090 class has been proven end to end on this pipeline.\n\nThis is why the collective's gamer machine is genuinely useful infrastructure: plugged in as a worker, it clears the video queue while everyone sleeps. Software encoding still happens on machines without a card, just slower.",
+          es: "Las máquinas usan NVENC, el chip codificador integrado en las tarjetas NVIDIA, cuando hay una presente. La codificación por hardware convierte minutos de moliente CPU en segundos; una tarjeta de la clase de la RTX 3090 está probada de punta a punta en este circuito.\n\nPor eso la máquina gamer del colectivo es infraestructura de verdad: enchufada como trabajadora, despeja la cola de video mientras todos duermen. En máquinas sin tarjeta se codifica por software igual, solo más lento.",
+        },
+      },
+      {
+        heading: { en: "The sandbox: why untrusted video is safe", es: "El sandbox: por qué el video no confiable es seguro" },
+        body: {
+          en: "Video files are untrusted input: malformed files are a classic attack vector. Every FFmpeg job therefore runs in a sandbox — its own user ID, a seccomp filter (a list of system calls it may make), and no network access at all. Each job gets a fresh jail, and resource caps stop one job from starving the machine.\n\nFor you this means: upload footage from anyone, including hostile strangers, without the upload being able to touch the worker machine. Security here is structural, not a matter of trusting people.",
+          es: "Los archivos de video son material no confiable: los archivos malformados son un vector de ataque clásico. Por eso cada trabajo de FFmpeg corre en un sandbox: su propio UID, un filtro seccomp (una lista de llamadas al sistema permitidas) y ninguna clase de acceso a red. Cada trabajo recibe una jaula nueva, y los topes de recursos impiden que un trabajo hambre la máquina.\n\nPara ti esto significa: sube material de cualquiera, incluidos desconocidos hostiles, sin que la subida pueda tocar la máquina trabajadora. La seguridad aquí es estructural, no cuestión de confiar en personas.",
+        },
+      },
+    ],
+  },
+
+  {
+    slug: "analytics",
+    title: { en: "Analytics", es: "Analítica" },
+    blurb: {
+      en: "Read the monthly snapshots, understand what the deltas mean, and break numbers down per provider.",
+      es: "Lee las instantáneas mensuales, entiende qué significan las diferencias y desglosa los números por proveedor.",
+    },
+    sections: [
+      {
+        heading: { en: "What analytics counts — and refuses to count", es: "Qué cuenta la analítica — y qué se niega a contar" },
+        body: {
+          en: "The **Analytics** page shows what your collective did: drafts written, publications sent, attempts per platform, failures, channels, archived items. It counts your outgoing work and the health of your accounts.\n\nWhat it does not do is track your audience like a corporation would. There is no profiling of individuals, no follower demographics, no \"engagement\" panopticon. Reach numbers belong to the platforms; your numbers describe your own machinery.",
+          es: "La página de **Analytics** muestra lo que hizo tu colectivo: borradores escritos, publicaciones enviadas, intentos por plataforma, fallos, canales, ítems archivados. Cuenta tu trabajo de salida y la salud de tus cuentas.\n\nLo que no hace es rastrear a tu audiencia como lo haría una corporación. No hay perfilado de personas, ni demografía de seguidores, ni panóptico de \"interacción\". Los números de alcance son de las plataformas; los tuyos describen tu propia maquinaria.",
+        },
+      },
+      {
+        heading: { en: "Monthly snapshots", es: "Instantáneas mensuales" },
+        body: {
+          en: "Numbers are stored as **Month** snapshots: one frozen picture per month, so a month never changes after it closes. The page shows the current month and the previous month side by side under **Snapshot history**.\n\nBecause each snapshot is fixed, the history is trustworthy — you cannot accidentally rewrite last month by running a report again. New activity lands in the current month's snapshot only.",
+          es: "Los números se guardan como instantáneas por **Month**: una foto congelada por mes, así un mes cerrado nunca cambia. La página muestra el mes en curso y el anterior lado a lado, bajo **Snapshot history**.\n\nComo cada instantánea queda fija, el historial es confiable: no puedes reescribir el mes pasado por accidente volviendo a correr un informe. La actividad nueva cae solo en la instantánea del mes en curso.",
+        },
+      },
+      {
+        heading: { en: "Reading the deltas", es: "Leer las diferencias" },
+        body: {
+          en: "A delta is the difference between this month and the one before, shown next to each figure. A delta answers \"did we do more or less than last month\" — publications up, failures down is the healthy shape.\n\nRead deltas with the calendar, not alone: a month with a big mobilisation should show more of everything; a quiet month does not mean the collective is dying. A rising **Failures** line while **Attempts** stays flat is the one pattern that deserves immediate attention — that is accounts degrading, not effort dropping.",
+          es: "La diferencia (delta) es el cambio entre este mes y el anterior, mostrada junto a cada cifra. Responde a \"hicimos más o menos que el mes pasado\": publicaciones arriba y fallos abajo es la forma sana.\n\nLee las diferencias junto al calendario, no solas: un mes con movilización grande debería mostrar más de todo; un mes tranquilo no significa que el colectivo se muere. Una línea de **Failures** que sube mientras **Attempts** se mantiene plana es el único patrón que merece atención inmediata: eso son cuentas degradándose, no esfuerzo cayendo.",
+        },
+      },
+      {
+        heading: { en: "Per-provider breakdown", es: "Desglose por proveedor" },
+        body: {
+          en: "The per-provider breakdown splits the same figures by platform: **Attempts** and **Failures** per provider, plus **Channels** and **Archived** counts. This is where you see which platform is quietly eating your posts.\n\nUse it for account strategy: a provider with persistent failures gets the fan-out reduced before it burns the account entirely, and the healthiest providers take the volume. Combined with the Connections page you can match failures to specific accounts and reconnect only what is actually broken.",
+          es: "El desglose por proveedor separa las mismas cifras por plataforma: **Attempts** y **Failures** por proveedor, más conteos de **Channels** y **Archived**. Aquí ves qué plataforma se está comiendo tus publicaciones en silencio.\n\nÚsalo para la estrategia de cuentas: a un proveedor con fallos persistentes se le reduce la difusión antes de que queme la cuenta del todo, y los más sanos cargan el volumen. Junto con la página de Connections puedes emparejar fallos con cuentas concretas y reconectar solo lo que de verdad está roto.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "team-management",
+    title: { en: "Team management", es: "Gestión del equipo" },
+    blurb: {
+      en: "Invite members, understand each role, control invite links, and remove access when someone leaves.",
+      es: "Invita miembros, entiende cada rol, controla los enlaces de invitación y quita el acceso cuando alguien se va.",
+    },
+    sections: [
+      {
+        heading: { en: "Where team lives", es: "Dónde está el equipo" },
+        body: {
+          en: "Open **Team** (Admins and Owners only). The page lists every member with their **Role** and **Status**, plus the active **Invite links** and their counters.\n\nOnly roles you are allowed to grant appear as choices; an Admin who cannot mint Owners simply will not see that option, which prevents accidental privilege escalation better than a warning dialog.",
+          es: "Abre **Team** (solo Admin y Owner). La página lista a cada miembro con su **Role** y **Status**, además de los **Invite links** activos y sus contadores.\n\nSolo aparecen como opciones los roles que puedes conceder; un Admin que no puede crear Owners simplemente no ve esa opción, lo que evita escaladas de privilegios accidentales mejor que un aviso emergente.",
+        },
+      },
+      {
+        heading: { en: "Inviting a member by email", es: "Invitar a una persona por correo" },
+        body: {
+          en: "Enter their address (teammate@studio.io), pick a role, and press **Send invite**. They receive a link that creates their account inside your workspace with the role you chose.\n\nBefore you send, ask yourself whether this person needs write access or just needs to see. Viewer is the safest role that still lets someone follow the work; you can always raise it later, and raising is easier than recovering from a leaked Editor password.",
+          es: "Escribe su correo (compañera@studio.io), elige un rol y pulsa **Send invite**. Recibirán un enlace que crea su cuenta dentro de tu espacio de trabajo con el rol que elegiste.\n\nAntes de enviar, pregúntate si esa persona necesita escribir o solo ver. Viewer es el rol más seguro que aún permite seguir el trabajo; siempre puedes subirlo después, y subir es más fácil que recuperarse de una contraseña de Editor filtrada.",
+        },
+      },
+      {
+        heading: { en: "Invite links, and why they expire", es: "Enlaces de invitación y por qué caducan" },
+        body: {
+          en: "Press **Create link** to mint a shareable invite instead of an email: set **Max uses (optional)** and an expiry under **Expires**, then hand the link over Signal or in person. The **Uses** counter shows how many people have joined through it.\n\nLinks exist because actions happen fast, but every live link is a door. **Revoke** any link the moment the people you expected have joined, and let the rest expire on their own — a link nobody can revoke is a liability, not a convenience.",
+          es: "Pulsa **Create link** para crear una invitación compartible en vez de un correo: fija **Max uses (opcional)** y una caducidad en **Expires**, y pasa el enlace por Signal o en persona. El contador de **Uses** muestra cuánta gente entró por él.\n\nLos enlaces existen porque las acciones son rápidas, pero cada enlace vivo es una puerta. **Revoke** cualquier enlace apenas entre la gente que esperabas, y deja que el resto caduque solo: un enlace que nadie puede revocar es un pasivo, no una comodidad.",
+        },
+      },
+      {
+        heading: { en: "Choosing the right role", es: "Elegir el rol correcto" },
+        body: {
+          en: "Grant the smallest role that lets the person do their job:\n\n- **Viewer** — follows streams, calendar, archive; changes nothing. Right for most of the collective.\n- **Moderator** — runs the bridged chats during streams.\n- **Editor** — writes drafts and requests approval.\n- **Approver** — votes and blocks in review.\n- **Publisher** — dispatches approved posts and owns the schedule.\n- **BroadcastOperator** — runs the control room and destinations.\n- **Admin** — members, connections, settings.\n- **Owner** — everything, including transfer and deletion. Keep Owners to the people the assembly would trust with the keys to the space.\n\nThe strongest protection is structural: whoever writes should not be the sole approver, and whoever dispatches should not be the only auditor.",
+          es: "Concede el rol más pequeño que le permita hacer su tarea:\n\n- **Viewer** — sigue streams, calendario y archivo; no cambia nada. Para la mayoría del colectivo.\n- **Moderator** — lleva los chats unidos durante las transmisiones.\n- **Editor** — escribe borradores y pide aprobación.\n- **Approver** — vota y bloquea en revisión.\n- **Publisher** — despacha lo aprobado y cuida la programación.\n- **BroadcastOperator** — maneja la sala de control y los destinos.\n- **Admin** — miembros, conexiones, ajustes.\n- **Owner** — todo, incluida la transferencia y el borrado. Reserva Owner para quien la asamblea dejaría con las llaves del local.\n\nLa protección más fuerte es estructural: quien escribe no debería ser el único que aprueba, y quien despacha no debería ser el único que audita.",
+        },
+      },
+      {
+        heading: { en: "Changing or removing access", es: "Cambiar o quitar el acceso" },
+        body: {
+          en: "Open the member row to change their role, or press remove and confirm with **Confirm remove**. Removal takes effect immediately: their session stops working and their invite is spent. Every one of these actions is written to the audit log with your name on it.\n\nRemove access the day someone leaves the collective, not the week after. Parting on good terms is compatible with locking the door — most leaks are old accounts nobody bothered to close.",
+          es: "Abre la fila de la persona para cambiar su rol, o pulsa quitar y confirma con **Confirm remove**. El retiro surte efecto de inmediato: su sesión deja de funcionar y su invitación queda gastada. Cada una de estas acciones queda escrita en el registro de auditoría con tu nombre.\n\nQuita el acceso el día que alguien se va del colectivo, no la semana siguiente. Despedirse bien es compatible con cerrar la puerta: la mayoría de las filtraciones son cuentas viejas que nadie se tomó el trabajo de cerrar.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "audit-log",
+    title: { en: "Audit log", es: "Registro de auditoría" },
+    blurb: {
+      en: "What gets recorded, how the hash chain makes the log tamper-evident, and how to export it for safekeeping.",
+      es: "Qué se registra, cómo la cadena de hashes hace evidente cualquier manipulación y cómo exportarlo para resguardarlo.",
+    },
+    sections: [
+      {
+        heading: { en: "What the audit log is", es: "Qué es el registro de auditoría" },
+        body: {
+          en: "Open **Audit** to see the **Audit trail**: one line per meaningful action, with **When** it happened, **Actor** (who did it), **Action** (what) and **Target** (to what). Publishes, approvals, blocks, role changes, connections, exports, removals — all of it.\n\nThe log answers the questions that come up when things go wrong: who approved that post, who removed that account, who exported the archive last month. It is the collective's memory of its own decisions.",
+          es: "Abre **Audit** para ver el **Audit trail**: una línea por acción relevante, con **When** (cuándo), **Actor** (quién), **Action** (qué) y **Target** (sobre qué). Publicaciones, aprobaciones, bloqueos, cambios de rol, conexiones, exportaciones, retiros: todo.\n\nEl registro responde las preguntas que aparecen cuando algo sale mal: quién aprobó esa publicación, quién quitó esa cuenta, quién exportó el archivo el mes pasado. Es la memoria del colectivo sobre sus propias decisiones.",
+        },
+      },
+      {
+        heading: { en: "Filtering the trail", es: "Filtrar el rastro" },
+        body: {
+          en: "Use the filters at the top: **All actions** / **All actors** narrow the list to one kind of event or one person. Filtering by actor plus action is how you reconstruct a timeline — everything a given person did around a specific incident.\n\nThe trail is long by design; the filters are how you read it. Do not scroll a year of entries when \"approvals by this member, this week\" is two clicks away.",
+          es: "Usa los filtros de arriba: **All actions** / **All actors** acotan la lista a un tipo de evento o a una persona. Filtrar por actor más acción es como reconstruyes una línea de tiempo: todo lo que hizo una persona alrededor de un incidente concreto.\n\nEl rastro es largo a propósito; los filtros son cómo se lee. No desplaces un año de entradas cuando \"aprobaciones de esta persona, esta semana\" está a dos clics.",
+        },
+      },
+      {
+        heading: { en: "The hash chain: tampering that shows", es: "La cadena de hashes: manipular se nota" },
+        body: {
+          en: "Every entry carries a cryptographic hash computed from its own content plus the hash of the entry before it — a chain. Change any entry after the fact and its hash no longer matches the next entry's link, so the break is visible.\n\nIn practice: nobody, including an Owner, can quietly rewrite who approved what. The log can be lost if storage is destroyed, but it cannot be edited in place without the damage being detectable. That asymmetry is what makes the log evidence rather than a diary.",
+          es: "Cada entrada lleva un hash criptográfico calculado a partir de su propio contenido más el hash de la entrada anterior: una cadena. Cambia una entrada después de hecho y su hash deja de coincidir con el enlace de la siguiente, así que la rotura se ve.\n\nEn la práctica: nadie, incluido un Owner, puede reescribir en silencio quién aprobó qué. El registro puede perderse si se destruye el almacenamiento, pero no puede editarse sin que el daño sea detectable. Esa asimetría es lo que convierte el registro en evidencia y no en diario.",
+        },
+      },
+      {
+        heading: { en: "Exporting for safekeeping", es: "Exportar para resguardar" },
+        body: {
+          en: "Export the trail to CSV from the audit page, and store the copy somewhere other than the server. A log that lives only on the machine that could be seized protects nobody.\n\nA healthy rhythm: export after any contested decision, and at least monthly. The export action is itself audited, so the record shows that a copy left — which is exactly what you want a court or a journalists' collective to be able to see.",
+          es: "Exporta el rastro a CSV desde la página de auditoría y guarda la copia en un lugar distinto del servidor. Un registro que vive solo en la máquina que pueden intervenir no protege a nadie.\n\nUn ritmo sano: exporta tras cada decisión discutida y al menos una vez al mes. La exportación está ella misma auditada, así que el registro muestra que salió una copia: exactamente lo que quieres que un tribunal o un colectivo de prensa pueda ver.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "settings-security",
+    title: { en: "Settings and security", es: "Ajustes y seguridad" },
+    blurb: {
+      en: "What the Settings page tells you, how sessions work, and how the encrypted vault protects every credential.",
+      es: "Qué te dice la página de Ajustes, cómo funcionan las sesiones y cómo la bóveda cifrada protege cada credencial.",
+    },
+    sections: [
+      {
+        heading: { en: "What Settings shows", es: "Qué muestra Ajustes" },
+        body: {
+          en: "Open **Settings** to see exactly what the server knows about your current session: username, workspace, role, permissions, and the session state. There are no fake toggles on this page — if the API has no preference for it, the app does not pretend to save one.\n\nWorkspace-level configuration (members, connections, destinations) lives in **Team** and **Connections**, not here. Settings is about you and your session, nothing else.",
+          es: "Abre **Settings** para ver exactamente lo que el servidor sabe de tu sesión actual: usuario, espacio de trabajo, rol, permisos y el estado de la sesión. No hay interruptores de mentira en esta página: si la API no tiene esa preferencia, la app no finge guardarla.\n\nLa configuración a nivel del espacio (miembros, conexiones, destinos) está en **Team** y **Connections**, no aquí. Ajustes trata de ti y de tu sesión, nada más.",
+        },
+      },
+      {
+        heading: { en: "Signing out and shared devices", es: "Cerrar sesión y dispositivos compartidos" },
+        body: {
+          en: "**Sign out** (from Settings or from **More**) ends the session on this device and clears the stored token. On a shared machine — a social centre laptop, a borrowed phone — sign out every single time; the two seconds are the whole defence.\n\nIf you suspect a session is still live somewhere you cannot reach, tell an Admin: access is removed on the server side by removing or re-roling the member, which kills their sessions too.",
+          es: "**Sign out** (desde Settings o desde **More**) termina la sesión en este dispositivo y borra el token guardado. En una máquina compartida — un portátil del centro social, un móvil prestado — cierra sesión cada vez; esos dos segundos son toda la defensa.\n\nSi sospechas que una sesión sigue viva donde no puedes llegar, avisa a un Admin: el acceso se quita del lado del servidor retirando o cambiando el rol de la persona, lo que también mata sus sesiones.",
+        },
+      },
+      {
+        heading: { en: "The encrypted vault", es: "La bóveda cifrada" },
+        body: {
+          en: "Every credential the workspace holds — platform tokens, bot tokens, stream keys — lives in an **encrypted vault**. The app stores only a handle: an opaque reference that lets the system use the credential without ever exposing the secret to a browser.\n\nYou will see this in three places: connecting an account, going live (the RTMP key is redeemed from the vault at the moment of the stream, never typed), and connections being removed (the handle is revoked). Nobody can read your Twitch key out of the UI, because the UI never receives it.",
+          es: "Cada credencial que guarda el espacio de trabajo — tokens de plataformas, tokens de bots, claves de transmisión — vive en una **bóveda cifrada**. La app guarda solo un identificador: una referencia opaca que permite al sistema usar la credencial sin exponer jamás el secreto a un navegador.\n\nLo verás en tres momentos: al conectar una cuenta, al salir al aire (la clave RTMP se canjea de la bóveda en el momento de la transmisión, nunca se teclea) y al quitar conexiones (el identificador se revoca). Nadie puede leer tu clave de Twitch desde la interfaz, porque la interfaz nunca la recibe.",
+        },
+      },
+      {
+        heading: { en: "Practical security habits for the collective", es: "Hábitos prácticos de seguridad para el colectivo" },
+        body: {
+          en: "Security here is mostly habits, not settings:\n\n- Long passwords, one per person; never share accounts — roles exist so you do not have to.\n- Invite links expire; revoke them once the expected people are in.\n- Remove access the day someone leaves.\n- Keep archive and audit exports somewhere other than the server.\n- Assume any platform account can be lost; the archive and the audit log are what survive.\n\nThe threat model is not exotic hackers: it is a seized laptop, a flipped member, a platform ban. All three are survivable if the credentials were compartmentalised and the records were exported.",
+          es: "La seguridad aquí es sobre todo hábitos, no ajustes:\n\n- Contraseñas largas, una por persona; nunca compartan cuentas: los roles existen para que no haga falta.\n- Los enlaces de invitación caducan; revócalos apenas entre la gente esperada.\n- Quita el acceso el día que alguien se va.\n- Guarda las exportaciones de archivo y auditoría en un lugar distinto del servidor.\n- Asume que cualquier cuenta de plataforma puede perderse; el archivo y el registro de auditoría son lo que sobrevive.\n\nEl modelo de amenaza no son hackers exóticos: es un portátil intervenido, un miembro que cambia de bando, un ban de plataforma. Los tres son sobrevivibles si las credenciales estaban compartimentadas y los registros exportados.",
+        },
+      },
+    ],
+  },
+  {
+    slug: "intake-firehose",
+    title: { en: "Intake firehose", es: "Toma de fuentes" },
+    blurb: {
+      en: "Subscribe the workspace to RSS, Telegram, Mastodon and Bluesky sources; watch them flow into columns and the archive.",
+      es: "Suscribe el espacio de trabajo a fuentes RSS, Telegram, Mastodon y Bluesky; mira cómo fluyen a las columnas y al archivo.",
+    },
+    sections: [
+      {
+        heading: { en: "What intake is", es: "Qué es la toma de fuentes" },
+        body: {
+          en: "Intake is the workspace's subscription system: RSS or Atom feeds, Telegram channels, Mastodon accounts and Bluesky feeds you follow, so their new content flows in continuously. Subscribed content lands in two places: the streams wall as columns to read, and the archive as searchable, kept copies.\n\nThis is how a small collective runs a newsroom: you do not need people watching twenty accounts, you need the machine watching them and people reading what matters.",
+          es: "La toma es el sistema de suscripciones del espacio de trabajo: fuentes RSS o Atom, canales de Telegram, cuentas de Mastodon y feeds de Bluesky que sigues, para que su contenido nuevo entre de continuo. Lo suscrito llega a dos lugares: el muro de streams como columnas para leer, y el archivo como copias guardadas y buscables.\n\nAsí un colectivo pequeño maneja una redacción: no necesitas gente vigilando veinte cuentas, necesitas la máquina vigilándolas y gente leyendo lo que importa.",
+        },
+      },
+      {
+        heading: { en: "Subscribing to a source", es: "Suscribir una fuente" },
+        body: {
+          en: "Subscriptions are managed as connections: open **Connections**, press **Connect account**, choose the provider and give it what it needs — the feed URL for RSS, the @channel or numeric chat ID for Telegram, the account for Mastodon or Bluesky. Confirm with **Connect**.\n\nOnce connected, the source is available everywhere a feed can be picked: add it as a column on **Streams** with **Columns**, filter the wall to it, or search its accumulated content from **Search**. There is no separate \"intake\" page to remember — subscriptions are just accounts the workspace follows.",
+          es: "Las suscripciones se gestionan como conexiones: abre **Connections**, pulsa **Connect account**, elige el proveedor y dale lo que pida — la URL del feed para RSS, el @canal o ID numérico de chat para Telegram, la cuenta para Mastodon o Bluesky. Confirma con **Connect**.\n\nUna vez conectada, la fuente queda disponible dondequiera que se pueda elegir un feed: añádela como columna en **Streams** con **Columns**, filtra el muro a ella, o busca su contenido acumulado desde **Search**. No hay una página aparte de \"toma\" que recordar: las suscripciones son simplemente cuentas que el espacio de trabajo sigue.",
+        },
+      },
+      {
+        heading: { en: "From intake to column", es: "De la toma a la columna" },
+        body: {
+          en: "Each subscribed source can be added to the wall as its own column, and **All feeds** merges everything into one firehose view when a night is moving fast. Saved searches turn a phrase (a neighbourhood, a company, a hashtag) into a standing column across all subscribed sources.\n\nRemember the cooldown: each source is fetched on its own pace, so a column shows content as it is fetched, not literally live. That pace is what keeps the accounts healthy.",
+          es: "Cada fuente suscrita puede añadirse al muro como su propia columna, y **All feeds** funde todo en una vista de manguera cuando la noche avanza rápido. Las búsquedas guardadas convierten una frase (un barrio, una empresa, un hashtag) en una columna permanente sobre todas las fuentes suscritas.\n\nRecuerda el enfriamiento: cada fuente se consulta a su propio ritmo, así que una columna muestra el contenido a medida que se consulta, no literalmente en vivo. Ese ritmo es lo que mantiene sanas las cuentas.",
+        },
+      },
+      {
+        heading: { en: "From intake to archive", es: "De la toma al archivo" },
+        body: {
+          en: "Everything that arrives through intake is written to the archive with its attribution — channel title, author signature, forward origin — and its media. That means a channel you follow today is quotable in six months, even if the original was deleted.\n\nProtected-content sources (channels that block copying) are archived too, with the flag set; your record of what arrived is not the same as the platform's permission to redistribute it, so still pass reuse through review and keep attribution on.",
+          es: "Todo lo que llega por la toma se escribe en el archivo con su atribución — título del canal, firma de autor, origen del reenvío — y sus medios. Eso significa que un canal que sigues hoy es citable en seis meses, aunque el original se haya borrado.\n\nLas fuentes con contenido protegido (canales que bloquean la copia) también se archivan, con la marca activada; tu registro de lo que llegó no es lo mismo que el permiso de la plataforma para redistribuirlo, así que pasa igualmente el reúso por revisión y conserva la atribución.",
+        },
+      },
+      {
+        heading: { en: "Per-host budgets and backoff", es: "Presupuestos por host y retroceso" },
+        body: {
+          en: "Each host the intake fetches from has a **rate budget**: a ceiling on how often it may be contacted. Within one platform, each source also has its own cooldown, and when a host is slow or refuses, the system backs off progressively — the pause doubles rather than retries piling up.\n\nBudgets exist so one hungry subscription cannot burn the workspace's standing with a whole platform. If a source's column looks stale for a long while, that is usually backoff in effect: check its health on **Connections** and **Reconnect** only when the credential is the problem.",
+          es: "Cada host del que la toma consulta tiene un **presupuesto de tasa**: un techo sobre cuántas veces puede contactárselo. Dentro de una plataforma, cada fuente tiene además su propio enfriamiento, y cuando un host va lento o se niega, el sistema retrocede de forma progresiva: la pausa se duplica en vez de acumularse reintentos.\n\nLos presupuestos existen para que una suscripción hambrienta no queme la reputación del espacio ante toda una plataforma. Si la columna de una fuente se ve desactualizada un buen rato, suele ser el retroceso actuando: revisa su salud en **Connections** y usa **Reconnect** solo cuando el problema sea la credencial.",
+        },
+      },
+      {
+        heading: { en: "Live source monitoring", es: "Monitoreo de fuentes en vivo" },
+        body: {
+          en: "Live sources can announce themselves instead of being polled: a webhook ingest where the source calls us, verified with HMAC — a shared-secret signature on each delivery, so a forged call is rejected before it touches anything. HLS streams are checked by a probe driver that verifies a playlist is really playable.\n\nFor you this shows up as reliability: a live column that says live really is live, and when a source dies the wall says so instead of showing a frozen picture. Combine intake monitoring with the Control Room to cut between real sources as they come online.",
+          es: "Las fuentes en vivo pueden anunciarse en vez de ser consultadas: una entrada por webhook donde la fuente nos llama, verificada con HMAC — una firma de secreto compartido en cada entrega, así que una llamada falsificada se rechaza antes de tocar nada. Los streams HLS los revisa un controlador de sondeo que verifica que una lista de reproducción de verdad funcione.\n\nPara ti esto se traduce en confiabilidad: una columna en vivo que dice \"en vivo\" de verdad lo está, y cuando una fuente muere el muro lo dice en vez de mostrar una imagen congelada. Combina el monitoreo de la toma con la Sala de control para cortar entre fuentes reales a medida que aparecen.",
+        },
+      },
+    ],
+  },
+];
diff --git a/apps/web/tsconfig.json b/apps/web/tsconfig.json
new file mode 100644
index 0000000..c9dce17
--- /dev/null
+++ b/apps/web/tsconfig.json
@@ -0,0 +1,30 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "jsx": "preserve",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "noEmit": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "lib": [
+      "DOM",
+      "DOM.Iterable",
+      "ES2022"
+    ],
+    "allowJs": true,
+    "incremental": true,
+    "isolatedModules": true
+  },
+  "include": [
+    "src",
+    "next-env.d.ts",
+    ".next/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}
diff --git a/docs/2026-10-09-tweetdeck-on-steroids-call-for-help-ES.pdf b/docs/2026-10-09-tweetdeck-on-steroids-call-for-help-ES.pdf
new file mode 100644
index 0000000..f4d6613
Binary files /dev/null and b/docs/2026-10-09-tweetdeck-on-steroids-call-for-help-ES.pdf differ
diff --git a/docs/2026-10-09-tweetdeck-on-steroids-call-for-help.md b/docs/2026-10-09-tweetdeck-on-steroids-call-for-help.md
new file mode 100644
index 0000000..2c71d61
--- /dev/null
+++ b/docs/2026-10-09-tweetdeck-on-steroids-call-for-help.md
@@ -0,0 +1,94 @@
+# TweetDeck on Steroids — the full feature set
+
+**Call for help — 2026-10-09.** We're looking for **testers** across the whole flow and **intake hackers** for the hard problem at the end of this document. Everything below in the "running today" sections is built and running — this is an invitation to use it, break it, and help finish the rest.
+
+**A self-hosted, multi-platform broadcast newsroom for collectives: a column wall that watches every platform at once, chats that organize themselves, votes that turn into posts, and a live channel behind it all.**
+
+TweetDeck died when X locked its doors. We built what should have replaced it — and went much further. Watch everything, decide together, publish everywhere, mix live, and keep an archive no platform can take away. Self-hosted. No algorithm in between. No platform holding your keys.
+
+---
+
+## The column wall — every platform in one wall
+
+Live columns watch all your connected accounts at once: Mastodon, Telegram, Bluesky, PeerTube, Twitch, and more. The whole collective sees the same picture at the same moment.
+
+Every post is rendered safe (hostile HTML is parsed into a typed format — scripts, tracking pixels and trick links are stripped at ingest and tested against an attack corpus), media is proxied through your server, and duplicates are deduplicated into the archive automatically.
+
+Columns are becoming **editable**: a column can be a platform feed, a **keyword search across platforms** (one query like "acampada26" pulling from every network that allows it), a curated **list of accounts across platforms**, or a saved search. Columns persist per group, can be reordered, paused, and shared.
+
+## Collaborative chats
+
+Chats from every platform bridge into one shared overlay and one web chat — viewers, contributors and moderators in the same room, with flood governors and moderation tools keeping it usable during action.
+
+The chat is a coordination surface, not just a mirror: it sits next to the live program, next to the file store, next to the drafts. What people say in the chat drives what happens in the system.
+
+## Voting and decision making — in the chat, automatically
+
+Run a poll inside any bridged chat: **"post this?"** — and set the rules for what counts as a pass. Configurable per poll:
+
+- approved by **x of y admins**
+- approved by **x of y participants**
+- mixed quorum (admins + participants), veto rights, timeboxes, anonymous or named voting
+
+Votes come in through Telegram buttons and the web overlay — live tally bars, quorum meters, countdowns. Ineligible votes are stored but never counted; vetoes fail the poll instantly; revotes are supported; everything lands in a tamper-evident audit trail.
+
+**When the quorum passes, the posting bot fires automatically** — the approved content goes out to the channel, topic, or account the poll was about. No admin phone in the loop. Decisions happen at the speed of the chat, with the full trail preserved.
+
+## Configurable posting bots — every account, its own rules
+
+Every connected account carries its own settable rules for what it takes to post:
+
+- **immediate** — no gate, post as today
+- **admin-only** — an admin's approval is the whole quorum
+- **quorum** — configurable thresholds of admins and/or participants
+- per **topic** and per **content type** overrides, dry-run shadow mode, timeboxes, reset-on-edit
+
+A rules editor shows the resolved effective policy before you save it — and a blocked queue shows every post waiting on its quorum with a live gap meter. Nothing is ambiguous about why something did or didn't go out.
+
+## Subchats and topics — structure that follows the work
+
+Forum topics become **subchats**: working groups inside a channel, created and managed by the bot. Accounts are **assigned to topics** — the press crew on the press topic, the stream crew on the stream topic — and each topic carries its own posting rules and its own view of the store. Topics can be bound to broadcast channels, so a topic isn't just conversation: it's a control surface.
+
+## Chat-linked files — the store organizes itself
+
+Files posted into the chat land in the **group's file store automatically** — content-addressed, encrypted, deduplicated (the same clip shared five times is stored once).
+
+Admins organize: assign items to folders, copy them across subfolder trees, refile by type or date — from **chat commands** (`/ls`, `/find`, `/move`) or from the **mobile file screen** that lives next to the chat, with deep links from bot messages straight into the filtered folder view.
+
+Bot listings, search across the whole library, and an audit of every move: the file storage stays organized because the people in the chat keep it organized, from their phones.
+
+## Cross-amplification and retweets — one approval, every platform
+
+One approved draft fans out to every connected account, native to each platform. Where a platform has native quoting (Mastodon quote posts, Bluesky, Telegram forwards), it's used. Where it doesn't, the system generates a proper attributed quote — author, instance, link back — never a silent copy-paste.
+
+Amplifying a sister collective's post keeps their names on it by default. Scheduling, per-account timing, and rate awareness come along for free.
+
+## Live video mixing and channel production
+
+The **Control Room** runs in the browser: a multiview grid of every feed, TAKE/CUT between preview and program, scene layouts (single, picture-in-picture, two-up, splits, grid), lower-thirds, scrolling chyrons, clocks and logos as overlays, per-source audio mixing with a tally of what's hot.
+
+**Field streamers** push cameras from a phone straight to your server. The director mixes in the browser; the program goes to your **PeerTube channel**; and when no one is live, the channel keeps broadcasting a scheduled playlist so the station never goes dark.
+
+**Auto-Director** switches sources by priority rules — a streamer goes down, the next source fades in, the fallback slate catches anything else.
+
+**Distributed transcode workers:** laptops and GPUs join as render workers over Tailscale — an RTX 3090 laptop is already transcoding real PeerTube jobs with hardware encoding, verified end to end. More workers join the pool as load rises.
+
+## The backbone
+
+- **Encrypted vault** for every platform credential — the database never sees a plaintext key.
+- **Hash-chained audit log** — every editorial action tamper-evident, forever.
+- **DST-proof scheduling** — the occurrence engine survives clock changes; two scheduled posts that collapse onto the same instant fire exactly once.
+- **Media sandbox** — every FFmpeg job runs in a per-job jail: unprivileged, no network, resource-capped.
+- **An archive that can't be purged** — content-addressed, encrypted, deduplicated. Deleted threads stay citable; yesterday's footage is tomorrow's playlist.
+- **Teams without password-sharing** — roles per account, invite links, people can remove their own access when they move on.
+- **Self-hosted end to end** — no corporate cloud, no accounts needed to run the system itself.
+
+---
+
+## What we're asking for
+
+**Testers.** Take the whole flow for a spin with your real feeds and your real accounts: post through the approval flow, run the column wall, mix a stream in the Control Room, vote in a bridged chat, break the scheduler across timezones, try to break the archive. Every finding makes the next collective's deployment safer.
+
+**Intake hackers.** The hard problem is pulling content from the locked platforms — hashtags, accounts, search columns on X, Instagram, TikTok — without burning accounts or exposing the collective. We have a verified architecture for the sanctioned sources (RSS, fediverse, Bluesky firehose, Telegram, PeerTube, YouTube RSS) and per-URL fetchers for single public posts. What we want is your design input and build help on: bridge services, community-submitted link intake, archive harvesters, and honest assessments of what is and isn't worth the risk. If you've built scrapers, run intake pipelines, or know the platform-integrity arms race from the inside — this is the problem to bring your scars to.
+
+**Stack if you want to hack:** Next.js + NestJS + Postgres (RLS) + Temporal + Redis + S3 + FFmpeg/PeerTube. Self-hosted end to end, multi-tenant, everything audited.
diff --git a/docs/2026-10-09-tweetdeck-on-steroids-call-for-help.pdf b/docs/2026-10-09-tweetdeck-on-steroids-call-for-help.pdf
new file mode 100644
index 0000000..b49892d
Binary files /dev/null and b/docs/2026-10-09-tweetdeck-on-steroids-call-for-help.pdf differ
diff --git a/docs/2026-10-09-tweetdeck-on-steroids-pitch.md b/docs/2026-10-09-tweetdeck-on-steroids-pitch.md
new file mode 100644
index 0000000..f931863
--- /dev/null
+++ b/docs/2026-10-09-tweetdeck-on-steroids-pitch.md
@@ -0,0 +1,26 @@
+# TweetDeck on Steroids
+
+**A self-hosted, multi-platform broadcast newsroom for collectives — a column wall that watches every platform at once, wired into a full live broadcast pipeline.**
+
+TweetDeck died when X locked its doors. We built what should have replaced it: columns that watch Mastodon, Telegram, Bluesky, PeerTube, Twitch and more in one wall — wired into publishing, approvals, live mixing, and an archive that can't be purged. Self-hosted. No algorithm in between. No platform holding your keys.
+
+## How people work together in it
+
+- **The wall is the room.** Live columns watch all your connected accounts at once — every post rendered safe, media proxied, duplicates deduplicated into the archive. The whole collective sees the same picture.
+- **Draft once, approve together, publish everywhere.** Anyone can draft into any account. Every draft goes through configurable group approval before it moves. On sign-off it fans out natively per platform — proper quotes, attribution intact, tamper-evident audit of who decided what.
+- **Roles, not passwords.** Editors draft, reviewers approve, publishers publish — per account, per channel. Invite links bring people in; leaving removes access. No shared logins, no bottlenecks.
+- **Schedule like a station.** Timezone-correct scheduled posts with a DST-proof occurrence engine. Cancel, review, re-schedule — the calendar survives clock changes.
+- **Live control room in the browser.** Multiview grid, TAKE/CUT, preview/program, lower-thirds and chyrons, audio mixing — program out to your PeerTube channel, 24/7 playlist when you're dark. Works from a laptop.
+- **Auto-Director.** Priority rules switch sources automatically so the stream never dies mid-action.
+- **Chat from every platform** bridged into one overlay — viewers heard, moderators acting, the streamer focused on the shot.
+- **Your own transcode workers.** Laptops and GPUs join as render workers over Tailscale — an RTX 3090 laptop is already transcoding real PeerTube jobs. More workers, more channels, all self-hosted.
+- **An archive that can't be purged.** Content-addressed, encrypted, deduplicated. Platforms purge; the archive remembers. Deleted threads stay citable.
+- **Analytics.** Month-by-month snapshots: what published where, what failed, what got archived.
+
+## What we need: testers and scrapers
+
+We're looking for **testers** across the flow — post through approvals, run a column wall against your real feeds, mix a stream, break the scheduler across timezones. And we're looking for help on the **hard problem: intake at scale.** Watching RSS, the fediverse and Telegram is solved. What we want next: reliable ways to pull from the locked platforms — hashtags, accounts, search columns — without burning accounts. If you've built scrapers, run intake pipelines, or know the platform-integrity arms race from the inside, help us design the intake layer: per-URL fetchers, community-submitted links, archive harvesters, bridge services.
+
+## Stack
+
+Next.js + NestJS + Postgres (RLS) + Temporal + Redis + S3 + FFmpeg/PeerTube. Self-hosted end to end, multi-tenant, everything audited.
diff --git a/docs/admin-guide.md b/docs/admin-guide.md
new file mode 100644
index 0000000..99d258e
--- /dev/null
+++ b/docs/admin-guide.md
@@ -0,0 +1,133 @@
+# Tactical Media Broadcast Hub — Administrator Guide
+
+For operators running Tactical Media Broadcast Hub for one or more workspaces. Engineering detail lives in [engineering-guide.md](./engineering-guide.md); end-user help in [user-guide.md](./user-guide.md).
+
+---
+
+## 1. Quick start (development)
+
+```bash
+pnpm install
+docker compose -f infra/docker-compose.yml up -d postgres redis temporal
+# dev extras: --profile dev  (adds media-worker stub, mock live source, mock RTMP sink)
+
+pnpm --filter @tactical-media-broadcast-hub/api dev          # API on :3000
+pnpm --filter @tactical-media-broadcast-hub/web dev -- -p 3001   # UI on :3001
+pnpm --filter @tactical-media-broadcast-hub/scheduler dev   # Temporal worker
+
+curl localhost:3000/healthz                # {"status":"alive"}
+curl localhost:3000/readyz                 # per-component: postgres/redis/temporal
+```
+
+Default dev ports: API **3000** · Web **3001** · media-worker **3100** · Postgres **5433** (host 5432 was already taken) · Redis 6379 · Temporal 7233 · MinIO 9000 (console 9001) · Prometheus 9090 · Grafana **3001→3000**.
+
+> Docker image pulls can fail when the registry route is degraded (observed: minio/minio denied). Storage/S3 integration tests skip gracefully without an endpoint; everything else runs.
+
+## 2. Environment variables
+
+### API (`apps/api`)
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `DATABASE_URL` | prod | **App pool** — connect as `sp_app` (RLS-bound). Never the owner. |
+| `SUPER_DATABASE_URL` | prod | **Owner pool** — migrations + provisioning only. |
+| `SESSION_SECRET` | prod | HMAC key for session tokens. |
+| `SUPERPOSTER_KEK` | prod | Vault master KEK, 32 bytes base64. Wraps per-workspace DEKs. |
+| `S3_KEK` | prod | Media-encryption KEK, 32 bytes base64. Seals every S3 object. |
+| `S3_ENDPOINT` / `S3_REGION` | prod | S3-compatible endpoint (MinIO, AWS, Spaces…). |
+| `S3_ACCESS_KEY` / `S3_SECRET_KEY` | prod | Storage credentials. |
+| `S3_BUCKET` | no | Default `tactical-media-broadcast-hub-media`. |
+| `S3_FORCE_PATH_STYLE` | no | `true` (default) for MinIO; `false` for AWS virtual-host style. |
+| `OIDC_ISSUER` / `OIDC_CLIENT_ID` / `OIDC_CLIENT_SECRET` / `OIDC_REDIRECT_URI` | prod | Any compliant OIDC IdP (Authentik, Keycloak). |
+| `TEMPORAL_ADDRESS` / `TEMPORAL_NAMESPACE` | no | Default `localhost:7233` / `default`. |
+| `POSTGRES_HOST/PORT`, `REDIS_HOST/PORT` | no | Readiness probes. Default localhost, pg port **5433**. |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | no | Tracing to the collector; absent = disabled. |
+| `LOG_LEVEL` | no | pino level, default `info`. |
+
+In development, missing KEKs derive stable local fallbacks; **in production the API refuses to start without both KEKs and `SESSION_SECRET`** — encryption cannot be silently skipped.
+
+## 3. Key management (critical)
+
+Generate each key once, store in your secret manager, and back them up **separately from the database**:
+
+```bash
+openssl rand -base64 32   # → SUPERPOSTER_KEK  (credential vault)
+openssl rand -base64 32   # → S3_KEK           (media encryption)
+openssl rand -base64 32   # → SESSION_SECRET
+```
+
+- **Lose `SUPERPOSTER_KEK`** → all stored provider tokens are unrecoverable; users must reconnect accounts.
+- **Lose `S3_KEK`** → the entire media archive is unrecoverable even though the S3 bytes remain.
+- **Rotation:** `SUPERPOSTER_KEK` rotation re-wraps DEKs via the vault's `rotate()`. `S3_KEK` rotation re-wraps per-object CEKs without re-encrypting bodies (roadmap item; see engineering guide §3.8).
+- Both KEKs are distinct from database credentials; changing DB passwords never affects them.
+
+## 4. Database
+
+### 4.1 Roles
+- `tmbh` (docker `POSTGRES_USER`) — superuser, **owner pool only** (migrations via `SUPER_DATABASE_URL`).
+- `sp_app` — created by migration `003_app_role.sql`; `NOSUPERUSER`, grants on all tables/sequences. **All runtime connections.** `FORCE ROW LEVEL SECURITY` means even the table owner cannot silently bypass tenancy.
+
+### 4.2 Migrations
+Ordered SQL files in `apps/api/migrations/` (001 tenants + RLS + audit chain · 002 RBAC seed · 003 sp_app role · 004 NULLIF policy fix · 005 epoch trigger fix · 006 publishing). Idempotent runner (`apps/api/src/db/migrate.ts`) tracks `schema_migrations`:
+
+```bash
+cd apps/api && SUPER_DATABASE_URL='postgresql://tmbh:…@localhost:5433/tmbh' \
+  pnpm exec tsx -e 'import {runMigrations} from "./src/db/migrate.js"; runMigrations("./migrations").then(m => console.log("applied:", m))'
+```
+Integration tests apply migrations automatically when `SUPER_DATABASE_URL` is set.
+
+### 4.3 Backups
+- Nightly `pg_dump` of the `tmbh` DB.
+- S3 bucket lifecycle/replication per your provider (objects are already encrypted client-side; provider snapshots never see plaintext).
+- **KEKs** (§3) — without them backups are unrecoverable.
+
+## 5. Rate & capacity settings (per connection)
+
+Post/rate caps are **settings, never hardcoded**. Three layers, highest wins:
+
+1. **Per-connection override** (workspace settings) — e.g. a news account with elevated API tier declares `dailyPostCap: 100`.
+2. **Deployment env** — `CONNECTOR_RATE_<PROVIDER>_RPS`, `CONNECTOR_RATE_<PROVIDER>_DAILY_POSTS`, `CONNECTOR_RATE_<PROVIDER>_COMMENTS_PER_HOUR`, `CONNECTOR_RATE_<PROVIDER>_TIER_NOTE` (provider upper-cased, dashes→underscores: `CONNECTOR_RATE_INSTAGRAM_DAILY_POSTS`).
+3. **Documented provider defaults** (standard-access caps: Instagram 25 posts/24h, Threads 250/24h — Meta enforces these server-side).
+
+Truth model: raising a value **does not bypass the provider** — it declares what your tier actually permits (news-publisher/advanced-access programs raise real limits) so the scheduler paces within true capacity. The UI warns (`exceedsDocumentedCap`) when an override exceeds the documented cap: the provider will reject the excess unless your tier genuinely allows it.
+
+## 6. Workspaces, roles & permissions
+
+37 permissions across 10 seeded roles (Owner, Admin, Publisher, Editor, Approver, Analyst, Moderator, VideoPublisher, StreamOperator, BroadcastOperator). Role changes bump the workspace `authz_epoch`; affected live sessions fail closed on their next request. Audit every membership change (hash-chained; `audit_verify_chain()` detects tampering).
+
+## 7. Monitoring & health
+
+- `GET /healthz` — liveness (no dependencies).
+- `GET /readyz` — readiness: TCP probes for postgres/redis/temporal, `503` + component detail when degraded.
+- Grafana `http://localhost:3001` (anonymous admin in dev) with Prometheus datasource pre-provisioned; scrape targets for API and media-worker are in `infra/prometheus/prometheus.yml`.
+- Logs: structured JSON; credential-shaped keys are redacted at the logger. Never log raw tokens — the scrubbing is defense-in-depth, not permission.
+
+## 8. Security operations checklist
+
+- [ ] Both KEKs generated, stored in secret manager, backed up off-box.
+- [ ] `DATABASE_URL` uses `sp_app`, never the owner role.
+- [ ] OIDC issuer uses HTTPS; redirect URI exact.
+- [ ] Postgres not exposed beyond the host (compose binds 5433 locally).
+- [ ] Audit-chain verification scheduled (a cron calling `audit_verify_chain` per workspace and alerting on `false`).
+- [ ] Connector credentials rotate on schedule (vault `rotate()`).
+- [ ] S3 bucket: no public access; presigned URLs are the only sharing path.
+
+## 9. Troubleshooting
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| API won't start, "S3_KEK is required" | production without KEKs | set both KEKs (§3) |
+| `tenant context mismatch` errors | SECURITY DEFINER call without matching `withTenant` context | code bug — file an issue; do not grant sp_app more privileges |
+| Sessions mass-invalidated after role change | `authz_epoch` bump (by design) | users re-login once |
+| Scheduler idle, posts stuck `pending` | Temporal down when scheduled | worker sweeps pending rows on startup; verify `TEMPORAL_ADDRESS` |
+| Postgres port conflict | host 5432 occupied | compose maps 5433; set `POSTGRES_PORT` accordingly |
+| MinIO image pull denied | registry degradation | retry later or point `S3_ENDPOINT` at any S3 |
+| Streams columns empty in UI | mock-registry data (API not wired yet) | expected pre-WP3-integration |
+
+## 10. Upgrading
+
+1. Back up DB + confirm KEK backups (§4.3).
+2. `git pull && pnpm install`.
+3. Run migrations (§4.2) — additive by design; expand/contract policy documented per migration.
+4. Restart API, then scheduler.
+5. Watch `/readyz` and the audit chain verification.
diff --git a/docs/asset-creation-guide.md b/docs/asset-creation-guide.md
new file mode 100644
index 0000000..5c333e2
--- /dev/null
+++ b/docs/asset-creation-guide.md
@@ -0,0 +1,97 @@
+# Tactical Media Broadcast Hub — Design Language & Asset Creation Guide
+
+**Brand asset:** `apps/web/public/brand/logo.svg` — the anarchist circle-A with outward-pointing arrows
+**Palette:** Black (#000-#0a0a0b) + Warm Red-Orange (#FF1610 → oklch(0.62 0.22 30)) + semantic colors (green=live, amber=warn)
+**Direction:** Bold, defiant, activist-poster aesthetic. Black t-shirts with red screen-printing. High contrast, no apologies.
+
+---
+
+## The Design DNA
+
+Your logo has five visual elements that define the entire brand:
+
+| Element | What it communicates | How to reuse it |
+|---|---|---|
+| **Circle** | Community, enclosure, the "O" in anarchy | Use for avatars, badges, loading spinners |
+| **The A** | The core symbol — Tactical Media Broadcast Hub, anarchy, action | Use alone for favicons, watermarks, empty states |
+| **Arrows** (5x) | Outward direction — decentralization, spreading the message | Use as accent motifs on buttons, cards, headers |
+| **Black background** | The void we fill | Always the base |
+| **Red #FF1610** | Energy, urgency, defiance | The only accent color |
+
+## Rules for creating new assets
+
+### Rule 1: Two colors only (plus semantic)
+Every asset uses black + #FF1610 (or the warm accent oklch equivalent). Green (live), amber (warn), and deeper red (danger) are reserved for semantic status — never decoration.
+
+### Rule 2: Bold strokes, no gradients
+Minimum stroke weight: 4px at 100px viewport. Think screen-print, not watercolor. No gradients, no shadows, no glow effects.
+
+### Rule 3: Geometric construction
+The logo is pure geometry: circle + triangle + rectangles. New assets should use the same primitives. No organic shapes, no curves that aren't circles/arcs.
+
+### Rule 4: Arrows point outward
+The five arrows on the logo all point away from center. This is the brand's core gesture: spreading outward, pushing content to the edges (the platforms). Reuse this directionality.
+
+### Rule 5: High contrast or nothing
+Every element must be readable at 16px favicon size OR be a hero asset. No subtle textures, no mid-tones for decoration.
+
+---
+
+## Assets to create (in priority order)
+
+### 1. Favicon (32×32 SVG)
+Simplify the logo: just the circle outline + the A path, red on transparent. Drop the arrows and the internal marks.
+```svg
+<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" viewBox="0 0 1200 1200">
+  <g fill="none" stroke="#FF1610" stroke-linecap="round" stroke-linejoin="round">
+    <circle cx="600" cy="610" r="330" stroke-width="120"/>
+    <path d="M 365 915 L 600 250 L 835 915" stroke-width="140"/>
+    <path d="M 250 610 L 950 610" stroke-width="120"/>
+  </g>
+</svg>
+```
+
+### 2. Empty State Illustration (200×200 SVG)
+The circle-A outline at low opacity (30%) with a single red arrow pointing outward. Message sits beside it. This communicates "nothing here yet, but you're ready to broadcast."
+
+### 3. Loading Spinner (48×48 SVG)
+The circle from the logo (no A), rotating. Red stroke, black background. CSS `animation: rotate 1s linear infinite`.
+
+### 4. Hero/Background Image (1920×1080)
+If you want the aerial shot: take a real aerial photo, overlay a black gradient (bottom-heavy), then place the circle-A mark at 15% opacity in the background. The UI sits on top. Alternatively, create a pattern of the circle-A repeated at varying scales/opacities on black.
+
+### 5. Platform Connection Icons
+Each platform (Mastodon, Telegram, etc.) gets a small circular icon in the brand style:
+- Black circle with red stroke
+- The platform's simplified symbol inside (drawn in red strokes, same weight)
+- 32×32 base size
+
+### 6. Banner for Onboarding (1200×400)
+The full logo on the left, "Tactical Media Broadcast Hub" in bold red on the right, on black. Can include the tagline: "Broadcast everywhere. Answer to no one."
+
+---
+
+## How to create assets in Canva (matching this language)
+
+1. **Open your Canva design kit** (the links you shared)
+2. **Set the canvas background to pure black** (#000000)
+3. **Use only these colors:**
+   - Primary: #FF1610 (bright red — the brand color from your SVG)
+   - Warm variant: #E8501E (more orange, for hover states)
+   - Background: #000000 or #0A0A0B
+4. **Use geometric shapes only:** circles, triangles, rectangles, straight lines
+5. **Stroke weight:** thick (equivalent to 8-12px at 1000px canvas)
+6. **No:** gradients, shadows, blur, photos (except for the aerial background), curved lines that aren't circles, pastel colors, blue/purple/green
+7. **Export as:** SVG for icons/illustrations, PNG (1920×1080) for backgrounds
+
+## File format guide
+
+| Asset type | Format | Where to put it |
+|---|---|---|
+| Icons, logos, illustrations | SVG | `apps/web/public/brand/` |
+| Background images | PNG or WebP | `apps/web/public/brand/` |
+| Favicon | SVG (32×32) | `apps/web/public/brand/favicon.svg` |
+| Hero/banner | PNG (1200×400 or 1920×1080) | `apps/web/public/brand/` |
+| Animations | CSS (not GIF) | in the component code directly |
+
+Once you create assets and drop them in `apps/web/public/brand/`, tell me what each one is and I'll wire them into the UI.
diff --git a/docs/decisions/2026-10-09-intake-posture.md b/docs/decisions/2026-10-09-intake-posture.md
new file mode 100644
index 0000000..f76b085
--- /dev/null
+++ b/docs/decisions/2026-10-09-intake-posture.md
@@ -0,0 +1,22 @@
+# Decision: Content intake posture — 2026-10-09
+
+**Decision:** metadata-only + community submissions + Tier-1 sanctioned sources. **No gray-market account farming.**
+
+## Context
+The collective wants an intake firehose: continuous content ingestion from social platforms for media work — hashtags, accounts, search — feeding Streams columns, Compose, and the archive.
+
+## Research base (live-verified 2026-10-09; the research archive lives outside this repository)
+- `2026-10-09-intake-firehose-architecture.md` — per-source feasibility, verified volumes (Jetstream ~52 posts/s measured, Mastodon 300 req/5min anon verified, YouTube channel RSS keyless verified), architecture, storage math (~37 GB/day modeled), phased rollout.
+- `2026-10-09-scraping-feasibility.md` — farm-account + browser-automation scraping: every platform rated Brittle or worse; enforcement record (X C&D'd Nitter Aug 2026; Meta won injunctions specifically on fake-account scraping).
+- `2026-10-09-gray-market-services.md` — the vendor layer exists and is priced ($1–50 aged accounts, SMS pools, captcha farms, proxies, anti-detect browsers, pre-scraped datasets) but delivers +15–20% coverage for 10–30× the cost of the alternative posture, with 60–90% farm-detection probability within a year, material contagion risk to legitimate accounts, and documented identity-crime supply chains.
+
+## Decision
+1. **Tier 1 (build now, zero ban risk, no accounts):** RSS/Atom (incl. YouTube channel RSS), Mastodon public tag/account timelines, Bluesky Jetstream with server-side keyword gate, PeerTube REST, per-URL public fetchers (gallery-dl/instaloader-class).
+2. **Tier 2 (small bounded pool, later):** 1–3 Telegram MTProto session accounts for public channel reading (quiet, warmed, never org-linked); optionally 3–5 read-only X accounts, dedicated egress each, 90-day sunset, kill switches.
+3. **Rejected:** mass account farming, hashtag firehoses via farms, gray-market datasets, managed-scraping retainers — 10–30× cost, existential tail risk, documented identity-crime supply chain (see gray-market ledger §9.4).
+4. **Per-URL ingestion** covers locked platforms: community-submitted public post URLs are fetched individually (gallery-dl/instaloader-class) — categorically different from authenticated crawling.
+
+## Consequences
+- Intake adapters draw from `packages/egress` per-host budgets.
+- Locked-platform columns show community-submitted + metadata-only content; full firehose coverage concentrates on sanctioned sources.
+- Decision revisitable if platform APIs open or a funded data vendor passes legal review.
diff --git a/docs/design/2026-10-09-chat-governance-design.md b/docs/design/2026-10-09-chat-governance-design.md
new file mode 100644
index 0000000..1b5afec
--- /dev/null
+++ b/docs/design/2026-10-09-chat-governance-design.md
@@ -0,0 +1,385 @@
+# Chat Governance Design — Polls · Approval-Gated Posting · Forum Topics · Multi-Account Policies · Telegram Bot Control
+*Design doc: 2026-10-09 · Codebase: `apps/api/src/live-chat/**`, `packages/connector-telegram/src`, `apps/api/src/publishing`, `apps/api/src/media-control`.*
+
+---
+
+## 0. Decision summary (the ten calls this design makes)
+
+| # | Decision |
+|---|---|
+| D1 | **Polls are OURS, not Telegram's.** Ballots live in `poll_votes`; the Telegram card is an inline-keyboard *mirror* edited in place. Native `sendPoll` is allowed **only** for audience sentiment (≤600 s, anonymous, aggregate-only) and can never gate a post. Rationale: 600 s ceiling, anonymous-by-default, no voter roster API, no reopen (polls report §1). |
+| D2 | **Chat-governance bot = grammY 1.46 gateway module** inside the API (`apps/api/src/chat-gov/`), webhook in prod (secret per binding), `@grammyjs/runner` long-poll in dev. Publishing *sends* continue to flow through the existing connector-telegram + Temporal pipeline — the gateway never bulk-posts. |
+| D3 | **Forum topics are a binding registry, not a mirror of Telegram state.** Bot API has no list-topics → we persist `message_thread_id` at creation; enabling forum mode stays a human/MTProto runbook step (documented, no userbot in v1). |
+| D4 | **Posting rules are data, evaluated at three gates (E1/E2/E3)** with precedence `topic > contentType > account > workspace`, whole-block replacement, compiled snapshot + `policy_version` pinned at save and at every decision. **E3 pre-dispatch re-check is mandatory.** |
+| D5 | **Poll-pass NEVER side-channels a platform post.** Pass → `approve`-equivalent transition on a draft (system actor `system:chat-poll-gate`) → existing schedule/publish machinery → E3. Chat-originated posts are auto-materialized as drafts first. |
+| D6 | **Chat commands map 1:1 onto existing `DirectorOperation`** (`take|cut|pst-select|lock|override|desired`); authorization reuses workspace RBAC permissions (`director.take`, `director.lock_program`, …) resolved from immutable Telegram numeric `from.id` → `chat_identities` → membership role. Chat is UX; the control plane stays the enforcement point. |
+| D7 | **Destructive commands are confirmation-gated**: inline CONFIRM/ABORT, 30 s TTL, requester-only callback, dry-run diff echo, nonce; ephemeral `replace_callback_query_message` (Bot API 10.3) when available. |
+| D8 | **Every account/destination evaluates its own policy.** One draft → N destination decision records; partial fan-out (A sent, B blocked) is a first-class outcome. |
+| D9 | **Votes from ineligible users are stored, never counted** (GitLab pattern) and surfaced with `INELIGIBLE_ACTOR`; eligibility is re-read at close time. |
+| D10 | **Anti-abuse reuses what exists**: `SendGovernors`/`TokenBucket` in front of every outbound mirror/ack, grammY throttler (30/s global, 1/s per chat, 20/min group) with `bypassThrottler` for acks, `update_id` dedupe, per-user per-command-class token bucket, and the existing `live_chat_requests` idempotency pattern for close→publish. |
+
+---
+
+## 1. Feature set
+
+### 1a. Polls in bridged chats — configurable pass criteria
+
+**Subject of a poll.** A poll gates a *thing*: a `draft` (existing DraftPost), a *chat post* (text/media composed via `/post` → materialized as a draft, D5), or nothing (free-standing sentiment/procedural vote). Polls are created from the web UI, the overlay, or `/post`+`/poll` in a bound chat.
+
+**Pass criteria — compiled rule object** (stored on the poll at open; never re-resolved mid-flight):
+
+```jsonc
+{
+  "version": 1,
+  "mode": "quorum",                    // immediate | quorum | admin_only
+  "arms": [
+    { "kind": "admins",      "x": 2 },                       // x of workspace Admin/Owner set
+    { "kind": "participants","x": 3, "of": "observed" }      // of: observed | eligible | none(count-only)
+  ],
+  "join": "all",                       // all (AND, default) | any (OR)
+  "allowVeto": true,                   // one veto fails regardless of quorum
+  "minDwellSeconds": 45,               // early close only when quorum ∧ dwell (anti-railroading)
+  "timebox": { "duration": "PT2H", "onExpire": "reject" },   // approve | reject | escalateOwner
+  "anonymity": "named",                // named | anonymous (never mixed silently)
+  "allowSelfApproval": false,          // draft author's yes is stored, not counted
+  "resetOnChange": true,               // draft edit ⇒ approvals reset, poll re-arms
+  "dryRun": false                      // evaluate + log, never block/fire
+}
+```
+
+- **admins arm**: eligibility = workspace membership role ∈ {Owner, Admin} (or `chat_identities.role_override` ≥ that) *evaluated at close time* (TOCTOU guard).
+- **participants arm**: `of:observed` = distinct chat identities seen in the channel since `opens_at` (roster derived from `live_chat_messages` — we already own that table); `of:eligible` = explicit roster bound to the topic/channel; `of:none` = pure count.
+- **mixed** = conjunctive arms (`join:"all"`), the GitHub count+code-owner shape; each arm keeps its own `x`.
+- **State machine**: `open → passed | failed | vetoed | quorum_unreachable | cancelled`. `quorum_unreachable` fires eagerly when remaining eligible voters < needed (grey-the-card UI). Closed is terminal; a re-vote is a **new poll with `parent_poll_id`**.
+- **Close events**: (1) quorum ∧ minDwell → early close; (2) `closes_at` timebox expiry → `onExpire` action; (3) veto → immediate. Evaluation is event-driven (every ballot re-evaluates); the timebox is the only timer (Temporal `pollTimebox` workflow + lazy re-eval on read).
+- **Idempotent close**: state flip and downstream trigger live in one transaction guarded by `poll_outbox` exactly-once claim; double-close cannot double-publish.
+- **Native Telegram polls**: `/sentiment <question> ; <opt1> ; <opt2>…` sends `sendPoll` (anonymous, `open_period` ≤600 s), aggregate mirrored into the overlay card, **never linked to a draft**. Capability-gated: `poll.sentiment`.
+
+### 1b. Poll-pass → automatic posting bot
+
+Two wiring modes per destination policy:
+
+1. **Gate mode (default)**: poll arms = the E2 gate on a draft. Pass → approve transition (system actor, §4) → E3 per destination → connector publish (`sendMessage`/`sendPhoto`/`sendMediaGroup`, `message_thread_id` when topic-bound) → `message_id` stored for edit/withdraw. Fail/veto → `reject` with poll reference.
+2. **Echo mode (small chats)**: poll subject is a chat post with no scheduled fan-out; pass posts the *same content* back into the originating chat/topic via the announce binding. Internally still materializes a draft + one destination (auditability, D5) — the "direct post" is a fan-out of size 1.
+
+Poll-pass can also **trigger compose**: `/post` with attachments creates the draft in `editing`; on pass with `triggerCompose: true` the UI opens the composer pre-loaded with the approved draft for crosspost (WP15 path: fetch media → asset → draft quoting original → normal policies).
+
+### 1c. Forum topics as subchats
+
+- **`topic_bindings`** registry: `(workspace, connection, chat_id, message_thread_id)` → role `announce | control | audit`, plus assigned accounts and linked virtual channel. A topic binding behaves as a **subchat**: it has its own live-chat channel key (its own seq/fanout topic), its own posting policy (highest precedence), its own member roster.
+- **Bot operations**: create (`createForumTopic`, needs `can_manage_topics`), rename (`editForumTopic`), close/reopen (`closeForumTopic`/`reopenForumTopic`), plus `unpinAllForumTopicMessages` on archive. **`deleteForumTopic` is never exposed from chat** (deletes all messages; console-only with confirmation). Enabling forum mode on a supergroup: runbook step for a human admin (Bot API cannot; see research §2). Topic listing/backfill would need MTProto — **deferred**; our registry is authoritative for what we created.
+- **Accounts assigned to topics**: `topic_bindings.account_ids[]` — a destination account may be bound to zero+ topics; posts to that account ride `message_thread_id` of the binding. Unbound announce channels post to the channel root.
+- Auto-topic-per-series: on first approval pass for a show/series, broadcaster auto-creates a color-coded topic (icon colors from the fixed Telegram palette) and binds it; archive closes it. An **audit topic** is auto-created per workspace and kept append-only (every governance decision mirrored there).
+
+### 1d. Multiple accounts per platform, each with posting rules
+
+- Any number of connections per platform (each Telegram connection = one bot token; Mastodon = one handle; …). Policies anchor to **(platform, accountId)** — the account is the policy anchor, platform is an attribute.
+- **Modes**: `immediate` (no gate, still audited) · `quorum` (arms as §1a; `admins`/`participants`/mixed) · `admin_only` (single-admin gate: `quorum:[{kind:admins,x:1}]`, no participant arm, poll optional).
+- Cross-cutting knobs per policy: `timebox.onExpire`, `allowSelfApproval:false`, `resetOnChange:true`, `dryRun`, `fallback:block`.
+- **Precedence**: `topic > contentType > account > workspace default`, most-specific-wins, **whole-block replacement** (no field merges). Compiled at save-time into a resolved snapshot + `policy_version` hash persisted on the binding; evaluation reads only snapshots. Every rule supports `dryRun` (shadow) for onboarding a new policy.
+- Fan-out law (D8): one draft → N destinations → N independent decision records; "fully sent" = all destinations fired.
+
+### 1e. Telegram bot broadcast control
+
+Command grammar (control binding / locked `#control` topic only):
+
+| Command | Maps to | Permission | Confirm? |
+|---|---|---|---|
+| `/tally` | read director state | `director.view` | no |
+| `/pst <sceneId>` | `{type:"pst-select"}` | `director.take` | no |
+| `/take [sceneId]` | `{type:"take"}` | `director.take` | no |
+| `/cut [sceneId]` | `{type:"cut"}` | `director.take` | **yes** |
+| `/lock on` | `{type:"lock",enabled:true}` | `director.lock_program` | no (protective) |
+| `/lock off` / `/unlock` | `{type:"lock",enabled:false}` | `director.lock_program` | **yes** |
+| `/override <mode|off>` | `{type:"override"}` | `director.override_auto` | **yes** |
+| `/start` `/stop` | desired RUNNING/STOPPED | `director.take` | stop: **yes** |
+| `/topics new\|close\|list` | topic registry ops | `chatgov.manage` | no |
+| `/post <text> [+media reply]` | draft + poll | `drafts.create` | no |
+| `/poll` (reply) | open vote on a draft/chat post | `chatgov.vote` | no |
+| `/sentiment …` | native sendPoll | `chatgov.sentiment` | no |
+| `/register` | claim identity → console approval | — | n/a (approval in console) |
+| `/help` | — | — | no |
+
+Channel binding: each control binding carries `linked_channel_id` (the virtual channel commands act on); `/tally` replies with program/preview/lock/override snapshot. Locked channel ⇒ `/take`/`/cut` refused with the interlock reason (state machine enforced server-side in `media-control`, chat only displays).
+
+**Confirmation UX (destructive)**: (1) dry-run diff echo ("program: SRC-A → SRC-B · ch s27-main"); (2) inline `CONFIRM / ABORT` keyboard, `callback_data = cf:<nonce>` (≤64 B); (3) callback accepted **only** from the requesting `from.id`; (4) 30 s TTL → panel self-erases via `replace_callback_query_message` (10.3) or edits to "expired"; (5) `answerCallbackQuery` ack; (6) execution goes through the same idempotent `director()` call the console uses, with the chat nonce as `Idempotency-Key`; (7) result + actor mirrored to the audit topic.
+
+
+---
+
+## 2. Data model
+
+All tables: `workspace_id uuid NOT NULL`, RLS `ENABLE`+`FORCE` with the standard tenant policy (migration lint enforces), all access via `withTenant`, each added to the guards-bypassed RLS denial suite (WP2 convention).
+
+```sql
+-- 001_chatgov.sql (sketch)
+CREATE TABLE polls (
+  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id      uuid NOT NULL,
+  channel_id        uuid,                    -- live-chat channel (nullable: console-only poll)
+  topic_binding_id  uuid,                    -- vote scoped to a subchat when set
+  subject_kind      text NOT NULL CHECK (subject_kind IN ('draft','chat_post','none')),
+  draft_id          uuid,                    -- FK drafts(id) when subject_kind='draft'
+  question          text NOT NULL,           -- 1..300
+  parent_poll_id    uuid,                    -- revote lineage
+  rule              jsonb NOT NULL,          -- compiled §1a object (snapshot at open)
+  policy_version    text NOT NULL,           -- hash of rule at open
+  state             text NOT NULL DEFAULT 'open'
+                    CHECK (state IN ('open','passed','failed','vetoed','quorum_unreachable','cancelled')),
+  opens_at          timestamptz NOT NULL DEFAULT now(),
+  closes_at         timestamptz NOT NULL,    -- opens_at + timebox.duration
+  closed_at         timestamptz,
+  close_reason      text,                    -- quorum_early | timebox | veto | cancelled
+  outbox_state      text NOT NULL DEFAULT 'none'   -- none|claimed|done  (exactly-once close)
+                    CHECK (outbox_state IN ('none','claimed','done')),
+  created_by        uuid NOT NULL,
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE UNIQUE INDEX polls_open_one_per_draft ON polls (workspace_id, draft_id)
+  WHERE state = 'open' AND draft_id IS NOT NULL;      -- one open gate per draft
+CREATE INDEX polls_ws_state ON polls (workspace_id, state, closes_at);
+
+CREATE TABLE poll_votes (
+  poll_id           uuid NOT NULL REFERENCES polls(id),
+  workspace_id      uuid NOT NULL,
+  voter_kind        text NOT NULL CHECK (voter_kind IN ('user','chat_identity','system')),
+  voter_user_id     uuid,                    -- resolved workspace user, when known
+  voter_remote_id   text NOT NULL,           -- provider:from.id (numeric for TG)
+  voter_handle      text NOT NULL,
+  ballot            text NOT NULL CHECK (ballot IN ('yes','no','veto','abstain')),
+  eligible          boolean NOT NULL DEFAULT true,   -- eligibility AT CAST (informational)
+  counted           boolean NOT NULL DEFAULT true,   -- ineligible votes stored, not counted
+  ineligible_reason text,                    -- INELIGIBLE_ACTOR | SELF_APPROVAL_DENIED
+  cast_at           timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (poll_id, voter_remote_id)     -- idempotent upsert; revote = replace ballot
+);
+CREATE INDEX poll_votes_poll ON poll_votes (poll_id, counted);
+
+CREATE TABLE posting_rules (
+  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id      uuid NOT NULL,
+  scope             text NOT NULL CHECK (scope IN ('workspace','account','content_type','topic')),
+  account_id        uuid,                    -- connection id; NULL for workspace
+  topic_binding_id  uuid,                    -- when scope='topic'
+  content_type      text,                    -- 'alert' | 'video' | ... when scope='content_type'
+  policy            jsonb NOT NULL,          -- §1a-shaped rule (minus subject)
+  policy_version    text NOT NULL,           -- compiled snapshot hash at save
+  dry_run           boolean NOT NULL DEFAULT false,
+  created_by        uuid NOT NULL,
+  created_at        timestamptz NOT NULL DEFAULT now(),
+  superseded_by     uuid,
+  UNIQUE (workspace_id, scope, account_id, topic_binding_id, content_type)
+);
+-- Effective policy resolution is done at SAVE time into:
+CREATE TABLE posting_policy_snapshots (
+  workspace_id      uuid NOT NULL,
+  destination_kind  text NOT NULL,           -- 'account' | 'topic'
+  account_id        uuid NOT NULL,
+  topic_binding_id  uuid,
+  effective         jsonb NOT NULL,
+  policy_version    text NOT NULL,
+  resolved_from     jsonb NOT NULL,          -- audit: which scopes contributed
+  updated_at        timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (workspace_id, account_id, topic_binding_id)
+);
+
+CREATE TABLE topic_bindings (
+  id                    uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id          uuid NOT NULL,
+  connection_id         uuid NOT NULL,       -- telegram connection (bot)
+  chat_id               text NOT NULL,       -- numeric -100… preferred (usernames drift)
+  message_thread_id     text,                -- NULL = channel root / whole group
+  binding_type          text NOT NULL CHECK (binding_type IN ('announce','control','audit')),
+  name                  text NOT NULL,       -- 1..128 (Telegram topic name limit)
+  icon_color            integer,             -- one of the 6 fixed TG colors
+  state                text NOT NULL DEFAULT 'active' CHECK (state IN ('active','closed','archived')),
+  account_ids           uuid[] NOT NULL DEFAULT '{}',  -- accounts that post here
+  linked_channel_id     uuid,                -- control: VC this binding commands
+  created_at            timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, connection_id, chat_id, message_thread_id)
+);
+CREATE UNIQUE INDEX topic_bindings_one_control
+  ON topic_bindings (workspace_id, linked_channel_id)
+  WHERE binding_type = 'control' AND linked_channel_id IS NOT NULL;
+
+CREATE TABLE chat_identities (
+  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id      uuid NOT NULL,
+  provider          text NOT NULL,
+  remote_user_id    text NOT NULL,           -- immutable numeric TG id — NEVER username
+  user_id           uuid,                    -- linked workspace user (after /register approval)
+  display_name      text,
+  status            text NOT NULL DEFAULT 'pending'   -- pending|approved|rejected|banned
+                    CHECK (status IN ('pending','approved','rejected','banned')),
+  approved_by       uuid,
+  first_seen_at     timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, provider, remote_user_id)
+);
+
+CREATE TABLE chat_command_audit (
+  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id      uuid NOT NULL,
+  update_id         bigint NOT NULL,         -- Telegram update id (dedupe)
+  binding_id        uuid,                    -- topic binding command arrived on
+  provider          text NOT NULL,
+  remote_user_id    text NOT NULL,
+  user_id           uuid,                    -- resolved identity, if any
+  command           text NOT NULL,           -- '/cut'
+  args              jsonb NOT NULL DEFAULT '{}',
+  permission        text,                    -- RBAC permission required
+  decision          text NOT NULL CHECK (decision IN ('accepted','rejected','unauthorized','unknown_command','rate_limited')),
+  reason            text,                    -- machine code: INELIGIBLE_ACTOR | LOCKED_CHANNEL | CONFIRM_EXPIRED | ...
+  nonce             text,                    -- confirmation nonce when confirm-gated
+  idempotency_key   text,                    -- chat nonce used as director key
+  result_ref        jsonb,                   -- receipt fingerprint / poll id / draft id
+  received_at       timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (workspace_id, provider, update_id)
+);
+CREATE INDEX chat_command_audit_ws_time ON chat_command_audit (workspace_id, received_at DESC);
+
+-- Governance decision records (one per destination per evaluation, §4)
+CREATE TABLE gate_decisions (
+  id                uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id      uuid NOT NULL,
+  draft_id          uuid NOT NULL,
+  destination       jsonb NOT NULL,          -- {platform, accountId, topicBindingId?}
+  gate              text NOT NULL CHECK (gate IN ('E1','E2','E3')),
+  policy_version    text NOT NULL,
+  outcome           text NOT NULL CHECK (outcome IN ('fired','blocked','pending')),
+  inputs            jsonb NOT NULL,          -- approvals, poll tally, quorum gaps
+  reason_codes      text[] NOT NULL DEFAULT '{}',
+  actor             text NOT NULL,           -- 'system:gate-e3' | 'user:<id>' | 'chat_poll:<pollId>'
+  created_at        timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX gate_decisions_draft ON gate_decisions (workspace_id, draft_id, gate);
+
+-- Poll mirror bookkeeping (card = edited, never re-sent)
+CREATE TABLE poll_mirrors (
+  poll_id           uuid NOT NULL,
+  workspace_id      uuid NOT NULL,
+  binding_id        uuid NOT NULL,
+  message_remote_id text NOT NULL,           -- for editMessageText
+  last_edit_at      timestamptz NOT NULL DEFAULT now(),
+  last_render_hash  text NOT NULL,           -- edit-on-change guard
+  PRIMARY KEY (poll_id, binding_id)
+);
+```
+
+**Migration sketch** — single forward migration `001_chatgov.sql`: create the tables above + RLS enable/force + tenant policies + indexes; register retention classes (`poll_votes`, `chat_command_audit`, `gate_decisions` append-hot, monthly-partition candidates per WP2 convention; `polls`/`posting_rules` stay unpartitioned FK parents). Rollback = drop schema objects (no data migration in v1). Decision-record events additionally append to the existing `audit_append` chain (`poll.*`, `policy.*`, `chatcmd.*` actions) so governance lands in the tamper-evident spine.
+
+---
+
+## 3. Bot architecture
+
+**Library: grammY 1.46** (+ `@grammyjs/transformer-throttler`, `@grammyjs/conversations`, `@grammyjs/menu`, `@grammyjs/runner`). TS-first, tracks Bot API 10.3, throttler ships compliant budgets (30/s global · 1/s per chat · 20/min group) and honors 429 `retry_after`; `bypassThrottler` fast-lanes command acks. Telegraf is stale (2024); node-telegram-bot-api is an immature RC — both rejected per research.
+
+**Topology — module, not a new service.** `apps/api/src/chat-gov/`:
+
+```
+chat-gov/
+  telegram-gateway.ts   grammY Bot per approved token; webhook in prod
+                        (POST /webhooks/chatgov/:bindingId, secret_token per
+                        connection), runner+long-poll in dev; 1 poller per token
+  command-router.ts     grammar → RBAC check → confirm gate → control-plane call
+  poll-mirror.ts        poll card render/edit (edit-on-change, 2–5 s throttle)
+  poll-service.ts       open/vote/close/evaluate; emits governance WS frames
+  policy-service.ts     rule CRUD + compile to posting_policy_snapshots
+  gate-evaluator.ts     E1/E2/E3 evaluation + decision records
+  chat-gov.module.ts
+```
+
+- **Bridge to live-chat WS**: inbound TG messages in bound chats → `NormalizedChatEvent` → existing `LiveChatHubService.ingest` (same dedupe, seq, ring buffer); a topic binding supplies its own `channel_id` so each subchat sequences and fans out independently on the existing `chat:<ws>:<channel>` Redis topic. Outbound, `poll-mirror` and acks go through `SendGovernors`-wrapped transports — a new `ChatTransport` impl for telegram whose `send`/`edit` consume the same token buckets. Governance frames ride the same fanout as `kind:"chat"`: new `kind:"poll"` (snapshot + delta), `kind:"poll_closed"`, `kind:"tally"` — same subscribe/ack/resume contract, server-side debounce (≥250 ms coalesce) so vote storms don't flood the overlay.
+- **Capability plumbing**: extend `LiveChatCapability` in `packages/core/src/chat-contract.ts` with `poll: "none" | "vote" | "sentiment"` and `topics: boolean`; `capability-probe.ts` verifies a callback_query round-trip before advertising `vote` (inline keyboards are always sendable; the *callback* is what must work).
+- **Command router pipeline** (order fixed): dedupe on `update_id` → resolve binding (chat_id + thread → topic_bindings) → resolve identity (`chat_identities`, numeric id) → RBAC map (identity.user → membership role → permission via existing permission table; role sources are ours, TG admin flags are display hints only) → per-user per-command-class token bucket → parse/validate args → confirm gate for destructive → call control plane (`media-control.director()`, `publishing`, or chat-gov service) with chat nonce as `Idempotency-Key` → `chat_command_audit` row → reply + audit-topic mirror.
+- **Permission mapping**: `/tally`→`director.view`; `/pst|/take|/cut|/start|/stop`→`director.take`; `/lock`→`director.lock_program`; `/override`→`director.override_auto`; `/topics`→`chatgov.manage`; `/post`→`drafts.create`; `/poll`→`chatgov.vote`; `/register`→self-service + console approval (`chatgov.manage` approves). Unregistered identity ⇒ everything except `/help`, `/register`, `/tally` is `unauthorized`. Unlinked control binding ⇒ commands rejected with `NO_CHANNEL_BOUND`.
+- **Rate limiting, layered**: grammY throttler (outbound API shape) → `SendGovernors` token buckets (our policy: mirror edits ≤1 per 3 s per binding, priority lanes control > notify > bulk) → per-user per-command-class bucket (e.g. `/cut` ≤3/min) → 429 global backoff with jitter. `poll-mirror` edits only when `render_hash` changes.
+
+---
+
+## 4. Quorum evaluation ↔ publishing pipeline
+
+**Draft states today**: `editing → in_review → approved → rejected → scheduled → published`, with `approved_hash`/`approved_revision` pinned at approve time, and `audit_append` per transition. Chat governance plugs into exactly these seams — no parallel pipeline.
+
+**Gates (Argo sync-wave order):**
+
+| Gate | Where | Signal | Fires |
+|---|---|---|---|
+| E1 | `review → approved` transition | RBAC approvals on the draft | Editor submits / console approve |
+| E2 | **Chat poll gate** | `polls.state` outcome | ballot cast (event-driven) or timebox (timer) |
+| E3 | Immediately before each platform dispatch | compiled snapshot + approvals + poll state | connector publish call |
+
+**Flow for a quorum-gated destination:**
+
+1. Draft created (console or `/post`) with N destinations → each destination's effective snapshot resolved → `gate_decisions` rows created `pending`.
+2. Poll opened (auto on submit when an arm requires chat signal, or manually): rule compiled from the destination's most-gating arm; `polls.rule` snapshot + `policy_version` pinned.
+3. **Every ballot** upserts `poll_votes` (idempotent on `(poll_id, voter_remote_id)`) and re-evaluates in the same transaction: eligibility re-read, arms computed, `quorum_unreachable` checked eagerly. Card edits flow through mirror throttle.
+4. **Close** (quorum ∧ minDwell | timebox `onExpire` | veto): claim `outbox_state` (exactly-once), set final state, then in the *same transaction*: pass ⇒ `publishingService` transition `in_review → approved` with **system actor** `system:chat-poll-gate:<pollId>`; veto/fail ⇒ `→ rejected` with reason. The poll id doubles as the idempotency key — replayed closes are no-ops. `approved_hash` pinning stays intact: a post-close draft edit re-validates at E3 and is blocked (`RESET_ON_CHANGE` / hash mismatch).
+5. **E3 pre-dispatch** (Temporal `scheduledPublish` worker, per destination): re-read snapshot + approvals + poll state + `approved_hash`; evaluate; write the `gate_decisions` outcome (`fired`/`blocked` + reason codes); only then connector publish. Partial fan-out is normal: A fires, B blocked ⇒ B's destination shows in the blocked queue with its reason codes and gap-to-quorum.
+6. **Audit trail**: `poll.opened/voted/closed` + `policy.evaluated` + `release.fired/blocked` all append via `audit_append` (tamper-evident chain, actor = system identity with poll ref); every decision record embeds `policy_version`. `admin_only` mode = same path with a 1-arm poll or an E1-only console approval. `immediate` mode = E1 minimal + E3 always.
+
+**Reason codes** (machine-readable, attached to the blocked post object, not just logs): `INSUFFICIENT_QUORUM` (got x, need y, per arm) · `INELIGIBLE_ACTOR` · `SELF_APPROVAL_DENIED` · `TIMEBOX_EXPIRED_AUTO_REJECT` / `..._AUTO_APPROVE` · `RESET_ON_CHANGE` · `PENDING_POLL` · `VETOED` · `OUTSIDE_POLICY` · `POLICY_DRY_RUN` · `OVERRIDDEN_BY_OWNER` · `LOCKED_CHANNEL` · `NO_CHANNEL_BOUND` · `CONFIRM_EXPIRED`.
+
+---
+
+## 5. UI spec
+
+**Poll card (one React component, three mount points: web chat pane, OBS/browser overlay, mobile).**
+- Header: question + author avatar + status chip (`collecting votes → quorum met → passed → publishing` phase ribbon).
+- Body: horizontal **tally bars** per option, width = share, count + % right-aligned; named mode renders **avatar stacks** (max 5 + `+n`) under each bar; anonymous renders a lock glyph and "votes hidden" — never mixed.
+- **Quorum strip**: visually distinct segmented meter per arm — `2/3 admins ●●○ · 1/3 participants ●○○` (dots, not bars: a gate, not an option). Greyed card + "quorum unreachable — 1 eligible voter remaining" when eager-check trips.
+- **Countdown chip** on the card edge; `closing soon` (<10% left) gets emphasis. Terminal state: bars freeze, winner highlighted, outcome ribbon `PASS ✓ / FAIL ✗ / VETO ⛔`, auto-collapse to one line in history after 60 s (overlay immediately).
+- **Interaction**: web/mobile tap a bar (or 👍/👎/veto buttons); Telegram inline keyboard `[👍 2] [👎 1] [⛔ veto]` — the *card*, not chat messages, is the only surface that changes. Revote overwrites; keyboard row re-renders counts on edit.
+- **Overlay mount**: 320–400 px corner card, same component, fed by the same WS frames; server-debounced deltas; resolved state collapses to a single line.
+
+**Vote flow (mobile)**: tap → optimistic bar update (client) → WS confirm (authoritative, replaces optimistic) → haptic + checkmark on your bar. Offline/late frames: card always renders from the last authoritative snapshot (`kind:"poll"` snapshot after `kind:"poll_delta"` catch-up on resume).
+
+**Posting-rules editor** (console, per account and per topic):
+- Left: destination tree (platform → accounts → topics). Right: rule card with mode selector (`immediate / quorum / admin_only`), arm builder rows (`kind` + `x` + `of`), `join` toggle, veto switch, min-dwell, timebox duration + `onExpire` select, anonymity, self-approval, reset-on-change, **dry-run toggle with a badge**.
+- Save action shows the **resolved preview** ("effective for @newsbot: 2-of-admins AND 3 participants, veto on, 2 h → auto-reject") before commit; the compiled `policy_version` hash is displayed. Every save writes `policy.revised` to the audit chain; edits require `chatgov.manage`.
+- **Blocked queue view**: drafts blocked at E2/E3 as first-class cards with gap-to-quorum meter (live), reason-code chips, and actions (nudge voters / open re-vote with `parent_poll_id` / owner override-with-reason).
+
+**Topic management screen**:
+- Grid of topic bindings per connection: name, icon color chip, type badge (announce/control/audit), state (active/closed/archived), assigned accounts, linked VC, live policy summary chip.
+- Actions: create (calls bot `createForumTopic`, persists thread id), rename, close/reopen, bind/unbind accounts, set control link, edit policy (jumps to rules editor scoped to topic), archive (close + unpin). `delete` is deliberately absent (console-only runbook with typed confirmation; destructive to history).
+- Header banner when forum mode is off on the target supergroup: runbook steps (toggle Topics, re-promote bot with `can_manage_topics`) — we cannot detect or fix this from the Bot API; create attempts surface the Telegram error verbatim.
+
+---
+
+## 6. Security
+
+- **Token vault**: bot tokens and any MTProto session are opaque **vault credential handles** (existing envelope-encryption vault, same boundary as stream keys — `credential-handles.ts` pattern). Tokens never appear in DTOs, logs, WS frames, argv, or chat. Gateway reads handles at boot and on rotation; every credential read is audited. Rotation runbook: BotFather `/revoke` → re-vault → gateway reload → old token dead.
+- **Identity**: authorization keyed on immutable numeric `from.id` → `chat_identities` (status `approved` only) → membership role → RBAC permission. **Usernames are never trusted.** Unregistered senders get `/register`, which creates a `pending` identity an admin approves in console — no self-elevation.
+- **Least privilege on-platform**: bot promoted with only `can_post_messages`, `can_edit_messages`, `can_delete_messages`, `can_manage_topics` — never `can_promote_members`.
+- **Anti-abuse**: layered rate limiting (§3); `update_id` uniqueness kills replays; webhook `secret_token` per binding rejects forged updates; per-user per-command-class buckets; flood governors already refuse (not queue) over-budget sends so a poll storm can't wedge the API; poll mirror edit-on-change + render-hash guard; one-open-poll-per-draft unique index stops poll spam gating the same draft; `chat_command_audit` makes every attempt (including rejects) inspectable.
+- **NEVER runs from chat without confirmation** (and some never from chat at all):
+  - *Confirm-gated*: `/cut`, `/unlock`, `/override on`, `/stop` — CONFIRM/ABORT + dry-run diff + 30 s TTL + requester-only callback + nonce idempotency.
+  - *Console-only, never from chat*: credential/token management, role grants and identity approvals, topic **delete**, policy `dry_run`→enforce flips, retention, workspace settings, and any multi-destination bulk publish that would exceed the broadcast lane (bulk always goes through the Temporal pipeline, never a chat command).
+  - *Structurally impossible from chat*: reading vault contents, cross-workspace data (RLS + no chat surface for it), editing another user's draft.
+- **Privacy**: anonymous polls store no voter linkage (ballot rows only for named mode); scrub() applies to all audited diffs (existing pattern); control chatter is confined to the locked `#control` topic, and the audit topic is append-only (bot has no delete there operationally).
+- **Account posture (from scrape-feasibility)**: the multi-account feature targets *our own legitimate accounts* (bots/handles we own). No browser-automation posting, no scraped-account fan-out; any future MTProto admin sidecar (forum-mode enable, topic backfill) stays admin-ops-only, never bulk-posting — that is the documented boundary.
+
+---
+
+## 7. Phased build plan
+
+| Phase | Slice | Deps | Acceptance criteria |
+|---|---|---|---|
+| **P0 — spine** | Migrations (§2 tables + RLS + indexes + retention classes), `policy-service` rule CRUD + compile-to-snapshot, `gate_decisions` writer, RBAC permissions (`chatgov.*`), audit events | WP2 vault/RBAC, WP3 drafts | Migrations idempotent + lint-clean; RLS denial suite covers every new table (workspace B sees zero A rows); policy compile is pure + snapshot hash deterministic; `policy.revised` lands in audit chain |
+| **P1 — E1/E3 gates** | Wire snapshot evaluation into `review→approved` (E1) and the Temporal dispatch worker (E3); blocked queue rows + reason codes; `immediate`/`admin_only` modes live | P0 | `immediate` posts with no gate; `admin_only` blocks until one admin approve; E3 re-check blocks an approval revoked post-approve; partial fan-out observable (A fired, B blocked with codes); no behavior change for existing drafts |
+| **P2 — polls core (web)** | `poll-service` + open/vote/close/evaluate; WS `kind:"poll"` frames; web chat poll card + vote flow; mixed arms, veto, timebox, min-dwell, anonymity; E2 pass→approve integration with exactly-once outbox | P0, P1 | 2-of-admins poll passes → draft `approved` once under 5 concurrent closing triggers; veto fails immediately; timebox auto-reject fires once; ineligible/self votes stored-not-counted with codes; `quorum_unreachable` eager; draft edit after close blocks E3 (`RESET_ON_CHANGE`) |
+| **P3 — Telegram gateway** | grammY module, webhook + secret per binding, identity registry + `/register` approval, command router with RBAC + per-class buckets, `chat_command_audit`, non-destructive commands (`/tally`, `/pst`, `/take`, `/lock on`, `/topics`) | P0 | Replay of same `update_id` is a no-op; unregistered identity gets `unauthorized` + `/register`; wrong-permission command rejected with code + audited; `/take`/`/pst` produce real DirectorReceipts via existing `director()`; `/lock on` on locked channel consistent with console |
+| **P4 — confirm UX + destructive** | CONFIRM/ABORT conversations, nonce idempotency, dry-run diff echo, ephemeral replace (10.3), audit-topic mirror; `/cut`, `/unlock`, `/override`, `/stop` | P3 | `/cut` without confirm never reaches the control plane; confirm panel expires at 30 s; second user's callback on my panel rejected; same nonce can't fire twice; every destructive action mirrored to audit topic with actor + before/after |
+| **P5 — poll mirror + topics** | Inline-keyboard poll cards (`callback_data ≤64B`), edit-on-change throttled through governors, `poll_mirrors`; `topic_bindings` CRUD, bot create/close/rename topics, per-topic policy precedence, subchat channel keys in live-chat, accounts↔topics assignment | P2, P3 | Vote via Telegram button updates web card ≤3 s and vice versa (same WS spine); card edits throttled ≥2 s and only on change (governor test); topic create returns persisted `message_thread_id`; topic policy overrides account policy (precedence test); forum-mode-off surfaces runbook banner |
+| **P6 — rules editor + topic screen + blocked queue** | Console UI (§5): destination tree, arm builder, resolved preview, dry-run badge; topic management grid; blocked queue with gap-to-quorum + override-with-reason; mobile vote polish | P1, P2, P5 | Editor save shows exact effective preview matching compiled snapshot hash; dry-run badge blocks nothing but logs `POLICY_DRY_RUN`; blocked post card shows live gap + reason chips; override requires free-text reason and is audited |
+| **P7 — echo/auto-topic + hardening** | Echo mode (pass→post into same chat/topic as 1-destination fan-out), auto-topic-per-series, `triggerCompose` crosspost hook (WP15), sentiment `sendPoll`, load test (vote storms), secret-scan pass, retention wiring, docs | P5, P6 | Echo post lands in originating topic after pass with `message_id` stored; auto-topic created once per series and closed on archive; 1k votes/min sustained with flat WS queue + no unthrottled mirror edits; secret-scan clean on all gateway paths; docs updated |
+
+**Dependency order**: P0 → P1 → P2 → {P3 → P4} ∥ P5(P2+P3) → P6 → P7. P3 can start immediately after P0 in parallel with P2 (independent seams: inbound commands vs. poll state machine).
+
+**Out of scope v1 (explicit)**: MTProto userbot sidecar (forum-mode enable, topic backfill — runbook doc only), weighted votes, OPA/Rego expression policies, Discord/Discourse poll connectors (schema is provider-neutral; adapters later), paid broadcast (`allow_paid_broadcast`).
+
+---
+
+## 8. Open items (flagged, decided by default)
+1. **`of:eligible` rosters** need a membership UI per topic — v1 ships `admins` + `of:observed` + count-only; explicit rosters land with P6 if asked for.
+2. **Overlay auth for anonymous viewers** voting in browser: v1 restricts overlay poll cards to *display*; voting happens in Telegram/web-app logged-in surface (avoids a new anon-auth surface).
+3. **Multiple bots per workspace**: supported (per-account tokens = blast-radius isolation + independent rate budgets); one poll may still span destinations on different bots — cards mirror per binding.
diff --git a/docs/design/2026-10-09-columns-design.md b/docs/design/2026-10-09-columns-design.md
new file mode 100644
index 0000000..425d3d9
--- /dev/null
+++ b/docs/design/2026-10-09-columns-design.md
@@ -0,0 +1,385 @@
+# WP3 — Editable Multi-Platform Streams Columns: Design
+**Status:** decision-complete design (no implementation) · **Author:** glm-5.3 design agent · **Inputs:** `internal-survey.md`, `platform-research.md`, `docs/work-breakdown.md` WP3, current `streams/page.tsx` + `lib/streams-data.ts`.
+
+---
+
+## 0. Ground rules (non-negotiable constraints this design obeys)
+
+1. **No logged-in scraping, no ToS-gray bridges** except where explicitly signed off (Telegram via RSS-Bridge is the only candidate; deferred, not in scope of the base plan).
+2. **All provider content renders only through `packages/safe-content`** (typed rich-text AST; raw HTML never reaches the client). See §5.
+3. **Every outbound request goes through the `egress` client** and draws from the **per-host budget** (`app.take_host_budget`) machinery shipped by WP7/WP8 — columns add *callers* of that machinery, not a parallel limiter.
+4. **Back-compat:** `GET /feeds` (merged all-feeds view, `meta.connections`, cursor shape) keeps working unchanged. Columns are additive.
+5. **Workspace-scoped everything** (multi-tenant; `workspace_id` in every unique constraint, RLS-checked reads, `draft.view`-class RBAC extended with a `streams.columns.manage` permission — see §5.6).
+
+---
+
+## 1. Column types, schema, migration, API surface
+
+### 1.1 The four column types
+
+| Type | What it shows | Sources resolved at runtime | Example |
+|---|---|---|---|
+| `platform_feed` | One connected account's own home/mentions (today's implicit column, made explicit & editable) | 1 connection × kinds | "Mastodon · @acampada" |
+| `keyword` | One query across N platforms (each platform adapter shapes the query: full-text, hashtag, video-search) | per-(connection or keyless-source) search job | "acampada26" on Bluesky+Mastodon+YouTube |
+| `account_list` | A curated list of accounts across platforms (author timelines / RSS) | per-account author-feed job | "Movement voices" = 5 handles × 3 platforms |
+| `saved_search` | A keyword column created via the existing saved-search UX (localStorage migrated to server) | same as `keyword` | "product" |
+
+`saved_search` is **not a separate engine** — it is `keyword` with `origin: "saved_search"`. It exists as a persisted type so the UI can label, migrate, and later diverge (e.g. notifications) without another migration. Decision: single `type` enum column with the four values; the keyword engine is shared.
+
+### 1.2 Persisted schema (workspace-scoped)
+
+New tables (forward-only numbered SQL migration, additive, no changes to existing tables):
+
+```sql
+-- 1. Column definitions
+CREATE TABLE stream_columns (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id    UUID NOT NULL,
+  type            TEXT NOT NULL CHECK (type IN ('platform_feed','keyword','account_list','saved_search')),
+  title           TEXT NOT NULL,                    -- user-editable, max 80 chars
+  position        INTEGER NOT NULL DEFAULT 0,       -- dense rank; reorder rewrites the tail
+  spec            JSONB NOT NULL,                   -- typed per-type, validated in app layer (below)
+  refresh_policy  JSONB NOT NULL DEFAULT '{}',      -- { "intervalMs"?: number, "paused"?: boolean }
+  created_by      UUID NOT NULL,
+  created_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  updated_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  deleted_at      TIMESTAMPTZ                       -- soft delete keeps feed_items FK-stable
+);
+CREATE UNIQUE INDEX stream_columns_ws_order_uq ON stream_columns (workspace_id, position) WHERE deleted_at IS NULL;
+CREATE INDEX stream_columns_ws_idx ON stream_columns (workspace_id) WHERE deleted_at IS NULL;
+
+-- 2. Resolved sources: what the scheduler actually polls for a column
+CREATE TABLE column_sources (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id    UUID NOT NULL,
+  column_id       UUID NOT NULL REFERENCES stream_columns(id),
+  -- identity of the thing polled:
+  provider        TEXT NOT NULL,                    -- 'bluesky' | 'mastodon' | 'youtube' | ...
+  connection_id   UUID NULL,                        -- NULL for keyless sources (YouTube RSS, public Bluesky/Mastodon)
+  source_kind     TEXT NOT NULL CHECK (source_kind IN ('home','mentions','search','author')),
+  query           TEXT NULL,                        -- platform-adapted query (post-adaptation, what gets sent)
+  actor_ref       TEXT NULL,                        -- canonical account ref for source_kind='author': '{provider}:{handle@host}'
+  state           TEXT NOT NULL DEFAULT 'pending'
+                  CHECK (state IN ('pending','ready','stale','error','unsupported','rate_limited','budget_paused','disabled')),
+  last_error      TEXT NULL,
+  last_polled_at  TIMESTAMPTZ NULL,
+  next_poll_at    TIMESTAMPTZ NULL,
+  consecutive_failures INTEGER NOT NULL DEFAULT 0,
+  UNIQUE (workspace_id, column_id, provider, source_kind, COALESCE(connection_id::text,''), COALESCE(query,''), COALESCE(actor_ref,''))
+);
+CREATE INDEX column_sources_due_idx ON column_sources (next_poll_at) WHERE state NOT IN ('disabled');
+CREATE INDEX column_sources_column_idx ON column_sources (column_id);
+
+-- 3. Ingested items (replaces "cache-only" depth; enables deep pagination + per-column serving)
+CREATE TABLE feed_items (
+  id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id    UUID NOT NULL,
+  dedup_key       TEXT NOT NULL,                    -- see §3.3
+  provider        TEXT NOT NULL,
+  remote_id       TEXT NOT NULL,
+  author_handle   TEXT NOT NULL,
+  author_ref      TEXT NULL,                        -- canonical '{provider}:{handle@host}' when resolvable
+  url             TEXT NULL,                        -- provider permalink (http/https only)
+  created_at_remote TIMESTAMPTZ NOT NULL,           -- provider timestamp (sort key)
+  fetched_at      TIMESTAMPTZ NOT NULL DEFAULT now(),
+  content         JSONB NOT NULL,                   -- safe-content typed AST (NEVER raw HTML) — §5
+  plain_text      TEXT NOT NULL,                    -- derived flat text (for saved-search client filter & search preview)
+  media           JSONB NOT NULL DEFAULT '[]',      -- [{kind:'image'|'video', proxyUrl, width?, height?, alt?}] — proxy-minted only
+  metrics         JSONB NOT NULL DEFAULT '{}',      -- finite numbers only
+  source_id       UUID NOT NULL REFERENCES column_sources(id),
+  expires_at      TIMESTAMPTZ NULL,                 -- set for YouTube Data-API-sourced items: fetched_at + 30d (ToS)
+  UNIQUE (workspace_id, dedup_key)
+);
+CREATE INDEX feed_items_ws_time_idx ON feed_items (workspace_id, created_at_remote DESC, dedup_key DESC); -- keyset
+CREATE INDEX feed_items_source_idx ON feed_items (source_id, created_at_remote DESC);
+CREATE INDEX feed_items_expiry_idx ON feed_items (expires_at) WHERE expires_at IS NOT NULL;
+
+-- 4. Join: which columns show an item (an item ingested for a source is visible to every column sharing that source)
+CREATE TABLE feed_item_columns (
+  workspace_id  UUID NOT NULL,
+  item_id       UUID NOT NULL REFERENCES feed_items(id) ON DELETE CASCADE,
+  column_id     UUID NOT NULL REFERENCES stream_columns(id),
+  PRIMARY KEY (item_id, column_id)
+);
+
+-- 5. Per-provider budget/spend ledger (X pay-per-use, IG 30-tags/7d, YT search bucket)
+CREATE TABLE provider_budget_ledger (
+  workspace_id TEXT NOT NULL,                       -- '' = global (API keys are workspace-owned; see §2.5)
+  provider     TEXT NOT NULL,
+  bucket       TEXT NOT NULL,                       -- 'x_post_reads' | 'ig_hashtag_window' | 'yt_search_calls'
+  window_start TIMESTAMPTZ NOT NULL,
+  units_used   NUMERIC NOT NULL DEFAULT 0,
+  units_cap    NUMERIC NOT NULL,
+  UNIQUE (workspace_id, provider, bucket, window_start)
+);
+```
+
+**Why items are persisted, not just cached:** today's 40-item Redis cache + TTL means cursors die and "Load older" is shallow. Columns are user-curated surfaces; they need stable keyset pagination and cross-column dedup. Redis stays as the hot read-through cache in front of `feed_items`.
+
+**`spec` JSONB shapes** (validated by a zod-style schema in `packages/core`; invalid spec → `422`, never stored):
+
+```ts
+// platform_feed
+{ connectionId: string, kinds: ("home"|"mentions")[] }   // default ["home"]
+// keyword / saved_search
+{ query: string,                       // 1..200 chars, trimmed; no NUL/control chars
+  platforms: string[],                 // provider ids, e.g. ["bluesky","mastodon","youtube"]
+  matchMode?: "any" }                  // reserved; v1 = single term set, no boolean ops
+// account_list
+{ accounts: Array<{ provider: string, handle: string }> } // 1..50 entries; handle free-text "@user@instance.social" | "@user" | "UC..." for YT
+```
+
+`refresh_policy` (clamped server-side): `{ intervalMs?: 60_000..3_600_000, paused?: boolean }`. Defaults per type: `platform_feed` 60 000 (inherits today's effective cadence), `keyword` 120 000, `account_list` 180 000, `saved_search` 300 000. The clamp floor is **never below the per-connection budget-derived interval** — a user setting 60 s on a source whose budget says 300 s gets 300 s and a `meta` hint `effectiveIntervalMs`.
+
+**Keyless sources:** `column_sources.connection_id` is NULL for YouTube-RSS channels, public Bluesky (`getAuthorFeed`/`searchPosts` unauthenticated), and Mastodon public/RSS reads. These draw from the **per-host budget only** (plus a global keyless concurrency cap of 2 in-flight per host), not from any connection's token bucket. This is what lets an account-list column follow YouTube/Mastodon accounts with **zero connections**.
+
+### 1.3 Migration approach
+
+1. **DDL migration** (additive, numbered): the five tables above. No existing table touched.
+2. **Lazy seeding (no backfill job):** on first `GET /feeds/columns` for a workspace with zero rows, the API inserts one `platform_feed` column per feed-capable visible connection (kinds `["home"]`, title `` `${displayName} · ${handle}` ``) — exactly what `liveColumns()` derives client-side today. Seeding is idempotent under the unique `(workspace_id, position)` index (transaction + `ON CONFLICT DO NOTHING` re-check).
+3. **Saved-search migration (opt-in, client-driven):** `POST /feeds/columns/import-saved-searches { terms: string[] }` creates `saved_search` columns (platforms = all search-capable connected/keyless providers). The web app calls it once when localStorage `tmbh.saved-searches` is non-empty and the server list lacks them; on success it clears localStorage and dispatches `saved-searches-change`. LocalStorage remains the fallback when the API is unreachable (sample mode) — no behavior regression offline.
+4. **Rollback story:** columns are additive; disabling the feature flag (`STREAMS_COLUMNS_ENABLED`, default on) falls the UI back to today's derivation path. `/feeds` legacy shape never changes.
+
+### 1.4 API surface
+
+All under the existing feeds module, RBAC `draft.view` to read; **new permission `streams.columns.manage`** (granted to Owner/Admin/Editor by default) to write. Group-visibility: a `platform_feed` column referencing a non-visible connection is rejected `403`; keyword/account columns only see what their sources legitimately fetch.
+
+```
+GET    /feeds/columns                       → { columns: ColumnView[] }   (ordered, with per-source status)
+POST   /feeds/columns                       → 201 ColumnView              (validates spec, resolves column_sources)
+PATCH  /feeds/columns/:id                   → ColumnView                  (title, spec, refresh_policy, position-delta)
+DELETE /feeds/columns/:id                   → 204                         (soft delete; source items expire naturally)
+POST   /feeds/columns/reorder               → { columns: ColumnView[] }   { orderedIds: string[] } — rewrites positions
+POST   /feeds/columns/import-saved-searches → { columns: ColumnView[] }
+GET    /feeds/columns/:id/items?cursor&limit(1..200,def 40) → { items: FeedItemDTO[], nextCursor, meta: ColumnMeta }
+POST   /feeds/columns/:id/refresh           → 202                         (shares lease/cooldown/budget machinery)
+```
+
+`ColumnView`:
+```ts
+{ id, type, title, position, spec, refreshPolicy, effectiveIntervalMs,
+  sources: Array<{ id, provider, connectionId, sourceKind, query, actorRef,
+                   state, lastPolledAt, lastError?, handle?, displayName? }>,
+  aggregateState: "ready"|"pending"|"stale"|"error"|"partial"|"empty"|"paused" }  // worst-of, §3.5
+```
+
+`FeedItemDTO` (column items endpoint; superset of today's `/feeds` item — the UI's `StreamItem` maps 1:1):
+```ts
+{ id, remoteId, provider, connectionId: string|null, sourceId,
+  authorHandle, authorRef?, url?, createdAt,
+  content: RichTextAst,          // §5 — the ONLY render source
+  plainText, media: MediaRef[], metrics: Record<string,number> }
+```
+`ColumnMeta`: `{ sources: [...same as ColumnView.sources], fetchedAt, nextCursor semantics }`.
+
+**Mapping into `/feeds` serving (back-compat + one merged view):**
+- `GET /feeds` **unchanged**: merged home-timeline view over capable connections, `meta.connections`, `excludedConnections`, cursor format, `POST /feeds/refresh`. It now reads through the same `feed_items` store (cache-first) — external shape identical.
+- `GET /feeds` gains **one additive** field: `meta.columns?: { id, title, type, position, aggregateState }[]` (omitted when the feature flag is off). The "All feeds" chip and offline/sample mode keep working off the old shape.
+- Per-column serving is **only** `GET /feeds/columns/:id/items`. The merged `/feeds` never mixes column-filtered results, so the current switcher ("All feeds" / "Columns" / per-column / per-saved-term) keeps exact semantics.
+
+**Cursor rule:** every cursor is the existing base64url `{at, key}` position tuple over a **deterministic sort** (`created_at_remote DESC, dedup_key DESC`). Per-column cursors are stable because they page persisted rows, not a Redis snapshot.
+
+---
+
+## 2. Feed acquisition strategy per platform
+
+Order follows the research matrix ("Low effort, $0" → up). **Build order: Bluesky → Mastodon → YouTube → X(paid, gated) → Instagram(hashtag, gated) → TikTok(embed-only, out of scope).**
+
+### 2.1 Platform decision table
+
+| Platform | Keyword column | Account-list column | Mechanism | Auth / credential | Budget | Phase |
+|---|---|---|---|---|---|---|
+| **Bluesky** | `app.bsky.feed.searchPosts` (`sort=latest`, `q`) | `app.bsky.feed.getAuthorFeed(actor)` | native REST via connector; **poll first**, jetstream later (§2.4) | **optional app password** — created via `createAppPassword`, vaulted per workspace as a *column credential*; unauthenticated mode is best-effort fallback (api.bsky.app works; design never *requires* keyless) | AppView "generous"; per-host bucket default 30 req/10 min/host; keyless concurrency cap 2 | **P2 / P3** |
+| **Mastodon** | hashtag timeline `timelines/tag/:tag` only (no global search — hard platform fact); non-tag query → provider marked `unsupported` | `accounts/:id/statuses` (public) **or** `@user.rss` (verified keyless) — prefer RSS for keyless follows, `/statuses` when a connection exists | native via existing connector | none for public/RSS; user token (existing connection) for streaming later | 300 req/5 min per account/IP → per-host bucket 10 req/10 s default (egress), per-connection 0.5 RPS cap as today | **P2 / P3** |
+| **YouTube** | Data API `search.list` (`type=video`, `publishedAfter` = last poll − slack) | **channel RSS** `feeds/videos.xml?channel_id=` (15 latest, keyless, verified) as primary; `playlistItems.list` (1 unit/50) for backfill/deep history | RSS fetcher (new shared `rss-source` reader in ingest, not a full connector) + Data API client | **API key** in vault, workspace-scoped `youtube_data` credential; RSS needs nothing | `search.list` own bucket **100 calls/day** → ledger `yt_search_calls` cap 90/day (10% headroom); `playlistItems` from shared 10k units; RSS = per-host bucket only. **30-day refresh-or-delete** on Data-API items → `expires_at`, attribution required in UI | **P2 (search) / P3 (RSS)** |
+| **X / Twitter** | `tweets/search/recent` (last 7–10 d) | `users/:id/tweets` | native connector, **behind a pay-per-use gate** | OAuth2 app Bearer; billing = operator's console credits (pay-per-use $0.005/post read; free tier has no reads) | **$ ledger**: `x_post_reads` cap per workspace (default **0 = off**); every read debited; hard stop at cap → source `budget_paused`; platform 3M reads/mo cap noted but irrelevant vs our caps | **P5 (opt-in)** |
+| **Instagram** | Graph API `ig_hasid_search` → `top_media`+`recent_media` (hashtag columns only) | **not possible** (others' accounts) — UI shows embed-card fallback for known URLs only, never auto-follow | native connector extension | Meta app + App Review; Business/Creator account connection | **30 unique hashtags / rolling 7 d** → ledger `ig_hashtag_window`; source `rate_limited` + "next tag slot frees {time}" when exhausted; `recent_media` ~50-item window → treat as shallow | **P5 (gated on App Review)** |
+| **TikTok** | none compliant (Research API = academic/nonprofit only; Commercial = ads) | embed-only for known URLs | none — **out of scope**; render link-cards | n/a | n/a | not built |
+| **Telegram / Discord / Slack** | n/a | n/a (channel-picker columns are WP5 inbox work) | existing `getFeed` home paths unchanged | existing | existing | n/a |
+| **Threads** | n/a (API is own-account only) | n/a | unchanged | n/a | n/a | n/a |
+
+**Bridge policy:** no RSS-Bridge/RSSHub/Nitter in any phase of this plan. Telegram public-channel via RSS-Bridge is recorded as a possible later opt-in with legal sign-off; not designed in.
+
+### 2.2 SDK interface changes (decided)
+
+Extend `PlatformConnector` (additive, optional methods — existing connectors untouched):
+
+```ts
+// keyword search — lifts the existing getFeed kind:"search" branches verbatim
+search?(connection | null, { query: string, cursor?: string, limit: number }): Promise<Page<FeedItem>>;
+// author timeline — new
+getUserFeed?(connection | null, { actorRef: string, cursor?: string, limit: number }): Promise<Page<FeedItem>>;
+```
+`connection | null` formalizes **keyless sources** (Bluesky public, Mastodon RSS/public, YouTube RSS). Capability flags added to `ConnectorCapabilities` + manifests: `search: boolean`, `authorFeed: boolean`. These mirror into `/feeds` `meta.connections[].capabilities` (already a string array) so the UI can gate affordances with zero new endpoints. Reddit's degenerate "search = subreddit hot" is **removed** from the search path (no `search()` implementation → `unsupported`), fixing a current semantic lie.
+
+A small **`rss-source` reader** (XML→FeedItem) lives in the ingest package for YouTube/Mastodon RSS — it is not a `PlatformConnector` because it has no publish/identity surface; it registers per-host budget usage like any egress caller.
+
+### 2.3 Credential & key residence (vault)
+
+- **Connection credentials** (Mastodon/Bluesky/IG/X user tokens): unchanged — `vault.open/seal` per `(workspaceId, connectionId)` exactly as `feeds.dependencies.ts` does today.
+- **Column credentials (new class):** workspace-scoped secrets not tied to a connection — Bluesky app password (optional), YouTube Data API key, X app Bearer. Stored vaulted under `(workspaceId, "columns", provider)`; the poller resolves provider→credential handle at poll time. **Never** in `stream_columns.spec`, never logged, never sent to the client (the API returns only `{ provider, configured: boolean, label }`).
+- **Keyless sources carry no secret at all** — egress policy + per-host budget is the only control (which is why they're preferred where equal).
+
+### 2.4 Polling vs streaming
+
+- **v1 = polling everywhere.** The generalized scheduler (§3.4) with per-source `next_poll_at`, exponential backoff on failure (×2 up to 30 min), jitter ±20%.
+- **Bluesky Jetstream (P6, optional):** a single workspace-shared subscriber (`collections=app.bsky.feed.post`) maintains a **local keyword index** (FTS table) that backs keyword columns for *Bluesky only*, giving near-real-time + historical depth beyond `searchPosts` page depth. Rules: self-hostable binary or public endpoint, no auth, cursor replay on reconnect, **index rows follow the same safe-content AST + 30-day retention**, and keyword columns **fall back to `searchPosts` polling** whenever the subscriber is down (state `stale`, never `error`). Jetstream is an accelerator, never a dependency.
+- **Mastodon streaming** (user token + `read:statuses`) is the same pattern later; hashtag polling is good enough for v1.
+
+### 2.5 Per-host rate budgets (reusing WP7/WP8 machinery)
+
+No new limiter. The column poller:
+1. computes the target host from the source's provider+instance (Mastodon instances vary! host = the connection's instance, not `mastodon.social` globally);
+2. acquires via `egress` → `app.take_host_budget(host_id, 'monitor', n, lease_seconds)` exactly like the live-monitor pollers — so columns, monitor polls, and any other caller of the same instance share one bucket;
+3. honors `429`/`Retry-After` → cooldown key + source state `rate_limited`;
+4. keeps the existing per-connection Redis lease/cooldown (`feeds:{ws}:{conn}:…` extended with `:{columnSourceId}`) so **manual refresh cannot bypass budgets** and replicas never double-poll (identical pattern to today's `FeedsService`, keyed finer).
+
+Per-provider defaults (conservative, env-overridable, `CONNECTOR_RATE_<PROVIDER>_RPS` style retained): Bluesky host 0.2 RPS sustained (keyless 0.05 RPS), Mastodon per-instance 0.1 RPS, YouTube RSS host 0.05 RPS, YouTube API search 90 calls/day ledger, X gated by spend ledger, Instagram by hashtag-window ledger. The **provider-budget ledger** (table 5) is checked *before* the host-budget debit; exhausted → `budget_paused` (distinct from `rate_limited`: no retry storm, requires user action or window rollover).
+
+---
+
+## 3. Ingest / search pipeline
+
+### 3.1 Source resolution (column spec → column_sources)
+
+On create/update of a column, a **resolution step** (no network for keyword columns; bounded network for account_list) writes `column_sources`:
+
+- `platform_feed`: 1–2 sources (per kind) on the named connection.
+- `keyword`: for each `platforms[]` entry → one source per (provider, connection-or-keyless) that **declares the capability** (`search: true` or RSS-search path). Providers in `platforms[]` without capability → **no row**; the API response lists them under `spec.unsupportedPlatforms` so the editor can show "TikTok: not available" without inventing a failing source. Query adaptation happens here, once, per provider:
+  - Bluesky: query as-is (full-text).
+  - Mastodon: extract first `#hashtag` token; if none → this provider is `unsupported` for the column (UI states "Mastodon supports #hashtag queries only").
+  - YouTube: query as-is (`search.list`, `type=video`).
+  - X: query as-is (`search/recent`), only if spend ledger enabled.
+  - Instagram: only if the entire query is a single hashtag; else `unsupported`.
+- `account_list`: each entry `{provider, handle}` → resolve to `actor_ref` via provider-specific resolution (`resolveHandle` for Bluesky DID, Mastodon `accounts/lookup`, YouTube channel-id via RSS/`channels.list` if key present). Resolution uses the bounded resolver pattern (≤4 in-flight/host, 10-min positive cache / 1-min negative). Unresolvable handle → source row with `state:'error', last_error:'handle_not_found'` — **it does not fail the column**.
+
+### 3.2 Normalization (into the existing shape, extended)
+
+Every source type funnels into one `normalize()` (today's `feeds.service.ts` validation retained: finite dates, string remoteId/handle, finite metrics; invalid items dropped + counted in source meta):
+
+| Provider source | author_handle | content (AST) | media | metrics | url |
+|---|---|---|---|---|---|
+| Bluesky post | handle | facets→AST (links, mentions) | embed images/video → **proxy** | likes/reposts/replies | `bsky.app/profile/…/post/…` |
+| Mastodon status/RSS | `@user@instance` | HTML→AST via allowlist parser (strip scripts/styles/iframes; keep p/br/a/strong/em; links http/https only) | media attachments → proxy | reblogs/favourites/replies | status permalink |
+| YouTube video/RSS item | channel title | title+description→AST (plain paragraphs; links auto-linked http/https only) | thumbnail → proxy | viewCount/likeCount (API only) | watch URL |
+| X tweet | handle | entities→AST | media → proxy | likes/reposts/replies | tweet permalink |
+| IG hashtag media | username | caption→AST | media → proxy | like/comment count | permalink |
+
+`plain_text` is derived at ingest (AST→text) so saved-search-style client filtering and the column preview keep working. **`media[].proxyUrl` is always our media proxy URL** (WP3 media path) — raw provider CDN URLs never reach the browser.
+
+### 3.3 Dedup & identity
+
+- `dedup_key = sha256(workspace_id | provider | canonical_remote_id)` where `canonical_remote_id` = `remoteId` lower-cased and, for handle-bearing providers, `{host}/{remoteId}` with the IDNA-canonical host (same canonicalization rule as WP7 `remote_ref`: lowercase host, punycode, default-port stripped). One object reached via two connections (or a connection + keyless) collapses to one row; the second ingest updates metrics/fetched_at in place (`ON CONFLICT … DO UPDATE` on metrics + fetched_at).
+- **Cross-provider dedup is explicitly NOT attempted** (no fuzzy matching) — an item is provider-scoped. The UI dedups by `streamItemKey` client-side as today.
+- `feed_item_columns` is filled by fan-out at ingest: an item lands in every column that shares that `column_source` identity — i.e., columns referencing the same (provider, actor_ref) or (provider, query) share ingested rows, so following the same account in two columns costs **one** poll (mirrors the WP8 "one remote live, three channels, one poller" rule).
+
+### 3.4 Scheduler (generalizing FeedsService)
+
+The existing 5 s discovery loop stays; `pollAll()` becomes "poll due `column_sources`" (the legacy per-connection home poll is literally a `platform_feed` source, so old behavior is the degenerate case):
+- select due sources (`next_poll_at <= now`, `state NOT IN ('disabled')`), `FEED_CONCURRENCY=4` waiter queue retained;
+- per-source flow: lease → resolve credential (vault or keyless) → budget/ledger check → egress call via connector `getFeed/search/getUserFeed` or RSS reader → normalize → upsert `feed_items` + fan-out join → write hot Redis slice (`feeds:{ws}:{column}:items` head, TTL = interval×1.2+30 s) → update source state/`next_poll_at` (success: interval; failure: backoff ×2 cap 30 min, `consecutive_failures`≥3 → `error`);
+- `RateLimitError.retryAfterMs` → cooldown, state `rate_limited`; ledger empty → `budget_paused`;
+- manual `POST /feeds/columns/:id/refresh` → same path (202; cooldown may make it a no-op — response carries `effectiveNextPollAt`).
+
+### 3.5 Stale / failed / empty behavior in a column
+
+Per-source `state` (§1.2) aggregates to `aggregateState` shown in the column header:
+- `ready` — all sources fresh (< 2× effective interval).
+- `stale` — any source's `last_polled_at` older than 2× interval but data present → header "Updated HH:MM" + amber dot; **old items remain visible** (persisted store — the big UX win over today's TTL'd cache).
+- `error` — all sources failed ≥3× → red dot + per-source error line (from `last_error`, provider message scrubbed); last-known items stay visible with "showing last data from …".
+- `partial` — some sources fine, some error/stale → amber; per-source chips in column menu.
+- `rate_limited` / `budget_paused` — distinct icon + actionable copy ("X reads paused: budget reached — raise cap in settings" / "Instagram hashtag slots full until {time}").
+- `empty` — source healthy, zero items ever → per-platform empty-state copy ("No public posts match #acampada26 on Mastodon yet").
+- `unsupported` — never a source row; surfaced in editor only.
+Deleting the underlying connection → its sources flip `disabled`; column survives with remaining sources; a `platform_feed` column whose connection dies becomes `error` with a reconnect CTA (not auto-deleted).
+
+**Retention / expiry sweeper:** daily job deletes `feed_items WHERE expires_at < now()` (YouTube Data-API sourced) and everything older than 30 days regardless of source (matches the strictest ToS we're under; RSS items keep 30 d too for uniformity). Deletion is the default; re-polling a live column continuously refreshes the visible window, satisfying "refresh or delete".
+
+---
+
+## 4. UI / UX spec (Streams page integration)
+
+### 4.1 Model change in the web app
+
+`lib/streams-data.ts` gains `columnViewsToColumns(ColumnView + items)` producing today's `ColumnDef` (key = column id, title, platformId from dominant provider, staleness from `aggregateState`/`lastPolledAt`). The sample/offline path (`MOCK_COLUMN_DEFS` + fixtures) is untouched. Data flow:
+
+- mount → `GET /feeds/columns` (once, plus after any mutation) → for the visible columns (and lazily the next offscreen ones) `GET /feeds/columns/:id/items` per column, 30 s polling retained per visible column (staggered), merged into `ColumnDef[]`.
+- "All feeds" chip → unchanged `GET /feeds` merged view. "Columns" chip → column array as above. Per-column chips → single column. Saved-term chips now resolve to their migrated server columns (id `saved:{term}` → real id after migration; localStorage terms still render offline).
+
+### 4.2 Column editor
+
+- **"+ Column" button** opens a right-side drawer (desktop) / bottom sheet (mobile): type selector (Platform feed · Keyword · Accounts · Saved search), then type-specific fields:
+  - *Platform feed*: connection picker (visible connections only, feed-capable, capability badge), kinds toggles (Home / Mentions).
+  - *Keyword*: query input with live per-platform feasibility hints as you type ("Bluesky ✓ full-text · Mastodon #hashtag only · YouTube ✓ · TikTok ✗"), platform multi-select chips (search-capable enabled, others visible-but-disabled with reason tooltip), interval select (1/2/5/10/30 min — clamped label shows effective value).
+  - *Accounts*: multi-entry list (paste handles one per line or chip input; provider inferred from handle shape `@x@bsky.social`/`@x@mastodon.social`/`UC…`; `@x` on TikTok/IG → blocked with reason), live resolution status per row (✓ resolved / ✗ not found / ⏳ resolving), 50-entry cap enforced client+server.
+  - *Saved search*: term input; identical to keyword with `origin` label.
+- **Edit**: column header "⋯" menu → same drawer prefilled; changing spec re-resolves sources (existing items for retained sources persist; removed sources' items age out via retention, no mass delete).
+- **Reorder**: drag handle on column headers (desktop) / up-down arrows in the columns sheet (mobile) → `POST /reorder`.
+- **Remove**: "⋯" → Remove (soft delete; confirm if the column has fresh data) and Pause (refresh_policy.paused).
+- Optimistic UI on create/reorder/remove with server reconciliation; failure → toast + revert.
+
+### 4.3 States, keyboard, mobile
+
+- **Empty states:** no columns → existing `EmptyState` + "Add column" CTA. Column with no items → per-source empty copy (§3.5). No connections at all → today's sample-mode fixtures with a "Sample data — connect an account" banner (unchanged).
+- **Error states:** header dot + per-source detail in the column menu; a "source status" strip lists each source (provider, handle/query, state, last polled, error).
+- **Sample state:** identical to today (API unreachable / 0 configured feeds → fixtures); the editor still opens but Create is disabled with "offline — changes need the server".
+- **Keyboard:** j/k flat navigation retained; `c` opens the column editor; `1..9` jumps to column n.
+- **Mobile:** single-column reading with the existing `SourceChips` bar (All feeds · Columns · each column · saved terms); Columns mode = swipeable pager (one column per screen, `PullToRefresh` triggers the column refresh endpoint); editor as bottom sheet; drag-reorder replaced by arrows. Desktop keeps the multi-column wall.
+
+### 4.4 Back-compat guarantee
+
+The source switcher's four modes (all / columns / per-column / saved-term) all survive with identical semantics; when the flag is off or seeding hasn't run, the page behaves exactly as the current build (derived columns from `/feeds` meta). Saved-search localStorage remains the offline fallback.
+
+---
+
+## 5. Security design
+
+1. **safe-content as the only render path.** `FeedItemDTO.content` is the safe-content **typed rich-text AST**, produced **at ingestion** (server-side): Mastodon HTML → AST via the allowlist parser inside the connector/ingest boundary; Bluesky facets, YouTube/RSS text, X entities → AST builders. Raw provider HTML **never** crosses the API boundary; there is no field a client could accidentally render. The web `StreamColumn`/`PostCard` render exclusively `<SafeContent ast={item.content}/>`; the repo lint rule fails on `dangerouslySetInnerHTML` (existing WP3 acceptance) and additionally on any new string prop named `html`.
+2. **Links:** AST link nodes are http/https-only (other schemes dropped at ingest, not CSS-hidden); unsafe-scheme links render as inert text, not clickable.
+3. **Media:** `media[].proxyUrl` only — provider CDN URLs are proxied through the media path (CSP `img-src`/`media-src` never include provider origins). No `<iframe>` embeds for IG/TikTok in v1 (an embed-only fallback, if ever added, gets its own sandboxed frame + CSP review — explicitly out of scope here).
+4. **SSRF:** no user-supplied URL is ever fetched. Account handles and queries go through provider APIs / the bounded resolver, all via `egress` (scheme allowlist, private-range denial, resolve-once pinning). YouTube/Mastodon RSS host URLs are constructed from validated channel-id/handle forms, never pasted URLs.
+5. **Secrets:** vault-only (§2.3); API responses expose `configured: boolean` at most. Ledger/credential management endpoints are admin-gated.
+6. **Authz:** read = `draft.view` (+ group visibility for connection-backed sources); write = `streams.columns.manage`; every route workspace-scoped and RLS-checked; import-saved-searches is rate-limited per user (it creates rows).
+7. **Cost safety:** X/IG gated ledgers with per-workspace caps default-off/pending-review; a keyword column targeting X shows a **pre-flight cost estimate** (posts × $0.005) before creation.
+
+---
+
+## 6. Phased build plan (agent-executable slices)
+
+Tiers: **flash** = small fully-specified slice; **glm** = medium feature slice; **sol** = large/complex or cross-cutting. Phases strictly dependency-ordered; marked slices parallelize.
+
+### P0 — Foundations (flash ×3, parallel)
+- **P0a Schema & validation:** migrations for the 5 tables; `spec`/`refresh_policy` zod schemas + clamps in `packages/core`; unit tests for clamps and invalid-spec rejection. **AC:** migration applies on a populated DB; invalid specs rejected `422`; `(workspace_id, position)` unique holds under concurrent inserts.
+- **P0b SDK contract:** optional `search()` / `getUserFeed()` (`connection | null`), capability flags `search`/`authorFeed`, manifest validation, contract-test fixtures. **AC:** extended contract tests pass; existing connectors compile untouched; capability strings surface in `/feeds` meta.
+- **P0c FeedItem extension + normalize v2:** extended normalization (author_ref, url, AST content, proxy media refs, expires_at) with per-connector fixtures incl. hostile HTML (script tag, `javascript:` link, iframe → AST contains none). **AC:** malicious fixture yields an AST with zero raw remnants; plain_text derivation stable.
+
+### P1 — Column CRUD + platform_feed persistence (glm)
+Tables wired into the API; `GET/POST/PATCH/DELETE /feeds/columns`, `reorder`, `import-saved-searches`; lazy seeding; RBAC `streams.columns.manage`; `GET /feeds/columns/:id/items` keyset-cursored over `feed_items`; scheduler generalization (due-sources loop, per-source lease/cooldown, backoff — legacy home poll becomes the degenerate `platform_feed` source); `/feeds` served cache-first from the store, external shape unchanged + additive `meta.columns`.
+**AC:** seeded workspace reproduces today's columns exactly (title/key/staleness); CRUD + reorder RBAC-enforced (403 for ungranted roles); manual refresh cannot bypass cooldown (existing test extended to column endpoints); cursor survives a Redis flush; re-running seeding creates no duplicates.
+
+### P2 — Keyword columns: Bluesky + Mastodon hashtag + YouTube search (glm ×2 + sol + parallel UI glm)
+- **P2a (glm):** Bluesky `search()` (optional app-password credential, keyless fallback), Mastodon hashtag `search()` (+ explicit `unsupported` for non-tag queries), query-adaptation resolver, keyword column creation flow, per-source states.
+- **P2b (glm):** YouTube Data-API `search()` client, `yt_search_calls` ledger (cap 90/day, pre-check, `budget_paused`), `publishedAfter` sliding window, `expires_at` = +30 d, attribution line in UI.
+- **P2c (sol):** ingest fan-out/dedup correctness (two columns sharing a query → one poll, shared rows; one object via two connections → one row), retention sweeper.
+- **UI slice (glm, parallel after P1):** column editor drawer (keyword type first), per-platform feasibility hints, source-status strip, mobile sheet.
+**AC:** "acampada26" column on Bluesky+Mastodon+YouTube returns merged, deduped, AST-rendered items; exhausting the API key quota → YouTube source `budget_paused`, others unaffected; a `#tag`-less query shows Mastodon as unsupported (never an error); Playwright malicious-content corpus renders inert through the column UI; YouTube items auto-expire at 30 d.
+
+### P3 — Account-list columns (glm ×2)
+- **P3a:** `getUserFeed()` for Bluesky (`getAuthorFeed`) + Mastodon (`/accounts/:id/statuses` with connection, RSS keyless) + YouTube channel RSS via the `rss-source` reader; bounded handle resolver with positive/negative caching.
+- **P3b:** account-list editor UX (paste list, live resolution, 50-cap), mixed connection/keyless column, connection-loss behavior (`disabled`/reconnect CTA).
+**AC:** a 50-account column across 3 platforms polls each host within budget (mock server counts requests); unresolvable handle → row error, column healthy; revoking the Mastodon connection flips its sources to `disabled` while Bluesky keyless sources are unaffected; the same account in two columns = one poll.
+
+### P4 — Saved-search migration + polish (flash + glm)
+localStorage import endpoint wired into the page; offline fallback preserved; "Layout" stub becomes real (column widths persisted client-side); keyboard `c`/`1..9`; empty/error copy pass.
+**AC:** a fresh browser with legacy localStorage sees identical saved columns server-side, localStorage cleared, no duplicates on double-run; feature flag off → behavior identical to the pre-columns build.
+
+### P5 — Gated paid/limited platforms (sol ×2, parallel after P2's ledger exists)
+- **P5a X:** connector `search()`/`getUserFeed()` vs `search/recent` + `users/:id/tweets`, spend ledger ($/post-read, per-workspace cap default 0=off), pre-flight cost estimate UI, `budget_paused` UX.
+- **P5b Instagram:** Graph-API hashtag sources (30-tags/7d ledger window math, `top_media`+`recent_media`, shallow-window handling), App-Review notes; account-follow explicitly surfaced as impossible with embed-card fallback design.
+**AC:** an X column with a $2 cap stops exactly at the cap (mock billing counts reads) and resumes only on explicit cap raise; the 31st unique IG hashtag in a window → `rate_limited` with next-slot time; both default-disabled via env.
+
+### P6 — Jetstream accelerator + realtime (sol, optional, after P2a)
+Workspace-shared Jetstream subscriber → local keyword index (same AST/retention); keyword columns prefer the index with `searchPosts` polling fallback; WS push of column item deltas via the existing `RealtimeModule` (versioned, last-value-wins per column).
+**AC:** killing the subscriber degrades columns to polling (`stale`, not `error`) within one interval; a new matching post appears < 5 s locally; index rows expire at 30 d; no duplicate rows vs the polling path.
+
+**Dependency chain:** P0 → P1 → P2 → P3 → P4; P5 ∥ after P2; P6 after P2a. Malicious-content Playwright acceptance runs in every phase touching rendering or ingest (P2, P3, P4 at minimum).
diff --git a/docs/design/2026-10-09-feature-set.md b/docs/design/2026-10-09-feature-set.md
new file mode 100644
index 0000000..f698e0a
--- /dev/null
+++ b/docs/design/2026-10-09-feature-set.md
@@ -0,0 +1,88 @@
+# TweetDeck on Steroids — the full feature set
+
+**A self-hosted, multi-platform broadcast newsroom for collectives: a column wall that watches every platform at once, chats that organize themselves, votes that turn into posts, and a live channel behind it all.**
+
+TweetDeck died when X locked its doors. We built what should have replaced it — and went much further. Watch everything, decide together, publish everywhere, mix live, and keep an archive no platform can take away. Self-hosted. No algorithm in between. No platform holding your keys.
+
+---
+
+## The column wall — every platform in one wall
+
+Live columns watch all your connected accounts at once: Mastodon, Telegram, Bluesky, PeerTube, Twitch, and more. The whole collective sees the same picture at the same moment.
+
+Every post is rendered safe (hostile HTML is parsed into a typed format — scripts, tracking pixels and trick links are stripped at ingest and tested against an attack corpus), media is proxied through your server, and duplicates are deduplicated into the archive automatically.
+
+Columns are becoming **editable**: a column can be a platform feed, a **keyword search across platforms** (one query like "acampada26" pulling from every network that allows it), a curated **list of accounts across platforms**, or a saved search. Columns persist per group, can be reordered, paused, and shared.
+
+## Collaborative chats
+
+Chats from every platform bridge into one shared overlay and one web chat — viewers, contributors and moderators in the same room, with flood governors and moderation tools keeping it usable during action.
+
+The chat is a coordination surface, not just a mirror: it sits next to the live program, next to the file store, next to the drafts. What people say in the chat drives what happens in the system.
+
+## Voting and decision making — in the chat, automatically
+
+Run a poll inside any bridged chat: **"post this?"** — and set the rules for what counts as a pass. Configurable per poll:
+
+- approved by **x of y admins**
+- approved by **x of y participants**
+- mixed quorum (admins + participants), veto rights, timeboxes, anonymous or named voting
+
+Votes come in through Telegram buttons and the web overlay — live tally bars, quorum meters, countdowns. Ineligible votes are stored but never counted; vetoes fail the poll instantly; revotes are supported; everything lands in a tamper-evident audit trail.
+
+**When the quorum passes, the posting bot fires automatically** — the approved content goes out to the channel, topic, or account the poll was about. No admin phone in the loop. Decisions happen at the speed of the chat, with the full trail preserved.
+
+## Configurable posting bots — every account, its own rules
+
+Every connected account carries its own settable rules for what it takes to post:
+
+- **immediate** — no gate, post as today
+- **admin-only** — an admin's approval is the whole quorum
+- **quorum** — configurable thresholds of admins and/or participants
+- per **topic** and per **content type** overrides, dry-run shadow mode, timeboxes, reset-on-edit
+
+A rules editor shows the resolved effective policy before you save it — and a blocked queue shows every post waiting on its quorum with a live gap meter. Nothing is ambiguous about why something did or didn't go out.
+
+## Subchats and topics — structure that follows the work
+
+Forum topics become **subchats**: working groups inside a channel, created and managed by the bot. Accounts are **assigned to topics** — the press crew on the press topic, the stream crew on the stream topic — and each topic carries its own posting rules and its own view of the store. Topics can be bound to broadcast channels, so a topic isn't just conversation: it's a control surface.
+
+## Chat-linked files — the store organizes itself
+
+Files posted into the chat land in the **group's file store automatically** — content-addressed, encrypted, deduplicated (the same clip shared five times is stored once).
+
+Admins organize: assign items to folders, copy them across subfolder trees, refile by type or date — from **chat commands** (`/ls`, `/find`, `/move`) or from the **mobile file screen** that lives next to the chat, with deep links from bot messages straight into the filtered folder view.
+
+Bot listings, search across the whole library, and an audit of every move: the file storage stays organized because the people in the chat keep it organized, from their phones.
+
+## Cross-amplification and retweets — one approval, every platform
+
+One approved draft fans out to every connected account, native to each platform. Where a platform has native quoting (Mastodon quote posts, Bluesky, Telegram forwards), it's used. Where it doesn't, the system generates a proper attributed quote — author, instance, link back — never a silent copy-paste.
+
+Amplifying a sister collective's post keeps their names on it by default. Scheduling, per-account timing, and rate awareness come along for free.
+
+## Live video mixing and channel production
+
+The **Control Room** runs in the browser: a multiview grid of every feed, TAKE/CUT between preview and program, scene layouts (single, picture-in-picture, two-up, splits, grid), lower-thirds, scrolling chyrons, clocks and logos as overlays, per-source audio mixing with a tally of what's hot.
+
+**Field streamers** push cameras from a phone straight to your server. The director mixes in the browser; the program goes to your **PeerTube channel**; and when no one is live, the channel keeps broadcasting a scheduled playlist so the station never goes dark.
+
+**Auto-Director** switches sources by priority rules — a streamer goes down, the next source fades in, the fallback slate catches anything else.
+
+**Distributed transcode workers:** laptops and GPUs join as render workers over Tailscale — an RTX 3090 laptop is already transcoding real PeerTube jobs with hardware encoding, verified end to end. More workers join the pool as load rises.
+
+## The backbone
+
+- **Encrypted vault** for every platform credential — the database never sees a plaintext key.
+- **Hash-chained audit log** — every editorial action tamper-evident, forever.
+- **DST-proof scheduling** — the occurrence engine survives clock changes; two scheduled posts that collapse onto the same instant fire exactly once.
+- **Media sandbox** — every FFmpeg job runs in a per-job jail: unprivileged, no network, resource-capped.
+- **An archive that can't be purged** — content-addressed, encrypted, deduplicated. Deleted threads stay citable; yesterday's footage is tomorrow's playlist.
+- **Teams without password-sharing** — roles per account, invite links, people can remove their own access when they move on.
+- **Self-hosted end to end** — no corporate cloud, no accounts needed to run the system itself.
+
+---
+
+## We're looking for testers and intake hackers
+
+Test the whole flow: post through approvals, run the column wall against your real feeds, mix a stream, break the scheduler across timezones, vote in the chats. And help us on the **hard problem: pulling from the locked platforms** — per-URL fetchers, community-submitted links, bridge services, archive harvesters. If you've built scrapers or run intake pipelines, we want your design input.
diff --git a/docs/design/2026-10-09-transcode-pool-design.md b/docs/design/2026-10-09-transcode-pool-design.md
new file mode 100644
index 0000000..1f8fc79
--- /dev/null
+++ b/docs/design/2026-10-09-transcode-pool-design.md
@@ -0,0 +1,632 @@
+# NVIDIA GPU Extension + Dynamic Pool Scaling — Design & Research
+PeerTube transcoding worker cluster · design wave · 2026-10-09
+
+Companion to the Intel QSV worker implementation landing in
+`infra/peertube-workers/` (the enrolled worker laptop). This document depends **only on the
+Intel worker's CONTRACT** (official `@peertube/peertube-runner`, per-worker
+admission controller, pluggable capability probe, status JSON, drain control,
+fail-closed hardware rule), never on its internals.
+
+Empirical anchors in this doc are marked **[E]** and were measured on this
+machine on 2026-10-09: WSL2 host, 2× NVIDIA GeForce RTX 3090 (Ampere GA102),
+Windows-side driver 595.58.03 / CUDA 13.2, Debian 12 ffmpeg 5.1.9
+(`0+deb12u1`, libmfx build), 56-core Xeon E5-2690 v4, 128 GiB RAM. Numbers not
+marked [E] are from NVIDIA primary documentation (Video Codec SDK 13.x
+support matrix, NVENC help page, driver release notes, CUDA-on-WSL guide) as
+recalled; **no web access was available in this session, so treat
+vendor-doc-derived figures as "verify against the live matrix when the first
+NVIDIA box is onboarded"** — every one of them is also re-derived at install
+time by the probe (§5.3), so a stale number here degrades to a warning, never
+to a wrong production decision.
+
+---
+
+## 0. Executive summary
+
+1. NVENC on GeForce is no longer meaningfully session-capped for our use
+   case: the driver limit is **8 concurrent encode sessions per GPU** since
+   driver branch 536 (mid-2023); professional/datacenter boards have **no
+   driver cap**. Our per-worker concurrency will be bounded by VRAM,
+   NVDEC+filter throughput and bandwidth long before 8 sessions matter —
+   but the cap must still be tracked, because PeerTube fans one job out to
+   many resolution renditions and a 5-rendition job on one GPU *is* 5
+   sessions.
+2. The hardware rule generalizes cleanly: the same fail-closed contract that
+   keeps QSV from falling back to x264 keeps NVENC from falling back to x264.
+   The only NVIDIA-specific additions are device selection (`-gpu N`),
+   driver/kernel-module installation, session accounting, and VRAM floors.
+3. **Do not put NVIDIA workers on WSL2.** [E] The API surface exists
+   (`h264_nvenc`/`hevc_nvenc` registered, `libnvidia-encode.so.595.58.03`
+   present) but the GPU is shared with the Windows host, NVML encoder
+   queries are reduced, and there is no `/dev/dri`, no persistence-mode
+   control and no isolation from Windows-side VRAM consumers. On this very
+   box NVENC is currently unusable because two co-tenant Windows processes
+   hold 23.8/24 GiB on each GPU. WSL2 is a dev/probe platform; production
+   NVIDIA workers are native Linux.
+4. Dynamic pool scaling does **not** require touching PeerTube's scheduler.
+   Runners register once and persist server-side; "joining the pool" is
+   `systemctl start` + admission AVAILABLE, "leaving" is graceful drain +
+   optional `systemctl stop`. The pool manager nudges *which* runners are
+   eligible (and at what concurrency), PeerTube still decides job
+   assignment. Mixed-vendor preference is expressed the same way: selective
+   availability + concurrency, not scheduler surgery.
+5. The one interface the Intel implementation must get right **now**: the
+   capability probe must be a *mandatory, fail-closed, versioned* plugin
+   interface, and the status JSON must be vendor-generic with a `gpu.vendor`
+   discriminator from day one.
+
+---
+
+## 1. NVIDIA capability research (2026)
+
+### 1.1 NVENC concurrent-session limits
+
+| GPU class | Driver-imposed concurrent NVENC sessions | Notes |
+|---|---|---|
+| GeForce (consumer) | **8** per GPU | Raised 3→5 in 530.41.03/531.29 (2023-03), 5→8 in branch 536 (2023-07). Applies per GPU, across all processes; an ffmpeg process using `-threads` still counts as 1 session per encode context. |
+| Professional / workstation (RTX A-series, RTX 5000/6000 Ada, RTX Pro Blackwell; ex-Quadro) | **No driver cap** | Bounded only by hardware/VRAM. |
+| Datacenter media-class (T4, A2, L4, L40, L40S) | **No driver cap** | These are the right datacenter parts for transcoding. |
+| Datacenter compute-class (A100, H100, H200, B100/B200) | **0 — no NVENC at all** | Compute dies ship no encode engine (and Hopper/A100 have reduced/absent NVDEC). Never buy these for a transcode pool. |
+
+Design consequences:
+
+- The cap counts **encode sessions**, not processes and not ffmpeg
+  "engines". A single PeerTube VOD job that produces 4 renditions from one
+  decode can hold 4 encode sessions (PeerTube today typically runs one
+  ffmpeg per rendition, so it holds 4 decode sessions too — see §3.4).
+- Session pressure must be *measured*, not assumed from the table: NVML
+  exposes `nvmlDeviceGetEncoderCapacity` / encoder-session counts on
+  bare-metal Linux, but **[E]** on WSL2 the capacity query returned a
+  non-success code in our ctypes probe, so the probe design (§5.3) treats
+  NVML as best-effort with a driver-class lookup table and our own
+  accounting as ground truth.
+
+### 1.2 NVENC encode support matrix by generation
+
+Generational numbering below is the commonly used NVENC-generation scheme
+(1=Kepler … 7=Blackwell); NVIDIA's own docs speak of "Turing NVENC",
+"Ampere NVENC", etc. Quality-relevant jumps: Turing (large HEVC/H.264
+quality+lookahead gains) and Ada (AV1 + HEVC 4:4:4).
+
+| NVENC generation (arch) | Example parts | H.264 | HEVC 8-bit | HEVC 10-bit | HEVC B-frames | HEVC 4:4:4 | AV1 |
+|---|---|---|---|---|---|---|---|
+| Gen 1 (Kepler) | GTX 680 | ✓ | — | — | — | — | — |
+| Gen 2 (Maxwell) | GTX 750Ti/970; GM206 (950/960) | ✓ | GM206 only | — | — | — | — |
+| Gen 3 (Pascal) | GTX 10xx, Quadro P | ✓ | ✓ | ✓ | — | — | — |
+| Gen 4 (Turing) | GTX 16xx, RTX 20xx, T4 | ✓ | ✓ | ✓ | ✓ | — | — |
+| Gen 5 (Ampere) | RTX 30xx, A-series | ✓ | ✓ | ✓ | ✓ | ✓ (Pro/A-series) | — |
+| Gen 6 (Ada) | RTX 40xx, L4, L40/L40S | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| Gen 7 (Blackwell) | RTX 50xx, RTX Pro | ✓ | ✓ | ✓ | ✓ | ✓ + 4:2:2 | ✓ (+UHQ) |
+
+**[E]** Consistency check on this box (RTX 3090 = Ampere = gen 5):
+ffmpeg 5.1.9 lists `h264_nvenc` and `hevc_nvenc` and does **not** list
+`av1_nvenc`; `av1_cuvid` decode **is** listed. Matches the matrix exactly
+(Ampere: AV1 decode yes, AV1 encode no).
+
+### 1.3 NVDEC decode support matrix
+
+| NVDEC generation (arch) | H.264 | HEVC 8/10-bit | VP9 | HEVC 4:4:4 | AV1 |
+|---|---|---|---|---|---|
+| Maxwell | ✓ | GM206: 8-bit only | — | — | — |
+| Pascal | ✓ | ✓ | ✓ | — | — |
+| Turing | ✓ | ✓ | ✓ 10/12-bit | ✓ | — |
+| Ampere | ✓ | ✓ | ✓ | ✓ | ✓ 8/10-bit |
+| Ada | ✓ | ✓ | ✓ | ✓ | ✓ (incl. higher bit depths) |
+| Blackwell | ✓ | ✓ (+4:2:2) | ✓ | ✓ | ✓ (+4:4:4/12-bit) |
+
+Practical rule for the pool: **any card we would actually buy (Turing or
+newer) decodes H.264/HEVC/VP9; AV1 decode needs Ampere+; AV1 *encode* needs
+Ada+**. An Ampere pool (like this box) can ingest AV1 sources and emit
+H.264/HEVC, which fits the stated "H.264 primary, HEVC secondary, no AV1
+output" policy with headroom.
+
+### 1.4 Linux driver stack
+
+- **Open vs proprietary kernel modules**: NVIDIA's open kernel modules
+  (`nvidia-open` / open-gpu-kernel-modules) are the **default recommended
+  path for Turing+ since the 560-series**; proprietary remains for
+  pre-Turing and a few feature gaps. All realistic pool hardware (Turing+)
+  → use open modules. Blackwell effectively requires them.
+- 2026 driver branches: current feature branches run in the 5xx range;
+  **[E]** this host's Windows-side driver is 595.58.03 (CUDA 13.2). Debian
+  packages: `nvidia-open-kernel-dkms` (or prebuilt `linux-image-amd64` +
+  signed modules), `nvidia-driver-libs`, `nvidia-smi`, `nvidia-utils`;
+  firmware from `non-free-firmware`. Keep driver version **pinned per pool
+  fleet** and record `driver + kernel + module flavor` in the status JSON.
+- Userspace pieces that matter to us: `libnvidia-encode.so.1` (NVENC),
+  CUDA driver (`libcuda.so.1`) used by ffmpeg's nvenc/cuvid code paths,
+  `libnvidia-ml.so.1` (NVML for nvidia-smi). ffmpeg needs no CUDA toolkit
+  — only the driver libs. (A statically-built ffmpeg with `--enable-ffnvcodec`
+  / `--enable-cuda-nvcc` is only needed for `scale_npp`; `scale_cuda` is
+  covered by the header-only ffnvcodec path.)
+- Access control: user in `video` group (or a dedicated worker user with a
+  udev/tagged device ACL); `nvidia-persistenced` (or
+  `NVreg_PreserveVideoMemoryAllocations=1`) to avoid multi-second GPU
+  re-init between jobs on an idle pool box — relevant to dynamic scale-up
+  latency (§3.7).
+- MIG/compute-mode: leave compute mode `DEFAULT` **[E]**; nothing to
+  configure, but note it in the probe report.
+
+### 1.5 WSL2: CUDA/NVENC status
+
+What works [E, this host]:
+- CUDA user-mode stack present via `/usr/lib/x86_64-linux-gnu/libnvidia-*.so`
+  (WSL-provided, version-matched to the Windows driver).
+- ffmpeg registers `h264_nvenc`, `hevc_nvenc`, `*_cuvid` decoders and the
+  `cuda` hwaccel; `libnvidia-encode.so.595.58.03` is installed.
+- `nvidia-smi` works (2 GPUs visible, temps, clocks, throttle counters).
+
+What breaks it (all [E] on this host):
+- **No isolation from Windows GPU consumers.** Two Windows processes hold
+  23 856 MiB of each 24 GB GPU → any CUDA context creation fails
+  (`CUDA_ERROR_OUT_OF_MEMORY`), so `h264_nvenc` init fails with *"No capable
+  devices found"* and `h264_cuvid` device setup fails. This is the textbook
+  `GPU_UNAVAILABLE` state, and it is caused by another tenant, not by the
+  driver.
+- **Reduced NVML**: encoder-capacity/session queries returned non-success
+  in a ctypes probe; `nvidia-smi -q` shows Encoder Stats fields that cannot
+  be validated.
+- **No `/dev/dri`** [E: directory absent/empty] → no VAAPI/QSV fallback on
+  the same box, no `intel_gpu_top`-style counters, no display-path controls.
+- No control of persistence mode, ECC, or power limits from inside WSL.
+
+Verdict: **transcoding in WSL2 is feasible in the "API present, demo works"
+sense but is not a production worker platform** — the GPU is a shared
+resource with the Windows host, NVML is limited, and admission signals are
+unreliable. Use WSL2 to develop the `nvidia-nvenc` probe; run production
+workers on native Linux (or pass a whole GPU to a VM with VFIO if the box
+must stay Windows-adjacent).
+
+### 1.6 FFmpeg flags: the NVIDIA pipeline
+
+The NVIDIA analogue of `hw decode → hw frames → hw scale → hw encode`:
+
+```bash
+# full hardware pipeline, frames never leave the GPU
+ffmpeg -y -init_hw_device cuda=cu:0 -filter_hw_device cu \
+  -hwaccel cuda -hwaccel_output_format cuda -c:v h264_cuvid -i INPUT \
+  -vf scale_cuda=1280:720:format=yuv420p \
+  -c:v h264_nvenc -preset p5 -tune hq -rc vbr -cq 23 -b:v 0 \
+  -rc-lookahead 20 -spatial_aq 1 -temporal_aq 1 \
+  -bf 3 -b_ref_mode middle \
+  -c:a copy OUTPUT
+```
+
+Key flags (PeerTube-runner passes its own argv; these are what the
+capability probe and any wrapper/profile must emit):
+
+| Purpose | Flag | Notes |
+|---|---|---|
+| HW decode | `-hwaccel cuda -hwaccel_output_format cuda` or explicit `-c:v h264_cuvid`/`hevc_cuvid`/`av1_cuvid` | explicit `*_cuvid` gives named-decoder certainty; `-hwaccel_output_format cuda` keeps frames on-GPU |
+| HW upload (when input is CPU-decoded) | `-vf hwupload_cuda` | needed for e.g. audio-merge jobs with CPU-side frames |
+| HW scale | `scale_cuda=w:h` (part of ffmpeg) or `scale_npp` (needs nvcc-built ffmpeg) | `scale_cuda` is sufficient and dependency-light |
+| Multi-GPU | `-init_hw_device cuda=cu:1`, encoder `-gpu N` | probe must test the *specific* device index it will advertise |
+| Encode | `-c:v h264_nvenc / hevc_nvenc / av1_nvenc` | `av1_nvenc` exists only on Ada+ builds of ffmpeg ≥ 5.0 |
+| Quality | `-preset p1..p7` (p7 slowest/best), `-tune hq\|ll\|ull`, `-multipass qres\|fullres` | p4–p5 is the sweet spot for VOD |
+| Rate control | `-rc vbr -cq N -b:v 0` (quality-targeted VBR) or `-rc constqp` | prefer `-cq` + `-b:v 0` for PeerTube's CRF-style outputs |
+| Lookahead/AQ | `-rc-lookahead`, `-spatial_aq`, `-temporal_aq`, `-bf`, `-b_ref_mode middle` (Turing+) | the Turing+ quality levers |
+| 10-bit HEVC | `-profile:v main10 -pix_fmt p010le` | verify per generation (§1.2) |
+| Session hygiene | `-delay 0`, and **one encode context per session** | sessions are the scarce resource on GeForce (§1.1) |
+| Verification | run under `nvidia-smi dmon -s u` (enc/dec columns), check encoder-session count delta | this is the no-silent-CPU *evidence*, see §5.4 |
+
+Minimal VRAM budget per 1080p hw pipeline ≈ 200–400 MiB (decode surfaces +
+scale + encode lookahead); 4K ≈ 0.8–1.5 GiB. The probe measures real usage
+per resolution class instead of trusting these numbers.
+
+---
+
+## 2. What an NVIDIA worker is (profile)
+
+Same shape as the Intel worker — official runner, admission controller,
+status JSON, drain control — differing only in the probe module, deps, and
+concurrency inputs.
+
+### 2.1 Differences for `install-peertube-worker.sh`
+
+| Aspect | Intel QSV worker | NVIDIA worker |
+|---|---|---|
+| Kernel/driver deps | `intel-media-va-driver-non-free`, oneVPL runtime, `/dev/dri/renderD128` + `render`/`video` groups | `nvidia-open` kernel module + pinned driver branch, `libnvidia-encode`, `nvidia-smi`, `nvidia-persistenced`, user in `video` group |
+| Device nodes | `/dev/dri/*` (always present) | `/dev/nvidia*` (created by module; `nvidia-modprobe`/udev) |
+| Probe module | `intel-qsv` | `nvidia-nvenc` (new module, same interface) |
+| Config additions | — | `PT_WORKER_GPU_DEVICES=0` (or `0,1`), `PT_WORKER_SESSIONS_RESERVE=1` (headroom sessions), `PT_WORKER_VRAM_FLOOR_MB=1024`, `PT_WORKER_DRIVER_MIN=550` |
+| Self-test | vainfo + QSV transcode | nvidia-smi gates + per-device NVENC transcode + session-slot test + VRAM floor (§5.3) |
+| Concurrency inputs | engine util, CPU/RAM | `min(sessions_free, cpu_bound, ram_bound, vram_bound, disk_bound, bw_bound)` |
+| Runner invocation | as Intel contract | plus `-gpu N` device pinning in the ffmpeg argv and one runner instance per GPU when a box has >1 GPU (see §2.2) |
+
+Everything else — systemd unit shape, service account, Tailscale posture,
+registration, VOD-only job types, drain semantics — is inherited unchanged.
+
+### 2.2 Multi-GPU boxes
+
+A box with K GPUs runs **K runner instances** (`peertube-worker@gpu0…gpuK-1`
+template units), each pinned to one device, rather than one runner juggling
+devices. Reasons: session accounting and VRAM floors are per-device;
+admission states (GPU_UNAVAILABLE for one card after a co-tenant/ECC event)
+should not drain healthy siblings; PeerTube sees N independent runners and
+load-balances them natively. [E: this host has 2× RTX 3090 and would onboard
+as `…:gpu0` and `…:gpu1`.]
+
+---
+
+## 3. Dynamic pool design
+
+### 3.1 Architecture
+
+```
+                ┌────────────────────────────────────────────┐
+                │ pool-manager (new, small, stateless-ish)   │
+                │  signals → policy engine → per-worker      │
+                │  desired state (AVAILABLE/DRAINED +        │
+                │  concurrency hint + job-class eligibility) │
+                └───────┬───────────────────┬────────────────┘
+        read-only admin │                   │ control channel (SSH over
+        API polls       │                   │ Tailscale → pt-worker CLI)
+   PeerTube ◄───────────┘                   ▼
+   keeps THE job queue          worker-1 (Intel, QSV)   worker-2 (NV gpu0) …
+   and does assignment          admission controller     admission controller
+                                + peertube-runner        + peertube-runner
+```
+
+The pool manager **never talks to PeerTube as a scheduler**. It only (a)
+observes queue pressure read-only, (b) starts/stops/drains worker services,
+(c) sets admission state and concurrency. Assignment remains PeerTube's, via
+the official runner request/accept cycle. This honors the "do not build a
+new job scheduler" constraint.
+
+### 3.2 (a) Load signals
+
+| Signal | Source | Cadence | Notes |
+|---|---|---|---|
+| `pending_depth` | PeerTube admin API: runner-jobs endpoint filtered by state=pending, per job type (vod-web-video / vod-hls / vod-audio-merge) | 15 s | the primary scale-up input |
+| `oldest_pending_age_s` | same endpoint, `createdAt` of oldest pending job | 15 s | catches stall at low depth (e.g. one 4K job nobody can serve) |
+| `completed_rate_ewma` | per-worker status JSON `jobs_completed` counters | 30 s | throughput of the currently-active set |
+| `enc_util`, `dec_util` | NVIDIA: `nvidia-smi --query-gpu=encoder.utilization...`/NVML; Intel: media-engine counters per Intel contract | 10 s | saturation of the active set |
+| `sessions_active/cap` | our own accounting + NVML where supported | per-job event | GeForce cap awareness (§1.1); NVML unsupported on WSL2 [E] |
+| `vram_free_mb` | NVML | 10 s | hard eligibility floor |
+| `recent_download_mbps` / `upload_mbps` (EWMA) | per-job transfer observations (Intel contract already defines these) | per-job | job-size-aware eligibility input |
+| `realtime_factor_ewma` | completed jobs (encode wall-clock vs duration) | per-job | learned worker weight (§3.3) |
+| `throttle_reasons`, `temp_c` | NVML throttle-cause bits / thermal zones | 10 s | THERMAL_THROTTLED mapping [E: counters visible on this host] |
+
+Pressure index (normalized 0..1), computed over *eligible* workers only:
+
+```
+P = clamp01( max(
+    pending_depth / (2 * Σ active_capacity_slots),
+    oldest_pending_age_s / 900s
+))
+```
+
+`Σ active_capacity_slots` = Σ over AVAILABLE/BUSY workers of their current
+concurrency hint. The `2×` makes P=1 mean "queue is two full waves deep".
+
+### 3.3 (b) Policy engine
+
+**Pool-worker states** (per worker; these are *manager-side* views layered
+on the worker's own admission states from the Intel contract):
+
+| Manager state | Meaning | Transition in |
+|---|---|---|
+| `COLD` | powered off / suspended (WoL-able, §3.8) | manual or WoL policy |
+| `SPARE` | service up, admission DRAINED (registered, idle) | default resting state |
+| `WARM` | service up, DRAINED, persistence-mode on, probe recently green | pre-warm tier |
+| `ACTIVE` | admission AVAILABLE at concurrency C | scale-up decision |
+| `DRAINING` | admission DRAINING, in-flight jobs finishing | scale-down or fault |
+| `COOLDOWN` | admission DRAINING after repeated job failures | failure policy |
+
+**Hysteresis** (per-worker and pool-wide):
+
+- Scale **up** when `P ≥ 0.6` sustained ≥ 90 s (two consecutive 45 s windows)
+  → promote the highest-weight SPARE/WARM worker to ACTIVE.
+- Scale **down** when `P ≤ 0.15` sustained ≥ 20 min **and** worker has been
+  idle ≥ 15 min → demote ACTIVE → SPARE (drain, then optional service stop).
+- Never demote below `min_active = 1` (or 2 once multi-tenant), regardless
+  of idle, to keep probe freshness and WoL-free response.
+- Promotions are staggered ≥ 30 s apart and probe-gated: a worker may only
+  become ACTIVE if its last probe is < 5 min old and green. This prevents
+  thundering-herd registration wake-ups and GPU re-init spikes.
+- Failure fast-path bypasses all hysteresis: GPU_UNAVAILABLE, thermal, or a
+  hardware-evidence-failed job → immediate DRAINING.
+
+**Per-worker learned weights** (used for promotion order and drain order):
+
+```
+w_i = EWMA_λ=0.3 over jobs of ( output_pixel_rate_i / class_baseline )
+      shrunk toward class prior:  ŵ = (n·w + k·w_prior) / (n + k),  k=3
+```
+
+`output_pixel_rate` = output pixels/sec during encode phase only (excludes
+download/upload), bucketed by job class so a worker isn't punished for
+getting small jobs. Cold-start workers inherit the class prior, so a new
+box's first promotion comes from queue pressure, not fabricated history.
+Drain order prefers low `ŵ` *and* low `recent_download_mbps` (cheapest to
+re-warm).
+
+**Job-size-aware eligibility.** Job classes from PeerTube job metadata
+(source resolution × duration, known at pending time):
+
+| Class | Definition (approx) | Requires |
+|---|---|---|
+| S | ≤1080p, ≤10 min | any ACTIVE worker |
+| M | ≤1080p long, or 1440p | enc_util headroom ≥ 30% |
+| L | 4K, or 4K-source→1080p | `realtime_factor_ewma ≥ 3`, `recent_download_mbps ≥ 50`, `vram_free ≥ 4 GiB` (NVIDIA) or equivalent QSV gate |
+| XL | 4K60 long-form | L gates + `ŵ ≥ 1.0` |
+
+Enforcement is, again, selective availability: when an L/XL job is pending
+and no one satisfies the gates, the manager *keeps* the small workers at
+their normal concurrency but does not count them as capacity for that job
+(PeerTube will still let a small worker take it if it asks — acceptable
+fallback, not silent CPU fallback, and it still satisfies the hardware
+rule).
+
+### 3.4 (c) Scale-up / scale-down mechanics
+
+The constraint: **PeerTube runner registration is static.** A runner row
+exists server-side from first `register` (with a registration token) until
+an admin deletes it; the runner process merely polls. Therefore:
+
+*Joining the pool* =
+1. box provisioned + runner registered **once** at install time
+   (`install-peertube-worker.sh --name w2:gpu0 …`),
+2. service exists but may be stopped or admission-DRAINED,
+3. manager: `systemctl start peertube-worker@…` (if stopped) then
+   `pt-worker enable` → admission AVAILABLE → runner starts
+   requesting jobs on its normal poll cycle.
+
+*Leaving the pool* (grace) =
+1. `pt-worker drain` → admission DRAINING; the controller stops offering
+   the runner for new jobs (per Intel contract: runner paused/disabled, not
+   killed),
+2. wait for in-flight jobs: `active_jobs → 0`, with a max-drain timeout
+   (e.g. 2× p99 job wall-clock, floor 30 min),
+3. then either leave at SPARE (service up, DRAINED — cheapest re-join) or
+   `systemctl stop` for overnight-class quiescence, or suspend (§3.8).
+
+Notes:
+- Repeated start/stop never touches registration tokens; tokens live only
+  in the install-time secret path on the worker.
+- Because a drained runner is still *registered*, PeerTube's per-runner
+  job-request rate is unaffected; there is no server-side cleanup needed.
+- One job → many sessions: PeerTube runs separate ffmpeg instances per
+  output rendition, so a "concurrency 1" job can still consume 4+ NVENC
+  sessions. The admission controller must therefore count **actual encode
+  sessions** (its own children's NVENC contexts), not just jobs, when
+  enforcing `sessions_active < cap` (§1.1, §5.3).
+
+### 3.5 (d) Mixed-vendor scheduling
+
+We cannot intercept PeerTube's runner→job assignment, so vendor preference
+is expressed as *eligibility*, decided at the moment a job class is pending:
+
+| Job / condition | Prefer | Mechanism |
+|---|---|---|
+| AV1 **source** | NVIDIA Ampere+ (NVDEC AV1) or CPU-decode on QSV box | gate QSV workers out of the AV1-decode class via probe capability (`av1_dec`) |
+| AV1 **output** | NVIDIA **Ada+ only** (`av1_enc`) | same gate; policy says: not enabled in production anyway |
+| 4K HEVC/H.264 outputs | NVIDIA (throughput, VRAM for lookahead) | weight-based promotion pulls NVENC boxes in first at L/XL classes |
+| ≤1080p H.264 bulk | whichever has session/enc headroom; QSV is typically *more* power-efficient per 1080p job | neutral; capacity-driven |
+| Session pressure (NVENC near cap, QSV idle) | QSV | temporarily demote NVENC availability for class S/M |
+| One vendor fleet-wide drained (driver CVE, bad driver branch) | the other | vendor-level kill switch in manager config: `vendor_disabled: [nvidia]` |
+
+Probe capability keys that drive this (identical names across vendors):
+`h264_enc, hevc_enc, av1_enc, h264_dec, hevc_dec, av1_dec, max10bit`,
+`max_sessions`, `max_width/height`. The Intel probe fills the same keys
+(i5-1240P: `h264_enc=1, hevc_enc=1, av1_enc=0, av1_dec=1`), which is the
+whole point of the pluggable module.
+
+### 3.6 (e) Unified status/metrics schema
+
+Extends the Intel status JSON with a versioned, vendor-generic `gpu` block.
+Bump `schema_version`; additive changes only.
+
+```jsonc
+{
+  "schema_version": 2,
+  "hostname": "w2", "runner_name": "w2:gpu0",
+  "tailscale_ip": "100.x.y.z", "net_path": "DIRECT|DERP",
+  "state": "AVAILABLE",            // Intel-contract states, unchanged
+  "registration_state": "registered",
+  "active_jobs": 1, "concurrency": 3, "concurrency_limiters": {
+      "cpu": 4, "ram": 4, "disk": 8, "bw": 3,
+      "gpu_sessions": 3,           // NVIDIA only; null on Intel
+      "vram": 3
+  },
+  "gpu": {                          // NEW: vendor-generic
+    "vendor": "nvidia",             // "intel" | "nvidia" | "none"
+    "probe_module": "nvidia-nvenc", // "intel-qsv" | "nvidia-nvenc"
+    "model": "RTX 3090", "generation": "ampere",
+    "nvenc_generation": 5,
+    "driver": "595.58.03", "kernel_module": "open",
+    "capabilities": { "h264_enc": 1, "hevc_enc": 1, "av1_enc": 0,
+                      "h264_dec": 1, "hevc_dec": 1, "av1_dec": 1,
+                      "max10bit": 1 },
+    "sessions": { "active": 2, "cap": 8,
+                  "cap_source": "driver_class_table|nvml|probe" },
+    "devices": [ { "index": 0, "uuid": "GPU-2095…",
+                   "vram_total_mb": 24576, "vram_free_mb": 22000,
+                   "enc_util_pct": 71, "dec_util_pct": 40,
+                   "temp_c": 66, "throttle_reasons": [] } ],
+    "self_test": { "ts": "2026-10-09T14:00:00Z", "ok": true,
+                   "evidence": "enc_util_delta=+68%", "detail": "…" }
+  },
+  "hw_evidence_last_job": { "ok": true,
+      "method": "encoder_session_delta>=1", "ts": "…" },
+  "cpu": {"model": "…", "util_pct": 40}, "temps_c": {"cpu": 55},
+  "disk_free_gb": 180,
+  "recent_download_mbps": 92.4, "recent_upload_mbps": 88.1,
+  "jobs": {"completed": 214, "failed": 3, "hw_fallback_prevented": 0},
+  "last_job": {"duration_s": 412, "realtime_factor": 7.1,
+               "class": "M", "output_pixel_rate_mpx_s": 22.6},
+  "manager": {"desired": "ACTIVE", "weight": 1.14, "class_gates": "ok"}
+}
+```
+
+Prometheus mapping is mechanical: one `pt_worker_up`, one
+`pt_worker_gpu_sessions{vendor,cap_source}`, one
+`pt_worker_hw_evidence_ok` (the no-silent-CPU invariant as an alertable
+series), plus re-exports of the Intel contract's series.
+
+### 3.7 (f) Future: bare-metal autoscaling hooks (WoL)
+
+Brief by request. If worker boxes are wakeable:
+
+- Manager keeps `wol_mac`, `wake_budget` (max 2 concurrent wakes, ≥ 3 min
+  apart), and a boot-readiness check = Tailscale SSH + agent status JSON
+  with fresh probe (typical budget 3–6 min including GPU persistence).
+- Wake policy reuses the scale-up rule with an extra tier: only wake when
+  `P ≥ 0.8` sustained 5 min and all SPARE/WARM workers are ACTIVE
+  (i.e. waking is the last resort, because boot latency is minutes not
+  seconds).
+- Sleep path = graceful drain (§3.4) then `systemctl suspend`; AC/battery
+  rules from the Intel laptop policy apply first (never sleep a box on
+  battery, never wake one).
+- Accounting: track `wakes/day` and `woken-minutes-saved` per box; cap wakes
+  (e.g. ≤ 6/day/box) to respect hardware and power-on cycles.
+
+---
+
+## 4. Rollout plan
+
+### 4.1 Change the Intel admission controller NOW (small interface list)
+
+Five things, all cheap while the code is fresh:
+
+1. **Versioned status JSON**: add `schema_version: 1` today, and the
+   vendor-generic `gpu` block shape (§3.6) with `"vendor": "intel"` —
+   i.e. `gpu.probe_module`, `gpu.capabilities{h264_enc,hevc_enc,av1_enc,
+   h264_dec,hevc_dec,av1_dec}`, `gpu.model/generation`, per-device array
+   (Intel: one entry, `/dev/dri/renderD128`, `enc_util` from media-engine
+   counters). Avoid leaking QSV-specific keys to the top level.
+2. **Probe interface contract** (document, even if only one impl exists):
+   `probe() → {ok, capabilities, maxSessions?, devices[], evidence}` and
+   `verifyHardwareDidWork(jobSamples) → {ok, evidence}` — both **fail
+   closed**: any exception, timeout, or absent evidence ⇒ GPU_UNAVAILABLE +
+   drain, never "assume CPU is fine". Selectable via
+   `PT_WORKER_GPU_PROBE=intel-qsv|nvidia-nvenc`.
+3. **Concurrency resolver** as a pure function of
+   `(probe, cpu, ram, disk, bw, [sessions], [vram])` so NVIDIA is a new
+   input set, not a new control path. Expose which limiter bound the choice
+   (`concurrency_limiters`, §3.6) — this is what the pool manager consumes.
+4. **Hardware-evidence hook per job**: after each completed job, sample the
+   GPU's encoder utilization delta (Intel: media-engine busy% delta during
+   the job; NVIDIA: NVML encoder-session/util delta) and record
+   `hw_evidence_last_job`. A job that completed without evidence must count
+   as a *failure* for pool purposes even if PeerTube marks it OK — this is
+   the enforcement teeth of the no-silent-CPU rule, and it is vendor-neutral.
+5. **Job-class metadata in per-job telemetry** (source res/codec, output
+   renditions, wall-clock, realtime factor) so the manager's weights and
+   gates (§3.3) have data from day one on the Intel cluster.
+
+### 4.2 Onboarding the first NVIDIA box (when one exists)
+
+1. Pick the platform: **native Linux** (Debian 12/13), Turing or newer;
+   Ada+ if AV1 encode is ever wanted. Reject A100/H100-class compute cards
+   (no NVENC, §1.1).
+2. Driver install, pinned branch (≥ 550; open kernel modules for Turing+),
+   `nvidia-persistenced`, user in `video`, verify
+   `nvidia-smi` + `libnvidia-encode.so.1` present. Reboot-verify.
+3. ffmpeg: distro build is fine if it lists `h264_nvenc`/`hevc_nvenc` and
+   `*_cuvid` **[E: Debian 12's ffmpeg 5.1.9 does]**; else pin a static
+   BtbN/johnvansickle-style build ≥ 5.0 with ffnvcodec. Record
+   `ffmpeg --version` in status JSON.
+4. `install-peertube-worker.sh --name <host>:gpu0 --gpu-probe nvidia-nvenc
+   --gpu-devices 0 …` — same script, new profile (§2.1). Per additional GPU
+   on the box, repeat with `:gpu1`, … (§2.2).
+5. Self-test gate (must pass before registration): see §5.3 — nvidia-smi
+   gates → per-device NVENC encode probe under `dmon` → session-slot test →
+   VRAM floor. Fail ⇒ abort install with `GPU_UNAVAILABLE`, no runner
+   registration.
+6. Register runner (VOD job types only, per Intel contract), start service,
+   run one real E2E job, and assert hardware evidence: encoder-session
+   delta ≥ 1 per rendition and enc-util delta > 0 **and** CPU-user-time of
+   the ffmpeg process ≪ CPU-encode baseline (belt and braces).
+7. Soak: 1 h at target concurrency; watch sessions, VRAM, temps, throttle
+   reasons, throughput; set the box's initial `concurrency` from measured
+   end-to-end throughput, not single-job fps (Intel Phase 9 methodology,
+   unchanged).
+8. Add to pool manager inventory as `SPARE` with class-prior weight; first
+   promotion happens on the next pressure event.
+9. Only then consider multi-GPU boxes and WoL tiers (§3.7).
+
+---
+
+## 5. Appendices
+
+### 5.1 Failure-mode → state mapping (NVIDIA additions)
+
+| Failure | Detection | State | Action |
+|---|---|---|---|
+| Driver/module missing or unloaded | nvidia-smi nonzero, no `/dev/nvidia*` | GPU_UNAVAILABLE | refuse work; re-probe 60 s |
+| VRAM exhausted (co-tenant, leak) [E] | CUDA_ERROR_OUT_OF_MEMORY / "No capable devices found" in ffmpeg init; NVML `vram_free` below floor | GPU_UNAVAILABLE (device-scoped) | drain that device's runner; sibling GPUs unaffected (§2.2) |
+| Session cap hit | our accounting ≥ cap − reserve | BUSY (capacity) | no new jobs until sessions free; never queue extra ffmpeg per job |
+| Thermal/power throttle | NVML throttle-cause bits, temp ≥ limit | THERMAL_THROTTLED | drain after in-flight; cooldown |
+| Encoder produced no HW evidence | `hw_evidence_last_job.ok=false` | GPU_UNAVAILABLE + job counted failed | page; **never** re-run on CPU |
+| Driver/GPU fallen off bus (Xid errors in dmesg) | dmesg `NVRM: Xid` watch | OFFLINE | drain + host-level alert |
+| Network DERP/throughput collapse | Intel contract's EWMA + path change | NETWORK_DEGRADED | unchanged from Intel |
+
+### 5.2 Config surface (NVIDIA profile)
+
+```
+PT_WORKER_GPU_PROBE=nvidia-nvenc
+PT_WORKER_GPU_DEVICES=0            # one runner instance per device
+PT_WORKER_SESSIONS_CAP=auto        # nvml → driver_class_table → 8 (GeForce)
+PT_WORKER_SESSIONS_RESERVE=1       # keep 1 session headroom
+PT_WORKER_VRAM_FLOOR_MB=1024
+PT_WORKER_DRIVER_MIN=550
+PT_WORKER_FFMPEG_NVENC_PRESET=p5   # map PeerTube quality tier → preset
+PT_WORKER_PROBE_INTERVAL=300       # full probe; 10 s counters in between
+```
+
+### 5.3 `nvidia-nvenc` probe / self-test design (ordered, fail-closed)
+
+1. **Gate**: `nvidia-smi` exits 0; driver ≥ min; module flavor recorded;
+   `libnvidia-encode.so.1` resolvable; ≥1 device with `vram_free ≥ floor`.
+2. **Capability enumeration**: per advertised device, from NVML name →
+   generation → capability table (§1.2/§1.3), *then verified empirically*:
+   attempt a 1-second `h264_nvenc` encode on that exact device (`-gpu N`);
+   attempt `hevc_nvenc`; attempt `av1_nvenc` only if generation ≥ Ada.
+   Absence of an encoder in `ffmpeg -encoders` downgrades capability
+   without failing the probe (e.g. distro ffmpeg without av1_nvenc).
+3. **Pipeline probe**: full hw chain (§1.6) at 1080p on the target device
+   under `nvidia-smi dmon -s u`; require `enc>0` and `dec>0` columns
+   observed during the run, and record VRAM delta as the per-class budget.
+4. **Session-slot test**: launch K parallel tiny `h264_nvenc` encodes
+   (K = advertised cap) and count how many initialize successfully
+   (`No capable devices found` / init failure = slot unavailable). The
+   largest K′ that succeeds becomes `sessions.cap` with
+   `cap_source=probe`. This is the ground truth the controller trusts —
+   it automatically reflects driver-class caps **and** whatever the
+   platform (e.g. WSL2 [E]) actually allows.
+5. **Decode matrix**: one decode-only pass per codec family
+   (h264/hevc/av1 `*_cuvid`) on a synthetic stream, asserting `dec>0`.
+6. **Report**: fill the §3.6 `gpu` block, include `dmon` excerpts and VRAM
+   deltas as `evidence`. Any step erroring or timing out (30 s/step) ⇒
+   `ok=false` ⇒ GPU_UNAVAILABLE. No step may conclude "use CPU instead".
+
+### 5.4 Enforcing the no-silent-CPU rule on NVIDIA
+
+Three independent tripwires, any one sufficient to fail a job:
+
+1. **Argv gate**: the wrapper/runner must be invoking `*_nvenc` for video
+   (grep the spawned argv); PeerTube's own fallback logic must be
+   disabled/refused in config.
+2. **Evidence gate**: NVML encoder-session count and encoder utilization
+   must increase while the job's ffmpeg runs (sampled ≥ 1 Hz); a completed
+   encode with flat counters = CPU fallback (or a no-op) ⇒ job marked
+   failed, worker GPU_UNAVAILABLE, manager COOLDOWN.
+3. **Plausibility gate**: ffmpeg CPU user-time for the job must be far
+   below the CPU-encode baseline for that resolution (measured once per
+   box during install); a CPU-encode-shaped CPU profile ⇒ same treatment.
+
+This is deliberately vendor-neutral (Intel uses media-engine busy% in place
+of NVML counters), which is exactly why it belongs in the shared admission
+controller rather than in the probe module.
+
+### 5.5 Open questions for the Intel implementation (blocking-free)
+
+- Exact admin endpoint + auth shape for pending runner-jobs depth (manager
+  needs it read-only; a proxy via the worker's own credentials is
+  acceptable if admin scope is unavailable).
+- Whether the Intel drain implementation pauses the runner process or
+  stops the unit — the manager wants to treat both as DRAINED and needs to
+  know which to expect for start/stop idempotency.
+- Whether per-rendition ffmpeg invocation is confirmed (drives
+  session-counting assumptions, §3.4).
diff --git a/docs/design/control-room-scope.md b/docs/design/control-room-scope.md
new file mode 100644
index 0000000..a0062a7
--- /dev/null
+++ b/docs/design/control-room-scope.md
@@ -0,0 +1,16 @@
+# Control Room — scope statement (user, 2026-10-07)
+
+The streaming service's job: view several screens and mix. (A separate mobile app is being developed and integrates LATER.)
+
+## Web (the "simplified OBS")
+1. **Multiview grid**: watch multiple live feeds simultaneously — layouts 2x1, 2x2, 3x3, 4x4.
+2. **Audio control**: pick ONE feed's audio, or MIX several audios.
+3. **Program out**: select what goes out — a single feed, or a mix/composite of feeds.
+4. **Overlays**: easily editable lower thirds; SCROLLING lower thirds (chyron); logo overlay from SVG input.
+5. **Playlist fallback**: schedule a playlist that plays on the PeerTube channel when no feeds are live.
+
+## Mobile (later integration)
+Simple controls for putting something live — preview→program flow, "go live from preview".
+
+## Research question
+Best way to incorporate this OBS-type experience (much simplified) into the existing stack: media-worker (supervisor + ffmpeg relay + signed command bus), live monitor, media-control plane, PeerTube connector.
diff --git a/docs/design/design-merged.md b/docs/design/design-merged.md
new file mode 100644
index 0000000..ebbe32a
--- /dev/null
+++ b/docs/design/design-merged.md
@@ -0,0 +1,453 @@
+# Merged Design — Group Review & Signoff for Posts
+
+Status: design for implementation (merge of three proposals + user decisions v2, pending audit)
+Date: 2026-10-07 (v2: connection-scoped approval delegation added per user decision)
+Inputs: `runs/wp5/proposal-opus.md` (rigor/defense-in-depth), `runs/wp5/proposal-sol.md` (submission lifecycle), `runs/wp5/proposal-glm.md` (minimal surface), spec `runs/wp5/spec-review-workflow.md`, user decisions 2026-10-07
+
+**Provenance legend**: [OP], [SOL], [GLM] mark which proposal a decision comes from; [ALL] = all three converged; [MERGE] = this document's synthesis.
+
+---
+
+## 1. Executive summary — what this design is
+
+1. **[OP] The foundation is fixed first.** Eight pre-existing defects (§2) are repaired in a prerequisite migration because the review feature multiplies each of them. Most critically: the scheduler currently publishes without checking draft state, and the audit hash does not cover the `diff` field (so "snapshot hash in the audit log" would not be tamper-evident).
+2. **[ALL] Group roles are a column on `group_members`** — `member | editor | reviewer`, mutually exclusive by construction. The existing epoch trigger fires on UPDATE, so role changes invalidate sessions for free.
+3. **[GLM+OP] Approvals attach to immutable version rows with a database-computed hash.** `post_versions.content_hash` is a Postgres *generated column* — it can never disagree with the content [GLM]. Votes copy the hash they approve; the scheduler publishes the approved version's bytes, never the mutable draft [OP]. **[AUDIT #24]** The defence order is explicit: §6.6 full-reset is the primary defence; the §4.2 schedule-time hash check is a backstop whose refusal is a 409 `STALE_VERSION` directing the author to re-submit — never a silent second path, never an approved-but-unschedulable draft.
+4. **[SOL+GLM] The review cycle is the unit of approval.** One `review_cycles` row per (draft, round) pins version, group (nullable + `group_name` snapshot [AUDIT #16]), quorum, deadline, and status. Quorum config (workspace default + group override) is **snapshotted at submit** — config changes never move goalposts mid-review [ALL].
+5. **[ALL] A single deny is a veto** — cycle closes `denied`, draft → `needs_changes` (replaces today's terminal `rejected`, unlocking resubmit). Deny asks for a reason in the UI (optional but suggested [USER v2]; recorded in thread + audit when given). Any content edit supersedes the cycle; resubmit always starts at 0/N.
+6. **[GLM] Chat is polling first** (4 s cursor endpoint), over [SOL]'s unified event log: chat messages and system events are rows in one `review_events` table. Schema is transport-agnostic; SSE doorbells [OP] are a later upgrade.
+7. **[GLM] Deadlocks are refused at the door — with one defined exception [AUDIT #17]**: submit runs an eligibility preflight ("not enough eligible reviewers (0) for quorum (2)") and 400s when quorum ≥ 2 is unreachable; when N=1 and 0 eligible reviewers exist, the cycle is still created, directly in `blocked` (`blocked-at-submit`), so the admin override always has a cycle to act on and quorum 1 never silently self-approves a solo author. A distinct `blocked` state handles mid-review reviewer-pool shrinkage. Admin override is a separate, reason-required action that writes no vote row [SOL+OP].
+8. **[GLM] `published` is the archive; moderation is flags, not states.** Hide/delete are admin-only soft flags; the scheduler's `scheduled→published` write needs zero changes.
+9. **[USER v2] Approval authority is per-account (connection), chosen when the account is added.** Every connection declares one of two approval modes: **`system`** — approvals flow through the group/workspace reviewer chain (the default), or **`delegated`** — the account's owner (whoever added/controls it) names the specific people who approve what goes out **from that account**. This scales to hundreds of accounts, each with its own approver pool. Quorum size and admin control remain **group settings** (§3.4).
+
+New states: `primed` [SOL], `needs_changes` [ALL], `expired` [ALL], `blocked` [GLM]. The state machine is enforced **twice**: CAS UPDATEs in the service and a DB legal-transition trigger (defense in depth) [ALL].
+
+---
+
+## 2. Prerequisite fixes (WP5.0) — from [OP], all verified real
+
+| # | Where | Defect | Fix |
+|---|---|---|---|
+| D1 | `apps/scheduler/src/activities/publish.activity.ts:136-141` | `claim()` joins drafts but never checks `d.state`; publishes any pending schedule row's `d.post` | claim requires `state='scheduled'` (plus the pending `scheduled_publications` row); publish `post_versions.post` of `approved_version_id` (post-011) |
+| D2 | `publish.activity.ts:79` | claim runs outside `try`; "not pending" throw retries forever (no retry limit) | move inside try; use non-retryable application error |
+| D3 | `001_tenants.sql:92-98` | `audit_hash` excludes `diff` — values recorded in diff are not tamper-evident | migration 010: hash v2 covers diff; verify both versions |
+| D4 | `publishing.service.ts:136+` | audit written after commit — crash window loses audit rows | same-tx `audit_append` via withTenant client (groups pattern, `groups.service.ts:123-133`) |
+| D5 | `publishing.controller.ts:113-129` + `rbac.guard.ts:64-74` | `schedule` takes `connectionId` from body; `RequireGroupAccess` only checks `:connectionId` params | validate body connection against group scope via `userCanUseConnection` - kept as the **API-level guard**; 4.1(3) adds the composite FK + seal-time trigger as the DB backstop [SECURITY #9] |
+| D6 | `realtime/gateway.ts:20-29` | epoch compared against raw bigint string (always "stale"); membership query omits `status='active'` | normalize to text compare; add status filter (kept even though we don't build WS now) |
+| D7 | `api-client.ts:90` + guard | any epoch bump 401s every user and the client drops the token — no re-issue | `POST /auth/reissue`: re-read live authz, mint fresh token; client retries once on epoch-401 |
+| D8 | `002_rbac_seed.sql:9,25,35` | `publication.delete` seeded to Owner/Admin/**Publisher**, unenforced | do not reuse it for moderation; new dedicated perms (§3) |
+
+Migrations: **`010_audit_hash_v2.sql`** (D3: `hash_version` column, `audit_hash_v2` covering diff, advisory-lock append serialization, dual-version `audit_verify_chain`) — full SQL in `proposal-opus.md` §2.2.
+
+---
+
+## 3. Roles & permissions (R2)
+
+### 3.1 Group roles [ALL]
+```sql
+ALTER TABLE group_members
+  ADD COLUMN review_role text NOT NULL DEFAULT 'member'
+    CHECK (review_role IN ('member', 'editor', 'reviewer'));
+```
+- **member**: author drafts, chat in review threads.
+- **editor**: edit any group post's content; submit for review; **cannot** approve/deny/publish.
+- **reviewer**: approve/deny (reason suggested, optional [USER v2]); **cannot** edit content.
+- Mutually exclusive single column = structural separation of duties. Role changes bump the authz epoch (trigger already fires on UPDATE, `008_groups.sql:79-80`); the service returns a `{token}` replacement for the caller (existing pattern, `groups.service.ts:226-269`) [ALL].
+- Workspace roles remain the *floor*: any review role still needs `draft.view` via active membership.
+
+### 3.2 New permissions [MERGE]
+| permission | granted to | purpose |
+|---|---|---|
+| `review.manage` | Owner, Admin | set workspace/group quorum, stale_after |
+| `approval.override` | Owner, Admin | reason-required override of a blocked/expired cycle (writes no vote) |
+| `moderation.hide` | Owner, Admin | hide a post (flag) |
+| `moderation.delete` | Owner, Admin | soft-delete a post (flag) |
+
+Author exclusion is **structural**: eligibility SQL excludes the author, every row in `draft_contributors` [OP], and (for override) any contributor. Sealed-by also excluded [OP].
+
+### 3.4 Group settings [USER v2]
+Groups carry the review settings (writable by `review.manage` holders): **quorum** (`review_approvals_required`, NULL = inherit workspace default) and **admin control** (`review_admin_control`: whether Owner/Admin may exempt their own posts from review or override a stuck cycle in this group).
+
+### 3.5 Connection approval modes [USER v2 — per-account delegation]
+Every account (connection) declares how its approvals work, set/changed by the connection's controller (its owner / whoever added it) or workspace admins:
+- **`system`** (default): the group's reviewer chain approves (§3.1).
+- **`delegated`**: the controller names a dedicated **approver pool for that account** (`connection_approvers`). Posts targeting this account need signoff from that pool — same quorum N from the group settings, same structural author/contributor exclusion. Group reviewers do **not** count for a delegated account unless also named in its pool.
+- Scale target: hundreds of connections, each with its own few approvers — "100 of accounts, and there are people per account who actually approve what goes out."
+- Admin override/exempt still applies per the group's `review_admin_control`, regardless of mode.
+
+### 3.3 Vote visibility [USER v2 — supersedes the merged blind default]
+**Fully transparent by default.** Everyone in the group sees the complete vote ledger during review: who approved, who denied, who is yet to vote ("2/3 — Ana ✓, Ben ✓, Chi pending"). Deny reasons (when given) are visible inline in the thread. No server-side identity masking. A `blind_votes` group setting remains available for teams that want blind review later, but transparency is the default posture: [USER] "votes etc super transparent".
+
+---
+
+## 4. Data model — `011_review_workflow.sql`
+
+(Numbering: `009_video.sql` already exists [OP, GLM caught this].)
+
+### 4.1 Tables
+
+```sql
+-- (1) group roles — §3.1
+-- (2) quorum config [GLM]
+CREATE TABLE workspace_review_settings (
+  workspace_id uuid PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+  approvals_required int NOT NULL DEFAULT 1 CHECK (approvals_required BETWEEN 1 AND 5),  -- [AUDIT #23] 0 is refused: no transition closes a required=0 cycle (deadlock-by-config)
+  stale_after_days int NOT NULL DEFAULT 90 CHECK (stale_after_days BETWEEN 1 AND 3650),
+  blind_votes boolean NOT NULL DEFAULT true,
+  updated_by uuid REFERENCES users(id),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+ALTER TABLE groups
+  ADD COLUMN review_approvals_required int CHECK (review_approvals_required BETWEEN 1 AND 5),  -- [AUDIT #23] same floor as the workspace default
+  ADD COLUMN review_blind_votes boolean,        -- NULL = inherit workspace default
+  ADD COLUMN review_admin_control boolean NOT NULL DEFAULT true;  -- [USER v2]
+-- Precedence resolved ONCE at submit: group row ?? workspace row ?? built-in default(1)
+-- and snapshotted onto the cycle (§6).
+
+-- (2b) per-account approval delegation [USER v2]
+ALTER TABLE connections
+  ADD COLUMN approval_mode text NOT NULL DEFAULT 'system'
+    CHECK (approval_mode IN ('system','delegated'));
+-- [AUDIT #9/#13] composite-FK target on connections: must exist before any FK that
+--   references connections(id, workspace_id) (connection_approvers, post_versions)
+ALTER TABLE connections ADD CONSTRAINT connections_id_ws_uk UNIQUE (id, workspace_id);
+
+CREATE TABLE connection_approvers (
+  workspace_id uuid NOT NULL,
+  connection_id uuid NOT NULL,
+  user_id uuid NOT NULL REFERENCES users(id),
+  assigned_by uuid NOT NULL REFERENCES users(id),
+  assigned_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (connection_id, user_id),
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections(id, workspace_id) ON DELETE CASCADE
+);
+-- Assignments: assigner must be the connection controller or hold connection.manage;
+-- approver must hold an active workspace membership. Changes bump the authz epoch
+-- (trigger, mirroring group_members) and revoke the removed approver's live votes.
+
+-- (2c) [AUDIT #5] composite-FK target on drafts: must exist before any FK that
+--   references drafts(id, workspace_id) (post_versions, draft_contributors,
+--   review_cycles, review_events below)
+ALTER TABLE drafts ADD CONSTRAINT drafts_id_ws_uk UNIQUE (id, workspace_id);
+
+-- (3) immutable versions [GLM hash mechanics + SOL target pinning]
+CREATE TABLE post_versions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  version int NOT NULL CHECK (version >= 1),
+  post jsonb NOT NULL,
+  connection_id uuid,                            -- sealed target; NOT NULL when draft is group-scoped [SOL]
+  content_hash text GENERATED ALWAYS AS (encode(digest(post::text, 'sha256'), 'hex')) STORED,
+  seal_kind text NOT NULL CHECK (seal_kind IN ('submit','edit','reopen','migrated')),
+  sealed_by uuid NOT NULL REFERENCES users(id),
+  sealed_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (draft_id, version),
+  UNIQUE (id, draft_id, workspace_id),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE,
+  FOREIGN KEY (connection_id, workspace_id) REFERENCES connections(id, workspace_id) ON DELETE RESTRICT  -- [SECURITY #9, AUDIT #13] composite FK: same-workspace target, DB-enforced; RESTRICT so a connection referenced by a sealed version cannot be deleted out from under it (connections are soft-disabled instead)
+);
+-- [AUDIT #11] Single contract, stated once: versions are update-immutable and
+--   cascade-deletable ONLY via `drafts` — the trigger rejects UPDATE outright and
+--   rejects any DELETE whose root is not the drafts cascade (pg_trigger_depth() check);
+-- BEFORE INSERT trigger requires connection_id when the draft has group_id [SOL].
+-- [SECURITY #9] Seal-time guard (BEFORE INSERT - a database invariant; D5 stays as the
+--   API-level guard): when connection_id IS NOT NULL the connection must belong to the
+--   SAME workspace (composite FK above) AND be in scope for the draft's group:
+--   drafts.group_id IS NULL OR EXISTS (SELECT 1 FROM group_connections gc
+--     WHERE gc.connection_id = NEW.connection_id AND gc.group_id = drafts.group_id).
+--   Any mismatch raises; a version is never sealed against a cross-tenant or
+--   out-of-scope connection.
+
+-- (4) contributors [OP]
+CREATE TABLE draft_contributors (
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  user_id uuid NOT NULL REFERENCES users(id),
+  first_at timestamptz NOT NULL DEFAULT now(),
+  last_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (draft_id, user_id),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE
+);
+-- [AUDIT #10] Append-only and immutable: a BEFORE INSERT/UPDATE/DELETE trigger
+--   rejects UPDATE and DELETE outright (contributor rows are history; last_at is
+--   never rewritten), with the sole exception of the drafts cascade
+--   (pg_trigger_depth() check). INSERT is the only legal mutation and it is
+--   mandatory: every seal (submit/edit/reopen) inserts rows for the sealer and any
+--   editor recorded since the last seal, in the same transaction — a post_versions
+--   seal trigger fails the tx if the sealer has no draft_contributors row.
+
+-- (5) review cycles [SOL shape, GLM snapshot semantics]
+CREATE TABLE review_cycles (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  group_id uuid,                                 -- [AUDIT #16] nullable: group delete SET NULL, mirroring drafts
+  group_name text,                               -- [AUDIT #16] group name snapshot at submit: audit trail survives group deletion
+  round int NOT NULL CHECK (round >= 1),
+  version_id uuid NOT NULL,
+  required_approvals smallint NOT NULL CHECK (required_approvals BETWEEN 1 AND 5),  -- [AUDIT #23] snapshot inherits the same 1..5 floor
+  policy_source text NOT NULL CHECK (policy_source IN ('group','workspace','default')),
+  approval_source text NOT NULL DEFAULT 'group' CHECK (approval_source IN ('group','connection')),  -- [USER v2]
+  blind_votes boolean NOT NULL,
+  publish_at timestamptz,                        -- declared schedule ("primed to go out")
+  deadline_at timestamptz NOT NULL,              -- LEAST(publish_at, submitted_at + stale_after)
+  status text NOT NULL CHECK (status IN
+    ('primed','in_review','approved','denied','superseded','expired','blocked','overridden')),
+  submitted_by uuid NOT NULL REFERENCES users(id),
+  submitted_at timestamptz NOT NULL DEFAULT now(),
+  closed_at timestamptz,
+  closed_reason text,
+  UNIQUE (draft_id, round),
+  UNIQUE (id, workspace_id),                     -- [AUDIT #5] composite-FK target for review_votes / review_overrides / review_events
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE,
+  FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id)
+    ON DELETE SET NULL (group_id),               -- [AUDIT #16] group deletion detaches the cycle; reference kept as history via group_name
+  FOREIGN KEY (version_id, draft_id, workspace_id)
+    REFERENCES post_versions(id, draft_id, workspace_id)
+);
+
+-- (6) votes [SOL constraints + OP hash binding]
+CREATE TABLE review_votes (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  cycle_id uuid NOT NULL,
+  voter_user_id uuid NOT NULL REFERENCES users(id),
+  decision text NOT NULL CHECK (decision IN ('approve','deny')),
+  reason text,                                   -- NOT NULL enforced for deny by CHECK
+  snapshot_sha256 text NOT NULL CHECK (snapshot_sha256 ~ '^[0-9a-f]{64}$'),
+  cast_at timestamptz NOT NULL DEFAULT now(),
+  revoked_at timestamptz,                        -- reviewer removed from group mid-review
+  revoked_reason text,
+  source text NOT NULL DEFAULT 'live' CHECK (source IN ('live','migrated')),
+  UNIQUE (cycle_id, voter_user_id),
+  CHECK (reason IS NULL OR btrim(reason) <> ''),   -- [USER v2] deny reason optional (UI-suggested); never stored blank
+  CHECK (revoked_at IS NULL OR (revoked_reason IS NOT NULL AND btrim(revoked_reason) <> '')),
+  FOREIGN KEY (cycle_id, workspace_id) REFERENCES review_cycles(id, workspace_id)
+    ON DELETE CASCADE                            -- [AUDIT #1] cycle-scoped history, no independent lifecycle: draft→cycle cascade must not be blocked
+);
+-- [AUDIT #11] Same single contract as versions and events: update-immutable, cascade-deletable
+--   only via `drafts` — the trigger rejects UPDATE of everything except the revoke fields
+--   (set only by the revocation trigger) and rejects any DELETE whose root is not the
+--   drafts cascade (pg_trigger_depth() check) [SOL].
+
+-- (7) overrides [SOL: separate table, one per cycle]
+CREATE TABLE review_overrides (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  cycle_id uuid NOT NULL,
+  admin_user_id uuid NOT NULL REFERENCES users(id),
+  reason text NOT NULL CHECK (btrim(reason) <> ''),
+  snapshot_sha256 text NOT NULL CHECK (snapshot_sha256 ~ '^[0-9a-f]{64}$'),  -- [AUDIT #19] same format constraint as review_votes
+  at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (cycle_id),
+  FOREIGN KEY (cycle_id, workspace_id) REFERENCES review_cycles(id, workspace_id)
+    ON DELETE CASCADE                            -- [AUDIT #1] cycle-scoped history, no independent lifecycle: draft→cycle cascade must not be blocked
+);
+-- append-only; BEFORE INSERT trigger: admin is Owner/Admin, NOT a contributor, cycle is blocked/expired,
+--   AND [AUDIT #19] NEW.snapshot_sha256 = (SELECT content_hash FROM post_versions WHERE id = cycle.version_id)
+--   — an override can only ratify the exact content the cycle pinned. The transition trigger's
+--   override-row requirement (4.2 enforce_review_transition) is the second layer.
+
+-- (8) unified event log = chat + system events [SOL]
+CREATE TABLE review_events (
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  seq bigint NOT NULL CHECK (seq > 0),           -- gapless per draft, allocated under draft row lock
+  cycle_id uuid,
+  kind text NOT NULL CHECK (kind IN
+    ('message','submitted','edited','approved','denied','vote_revoked','quorum_met',
+     'quorum_lost','needs_changes','blocked','unblocked','scheduled','expired',
+     'published','hidden','unhidden','deleted','override')),
+  actor_user_id uuid REFERENCES users(id),       -- NULL = system
+  body text,                                     -- required for kind='message'
+  data jsonb NOT NULL DEFAULT '{}',
+  CHECK (kind <> 'message' OR (body IS NOT NULL AND btrim(body) <> '')),  -- [AUDIT #18] message body must be non-empty
+  CHECK (octet_length(coalesce(body, '')) <= 8192),                      -- [AUDIT #18] bounded body: 8 KiB hard cap
+  CHECK (octet_length(data::text) <= 8192),                              -- [AUDIT #18] bounded event payload: 8 KiB hard cap
+  at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (draft_id, seq),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE,
+  FOREIGN KEY (cycle_id, workspace_id) REFERENCES review_cycles(id, workspace_id)  -- [AUDIT #20, #22] nullable composite FK to review_cycles(id, workspace_id), action consistent with #1/#2; system events carry the cycle they narrate (feasible via the UNIQUE (id, workspace_id) from #5); [AUDIT #22] the cycle-narrating kinds (denied/override/quorum_met/etc.) can never be orphaned from their cycle
+);
+-- [AUDIT #11] Same single contract as versions and votes: update-immutable, cascade-deletable
+--   only via `drafts` — UPDATE rejected; DELETE rejected unless its root is the drafts
+--   cascade (pg_trigger_depth() check); kind='message' requires non-empty body.
+-- [AUDIT #18] Size caps are table CHECKs, not conventions: body ≤ 8192 bytes (non-empty when
+--   kind='message') and data ≤ 8192 bytes — oversize writes are refused by the database.
+-- [SECURITY #7] review_events policy (RLS IN ADDITION to tenant_isolation; also a
+--   mandatory service-layer precondition, see 4.2):
+--   SELECT ... USING: caller holds draft.view AND (drafts.group_id IS NULL OR EXISTS (
+--     SELECT 1 FROM group_members gm WHERE gm.group_id = drafts.group_id
+--       AND gm.user_id = current_setting('app.user_id')::uuid AND gm.status = 'active'))
+--   INSERT of kind='message' WITH CHECK: that same predicate AND an active
+--     group_members row with review_role IN ('member','editor','reviewer') for
+--     drafts.group_id; system kinds are inserted only via the SECURITY DEFINER
+--     service path. Fails closed: no membership => zero rows on read, refused write.
+
+-- (9) drafts columns
+ALTER TABLE drafts
+  ADD COLUMN group_id uuid,
+  ADD COLUMN revision int NOT NULL DEFAULT 0,    -- optimistic concurrency, bumped on save
+  ADD COLUMN current_version_id uuid,
+  ADD COLUMN approved_version_id uuid,
+  ADD COLUMN event_seq bigint NOT NULL DEFAULT 0,
+  ADD COLUMN hidden_at timestamptz, ADD COLUMN hidden_by uuid REFERENCES users(id),
+  ADD COLUMN hidden_reason text,
+  ADD COLUMN deleted_at timestamptz, ADD COLUMN deleted_by uuid REFERENCES users(id),
+  ADD COLUMN deleted_reason text,
+  ADD CONSTRAINT drafts_group_fk FOREIGN KEY (group_id, workspace_id)
+    REFERENCES groups(id, workspace_id) ON DELETE SET NULL (group_id),
+  ADD CONSTRAINT drafts_curver_fk FOREIGN KEY (current_version_id, id, workspace_id)
+    REFERENCES post_versions(id, draft_id, workspace_id),
+  ADD CONSTRAINT drafts_appver_fk FOREIGN KEY (approved_version_id, id, workspace_id)
+    REFERENCES post_versions(id, draft_id, workspace_id),
+  ADD CONSTRAINT drafts_appver_state CHECK (                          -- [AUDIT #21] a live approval pointer exists only in approval-or-later states
+    approved_version_id IS NULL OR state IN ('approved','scheduled','published')),
+  ADD CONSTRAINT drafts_hidden_consistent CHECK (
+    (hidden_at IS NULL AND hidden_by IS NULL AND hidden_reason IS NULL)
+    OR (hidden_at IS NOT NULL AND hidden_by IS NOT NULL AND btrim(coalesce(hidden_reason,'')) <> '')),
+  ADD CONSTRAINT drafts_deleted_consistent CHECK (
+    (deleted_at IS NULL AND deleted_by IS NULL AND deleted_reason IS NULL)
+    OR (deleted_at IS NOT NULL AND deleted_by IS NOT NULL AND btrim(coalesce(deleted_reason,'')) <> ''));
+
+-- state set: drop 006 CHECK, install
+CHECK (state IN ('editing','primed','in_review','needs_changes','blocked',
+                 'approved','scheduled','published','expired'))
+```
+
+Every new table: denormalized `workspace_id` + composite FKs, `reject_workspace_change` trigger, `ENABLE`+`FORCE ROW LEVEL SECURITY` with the exact `tenant_isolation` NULLIF policy, `GRANT … TO sp_app` — shapes copied verbatim from `006`/`008` [ALL].
+
+### 4.2 Key SQL functions (SECURITY DEFINER, search_path pinned, sp_app-only [OP conventions])
+
+- **`review_events` access contract (binding)**: enforced as an RLS policy *in addition to* `tenant_isolation` and re-checked as a **mandatory service-layer precondition** on every read/write of the table. **Read** requires `draft.view` **AND** (`drafts.group_id IS NULL` **OR** an active `group_members` row for `drafts.group_id`). **Writes of `kind='message'`** additionally require `review_role IN ('member','editor','reviewer')` in that group. Fails closed: missing membership/permission yields no rows (read) or an exception (write). The `GET /publishing/drafts/:id/events` endpoint inherits exactly this predicate - never a generic `RbacGuard + RLS` passthrough. **[AUDIT #18]** The same endpoint serves reads only through the bounded-page contract of §7 (`limit` default 100 / max 500 with `next_cursor`) — there is no unbounded read of the event log.
+
+- **Moderation visibility contract (binding) [AUDIT #15]**: every draft read endpoint — list, detail, versions, diffs, events — applies `drafts.hidden_at IS NULL AND drafts.deleted_at IS NULL` unless the caller holds `moderation.hide` (hidden rows) / `moderation.delete` (deleted rows). Enforced as an RLS policy on `drafts` (and, via the parent draft, on `post_versions`/`review_events`) plus a shared repository filter used by every query path — never only a UI/archive filter. Fails closed: a non-admin direct request for a hidden/deleted draft, its versions, diffs or events yields 404/no rows.
+
+- `review_eligible_reviewers(draft uuid, workspace uuid)` → set of user ids: **[USER v2] if the draft's connection is `delegated`, its `connection_approvers`; else** group role `reviewer` — always ∩ active membership ∩ NOT author ∩ NOT contributor ∩ NOT sealer of current version. **One function used by the service, the vote trigger, and the quorum count** [OP: single source of truth]. **[SECURITY #8]** The body starts with fail-closed tenant validation: ASSERT the target draft's `workspace_id` equals the `workspace` argument (and, when invoked for a session, that `current_setting('app.workspace_id')` IS NOT NULL and equals it); mismatch raises immediately - no rows, no cross-tenant leak.
+- `review_valid_approval_count(cycle uuid, workspace uuid)` → count of live (not revoked) `approve` votes from eligible reviewers whose `snapshot_sha256` matches the cycle's version hash [SOL]. **[SECURITY #8]** Same contract: the body first asserts the cycle's `workspace_id` equals the `workspace` argument (and matches `current_setting('app.workspace_id')` when session-scoped). The single-UUID signatures are removed; every caller passes both arguments.
+- `review_vote_eligible()` trigger: refuses votes unless cycle `in_review`, voter eligible (re-checked live), snapshot hash matches [SOL+OP]. **[AUDIT #14]** The cycle-state and live-eligibility checks apply only when `NEW.source = 'live'` (refusal condition is `... AND NEW.source = 'live'`), so `source='migrated'` backfill rows (§11) — inserted into already-`approved` cycles, possibly by a legacy reviewer who is now author/contributor or lacks the reviewer role — bypass them; the snapshot-hash match and all CHECK constraints are still enforced for every row. Only the `011` migration role may insert `source='migrated'` (sp_app inserts with `source <> 'live'` are refused).
+- `enforce_review_transition()` trigger on drafts: the legal-pairs table in §5; refuses `post`/`group_id` changes outside `editing`/`needs_changes`; refuses `approved` without a closed quorum or an override row **[AUDIT #19]** whose `snapshot_sha256` equals the cycle version's `content_hash` — this override-row requirement is the second layer on top of the 4.1(7) override insert trigger; refuses `scheduled` unless `drafts.post` hash equals the approved version's [SOL] — **[AUDIT #24]** §6.6 full-reset is the primary defence (an edit after approval supersedes the cycle before scheduling can even be attempted); this hash check is the backstop for any gap in it, and its refusal surfaces as 409 `STALE_VERSION` directing the user to re-submit — no approved-but-unschedulable state without a recovery transition. **[AUDIT #12]** `→ expired` is legal only from the pre-publication set `primed|in_review|blocked|approved` — the trigger refuses `scheduled → expired` and `published → expired`. **[SECURITY #9]** It also refuses `scheduled` unless the approved version's `connection_id` satisfies the 4.1(3) seal-time guard (same workspace, in scope for `drafts.group_id`) - re-validated at the transition, not only at seal time.
+- `assign_event_seq()` trigger: `event_seq := event_seq + 1` under the draft row lock; gapless per draft [OP]. **[AUDIT #26] Global lock order** (binding for every path that touches review state): authz rows (`group_members` / `connection_approvers`) → draft row → cycle row → votes/events. The vote path takes the draft row `FOR UPDATE` (seq + quorum + deadline check) *before* the cycle row `FOR UPDATE` and only then inserts the vote/event; the membership-change path takes authz rows → draft → cycle → votes/events in the same order. No path may lock a cycle row before its draft row.
+- `review_due_expiries()` sweeper discovery, mirroring `publishing_due_schedules()` (`006:79-85`) [OP]. **[SECURITY #8]** It takes no row argument, so it runs strictly under the caller's tenant context: every candidate cycle must satisfy `workspace_id = current_setting('app.workspace_id')::uuid`; a NULL/empty setting selects zero rows (fail-closed), never all tenants.
+- Vote revocation on membership/role change: trigger on `group_members` UPDATE/DELETE revokes that user's live votes on open cycles in the group (sets `revoked_at/reason`), then recount — quorum already met stays met [OP, fixed lock order: authz rows → draft → cycle → votes/events — the [AUDIT #26] global order above, identical to the vote path].
+
+---
+
+## 5. State machine (deliverable 3)
+
+| from → to | fired by | guard |
+|---|---|---|
+| editing → primed | author/editor stages (choose group + connection + optional publish_at) | group has ≥ N eligible reviewers (**preflight, 400 if not**) — solo exception [AUDIT #17]: N=1 with 0 eligible reviewers still primes (workspace `approval.grant` holders are the fallback pool, and if that is empty too, submit lands `blocked-at-submit`) [GLM] |
+| needs_changes → primed | author re-stages after edits | same preflight |
+| expired → primed | author re-primes with new schedule | same preflight |
+| primed → in_review | submit (seals version n, opens cycle) | version sealed; policy snapshotted; deadline = LEAST(publish_at, now+stale_after); same tx inserts `draft_contributors` rows for the sealer + any editor since the last seal [AUDIT #10, seal trigger enforces] | **[AUDIT #17]** if N=1 and eligibility is 0, the cycle is created directly in `blocked` (`blocked-at-submit`) instead of `in_review` — a cycle always exists for the admin override |
+| in_review → approved | quorum_met (Nth valid approve, same tx) | row lock + `clock_timestamp() < deadline_at` else → expired [ALL] |
+| in_review → needs_changes | deny (veto) | reason optional, UI prompts for it [USER v2] |
+| in_review → editing | author withdraws for edits | cycle superseded |
+| in_review → blocked | recount after reviewer removal | eligibility < required [GLM] |
+| approved → scheduled | quorum tx (auto, if publish_at future) | same tx inserts `scheduled_publications`, starts workflow with startDelay [ALL] |
+| approved → editing | late edit | pending schedule cancelled in same tx; cycle superseded; loud dismissal event; **[AUDIT #21]** `approved_version_id = NULL` is set in the same tx as the supersede — between supersede and the next approval no reader (D1's claim check included) can dereference a stale approval |
+| scheduled → approved | cancelSchedule (existing) | unchanged from 006 |
+| scheduled → published | scheduler activity | **D1 fix: claim requires state='scheduled' AND a pending `scheduled_publications` row, and publishes `post_versions.post` of `approved_version_id`** |
+| published → (none) | archive = filtered read of published | no state change [GLM] |
+| primed, in_review, blocked, approved → expired | sweeper/vote-time check when deadline passes | pre-publication (deadline-bearing) states only — the explicit set `primed|in_review|blocked|approved → expired`; `scheduled → expired` and `published → expired` are refused by the trigger [AUDIT #12]; no remote publish; notification hook |
+| blocked → in_review | reviewer added (auto-recount) | eligibility ≥ required again [GLM] |
+| blocked/expired → approved | admin override | reason mandatory; not a contributor; cycle closed `overridden` [SOL+OP] |
+
+Service returns 400/403/409 with precise codes (`REVIEW_EXPIRED`, `QUORUM_UNREACHABLE`, `STALE_VERSION`, `VOTE_INELIGIBLE`); the DB trigger is the backstop, not the error surface [SOL].
+
+---
+
+## 6. Quorum engine semantics (deliverable 5)
+
+1. **Config**: `groups.review_approvals_required ?? workspace_review_settings.approvals_required ?? 1`, resolved once at submit, stored on the cycle with `policy_source`. Default `1` preserves today's behavior for solo workspaces **as a `blocked-at-submit` cycle, never a self-approval [AUDIT #17]**: with N=1 and 0 eligible reviewers the cycle is created in `blocked` and is resolved by a fallback reviewer (below) or the admin override. `≥2` turns on structural four-eyes [GLM]. Admin-only setters (`review.manage`). **[AUDIT #23]** `required` is bounded to 1–5 at every layer (workspace §4.1(2), group §4.1(2), cycle snapshot §4.1(5)): `required=0` has no closing rule — no transition fires `quorum_met` without a vote and submit-time auto-approve is deliberately not defined — so it is refused by CHECK at the door, exactly the deadlock-by-config class §6.8 exists to refuse.
+2. **Parallel any-N-of-eligible** [ALL]. No tiers (noted as future). **Eligibility pool [USER v2]**: if the draft's target connection is `delegated`, the pool is its `connection_approvers` (minus author/contributors); otherwise the group's `reviewer`s. **Solo fallback [AUDIT #17]**: when that pool is empty, workspace `approval.grant` holders (Owner/Admin/Approver, minus author/contributors) become eligible; if they are empty too, submit lands `blocked-at-submit` with the admin override as the only exit. Resolved at submit and snapshotted on the cycle (`approval_source`); mode changes affect future cycles only.
+3. **Vote rules**: one live vote per reviewer per cycle (`UNIQUE`); decision immutable after cast — a reviewer may not flip; they may deny later if they first approved? **No: one vote total, immutable.** To change course, the deny path is a *new* cycle after withdrawal — keep it strict [MERGE, strictest of the three].
+4. **Deny = veto** [ALL]: cycle closes `denied`, draft `needs_changes` [USER v2: deny reason **optional but suggested** — the UI asks "why?" and records it in chat + audit when given; this supersedes the spec's mandatory-reason rule]. Sibling approvals remain as history; count for nothing (cycle-scoped tally).
+5. **Staleness**: every vote copies the cycle's version hash; the vote trigger rejects a hash mismatch (409 `STALE_VERSION` — can't happen given full-reset, backstop only) [SOL].
+6. **Edit = full reset** [ALL]: any content/target change after seal supersedes the cycle, cancels any pending schedule in the same tx, seals version n+1 on resubmit, and emits a `edited` event listing dismissed approvers with a diff link (loud dismissal [OP]). **[AUDIT #10] Same-tx contributor contract (binding)**: every seal (`submit`/`edit`/`reopen`) inserts `draft_contributors` rows for the sealer and for any editor recorded since the last seal, in the seal transaction itself; the `post_versions` seal trigger fails the transaction if the sealer is absent — eligibility can never miss a contributor, and existing rows are immutable (§4.1(4)).
+7. **Scheduled-time race** [ALL]: quorum handler, holding the draft row lock, checks `clock_timestamp() < publish_at`; if true → schedule in same tx; else → `expired`. Submissions require `publish_at ≥ now() + 120 s` (min lead). Correctness never depends on sweeper latency.
+8. **Deadlock** [GLM]: preflight at priming (§5) + `blocked` state on mid-review shrinkage + override exit (§5). `blocked ≠ needs_changes`: "edit the post" is wrong advice when the problem is staffing.
+
+---
+
+## 7. Review chat & delivery (deliverable 6)
+
+- **One table, both kinds** [SOL]: `review_events` — `message` rows are human chat; everything else is system events rendered inline (submitted, votes **fully attributed** — transparent ledger, reasons shown when given [USER v2] — state changes, overrides, moderation).
+- **Transport = polling** [GLM]: `GET /publishing/drafts/:id/events?after=<seq>&limit=<n>` while a detail view is open (4 s); queue lists refresh on action or 15 s. Every poll rides the existing epoch-fenced `RbacGuard` + RLS, i.e. the 4.2 `review_events` policy (read = `draft.view` AND (ungrouped draft OR active `group_members` row for `drafts.group_id`); posting a `message` additionally requires `review_role IN ('member','editor','reviewer')` in that group) — revocation latency = poll interval, no new credential surface (EventSource can't send our Bearer header).
+- **Bounded pages [AUDIT #18]**: `limit` defaults to 100 and is clamped to 1–500; each response returns at most `limit` events plus `next_cursor` = the `seq` of the last row returned (omitted when the page is not full). Clients loop `?after=<next_cursor>` until no cursor is present, so a 4 s poll — or a backlog catch-up — always returns a bounded page (≤ 500 events), never an unbounded response.
+- **Ordering is structural**: gapless `seq` allocated under the draft row lock; the cursor is a total order; lost/duplicated polls are harmless (`?after=`).
+- **Upgrade path**: SSE doorbells + `LISTEN/NOTIFY` [OP] later; identical `after=<seq>` query, no schema change.
+- Approve/Deny buttons live in the chat surface (R5): approve = one click; deny = reason modal (required).
+
+---
+
+## 8. UI plan (deliverable 7)
+
+1. **Review queue** (replaces the `/approvals` stub): virtualized column list (reuse `components/streams/column.tsx` pattern, `@tanstack/react-virtual`, j/k navigation) of drafts in `primed/in_review/needs_changes/blocked/expired`; state chips (`STATE_TONE` extended); quorum progress ("2/3 ✓"); filters: needs-my-review, mine, needs-changes, expiring soon, blocked.
+2. **Post detail** (builds on Compose patterns): rendered post preview + version diff (v n-1 → n), side chat/event stream with vote buttons, quorum tracker, schedule info, contributor list.
+3. **Compose additions**: "Prime for review" action (group + connection + optional schedule), replacing the current self-approve chain when quorum ≥ 2.
+4. **Archive**: filtered read of `published` (chat history preserved, read-only), admin sees hidden posts with a badge + unhide/delete actions.
+5. **Team/group screens**: `review_role` selector on group members; **group settings** (quorum, admin control) [USER v2].
+6. **Connections screen additions [USER v2]**: per-account approval settings — mode picker (`system` vs `delegated to named approvers`), approver pool editor for delegated accounts, shown on the connection detail; the queue groups/filters by account so a delegated approver sees "awaiting my signoff" across the accounts they own.
+
+---
+
+## 9. Edge cases (deliverable 8) — each with its resolution
+
+1. **Reviewer leaves mid-review** → votes revoked by trigger (reason), recount; met quorums stay met; unmet → `blocked` [OP lock order: authz rows → draft → cycle → votes/events — global order [AUDIT #26], shared with the vote path so a concurrent vote cannot invert draft/cycle locks].
+2. **Deadline race (vote vs expiry)** → both take `FOR UPDATE` on the draft; vote-time expiry check; loser sees `REVIEW_EXPIRED` [ALL].
+3. **Sole reviewer is the author** → with quorum ≥ 2: preflight 400 at priming. With quorum 1: prime/submit succeeds — the pool falls back to workspace `approval.grant` holders [AUDIT #17], and if that pool is empty too the cycle is created `blocked-at-submit` awaiting admin override; never enters an unresolvable state [GLM].
+4. **Admin who contributed tries to override** → refused structurally (contributors table) [OP].
+5. **Quorum met after publish_at** → `expired`, nothing scheduled, author notified, re-prime path [ALL].
+6. **Concurrent Nth and (N+1)th vote** → both under row lock; second lands as history after cycle closed (no double schedule: `UNIQUE(draft_id)` on scheduled_publications backstop).
+7. **Epoch bump mid-vote** (role change logs reviewer out) → `POST /auth/reissue` + client single retry (D7 fix) [OP].
+8. **Group deleted while cycles open** → `ON DELETE SET NULL (group_id)` frees the draft **and sets `review_cycles.group_id` to NULL the same way [AUDIT #16]** — each cycle keeps its `group_name` snapshot so the audit trail stays readable, and superseding a cycle preserves the reference as history rather than deleting it; open cycles superseded by group-delete guard trigger; audit event [OP].
+9. **Workspace owner cleanup deletes drafts** → cascades flow (versions, cycles, votes, events) under the single §4.1 contract — **[AUDIT #1]** `review_votes` and `review_overrides` reference `review_cycles` with `ON DELETE CASCADE`, so drafts → cycles → votes/overrides is never blocked by a NO ACTION FK: events/versions/votes are update-immutable and cascade-deletable **only via `drafts`**; direct DELETEs are refused by the trigger [GLM, AUDIT #11].
+10. **Hidden post with open cycle** → hide is metadata only; cycle continues (admins act with full information) [MERGE].
+11. **Connection approval mode switched mid-review** [USER v2] → the cycle snapshotted `approval_source` at submit; open cycles keep their pool, new cycles use the new mode. Mode change emits a thread event for visibility.
+12. **Delegated pool shrinks below N** (approver removed/leaves) → same `blocked` handling as group reviewers: recount trigger revokes their live votes, `blocked` if quorum unreachable, admin override or pool restore resolves.
+13. **Preflight for delegated accounts** counts the connection pool, not group reviewers: "Account X needs 2 approvals; pool has 1" at priming.
+
+---
+
+## 10. Audit events (deliverable 9) — all through `audit_append`, same-tx (D4 fixed)
+
+`review.primed`, `review.submitted` (version hash, policy snapshot, approval_source), `review.vote_cast` (decision; reason when provided; snapshot hash), `review.vote_revoked`, `review.quorum_met`, `review.denied`, `review.cycle_superseded`, `review.blocked`, `review.unblocked`, `review.overridden` (admin, reason), `review.expired`, `review.hidden`/`unhidden`/`deleted` (moderation, reason), `review.policy_changed`, `review.connection_delegation_changed` (mode/pool changes [USER v2]).
+Scheduler keeps `publication.published`/`failed` as `sp_scheduler`. Hash v2 (010) makes every diff value — snapshot hashes, reasons, policy before/after — tamper-evident [OP].
+
+---
+
+## 11. Migration & backfill (deliverable: Q9) — `011`, per-tenant `set_config` before guard triggers
+
+| legacy state | new state | cycle | votes |
+|---|---|---|---|
+| editing | editing | none | none |
+| in_review | needs_changes | none (author re-primes) | none |
+| rejected | needs_changes | none | none |
+| approved/scheduled/published | unchanged | backfilled cycle `required=1, status=approved`, v1 from current post | one synthetic `approve` vote (source='migrated') by legacy `reviewer_user_id` where present — exempt from the live cycle-state/eligibility checks of `review_vote_eligible()` via its `NEW.source = 'live'` guard (§4.2), hash still verified [AUDIT #14] |
+| (none) | — | — | legacy deny reasons recovered from `audit_log.diff->>'reason'` on `draft.rejected`, else migration note |
+
+`reviewer_user_id` becomes read-only/deprecated; dropped in a later `012` once web stops reading it. Legacy self-approved drafts are kept as history and counted in a `review.migrated` audit row [OP].
+
+---
+
+## 12. Phased implementation (deliverable 10)
+
+- **WP5.0 — Foundation fixes (010)**: D1–D8. Gate: existing suites green + new regression tests for claim-state-check and audit hash v2.
+- **WP5.1 — Schema (011)**: tables, triggers, functions, RLS, backfill. Gate: migration up/down on dev DB; `audit_verify_chain()` true post-backfill.
+- **WP5.2 — Service + API**: priming/submit/vote/override/moderation endpoints, quorum engine, event log writes; every draft read endpoint (list, detail, versions, diffs, events) applies the §4.2 moderation visibility contract. Gate: integration tests (RLS, transitions, quorum, races) on live Postgres, including admin vs non-admin reads of hidden/deleted drafts across all five read endpoints.
+- **WP5.3 — Scheduler contract**: claim eligibility + approved-version publishing + expiry sweeper. Gate:Temporal tests incl. deadline race.
+- **WP5.4 — Web**: queue, detail+chat, compose changes, archive, role/quorum admin. Gate: E2E on real API; visual QA.
+- **WP5.5 — Hardening**: lock-order verification, load test on event seq allocation, docs.
+
+## 13. Test plan sketch (deliverable 11) — the 10 that catch the worst
+
+1. Claim refuses any draft not in `state='scheduled'` with a pending `scheduled_publications` row, and publishes `post_versions.post` of `approved_version_id` (D1). 2. Audit verify passes with v1+v2 rows. 3. Author/contributor vote → 403. 4. Deny without reason succeeds; deny with reason records it in thread + audit [USER v2]. 5. Nth vote under lock schedules exactly once. 6. Vote at deadline → expired, not scheduled. 7. Edit after approval cancels schedule + supersedes cycle same-tx. 8. Reviewer removal revokes votes; met quorum survives. 9. Preflight blocks solo-author quorum-2 priming. 10. Migration backfill: verify chain + counts + resubmit path from legacy rejected. 11. Delegated account: group reviewer's vote → 403; pool member's vote counts [USER v2]. 12. Mode switch mid-review: open cycle keeps its pool [USER v2]. 13. Delegated pool shrink → blocked + override path [USER v2]. 14. **Transition-table test [AUDIT #12]**: `enforce_review_transition()` refuses `scheduled → expired` and `published → expired`; `→ expired` succeeds from each of `primed`, `in_review`, `blocked`, `approved`. 15. **Seal/contributor test [AUDIT #10]**: a seal transaction that does not insert a `draft_contributors` row for the sealer fails; UPDATE/DELETE of an existing contributor row fails outside the drafts cascade. 16. **Edit-after-approval-then-schedule [AUDIT #24]**: both paths — (a) primary: an edit after approval supersedes the cycle and cancels the pending schedule in the same tx (draft back to `editing`, `approved_version_id = NULL`); (b) backstop: `approved → scheduled` while the `drafts.post` hash no longer equals the approved version's is refused with 409 `STALE_VERSION` and the UI directs the author to re-submit. 17. **Draft-delete cascade [AUDIT #1]**: under the real `011` migration, deleting a draft that has cast votes (live and revoked) and an `overridden` cycle with a `review_overrides` row succeeds and removes its cycles, votes, overrides, events and versions; a direct DELETE of a vote/override row is still refused.
+
+## 14. Confidence & risks
+
+- **Highest confidence**: schema shape, single-veto deny, full-reset staleness, cycle-snapshotted quorum (all three proposals converged independently).
+- **Least sure**: (a) gapless `seq` allocation under extreme concurrency — measure contention in WP5.5; (b) blind-vote redaction completeness (audit page leak accepted, documented); (c) D7 reissue flow client behavior across all screens.
+- **Prototype first**: WP5.0 + WP5.1 on a copy of dev data, run tests 1, 5, 6, 8 — everything whose failure would be silent.
diff --git a/docs/design/proposal-glm.md b/docs/design/proposal-glm.md
new file mode 100644
index 0000000..58db27f
--- /dev/null
+++ b/docs/design/proposal-glm.md
@@ -0,0 +1,987 @@
+# Proposal — Group Review & Signoff for Posts ("Editorial Workflow")
+
+Lane: `glm` · Date: 2026-10-07 · Spec: `runs/wp5/spec-review-workflow.md`
+Status: design only — nothing here is implemented.
+
+---
+
+## 0. Files this proposal is grounded in
+
+Everything below cites these repo files (paths relative to repo root):
+
+| File | What it establishes |
+| --- | --- |
+| `apps/api/migrations/006_publishing.sql` | current 6-state CHECK (`:7-8`), single `reviewer_user_id` (`:9`), `UNIQUE(draft_id)` on schedules (`:24`), FORCE RLS + `tenant_isolation` policies (`:52-66`), `sp_app` grants (`:68`), SECURITY DEFINER sweeper fns (`:72-89`) |
+| `apps/api/src/publishing/publishing.service.ts` | `DraftState` union (`:8`), submit/approve/reject (`:179-205`), schedule (`:212-247`), CAS `transition()` helper `WHERE id=$1 AND state=$4` (`:275-292`), the "FK checks bypass RLS" tenancy note (`:217-219`) |
+| `apps/scheduler/src/activities/publish.activity.ts` | scheduler owns `scheduled→published` (`:182`), claims via `publishing_schedule_workspace()` (`:160-176`), writes audit as `sp_scheduler` (`:184-199`), tenant-tx pattern `inTenant()` (`:228-245`) |
+| `apps/api/migrations/008_groups.sql` | `group_members` has **no role column** (`:27-39`), `UNIQUE(group_id,user_id)` (`:34`), composite tenant-pinning FKs (`:38-39`), epoch bump on any membership mutation (`:79-80`), `groups UNIQUE(id, workspace_id)` (`:21`) |
+| `apps/api/src/groups/groups.service.ts` | same-tx audit helper (`:100-110`), `{token}` replacement-session pattern on epoch-bumping mutations (`:168-200`), guard-side `userCanUseConnection` reading live role from DB (`:425-455`) |
+| `apps/api/migrations/002_rbac_seed.sql` | 10 roles; `approval.grant` on Owner/Admin/Approver (`:8, :24, :49`), `approval.request` on Owner/Admin/Publisher, workspace `Editor` role has `draft.edit` and **no** approval power (`:39-43`) |
+| `apps/api/src/rbac/rbac.guard.ts` | epoch fail-closed check (`:45-47`), permission lookup inside `withTenant` (`:57-62`), `RequireGroupAccess` precedent for guard-side group checks (`:64-74`) |
+| `apps/api/src/audit/audit.service.ts` + `apps/api/migrations/001_tenants.sql` | `scrub()` (`:11`), `AuditEvent` (`:20-27`), `audit_append` SECURITY DEFINER + `fn_assert_tenant` (`001:85-111`), `audit_hash` (`001:74-83`), `reject_workspace_change` (`001:141-150`), `bump_authz_epoch` (`001:160-168`), fail-closed NULLIF RLS (`001:172-190`) |
+| `apps/api/src/auth/auth.service.ts` / `session.ts` | `issueSessionInTenant` (`:72-84`), `epochValid` (`:50-52`) |
+| `apps/api/src/db/client.ts` | `withTenant` sets `app.workspace_id` per tx (`:18-44`) |
+| `apps/web/src/app/(main)/compose/page.tsx` | `STATE_TONE` badge map (`:35-42`), the create→submit→approve→schedule chain incl. self-approve (`:119-142`), preview cards (`:244-262`), "Recent drafts" list (`:255-263`) |
+| `apps/web/src/components/streams/column.tsx` + `streams/page.tsx` | virtualizer config (`column.tsx:26-34`), j/k keyboard model with input-guard (`streams/page.tsx:56-70`) |
+| `apps/web/src/app/(main)/inbox/page.tsx` | two-pane chat visual pattern (`:52-120`) |
+| `apps/web/src/app/(main)/approvals/page.tsx` | 10-line stub this feature replaces |
+| `apps/api/src/realtime/gateway.ts` | authz **port only** — no transport, no topics, no client (`:1-45`) |
+| `apps/api/migrations/009_video.sql` | takes number `009`; this proposal's migration is **`010_review_workflow.sql`** |
+| `apps/api/src/db/migrate.ts` | each migration file runs in one tx, exactly once (`:33-41`) |
+
+---
+
+## 1. Executive summary — the five sharpest decisions
+
+1. **Group roles are a column on `group_members`** (`role ∈ member|editor|reviewer`), not a new table and not workspace roles. The existing epoch trigger (`008_groups.sql:79-80`) already fires on UPDATE, so role changes invalidate sessions for free and the `{token}` re-issue pattern (`groups.service.ts:168-200`) extends verbatim. One role per user per group is a *feature*: letting one person be both editor and reviewer in the same group would re-open the maker-checker hole we are structurally closing.
+
+2. **Approvals attach to immutable version rows, never to the draft.** `post_versions` is append-only (UPDATE blocked by trigger), carries a `content_hash` generated column (`encode(digest(post::text,'sha256'),'hex')`, same crypto as `audit_hash` in `001:74-83`), and a review cycle pins one version. Any edit — before, during, or after review — closes the cycle as `superseded` and requires a fresh quorum. There is no state in which content is mutable while approvals are live.
+
+3. **Quorum is snapshotted per review cycle**, resolved as `groups.review_approvals_required ?? workspace_review_settings.approvals_required ?? 1` at submit time. Mid-review config changes never retroactively move the goalposts; only future cycles pick them up. Default `1` preserves today's behavior exactly (including the solo-workspace self-approve flow at `compose/page.tsx:128-131`); `≥2` turns on structural four-eyes, at which point author votes are refused server-side with a dedicated 403.
+
+4. **Chat is polling with a per-thread monotonic cursor**, not WS/SSE. `realtime/gateway.ts` is an unwired port; EventSource cannot send the Bearer token `api-client.ts` stores in localStorage; and every poll rides the existing epoch-fenced `RbacGuard` (`rbac.guard.ts:45-47`) for free, so an admin removing a reviewer mid-thread fails the *next poll* closed. The data model (`review_messages` with `UNIQUE(draft_id, ord)`) is transport-agnostic so WS can later reuse the identical "events since ord" query.
+
+5. **`published` is the archive; hide and delete are flags, not states.** The scheduler's `scheduled→published` write (`publish.activity.ts:182`) needs zero changes, the archive screen is a filtered read of `state='published'`, and moderation (`hidden_at`, `deleted_at`) is admin-only (`moderation.hide`, `moderation.delete` granted to Owner/Admin only), soft, and hash-chain-audited — the chat record survives deletion because review history is a compliance artifact.
+
+The five new machine states are `needs_changes` (replaces terminal `rejected`, unlocks resubmit), `expired`, `blocked`, plus reuse of `editing/in_review/approved/scheduled/published`; the state machine is enforced **twice** — CAS UPDATEs in `publishing.service.ts` style and a new DB legal-transition trigger (defense in depth, per spec §3).
+
+---
+
+## 2. Answers to the ten open questions (spec §5)
+
+**Q1 — Group-scoped role storage: column on `group_members` vs `group_member_roles` table vs reusing workspace roles?**
+**Decision: `group_members.role text NOT NULL DEFAULT 'member' CHECK (role IN ('member','editor','reviewer'))`.**
+Reusing workspace roles is disqualified by construction: `memberships` has `UNIQUE(workspace_id,user_id)` (`001_tenants.sql:30`), i.e. exactly one role per user per workspace, and the seed's `Editor`/`Approver` are workspace-wide — a group-scoped Approver would approve everything. A separate `group_member_roles` table buys multi-role-per-group, which we explicitly do not want (editor+reviewer in one group = the same person edits and approves; that is the conflict four-eyes exists to prevent) at the cost of a second cascade path, a second epoch trigger, and a join in every eligibility check. The column reuses the table `groups.service.ts` already owns, and — decisively — `trg_group_member_bump_epoch` (`008_groups.sql:79-80`) fires on `UPDATE`, so a role change already invalidates every live session; the service just has to return the caller's replacement token exactly like `addMember`/`removeMember` do today (`groups.service.ts:168-200`). *Future work:* if per-group role delegation ("reviewer for text, not for media") ever lands, promote to a table then; the CHECK constraint is the only thing to widen.
+
+**Q2 — Snapshot model: full content copies per version vs content-hash + immutable version rows?**
+**Decision: immutable version rows that contain the full post AND a stored generated hash — `post_versions(post jsonb, content_hash text GENERATED ALWAYS AS (encode(digest(post::text,'sha256'),'hex')) STORED)`.**
+These are usually presented as opposites; they shouldn't be. A hash alone can't be rendered or diffed, so the reviewer's "approve exactly what you see" surface (R4) would need to reconstruct content from somewhere — the moving target we're eliminating. Full copies make the version row the single source for preview, diff, and publication, and posts are tiny (`drafts.post jsonb`, `006_publishing.sql:6`), so copy cost is irrelevant. Making the hash a *generated* column (pgcrypto is already loaded, `001:3`, and `digest` is what `audit_hash` uses, `001:74-83`) means the hash can never disagree with the content — no TS-side canonicalization bugs, no `as any` json wrangling. Rows are append-only via a `BEFORE UPDATE` rejection trigger; `UNIQUE(draft_id, version)` gives stable version numbers for the UI ("v3 of 4"). *Future work:* content-addressed dedup (`UNIQUE(workspace_id, content_hash)`) if cross-post reuse ever matters.
+
+**Q3 — Where does quorum config live and what's the precedence?**
+**Decision: workspace default in a new 1:1 `workspace_review_settings` table (`approvals_required int NOT NULL DEFAULT 1 CHECK (… BETWEEN 1 AND 5)`), overridable per group by a nullable `groups.review_approvals_required`; precedence at **submit** time is `groups.review_approvals_required ?? workspace_review_settings.approvals_required ?? 1`, and the resolved value is **snapshotted onto the review cycle** (`review_cycles.required_approvals`).**
+The snapshot is the load-bearing part: a quorum rule that can change under an open review either silently promotes a post past a threshold the admin just raised, or strands it — both feel like tampering to reviewers. Snapshotting makes each cycle a closed contract ("2 approvals of version 3") and makes config changes purely forward-looking. Both setters are admin-only via `review.manage` (granted to Owner/Admin — matching `workspace.members.manage` holders in `002:7, :23`, satisfying R3's "who sets it"). A separate settings table (rather than a column on `workspaces`) keeps the migration additive and lets RLS/policy/grants copy the standard shape; `groups` already has an `ALTER` in this migration anyway. *Future work:* per-connection quorum (spec mentions it) is deliberately out — drafts target one connection but reviews are editorial, not per-channel.
+
+**Q4 — Chat transport: WS vs SSE vs polling?**
+**Decision: HTTP polling of a cursor endpoint, `GET /publishing/drafts/:id/messages?after=<ord>`, 4s while a detail view is open; queue lists refresh on action or every 15s.**
+Cost/complexity first: WS requires building the entire missing transport — `realtime/gateway.ts` is an authorization port with no socket server, no topic registry, no client (`gateway.ts:1-45`) — plus heartbeat/reconnect, plus an epoch-aware re-auth dance (any group membership change anywhere in the workspace invalidates the token the socket authenticated with, `008:79-80`, so sockets need mid-flight re-authentication or mass disconnect-reconnect). SSE is cheaper but `EventSource` cannot set an `Authorization` header, and this app authenticates every request with a Bearer token from localStorage (`api-client.ts:57-59`) — we'd have to mint query-param or cookie tokens, a new credential surface. Polling reuses `RbacGuard` + tenant RLS + the epoch check verbatim on every request, so revocation latency equals poll interval, and review-thread volume (a handful of messages per post) makes the cost negligible. Ordering is guaranteed structurally, not by transport: `ord` is assigned per-thread under a row lock on the draft (`UNIQUE(draft_id, ord)` backstop), so the cursor is a total order regardless of transport. *Future work:* the WS gateway should reuse `authorizeSubscription` plus the identical `after=<ord>` query — the data model was chosen so transport can swap without schema change.
+
+**Q5 — Deny semantics: 1-deny-returns-to-author vs majority-deny vs configurable; what happens to other cast approvals?**
+**Decision: single deny (reason mandatory) is a veto — cycle closes `denied`, draft → `needs_changes`. Other cast approvals are preserved immutably as history but belong to the closed cycle, so they count toward nothing on resubmit.**
+A reviewer empowered to approve is empowered to block; anything weaker (majority-deny) lets a post publish over an explicit, reasoned objection — the exact failure four-eyes exists to prevent — and configurable deny modes multiply the state space for no safety gain. Preserving rather than deleting sibling approvals matters for the record ("two had approved, one objected, here's why") and costs nothing because quorum is always evaluated *within a cycle*: `review_votes.cycle_id` scopes every tally, so "revoking" approvals is unnecessary — the next cycle simply starts at zero. The deny reason is mandatory at the API boundary (`400` if blank — same `requireString` semantics as `http/validation.ts:23-28`) and lands in both the thread (system event, R5) and the audit chain (R8). *Future work:* a group-level `deny_threshold` config if some workspace ever wants consensus-style review.
+
+**Q6 — Re-review after edit: full reset vs dismiss-only-changed-scope?**
+**Decision: full reset. Any content mutation after submission closes the cycle (`superseded`) and requires a new version, a new cycle, and a fresh quorum.**
+Partial dismissal requires knowing *which part* of a post each approval covered; there is no field-level approval scope in this system (nor in Hootsuite/Sprout per the research digest — both lock the whole post). Full reset is the only rule that makes "approve a frozen snapshot" structurally true: there is never a moment where `drafts.post` is mutable and an approval is live, which means the reviewer's diff view can be trusted without checking timestamps. It's also the cheapest to reason about under concurrency (one immutable version per cycle; no merge of partial validity). The cost — re-getting N approvals after a typo fix — is real, so the UI shows the version diff in the re-approval request ("v3→v4: 1 line changed") to make re-approval a two-second decision. *Future work:* "minor edit" carve-outs (e.g. schedule-only changes don't reset — which this design already grants: `publish_at` lives on the cycle, not the content, so rescheduling without quorum is impossible by the same rule; only content resets).
+
+**Q7 — Scheduled-time race: quorum completes at T-1min — auto-publish or manual re-confirm?**
+**Decision: auto-publish. The quorum-met handler creates the `scheduled_publications` row and starts the workflow iff `publish_at > now()`; if quorum lands after `publish_at`, the draft goes to `expired` and nothing is ever scheduled.**
+The content approved is bit-identical to what publishes (frozen version), the approvals are valid, and the schedule was declared up front ("primed to go out", user req #1) — a re-confirm step at T-1min injects a human bottleneck precisely when humans are scarcest, and its failure mode is a missed post. The Temporal path already handles near-term starts (`startDelay = max(0, …)`, `publishing.service.ts:99-101`) and the durable-row sweeper (`publishing_due_schedules()`, `006:79-87`) already covers a missed workflow start, so no new machinery is needed for the happy path. The guard is the ordering rule: **schedules are only ever created for future times**, which makes "approved too late" equivalent to "not approved in time" — the single `expired` state covers both R1 cases (deadline passed, and stale-beyond-90-days). The race between a last-instant vote and the expiry sweeper is serialized on the draft row (both take `FOR UPDATE`; see §9). *Future work:* per-workspace "re-confirm window" config for teams that want the brake.
+
+**Q8 — Author is also the only reviewer in a tiny group — deadlock handling?**
+**Decision: refuse at the door, then a named exit. Submit runs a preflight — count of *currently eligible non-author reviewers* ≥ `required_approvals` — and returns `400 not enough eligible reviewers (0) for quorum (2)` instead of entering a state that can never resolve. If the pool shrinks mid-review (reviewer removed/demoted), the recount trigger moves the draft to `blocked`; Owner/Admin can resolve `blocked` via the override endpoint (mandatory reason, logged as override) or by adding reviewers, which auto-reopens the cycle.**
+A deadlock you can enter is a bug; a deadlock you're told about at submit time is a configuration error with a clear message. The preflight is cheap (one count over memberships/group_members) and converts the worst failure mode into the best UX. `blocked` is a distinct state — not `needs_changes` — because "needs changes" tells the author to edit, when the actual problem is staffing; conflating them sends authors rewriting posts that were fine. The override path (R2: "Admin/Owner retain override power, logged as override") is the emergency brake for both deadlock and genuine urgency, and it is *not* a vote: it writes no `review_votes` row, it closes the cycle with `closed_reason='admin_override'` and a dedicated audit action, so quorum metrics can't be inflated by admin rescues. *Future work:* vacation delegation (a reviewer temporarily acting for another) — the group-role mechanism extends naturally.
+
+**Q9 — Migration path for existing single-step approvals (`reviewer_user_id` backfill)?**
+**Decision: migrate in `010` — every existing draft gets a `post_versions` v1 row from its current `post`; drafts with `reviewer_user_id` get a backfilled cycle (`required_approvals=1`) plus one synthetic vote (`approve`, or `deny` whose reason is recovered from the audit chain via `audit_log.diff->>'reason'` on the matching `draft.rejected` event, falling back to a migration note); terminal `rejected` rows become `needs_changes`. The `reviewer_user_id` column is then dead: `010` stops writing it, keeps it readable for one release, and a later `012` drops it once `draftFromRow` (`publishing.service.ts:315-317`) and `api-types.ts:70` stop referencing it.**
+Dropping in the same migration that the running API still reads from would couple deploy order brittlely; the repo ships API and migration together (`migrate.ts` runs on boot) but the web bundle may lag by a session lifetime, so a deprecation window is the honest cost. Recovering deny reasons from `audit_log` is possible because rejects already write `{reason}` into the diff (`publishing.service.ts:197-205`) and the chain is queryable by `target_id` (`audit.query.ts:30-45`) — this keeps the mandatory-reason invariant true even for migrated rows (synthetic fallback text where history is missing). Historical intermediate versions are unrecoverable (`updateDraft` overwrote `post` in place, `:160-176`), so v1 = content at migration time; noted rather than hidden. *Future work:* none needed — `012` drop is the only follow-up.
+
+**Q10 — Should reviewers see who else approved before them, or vote blind?**
+**Decision: blind until the cycle closes. While a cycle is `open`, the API returns only `{approvals: n, required: m, mine: …}` and system events in the thread are identity-masked ("an approval was recorded · 2/3"); on close (`approved`/`denied`/`superseded`) the full vote ledger with identities is revealed. Holders of `review.override` (Owner/Admin) see identities live.**
+Independence is the point of parallel review — the research digest flags rubber-stamping and anchoring as the failure modes of visible-first voting, and quorum metrics (approvals per reviewer, cycle time) only stay meaningful if early votes don't herd late ones. Masking is enforced server-side at the read endpoint (the `review_messages` row keeps the actor — the audit record must — but the serializer redacts `event_data.actorUserId` while `status='open'`), never trusted to the client. Admins see live because moderation is their job (spotting the rubber-stamper *during* review, not after). On close everything is revealed: the permanent record is fully transparent, which is what distinguishes this from secret balloting. *Future work:* per-group `blind_votes=false` toggle if a team insists on open voting.
+
+---
+
+## 3. Data model (deliverable 2) — `010_review_workflow.sql`
+
+One file, one transaction (`migrate.ts:33-41`). Ordering inside the file matters and is annotated. Conventions copied everywhere: denormalized `workspace_id`, composite tenant-pinning FKs where a parent exists (`008:38-39` pattern), `reject_workspace_change` trigger, `ENABLE`+`FORCE ROW LEVEL SECURITY`, the exact `tenant_isolation` NULLIF policy (`001:176-179` / `006:58-66`), and `GRANT … TO sp_app` (`003`).
+
+```sql
+-- 010: group review & signoff — post versions, review cycles, quorum votes,
+-- per-post chat, moderation flags. Extends 006 (publishing) and 008 (groups).
+
+-- ---------------------------------------------------------------------------
+-- (1) Group roles. Column, not a table (Q1): trg_group_member_bump_epoch
+--     (008:79-80) already fires on UPDATE, so role changes invalidate sessions
+--     and the service returns a replacement token (groups.service.ts:168-200).
+-- ---------------------------------------------------------------------------
+ALTER TABLE group_members
+  ADD COLUMN role text NOT NULL DEFAULT 'member'
+    CHECK (role IN ('member', 'editor', 'reviewer'));
+
+COMMENT ON COLUMN group_members.role IS
+  'member = author/chat only; editor = edit group posts, cannot approve/publish; reviewer = approve/deny with reason';
+
+-- ---------------------------------------------------------------------------
+-- (2) Quorum config (Q3). 1:1 with workspace -> same RLS shape as every table.
+-- ---------------------------------------------------------------------------
+CREATE TABLE workspace_review_settings (
+  workspace_id uuid PRIMARY KEY REFERENCES workspaces(id) ON DELETE CASCADE,
+  approvals_required int NOT NULL DEFAULT 1 CHECK (approvals_required BETWEEN 1 AND 5),
+  stale_after_days int NOT NULL DEFAULT 90 CHECK (stale_after_days BETWEEN 1 AND 3650),
+  updated_by uuid REFERENCES users(id),
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+ALTER TABLE groups
+  ADD COLUMN review_approvals_required int CHECK (review_approvals_required BETWEEN 1 AND 5);
+-- NULL = inherit workspace default. Resolved once, at submit, onto the cycle.
+
+-- ---------------------------------------------------------------------------
+-- (3) Immutable post versions (Q2, R4). Append-only; hash is GENERATED so it
+--     can never disagree with the content (pgcrypto digest, as in audit_hash
+--     001:74-83).
+-- ---------------------------------------------------------------------------
+CREATE TABLE post_versions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,
+  version int NOT NULL CHECK (version >= 1),
+  post jsonb NOT NULL,
+  content_hash text GENERATED ALWAYS AS (encode(digest(post::text, 'sha256'), 'hex')) STORED,
+  created_by uuid NOT NULL REFERENCES users(id),
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (draft_id, version)
+);
+
+CREATE INDEX post_versions_draft ON post_versions (draft_id, version DESC);
+
+-- Append-only guard (new helper; workspace-delete cascades still work because
+-- only UPDATE is blocked, DELETE flows through ON DELETE CASCADE).
+CREATE FUNCTION reject_mutation() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  RAISE EXCEPTION '% rows are append-only', TG_TABLE_NAME USING ERRCODE = '23514';
+END $$;
+
+CREATE TRIGGER trg_post_versions_immutable BEFORE UPDATE ON post_versions
+  FOR EACH ROW EXECUTE FUNCTION reject_mutation();
+
+-- ---------------------------------------------------------------------------
+-- (4) Drafts: group scoping, version pointer, moderation flags (R7).
+--     Composite FK pins the draft's group to this workspace (008 pattern);
+--     NO ACTION (not SET NULL) because SET NULL would null workspace_id,
+--     violating NOT NULL + trg_draft_ws_immutable (006:41-42). Consequence:
+--     a group with posts cannot be deleted (deleteGroup gains a guard).
+-- ---------------------------------------------------------------------------
+ALTER TABLE drafts
+  ADD COLUMN group_id uuid,
+  ADD COLUMN current_version_id uuid REFERENCES post_versions(id),
+  ADD COLUMN hidden_at timestamptz,
+  ADD COLUMN hidden_by uuid REFERENCES users(id),
+  ADD COLUMN deleted_at timestamptz,
+  ADD COLUMN deleted_by uuid REFERENCES users(id),
+  ADD CONSTRAINT drafts_group_fk
+    FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id);
+
+CREATE INDEX drafts_queue ON drafts (workspace_id, state, updated_at DESC)
+  WHERE deleted_at IS NULL;
+
+-- ---------------------------------------------------------------------------
+-- (5) Review cycles: one per (draft, submission). Pins the version and the
+--     quorum snapshot (Q3). At most one open cycle per draft.
+-- ---------------------------------------------------------------------------
+CREATE TABLE review_cycles (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,
+  version_id uuid NOT NULL REFERENCES post_versions(id),
+  cycle int NOT NULL CHECK (cycle >= 1),
+  required_approvals int NOT NULL CHECK (required_approvals BETWEEN 1 AND 5),
+  status text NOT NULL DEFAULT 'open'
+    CHECK (status IN ('open', 'approved', 'denied', 'superseded', 'expired', 'blocked')),
+  publish_at timestamptz,            -- "primed to go out": intent declared at submit
+  connection_id uuid REFERENCES connections(id),
+  opened_by uuid NOT NULL REFERENCES users(id),
+  closed_at timestamptz,
+  closed_reason text,                -- 'quorum' | 'deny' | 'superseded_by_edit' | 'expired' | 'pool_below_quorum' | 'admin_override'
+  UNIQUE (draft_id, cycle)
+);
+
+CREATE UNIQUE INDEX review_cycles_one_open ON review_cycles (draft_id) WHERE status = 'open';
+CREATE INDEX review_cycles_open_by_age ON review_cycles (workspace_id, created_at)  -- stale sweep
+  WHERE status = 'open';
+
+-- ---------------------------------------------------------------------------
+-- (6) Votes (Q5, R6 in spec's R3). Immutable (one live vote per reviewer per
+--     cycle, no vote changes). Deny reason mandatory, approve reason optional —
+--     expressed as a CHECK so the DB enforces it too, not just the DTO parser.
+-- ---------------------------------------------------------------------------
+CREATE TABLE review_votes (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  cycle_id uuid NOT NULL REFERENCES review_cycles(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,  -- denormalized for queue queries
+  voter_user_id uuid NOT NULL REFERENCES users(id),
+  vote text NOT NULL CHECK (vote IN ('approve', 'deny')),
+  reason text CHECK (vote = 'approve' OR btrim(reason) <> ''),
+  snapshot_hash text NOT NULL,       -- copy of the version hash the voter saw
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (cycle_id, voter_user_id)   -- one live vote per reviewer per submission
+);
+
+CREATE INDEX review_votes_cycle ON review_votes (cycle_id, vote);
+
+-- ---------------------------------------------------------------------------
+-- (7) Review chat (R5): messages + system events in one append-only thread.
+--     `ord` is per-thread, assigned under the draft row lock -> total order,
+--     transport-agnostic cursor (Q4).
+-- ---------------------------------------------------------------------------
+CREATE TABLE review_messages (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,
+  ord int NOT NULL,
+  kind text NOT NULL CHECK (kind IN ('message', 'system')),
+  author_user_id uuid REFERENCES users(id),   -- NULL for system events
+  body text NOT NULL CHECK (btrim(body) <> ''),
+  event text,                                 -- system only: submitted|vote|state|…
+  event_data jsonb NOT NULL DEFAULT '{}',
+  created_at timestamptz NOT NULL DEFAULT now(),
+  UNIQUE (draft_id, ord)
+);
+
+CREATE INDEX review_messages_thread ON review_messages (draft_id, ord DESC);
+
+CREATE TRIGGER trg_review_messages_immutable BEFORE UPDATE ON review_messages
+  FOR EACH ROW EXECUTE FUNCTION reject_mutation();
+
+-- ---------------------------------------------------------------------------
+-- (8) Notification hook (R9): transactional outbox; consumers come later.
+-- ---------------------------------------------------------------------------
+CREATE TABLE review_notifications (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  draft_id uuid NOT NULL REFERENCES drafts(id) ON DELETE CASCADE,
+  user_id uuid NOT NULL REFERENCES users(id),  -- intended recipient
+  kind text NOT NULL,                          -- 'review_requested'|'denied'|'quorum_met'|'expired'|'blocked'|'mentioned'
+  payload jsonb NOT NULL DEFAULT '{}',
+  consumed_at timestamptz,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX review_notifications_inbox ON review_notifications (workspace_id, user_id)
+  WHERE consumed_at IS NULL;
+
+-- ---------------------------------------------------------------------------
+-- (9) Backfill BEFORE touching the state CHECK (the old CHECK only allows the
+--     six legacy values, so 'needs_changes' must be written after dropping it).
+--     Order: drop legacy CHECK -> rewrite 'rejected' -> add new CHECK.
+--     (Trg_draft_ws_immutable from 006:41-42 is unaffected: workspace_id
+--     never changes here.)
+-- ---------------------------------------------------------------------------
+ALTER TABLE drafts DROP CONSTRAINT drafts_state_check;
+
+UPDATE drafts SET state = 'needs_changes' WHERE state = 'rejected';
+
+ALTER TABLE drafts ADD CONSTRAINT drafts_state_check
+  CHECK (state IN ('editing', 'in_review', 'needs_changes', 'approved',
+                   'scheduled', 'published', 'expired', 'blocked'));
+
+-- v1 for every draft: content as it exists at migration time (intermediate
+-- versions were overwritten in place by updateDraft, publishing.service.ts:160-176).
+INSERT INTO post_versions (workspace_id, draft_id, version, post, created_by, created_at)
+SELECT d.workspace_id, d.id, 1, d.post, d.author_user_id, d.created_at
+FROM drafts d;
+
+UPDATE drafts d SET current_version_id = pv.id
+FROM post_versions pv WHERE pv.draft_id = d.id AND pv.version = 1;
+
+-- Legacy single-step approvals (Q9): one cycle + one synthetic vote each.
+-- opened_by has no historical value; the author is the least-wrong actor and
+-- closed_reason marks the row as migrated.
+INSERT INTO review_cycles
+  (workspace_id, draft_id, version_id, cycle, required_approvals, status,
+   publish_at, connection_id, opened_by, closed_at, closed_reason)
+SELECT d.workspace_id, d.id, pv.id, 1, 1,
+       CASE d.state
+         WHEN 'published' THEN 'approved'
+         WHEN 'scheduled' THEN 'approved'
+         WHEN 'approved'  THEN 'approved'
+         WHEN 'needs_changes' THEN 'denied'      -- migrated from 'rejected'
+         ELSE 'open'                               -- in_review: keeps working, one vote finishes it
+       END,
+       NULL, NULL, d.author_user_id,
+       CASE WHEN d.state IN ('published','scheduled','approved','needs_changes')
+            THEN d.updated_at END,
+       'migrated_from_single_step'
+FROM drafts d
+JOIN post_versions pv ON pv.draft_id = d.id AND pv.version = 1
+WHERE d.reviewer_user_id IS NOT NULL OR d.state = 'in_review';
+
+INSERT INTO review_votes
+  (workspace_id, cycle_id, draft_id, voter_user_id, vote, reason, snapshot_hash, created_at)
+SELECT c.workspace_id, c.id, c.draft_id, d.reviewer_user_id,
+       CASE WHEN d.state = 'needs_changes' THEN 'deny' ELSE 'approve' END,
+       CASE WHEN d.state = 'needs_changes' THEN
+         COALESCE(a.reason, 'migrated from legacy rejection (no reason recorded)')
+       ELSE NULL END,
+       pv.content_hash, d.updated_at
+FROM drafts d
+JOIN review_cycles c ON c.draft_id = d.id AND c.cycle = 1
+JOIN post_versions pv ON pv.id = c.version_id
+LEFT JOIN LATERAL (
+  SELECT (diff ->> 'reason') AS reason
+  FROM audit_log
+  WHERE workspace_id = d.workspace_id AND target_id = d.id::text
+    AND action = 'draft.rejected'
+  ORDER BY seq DESC LIMIT 1
+) a ON true
+WHERE d.reviewer_user_id IS NOT NULL;
+
+-- reviewer_user_id is now dead: 010 never writes it, 012 drops it
+-- (publishing.service.ts:315-317 and api-types.ts:70 stop reading first).
+COMMENT ON COLUMN drafts.reviewer_user_id IS
+  'DEPRECATED: superseded by review_votes in 010; dropped in 012';
+
+-- ---------------------------------------------------------------------------
+-- (10) Defense in depth (spec §3): the state machine lives in the service AND
+--      in the DB. Same CAS shape as publishing.service.ts:283-288 stays valid;
+--      the scheduler's scheduled->published write (publish.activity.ts:182)
+--      is an allowed edge.
+-- ---------------------------------------------------------------------------
+CREATE FUNCTION drafts_assert_transition() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF OLD.state = NEW.state THEN RETURN NEW; END IF;
+  IF NOT (
+       (OLD.state = 'editing'       AND NEW.state IN ('in_review'))
+    OR (OLD.state = 'in_review'     AND NEW.state IN ('approved', 'scheduled', 'needs_changes',
+                                                      'expired', 'blocked', 'editing'))
+    OR (OLD.state = 'needs_changes' AND NEW.state IN ('in_review'))
+    OR (OLD.state = 'approved'      AND NEW.state IN ('scheduled', 'needs_changes'))
+    OR (OLD.state = 'scheduled'     AND NEW.state IN ('approved', 'published', 'needs_changes'))
+    OR (OLD.state = 'expired'       AND NEW.state IN ('in_review'))
+    OR (OLD.state = 'blocked'       AND NEW.state IN ('in_review', 'needs_changes'))
+  ) THEN
+    RAISE EXCEPTION 'illegal draft transition % -> %', OLD.state, NEW.state
+      USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $$;
+
+CREATE TRIGGER trg_drafts_legal_transition BEFORE UPDATE OF state ON drafts
+  FOR EACH ROW EXECUTE FUNCTION drafts_assert_transition();
+
+-- ---------------------------------------------------------------------------
+-- (11) Live-eligibility recount (R8): reviewer removed / role changed ->
+--      re-tally open cycles of that group's drafts. Pool below quorum =>
+--      blocked; pool restored => reopened. Runs as the mutating user inside
+--      the tenant tx, so RLS and audit_append's fn_assert_tenant both hold.
+-- ---------------------------------------------------------------------------
+CREATE FUNCTION review_recount_group() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE r record; v_pool int; v_tally int;
+BEGIN
+  WITH affected AS (
+    SELECT DISTINCT d.id AS draft_id
+    FROM drafts d
+    WHERE d.group_id = COALESCE(NEW.group_id, OLD.group_id)
+      AND d.state IN ('in_review', 'blocked')
+  )
+  SELECT c.id, c.draft_id, c.required_approvals, d.author_user_id
+  INTO r
+  FROM review_cycles c JOIN drafts d ON d.id = c.draft_id
+  WHERE c.status IN ('open', 'blocked')
+    AND EXISTS (SELECT 1 FROM affected a WHERE a.draft_id = c.draft_id)
+  LIMIT 1;
+  WHILE r IS NOT NULL LOOP
+    SELECT count(DISTINCT u.id) INTO v_pool          -- currently-eligible non-author reviewers
+    FROM (SELECT m.user_id AS id
+          FROM memberships m JOIN role_permissions rp ON rp.role = m.role
+          WHERE m.workspace_id = (SELECT workspace_id FROM drafts WHERE id = r.draft_id)
+            AND m.status = 'active' AND rp.permission = 'review.vote'
+          UNION
+          SELECT gm.user_id FROM group_members gm
+          WHERE gm.group_id = (SELECT group_id FROM drafts WHERE id = r.draft_id)
+            AND gm.role = 'reviewer') u
+    WHERE u.id <> r.author_user_id;
+
+    SELECT count(*) INTO v_tally                      -- live tally: votes JOIN current eligibility
+    FROM review_votes v
+    WHERE v.cycle_id = r.id AND v.vote = 'approve'
+      AND EXISTS (SELECT 1 FROM memberships m JOIN role_permissions rp ON rp.role = m.role
+                  WHERE m.user_id = v.voter_user_id AND m.status = 'active'
+                    AND rp.permission = 'review.vote'
+                  UNION ALL
+                  SELECT 1 FROM group_members gm
+                  WHERE gm.user_id = v.voter_user_id AND gm.role = 'reviewer')
+      AND v.voter_user_id <> r.author_user_id;
+
+    IF v_pool < r.required_approvals THEN
+      UPDATE review_cycles SET status = 'blocked', closed_reason = 'pool_below_quorum'
+       WHERE id = r.id AND status = 'open';
+      UPDATE drafts SET state = 'blocked', updated_at = now() WHERE id = r.draft_id AND state = 'in_review';
+    ELSE
+      UPDATE review_cycles SET status = 'open', closed_reason = NULL
+       WHERE id = r.id AND status = 'blocked';        -- pool restored: reopen
+      UPDATE drafts SET state = 'in_review', updated_at = now() WHERE id = r.draft_id AND state = 'blocked';
+    END IF;
+
+    SELECT NULL INTO r;                               -- loop replaced by set-based form in impl;
+  END LOOP;                                           -- sketch shows intent, see §6.4
+  RETURN COALESCE(NEW, OLD);
+END $$;
+
+CREATE TRIGGER trg_group_role_recount
+  AFTER INSERT OR UPDATE OF role ON group_members
+  FOR EACH ROW EXECUTE FUNCTION review_recount_group();
+-- DELETE is covered by the existing cascade path: removing a membership rows
+-- deletes group_members (008:39 FK), whose own AFTER trigger runs the recount.
+
+-- ---------------------------------------------------------------------------
+-- (12) Expiry sweeper for the scheduler (R1). Same shape as
+--      publishing_due_schedules (006:79-87): STABLE, SECURITY DEFINER, no
+--      tenant context needed, ids only, revoked from PUBLIC, granted to sp_app.
+--      Covers both deadline-passed and stale (stale_after_days).
+-- ---------------------------------------------------------------------------
+CREATE FUNCTION review_due_expiries() RETURNS TABLE(draft_id uuid, cycle_id uuid, kind text)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT c.draft_id, c.id,
+         CASE WHEN c.publish_at IS NOT NULL AND c.publish_at <= now()
+              THEN 'deadline' ELSE 'stale' END
+  FROM review_cycles c
+  JOIN workspace_review_settings s ON s.workspace_id = c.workspace_id
+  WHERE c.status = 'open'
+    AND ( (c.publish_at IS NOT NULL AND c.publish_at <= now())
+       OR (c.publish_at IS NULL AND c.created_at < now() - (s.stale_after_days || ' days')::interval) )
+$$;
+
+REVOKE ALL ON FUNCTION review_due_expiries() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION review_due_expiries() TO sp_app;
+
+-- ---------------------------------------------------------------------------
+-- (13) Tenancy: the standard block, verbatim from 006/008, per new table.
+-- ---------------------------------------------------------------------------
+CREATE TRIGGER trg_wrs_ws_immutable BEFORE UPDATE ON workspace_review_settings
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_post_versions_ws_immutable BEFORE UPDATE ON post_versions
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_cycles_ws_immutable BEFORE UPDATE ON review_cycles
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_votes_ws_immutable BEFORE UPDATE ON review_votes
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_messages_ws_immutable BEFORE UPDATE ON review_messages
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_notifications_ws_immutable BEFORE UPDATE ON review_notifications
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+ALTER TABLE workspace_review_settings ENABLE ROW LEVEL SECURITY;
+ALTER TABLE post_versions          ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_cycles          ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_votes           ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_messages        ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_notifications   ENABLE ROW LEVEL SECURITY;
+ALTER TABLE workspace_review_settings FORCE ROW LEVEL SECURITY;
+ALTER TABLE post_versions          FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_cycles          FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_votes           FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_messages        FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_notifications   FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON workspace_review_settings
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON post_versions
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_cycles
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_votes
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_messages
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_notifications
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE, DELETE ON workspace_review_settings, post_versions,
+  review_cycles, review_votes, review_messages, review_notifications TO sp_app;
+
+-- ---------------------------------------------------------------------------
+-- (14) Permission seeds — purely additive; no existing role loses anything
+--      (R2: extend, don't break the 10-role contract).
+-- ---------------------------------------------------------------------------
+INSERT INTO role_permissions (role, permission)
+SELECT r, p FROM unnest(ARRAY['Owner', 'Admin']) AS r,
+              unnest(ARRAY['review.vote', 'review.manage', 'review.override',
+                           'moderation.hide', 'moderation.delete']) AS p
+ON CONFLICT DO NOTHING;
+
+INSERT INTO role_permissions (role, permission)
+SELECT 'Approver', 'review.vote' ON CONFLICT DO NOTHING;
+```
+
+### 3.1 Why these shapes and not others
+
+- **`review_cycles` pins `version_id` and snapshots `required_approvals`, `publish_at`, `connection_id`.** The cycle is the unit of trust: "2 approvals of hash X by time T through connection C". Everything the quorum-met handler needs is on one row, so no config read can race the transition.
+- **`review_votes.snapshot_hash`** duplicates `post_versions.content_hash` so each vote is a self-contained attestation — the audit chain (`audit_log.diff`) and the vote ledger independently prove what was approved, without a join.
+- **`review_messages` merges human messages and system events** (R5 "system events rendered inline") instead of two tables: one cursor, one ordering, one render list; `kind` + nullable `author_user_id` + `event` distinguish them.
+- **Moderation is flags, not states** (§1): `hidden_at`/`deleted_by` coexist with any machine state, the legal-transition trigger stays a pure function of state, and the scheduler needs no second transition after publish.
+- **`drafts_queue` is a partial index** (`WHERE deleted_at IS NULL`) — soft-deleted rows are excluded from the hot path but retained for the audit record.
+
+---
+
+## 4. State machine (deliverable 3)
+
+States after `010`: `editing · in_review · needs_changes · approved · scheduled · published · expired · blocked`.
+`rejected` is gone (migrated to `needs_changes`, which is resubmittable — closing the "no resubmit path" gap, spec §2.1).
+
+| # | From | To | Fired by | Guard / effect |
+|---|------|----|----------|----------------|
+| 1 | `editing` | `in_review` | author, group **editor**, or `approval.request` holder | `POST /drafts/:id/submit {publishAt?, connectionId?}`. Freezes a new `post_versions` row, opens cycle 1..n with snapshotted quorum. **Preflight:** eligible non-author reviewers ≥ required (else `400`). If `connectionId` given: RLS-scoped existence + group-scope check (the `publishing.service.ts:217-219` pattern). Audit `review.submitted`. |
+| 2 | `in_review` | `needs_changes` | any eligible **reviewer**, deny vote | Reason mandatory (`400` if blank). Cycle → `denied`; sibling approvals preserved as history, count for nothing (Q5). System event + audit `review.denied`. |
+| 3 | `in_review` | `needs_changes` | author/group editor, **edit during review** | New version row; cycle → `superseded` (`closed_reason='superseded_by_edit'`). Full reset (Q6). Audit `review.cycle_superseded`. |
+| 4 | `in_review` | `approved` | quorum engine (N live approvals ≥ required), no `publish_at` | Cycle → `approved`; draft awaits manual schedule (existing `approved→scheduled` path unchanged). Audit `review.quorum_met`. |
+| 5 | `in_review` | `scheduled` | quorum engine, `publish_at` **and** `publish_at > now()` | Creates `scheduled_publications` + starts workflow (`startScheduledPublish`, `publishing.service.ts:83-113`). Audit `review.quorum_met` + `publication.scheduled`. |
+| 6 | `in_review` | `expired` | quorum engine with `publish_at <= now()`, **or** sweeper | Nothing is ever scheduled late (Q7). Audit `review.expired`. |
+| 7 | `in_review` | `blocked` | recount trigger (pool < quorum) | Reviewer removed/demoted mid-review (Q8). Audit `review.blocked`. |
+| 8 | `in_review` | `editing` | author withdraws | Cycle → `superseded`. Audit `review.withdrawn`. |
+| 9 | `needs_changes` | `in_review` | author or group editor resubmits | New version + new cycle (fresh quorum). Optionally new `publishAt`/`connectionId`. This is the resubmit path that does not exist today. |
+| 10 | `approved` | `scheduled` | `publication.schedule` holder | Existing `schedule()` unchanged (`publishing.service.ts:212-247`). |
+| 11 | `approved` | `needs_changes` | author/editor edit after approval | Post-approval edit re-triggers the chain (spec §3 lock-after-approve). Cycle already closed; new cycle on resubmit. |
+| 12 | `scheduled` | `approved` | `publication.schedule` holder | Existing `cancelSchedule()` unchanged. |
+| 13 | `scheduled` | `needs_changes` | edit, or admin override-deny | Transactionally deletes the pending `scheduled_publications` row first (else `UNIQUE(draft_id)`, `006:24`, blocks re-scheduling). |
+| 14 | `scheduled` | `published` | **scheduler only** (`sp_scheduler`) | Unchanged: `publish.activity.ts:182`. Archive = this state (§1). |
+| 15 | `expired` | `in_review` | author re-primes | New cycle; must supply a future `publishAt` if it wants scheduling. R1's "re-prime after re-approval". |
+| 16 | `blocked` | `in_review` | recount trigger (pool restored) | Adding/re-promoting a reviewer reopens automatically; no human step needed. |
+| 17 | `blocked` | `needs_changes` | admin override-deny, or author withdraws | Override: mandatory reason, `review.override_denied` audit. |
+| 18 | `blocked` | `approved`/`scheduled` | admin override-approve (`review.override`) | Emergency brake (Q8). Not a vote: no `review_votes` row; `closed_reason='admin_override'`. |
+
+Who **cannot** fire things (structural, server-side):
+
+- The **author can never vote** on their own post when `required_approvals ≥ 2` — `403 ForbiddenException("reviewers cannot vote on their own post")` from the service, *in addition to* eligibility being excluded from the tally SQL. At `required_approvals = 1` self-approval is permitted (legacy/self-service mode) and stamped `selfApproved: true` in the audit diff — see §6.3.
+- Group **editors** cannot vote (their group role grants edit, never `reviewer`), cannot schedule (`publication.schedule` is not granted to them), and workspace role `Editor` already lacks `approval.grant` (`002:39-43`).
+- Group **reviewers** cannot edit content (edit path checks author ∨ group-editor ∨ `draft.edit`).
+- Nobody transitions into `published` except the scheduler; nobody transitions out of it (terminal; moderation is flags).
+
+Every transition above is (a) a CAS `UPDATE … WHERE id=$1 AND state=$from` exactly like `transition()` (`publishing.service.ts:283-288`), **and** (b) legal per `trg_drafts_legal_transition` — the DB is the second enforcement layer even against direct SQL.
+
+---
+
+## 5. RBAC (deliverable 4)
+
+### 5.1 New permissions (additive seeds only)
+
+| Permission | Granted to | Meaning |
+|---|---|---|
+| `review.vote` | Owner, Admin, Approver | Workspace-level reviewer. Guard gate for the vote endpoint; the service then re-checks author-exclusion and group scope. |
+| `review.manage` | Owner, Admin | Set workspace/group quorum, resolve `blocked`, view live vote identities. (Same holders as `workspace.members.manage`, `002:7/:23` — admin-only per R3.) |
+| `review.override` | Owner, Admin | Force approve/deny with mandatory reason; logged as override, never as a vote. |
+| `moderation.hide` | Owner, Admin | Hide/unhide any post (R7, admin-only). |
+| `moderation.delete` | Owner, Admin | Soft-delete any post (R7, admin-only). |
+
+No existing role loses a permission; `approval.request`/`approval.grant` keep their seed rows (`002:8/:24/:35/:49`) — `approval.grant` becomes the *workspace-wide* form of review power (holders are eligible voters everywhere), which is exactly the "extend, don't break" reading of R2. The legacy `/approve` and `/reject` endpoints are superseded by `/votes` + `/override` and removed in WP-C (their guard permission `approval.grant` still exists for compatibility with any external caller during the deprecation window).
+
+### 5.2 Group-role mechanism
+
+`group_members.role` (§3 step 1). Effective capabilities for a draft with `group_id G`:
+
+| Capability | Satisfied by |
+|---|---|
+| Author | any member of G (or any `draft.create` holder for ungrouped drafts) |
+| Edit content | author ∨ `group_members.role='editor'` in G ∨ workspace `draft.edit` |
+| Submit / resubmit | author ∨ group editor ∨ `approval.request` |
+| Vote | (`review.vote` via workspace role) ∨ (`group_members.role='reviewer'` in G) — **and** ≠ author (at N≥2) |
+| Schedule | `publication.schedule` (unchanged; group editors never get it) |
+| Moderate | `moderation.hide`/`.delete` (Owner/Admin only) |
+
+Guard-side checks are service functions on the tenant client, mirroring `userCanUseConnection` (`groups.service.ts:425-455`) — role read from the DB, never from the token:
+
+```ts
+// apps/api/src/review/review.eligibility.ts (sketch)
+export interface VoteEligibility {
+  eligible: boolean;
+  reason?: "not_group_reviewer" | "author" | "not_in_review";
+  groupRole: "member" | "editor" | "reviewer" | null;
+}
+
+export async function voteEligibility(
+  client: PoolClient,
+  workspaceId: string,
+  userId: string,
+  draft: { id: string; groupId: string | null; authorUserId: string; state: DraftState },
+  requiredApprovals: number,
+): Promise<VoteEligibility> {
+  const res = await client.query(
+    `SELECT
+       EXISTS (SELECT 1 FROM role_permissions rp
+               JOIN memberships m ON m.role = rp.role
+                                  AND m.workspace_id = $1 AND m.user_id = $2
+                                  AND m.status = 'active'
+               WHERE rp.permission = 'review.vote') AS workspace_reviewer,
+       (SELECT gm.role FROM group_members gm
+         WHERE gm.group_id = $3 AND gm.user_id = $2)      AS group_role`,
+    [workspaceId, userId, draft.groupId],
+  );
+  const row = requiredRow(res.rows[0], "eligibility");
+  const byRole = row.group_role === "reviewer";
+  if (!byRole && row.workspace_reviewer !== true) {
+    return { eligible: false, reason: "not_group_reviewer", groupRole: null };
+  }
+  // Structural self-approval exclusion (four-eyes). At quorum 1 the legacy
+  // self-service mode is preserved (compose/page.tsx:128-131) and flagged.
+  if (userId === draft.authorUserId && requiredApprovals >= 2) {
+    return { eligible: false, reason: "author", groupRole: row.group_role };
+  }
+  if (draft.state !== "in_review") return { eligible: false, reason: "not_in_review", groupRole: row.group_role };
+  return { eligible: true, groupRole: row.group_role };
+}
+```
+
+`requiredRow` follows `publishing.service.ts:297-300`. No `as any`; `group_role` is `null` for ungrouped drafts and the SQL handles `$3 = NULL` (no row → NULL).
+
+### 5.3 Self-approval exclusion & admin override
+
+- Self-approval: enforced in `voteEligibility` (above) **and** excluded from the tally SQL (§6.2) **and** impossible to satisfy at N≥2 even for Owner — three independent layers.
+- Override: `POST /publishing/drafts/:id/override {decision: 'approve'|'deny', reason}` — `@RequirePermission("review.override")`, reason mandatory. Effects per §4 rows 17–18. Writes **no** `review_votes` row (overrides must not pollute quorum metrics), writes audit `review.override_granted`/`review.override_denied` with the reason and the actor, and a masked-then-revealed system event.
+
+### 5.4 Epoch interplay
+
+- `group_members.role` UPDATE fires `trg_group_member_bump_epoch` (`008:79-80`) → every session dies → `PATCH /groups/:id/members/:userId` returns `{token}` minted in-tx via `issueSessionInTenant` (`auth.service.ts:72-84`), same contract as `addMember`/`removeMember` (`groups.service.ts:168-200`).
+- Group **deletion** must gain a guard in `deleteGroup`: `drafts_group_fk` is `NO ACTION`, so deleting a group with posts raises FK — surface it as `409 group still has posts; move or delete them first` instead of a 500.
+- The recount trigger (§3 step 11) runs inside the same tx, so "reviewer demoted" and "cycle re-tallied" commit atomically — R8's "votes revoked/re-counted" is one transaction, not a eventual-consistency hope.
+
+---
+
+## 6. Quorum engine (deliverable 5)
+
+### 6.1 Vote lifecycle
+
+1. **One live vote per reviewer per submission**: `UNIQUE(cycle_id, voter_user_id)`; a second attempt returns `409 ConflictException("already voted in this cycle")`.
+2. **Votes are immutable** (no vote changes — `review_votes` has no UPDATE path and `reject_mutation`-style immutability is the norm here). Justification: a vote attests a hash; a changed attestation rewrites history the hash-chained audit already recorded. A reviewer who reconsidered can comment; a deny closes the cycle anyway; a genuine misfire is an admin override. *Future work:* "retract my approval while cycle open" if teams demand it.
+3. **Deny = veto** (Q5): closes the cycle `denied`, draft → `needs_changes`, reason mandatory end-to-end (DTO `requireString`, DB `CHECK (vote = 'approve' OR btrim(reason) <> '')`).
+4. **Eligibility is re-checked live at every evaluation** (spec §3 four-eyes): the tally JOINs *current* membership/role state, so a removed reviewer's historical vote stops counting without being deleted.
+
+### 6.2 Tally (live, cycle-scoped, author-excluded)
+
+```sql
+-- inside castVote(), same tx, after inserting the vote
+WITH eligible AS (
+  SELECT m.user_id AS id
+  FROM memberships m JOIN role_permissions rp ON rp.role = m.role
+  WHERE m.workspace_id = $1 AND m.status = 'active' AND rp.permission = 'review.vote'
+  UNION
+  SELECT gm.user_id FROM group_members gm
+  WHERE gm.group_id = $2 AND gm.role = 'reviewer'
+)
+SELECT count(*)::int AS approvals
+FROM review_votes v JOIN eligible e ON e.id = v.voter_user_id
+WHERE v.cycle_id = $3 AND v.vote = 'approve'
+  AND ($4 < 2 OR v.voter_user_id <> $5)   -- author exclusion applies only at quorum >= 2
+```
+
+`$4` = `required_approvals` snapshot, `$5` = author. At quorum 1 the author's own (permitted, flagged) vote counts — that is today's behavior, preserved.
+
+### 6.3 `castVote` service sketch (repo style: strict TS, DI like `PUBLISHING_DEPENDENCIES`)
+
+```ts
+export interface CastVoteInput {
+  vote: "approve" | "deny";
+  reason?: string;
+}
+
+export interface CastVoteResult {
+  draftState: DraftState;
+  cycleStatus: ReviewCycleStatus;
+  tally: { approvals: number; required: number };
+}
+
+async castVote(workspaceId: string, actor: Actor, draftId: string, input: CastVoteInput): Promise<CastVoteResult> {
+  if (input.vote === "deny" && (input.reason ?? "").trim() === "") {
+    throw new BadRequestException("deny requires a non-empty reason");
+  }
+  return withTenant(workspaceId, async (client) => {
+    await client.query("SELECT id FROM drafts WHERE id = $1 FOR UPDATE", [draftId]); // serialize vs sweeper/other voters
+    const draft = await lockDraft(client, draftId);                                   // 404 / RLS-scoped
+    const cycle = await openCycle(client, draftId);                                   // 409 if not open
+    const eligibility = await voteEligibility(client, workspaceId, actor.userId, draft, cycle.requiredApprovals);
+    if (!eligibility.eligible) {
+      if (eligibility.reason === "author") throw new ForbiddenException("reviewers cannot vote on their own post");
+      throw new ForbiddenException("you are not a reviewer for this post");
+    }
+    const version = await versionRow(client, cycle.versionId);
+    try {
+      await client.query(
+        `INSERT INTO review_votes (workspace_id, cycle_id, draft_id, voter_user_id, vote, reason, snapshot_hash)
+         VALUES ($1, $2, $3, $4, $5, $6, $7)`,
+        [workspaceId, cycle.id, draftId, actor.userId, input.vote, input.reason ?? null, version.contentHash],
+      );
+    } catch (err) {
+      if (pgCode(err) === UNIQUE_VIOLATION) throw new ConflictException("already voted in this cycle");
+      throw err;
+    }
+    const tally = await liveTally(client, workspaceId, draft.groupId, cycle.id, cycle.requiredApprovals, draft.authorUserId);
+
+    if (input.vote === "deny") {
+      await this.closeCycle(client, cycle, "denied", "deny");
+      await this.transitionDraft(client, draftId, "in_review", "needs_changes");
+    } else if (tally.approvals >= cycle.requiredApprovals) {
+      await this.meetQuorum(client, draft, cycle, tally);
+    }
+    // Same-tx audit + system message (groups.service.ts:100-110 pattern): a vote
+    // can never land without its audit entry.
+    await audit(client, workspaceId, {
+      actorUserId: actor.userId, actorRole: actor.role,
+      action: input.vote === "deny" ? "review.denied" : "review.vote_cast",
+      targetType: "draft", targetId: draftId,
+      diff: { cycle: cycle.cycle, vote: input.vote, ...(input.reason === undefined ? {} : { reason: input.reason }),
+              snapshotHash: version.contentHash, approvals: tally.approvals, required: cycle.requiredApprovals,
+              ...(actor.userId === draft.authorUserId ? { selfApproved: true } : {}) },
+    });
+    await systemMessage(client, workspaceId, draftId, "vote",
+      { masked: true, vote: input.vote, approvals: tally.approvals, required: cycle.requiredApprovals });
+    return { draftState: await draftState(client, draftId), cycleStatus: await cycleStatus(client, cycle.id), tally };
+  });
+}
+```
+
+### 6.4 `meetQuorum` — the race-condition core (Q7)
+
+```ts
+private async meetQuorum(client: PoolClient, draft: DraftRow, cycle: CycleRow, tally: Tally): Promise<void> {
+  if (draft.hiddenAt !== null || draft.deletedAt !== null) {
+    await this.closeCycle(client, cycle, "blocked", "hidden_at_quorum");
+    await this.transitionDraft(client, draft.id, "in_review", "blocked");
+    return; // hidden posts never publish; an admin resolves via override/delete
+  }
+  if (cycle.publishAt !== null) {
+    if (cycle.publishAt.getTime() <= Date.now()) {
+      await this.closeCycle(client, cycle, "expired", "deadline");        // too late: never schedule late
+      await this.transitionDraft(client, draft.id, "in_review", "expired");
+      return;
+    }
+    const scheduled = await this.insertSchedule(client, workspaceIdOf(draft), draft.id, cycle.connectionId, cycle.publishAt);
+    await this.closeCycle(client, cycle, "approved", "quorum");
+    await this.transitionDraft(client, draft.id, "in_review", "scheduled"); // edge 5 of §4
+    await this.workflowStarter.startScheduledPublish(scheduled.idempotencyKey, cycle.publishAt).catch(() => undefined);
+    return; // sweeper publishing_due_schedules() (006:79-87) re-starts if Temporal was down
+  }
+  await this.closeCycle(client, cycle, "approved", "quorum");
+  await this.transitionDraft(client, draft.id, "in_review", "approved");   // edge 4: manual schedule later
+}
+```
+
+Race resolutions:
+
+- **Two reviewers approve concurrently.** Both take `SELECT … FOR UPDATE` on the drafts row before touching the cycle; the second transaction blocks, then re-reads the cycle as already closed → its `openCycle` returns `409 cycle closed` *after* its vote insert… which would leak a vote onto a closed cycle. Fix (implementation note): the vote insert and the cycle re-read happen under the same row lock, and `closeCycle` is itself a CAS (`UPDATE review_cycles SET status=… WHERE id=$1 AND status='open'`); the loser's insert committed first in lock order, so the winner's tally **included** it — i.e. the "loser" is whoever didn't win the `closeCycle` CAS, and their vote is exactly what made quorum. The invariant to test (§12, test 4): exactly one `approved`/`scheduled` transition and at most one `scheduled_publications` row per draft (`UNIQUE(draft_id)`, `006:24`, is the backstop).
+- **Quorum vote vs expiry sweeper at T±ε.** Both paths lock the draft row; whichever wins sets the state, the other's CAS (`WHERE state='in_review'`) matches zero rows and no-ops (the `throwTransitionError` pattern from `publishing.service.ts:294-302` turns it into a clean "already handled").
+- **Quorum met at T-1min.** `publish_at > now()` → schedule created, `startDelay ≈ 60s` (`publishing.service.ts:99-101`), publishes on time. Auto, no re-confirm (Q7).
+- **Quorum met at T+1min.** `expired` (above). Nothing publishes late, ever.
+- **Sweeper shape.** `review_due_expiries()` (§3 step 12) + a scheduler activity `reviewExpire()` that mirrors `listDue`/`publishScheduled` (`publish.activity.ts:160-245`): look up workspace via a small SECURITY DEFINER helper (or return `workspace_id` from the sweeper fn), open `inTenant`, close cycle + transition + `audit_append(…, NULL, 'sp_scheduler', 'review.expired', …)` — the exact actor convention of `publication.published` (`publish.activity.ts:184-190`). Lazy double-check at quorum time (above) covers clock skew between API and scheduler.
+
+### 6.5 Submit preflight (Q8)
+
+```sql
+-- count of currently eligible non-author reviewers for this draft's scope
+WITH eligible AS ( /* same CTE as §6.2 */ )
+SELECT count(*)::int FROM eligible WHERE id <> $author
+```
+If `< requiredApprovals` → `400 BadRequestException("not enough eligible reviewers (0) for quorum (2) — add reviewers to the group or lower its quorum")`. The draft stays `editing`; nothing half-created. (At `required_approvals = 1` no preflight — solo workspaces keep today's self-serve flow.)
+
+---
+
+## 7. Review chat (deliverable 6)
+
+### 7.1 Data model
+
+`review_messages` (§3 step 7): one append-only thread per draft, human messages (`kind='message'`, `author_user_id` set) and system events (`kind='system'`, `event` + `event_data`) interleaved on one `ord` sequence. Posting:
+
+```ts
+async postMessage(workspaceId: string, actor: Actor, draftId: string, body: string): Promise<ReviewMessage> {
+  const clean = body.trim();
+  if (clean === "") throw new BadRequestException("message must be a non-empty string");
+  return withTenant(workspaceId, async (client) => {
+    await client.query("SELECT id FROM drafts WHERE id = $1 FOR UPDATE", [draftId]); // ord assignment is serialized
+    const res = await client.query(
+      `INSERT INTO review_messages (workspace_id, draft_id, ord, kind, author_user_id, body)
+       SELECT $1, $2, coalesce(max(ord), 0) + 1, 'message', $3, $4
+       FROM review_messages WHERE draft_id = $2
+       RETURNING *`,
+      [workspaceId, draftId, actor.userId, clean],
+    );
+    return messageFromRow(requiredRow(res.rows[0], "review message"));   // UNIQUE(draft_id, ord) is the backstop
+  });
+}
+```
+
+Who can post: any group member of the draft's group, any workspace member for ungrouped drafts (gate: `draft.view` at the guard + membership check in service, mirroring `RequireGroupAccess`'s split, `rbac.guard.ts:64-74`). Chat is **not** audit-chained (R8 requires transitions and votes; messages are content, preserved immutably by `reject_mutation` — their integrity story is append-only + RLS, not the hash chain). Reasons are content, not secrets: `scrub()` (`audit.service.ts:11-17`) would not redact them anyway (no secret-key match).
+
+### 7.2 System event types
+
+| `event` | Emitted on | `event_data` (masked while cycle open, Q10) |
+|---|---|---|
+| `submitted` | cycle opened (v, cycle n, required, publishAt?) | `{version, cycle, required, publishAt}` |
+| `vote` | vote cast | `{vote, approvals, required}` — actor identity added on cycle close |
+| `denied` | cycle closed `denied` | `{reason, by}` (identity revealed at close — the author must see who/why) |
+| `quorum_met` | cycle closed `approved` | `{approvals, required, scheduledAt?}` |
+| `cycle_superseded` | edit during/after review | `{fromVersion, toVersion}` |
+| `state` | any other draft transition (expired, blocked, scheduled, published, hidden, deleted) | `{from, to}` |
+| `override` | admin override | `{decision, reason, by}` |
+
+Read endpoint masks identity server-side while `status='open'` (Q10): the row keeps `event_data.actorUserId`, the serializer drops it unless the cycle is closed or the caller holds `review.override`.
+
+### 7.3 Transport (Q4 decision recap)
+
+`GET /publishing/drafts/:id/messages?after=<ord>&limit=100` — cursor pagination by `ord` (validate with `parseLimit`, `http/validation.ts:57-63`), polled at 4s while the detail pane is open; the queue polls at 15s or refetches on any local action. Every request passes `RbacGuard` (session → epoch → `draft.view`) and tenant RLS, so a reviewer removed mid-thread fails closed on the next poll with `401 authorization epoch stale` (`rbac.guard.ts:46-47`) and the client re-authenticates — no long-lived authorization to revoke. *Future work:* WS gateway reusing `authorizeSubscription` (`gateway.ts:12-45`) + a `review.<draftId>` topic check + the identical `after=<ord>` replay query.
+
+---
+
+## 8. UI plan (deliverable 7)
+
+### 8.1 `/approvals` → the working-posts queue (replaces the stub, `approvals/page.tsx`)
+
+Two-pane layout (the Inbox shape, `inbox/page.tsx:52-120`):
+
+- **Left: queue list** — virtualized with the exact `column.tsx:26-34` config (`useVirtualizer`, `estimateSize: () => 110`, `overscan: 8`, `scrollToIndex` on selection). Row: state chip (`Badge`, tones below), author, first line of text, **quorum progress chip `2/3 ✓`** (live tally from `GET /publishing/queue`), relative deadline when `publish_at` is near.
+- **Filters** (R6): `needs my review` (default; eligibility computed server-side per caller), `needs changes`, `expiring soon` (`publish_at < now()+24h`), `all`. Server-side filter params keep the virtualizer honest.
+- **Right: post detail** — three stacked zones:
+  1. **Rendered preview** — reuse the compose preview card markup (`compose/page.tsx:244-262`) against the pinned version's `post`.
+  2. **Version diff** — `v(n-1) → v(n)` selector; reuse the audit page's diff viewer (audit page, 236 lines, has the component) over the two `post` jsonbs.
+  3. **Chat + vote panel** — Inbox bubble thread (`inbox/page.tsx:82-104`) + reply box (`:105-118`) with **Approve / Deny…** buttons inline (R5). Deny opens a mandatory-reason textarea; submit disabled while blank (mirrors `requireString` server-side). Buttons render only when the server says the caller is eligible (`canVote` flag on the queue/detail payload — never inferred client-side).
+  - Schedule strip: `publish_at`, connection label, "expiring in 3h" warning.
+- **Keyboard model** (Streams pattern, `streams/page.tsx:56-70`, incl. the INPUT/TEXTAREA/contentEditable guard): `j/k` move, `Enter` open, `a` approve, `d` deny (focuses reason box), `c` focus chat, `e` toggle diff, `Esc` back to list.
+
+### 8.2 `/archive`
+
+Read-only list of `state='published'` (§1: archive *is* published), same virtualized list, chat history preserved and readable (record requirement, R7). Admin affordances gated on `can("moderation.hide")` / `can("moderation.delete")`: **Hide** (members stop seeing it; admins see a `hidden` danger Badge), **Delete** (soft; disappears for everyone, remains in audit). Moderation scope (R7 decision): **any state**, not just archive — an embarrassing draft should be removable before it publishes; hiding a `scheduled` post transactionally cancels the pending schedule first.
+
+### 8.3 Compose changes (`compose/page.tsx`)
+
+- **Group picker** when the author belongs to groups (`GET /groups/mine` exists, `groups.controller.ts:57-61`); ungrouped = workspace review.
+- The current auto-approve chain (`compose/page.tsx:119-142`) becomes: create → **submit** (`{publishAt, connectionId}` = "primed"), stop. The self-approve shortcut survives only in the `required_approvals=1` workspace via the vote endpoint; the button label changes to "Submit for review (2 approvals)" using the resolved quorum so expectations are set before submit.
+- `STATE_TONE` (`:35-42`) gains: `needs_changes: "warn"`, `expired: "danger"`, `blocked: "danger"`.
+- "Recent drafts" sidebar (`:255-263`) links queue-ward; sidebar badge (`sidebar.tsx:13` already hints "2") wires to the `needs my review` count.
+
+### 8.4 Client plumbing
+
+- `api-types.ts`: `DraftState` widened (mirrors `publishing.service.ts:8`), plus `ReviewCycleSummary`, `ReviewVoteSummary`, `ReviewMessage`, `QueueItem`. `reviewerUserId` (`:70`) marked deprecated (dropped with the column in 012).
+- `useApiResource` (`use-api.ts`) gains an optional `refetchIntervalMs` (non-breaking, default off) for the two poll rates; everything still flows through `api`/`apiFetch` so auth, 401 redirect, and offline fallback stay uniform (`api-client.ts:57-59, :100-106`).
+- Offline mode: queue/detail ship fixture data like every other screen (`DataSource: "sample"`, `use-api.ts:16-20`).
+
+---
+
+## 9. Edge cases — the ugly ones (deliverable 8)
+
+| # | Case | Concrete resolution |
+|---|---|---|
+| 1 | **Reviewer removed from group mid-review** | `group_members` DELETE cascades from `memberships` (FK, `008:39`) → `trg_group_role_recount` re-tallies: their historical vote stops counting (live-eligibility tally, §6.2); if pool < required → cycle `blocked`, draft `blocked` (same tx); the epoch bump (`008:79-80`) kills their session, so their in-flight client gets `401` on the next call — no stale vote can arrive after the removal commits. |
+| 2 | **Reviewer demoted to `member`/`editor`** | Same as #1 via the `UPDATE OF role` branch; the demote endpoint returns `{token}` (epoch re-issue pattern). |
+| 3 | **Reviewer added while `blocked`** | Recount sees pool ≥ required → cycle back to `open`, draft back to `in_review`, system event `state`. No human unblock step. |
+| 4 | **Deadline race: quorum at T-1min** | Auto-publish (Q7): schedule created (`publish_at > now()`), `startDelay ≈ 60s`, sweeper backstops a missed Temporal start (`006:79-87`). |
+| 5 | **Quorum at T+1min / never** | `expired` via the same `meetQuorum` branch or the `review_due_expiries()` sweep (covers both deadline and `stale_after_days` staleness). Author re-primes: `expired → in_review` with a new cycle and a fresh `publishAt`. |
+| 6 | **Vote tx races the expiry sweeper** | Both lock the draft row (`FOR UPDATE`); loser's CAS `WHERE state='in_review'` matches zero rows and no-ops (`throwTransitionError` pattern, `publishing.service.ts:294-302`). Test 7 in §12. |
+| 7 | **Deadlock: author is the only reviewer, quorum 2** | Submit preflight `400` with an actionable message (Q8); if it happens later anyway → `blocked` + admin `review.override` (mandatory reason) or add-a-reviewer. |
+| 8 | **Epoch churn mid-vote** | Vote is one tx; the guard's epoch check (`rbac.guard.ts:45-47`) runs *before* it, so a membership change between guard and commit is bounded by: the tally re-checks eligibility *inside* the tx, and the recount trigger already re-tallied — worst case the vote lands and immediately doesn't count, which is the correct outcome, not corruption. |
+| 9 | **Edit during review** | New version; cycle `superseded`; sibling votes preserved-but-not-counted; draft `needs_changes`; resubmit = new cycle, fresh quorum (Q6). Editors *can* edit in review — that's their job — the invariant is "no mutable content while approvals are live", not "no edits". |
+| 10 | **Edit after scheduling** | `scheduled → needs_changes` transactionally deletes the pending `scheduled_publications` row first (else `UNIQUE(draft_id)`, `006:24`); the started Temporal workflow finds no pending row and its claim fails cleanly (`publish.activity.ts:137-158` "not pending"). |
+| 11 | **Connection deleted between submit and quorum** | `meetQuorum`'s `insertSchedule` catches FK violation → cycle `blocked` (`closed_reason='connection_unavailable'`), audit `review.blocked`; admin overrides or author re-primes. (Same FK-bypasses-RLS caveat as `publishing.service.ts:217-219`: the *submit-time* check is an RLS-scoped read, the quorum-time failure is the backstop.) |
+| 12 | **Hidden post reaches quorum** | `meetQuorum` refuses to schedule: cycle `blocked` (`hidden_at_quorum`); an admin unhides (recount does not auto-reopen — hiding is a moderation decision, so the exit is override or unhide+resubmit). |
+| 13 | **Group deleted with in-flight posts** | `drafts_group_fk` is `NO ACTION` → FK error; `deleteGroup` surfaces `409 group still has posts`. (SET NULL was impossible: it would null `workspace_id`, violating NOT NULL + `trg_draft_ws_immutable`, `006:41-42`.) |
+| 14 | **Author leaves the workspace mid-review** | `memberships` cascade removes their group rows → recount (pool unchanged unless they were also a reviewer); draft and cycle persist (`author_user_id` has no cascade, `006:6`); the queue shows the (still existing) user record; `needs_changes` posts by a gone author are exited via admin override-deny or an editor resubmits (group editors may resubmit). |
+| 15 | **Duplicate/late vote on a closed cycle** | `openCycle` → `409 cycle closed`; the UI's vote panel is disabled by the server-computed `canVote` flag anyway. |
+| 16 | **Two messages concurrently** | `ord` assigned under the draft row lock; `UNIQUE(draft_id, ord)` is the backstop; clients reconcile by re-pulling from `after=<lastOrd>`. |
+| 17 | **Migration over existing data** | Backfills are plain INSERT/UPDATE inside the migration tx (`migrate.ts:33-41`); the state rewrite runs *after* dropping the legacy CHECK and *before* adding the new one (§3 step 9); `rejected` rows all become `needs_changes` so no row violates the new CHECK. |
+
+---
+
+## 10. Audit & security (deliverable 9)
+
+### 10.1 Event list (all through `audit_append` — `001:85-111` — same-tx for decisions, per `groups.service.ts:100-110`)
+
+| Action | Actor | When |
+|---|---|---|
+| `review.submitted` | submitter | cycle opened (diff: version, cycle, required, snapshotHash, publishAt?, connectionId?) |
+| `review.vote_cast` | voter | approve vote (diff: vote, snapshotHash, approvals/required, `selfApproved?`) |
+| `review.denied` | voter | deny vote (diff: reason — mandatory) |
+| `review.quorum_met` | last voter | cycle closed approved (diff: approvals, scheduled?) |
+| `review.cycle_superseded` | editor | edit during/after review (diff: from/to version hashes) |
+| `review.withdrawn` | author | in_review → editing |
+| `review.expired` | `sp_scheduler` (actor NULL) | sweep or late quorum |
+| `review.blocked` / `review.reopened` | trigger (actor: mutating admin) or `sp_scheduler` | pool below/restored |
+| `review.override_granted` / `review.override_denied` | Owner/Admin | override (reason mandatory; **never** a `review_votes` row) |
+| `review.settings_changed` | Owner/Admin | quorum/staleness config (diff old→new) |
+| `review.group_role_changed` | Owner/Admin | member→editor/reviewer (diff old→new) |
+| `post.hidden` / `post.unhidden` / `post.deleted` | Owner/Admin | moderation (diff: state at time, reason) |
+| `draft.created/updated/submitted`, `publication.scheduled/schedule_cancelled/published/failed` | existing | unchanged from `publishing.service.ts` / `publish.activity.ts:184-199` |
+
+Every state transition and every vote is hash-chained (R8). The chain stays verifiable with the existing `audit_verify_chain` (`001:113-126`) — new events are just new `action` strings; no schema change to `audit_log`. `snapshotHash` in vote/submit diffs ties the chain to `post_versions.content_hash`, so tampering with either side is detectable.
+
+### 10.2 Security notes
+
+- **Tenancy**: every new table has FORCE RLS + the verbatim `tenant_isolation` NULLIF policy + `reject_workspace_change` + `sp_app` grants (§3 step 13). Cross-tenant reads return zero rows even for the app role (`003` rationale).
+- **Enforcement order**: `RbacGuard` (session → epoch → permission) → service-level group-scope/eligibility checks on the tenant client (the `userCanUseConnection` precedent) → DB CHECKs/triggers as the last line. Three layers for the two structural rules that matter most: no self-approval at N≥2, no illegal transition.
+- **Soft delete / hide**: flags only; reads filter `deleted_at IS NULL` in the service (RLS stays pure tenancy — a simple predicate per repo convention, `001:172-179`). Audit rows outlive the rows they describe (`target_id` is text, no FK).
+- **Blind-vote masking is server-side** (§7.2): the client never receives identities it shouldn't, so it can't leak them.
+- **No new transport = no new attack surface**: polling endpoints are ordinary guarded routes; cursors are validated (`parseLimit`); `ord` is an int, not a raw SQL fragment.
+- **Reasons are not secrets** and intentionally survive in audit diffs (`scrub()` only matches secret-ish keys, `audit.service.ts:11-17`); visibility of the chain remains `audit.view`-gated (Approver/Analyst/Owner/Admin, `002`).
+
+---
+
+## 11. Phased implementation plan (deliverable 10)
+
+Each WP ships behind the previous one's test gate; migrations are sequential (`010` here; `011` sweeper indexes if needed; `012` column drop).
+
+| WP | Scope | Test gate |
+|---|---|---|
+| **WP-A: schema** | `010_review_workflow.sql` (all of §3 incl. backfill + transition trigger + seeds); `publishing.service.ts` state union widened; legacy `/approve`,`/reject` kept but routed through the new tables for `required=1`. | Migration applies on a seeded DB; tenancy integration test (mirror `db/tenancy.integration.test.ts`) proves zero cross-tenant rows on all six new tables; `audit_verify_chain` true after backfill; illegal-transition trigger rejects `published→in_review` via direct SQL. |
+| **WP-B: roles & config** | `PATCH /groups/:id/members/:userId {role}` (+ `{token}`), `GET/PUT /workspace/review-settings`, `PATCH /groups/:id` quorum override, `deleteGroup` post-guard; `voteEligibility`. | Role change bumps epoch (session dies, response carries fresh token); config writes are `review.manage`-only (403 for Publisher); preflight rejects quorum-2 submit in a 1-reviewer group. |
+| **WP-C: quorum engine** | `submit` (freeze+preflight+cycle), `POST /drafts/:id/votes`, `/override`, recount trigger hardening (set-based), `meetQuorum` + auto-schedule; same-tx audit + system messages. | Tests 1–5 of §12 green; concurrency test (two racing final votes) yields exactly one transition and ≤1 schedule row. |
+| **WP-D: chat & read models** | `review_messages` endpoints (post + cursor read + masking), `GET /publishing/queue` filters, `GET /publishing/drafts/:id` detail (version, tally, canVote, schedule), `GET /publishing/archive`. | Masking test (open cycle hides identities from non-override holders, closed reveals); cursor pagination stable under concurrent posts; RLS on all reads. |
+| **WP-E: web** | `/approvals` queue + detail (virtualizer, keyboard, vote panel, diff), `/archive` with moderation actions, Compose group picker + submit-only flow + tone map, `useApiResource` interval option, `api-types.ts`. | Keyboard model works with input-guard; vote buttons gated on server `canVote`; offline fixtures render; no `as any` (tsc strict). |
+| **WP-F: sweeper & moderation** | `review_due_expiries()` + scheduler `reviewExpire` activity + `notifications` outbox writes on submit/deny/quorum/expiry/block; hide/unhide/soft-delete endpoints (schedule-cancel-first). | Tests 6–10 of §12 green; hidden scheduled post never publishes; outbox rows written in the same tx as their transition. |
+| **WP-G (later)** | `012` drops `drafts.reviewer_user_id` once web stopped reading it. | Removal of dead code only. |
+
+---
+
+## 12. Test plan sketch (deliverable 11)
+
+1. **Tenancy wall**: as `sp_app` with tenant A context, read `review_votes`, `post_versions`, `review_cycles`, `review_messages`, `review_notifications`, `workspace_review_settings` for a tenant-B id → zero rows; a B-context write is rejected by `WITH CHECK`. (Mirror `db/tenancy.integration.test.ts`.)
+2. **Structural no-self-approval**: quorum-2 workspace, Owner authors and tries to vote → `403 reviewers cannot vote on their own post`; quorum-1 workspace, same action succeeds and the audit diff carries `selfApproved: true`.
+3. **Deny semantics**: deny without reason → `400`; with reason → cycle `denied`, draft `needs_changes`, sibling approve-votes still present in `review_votes` but the next cycle's tally starts at 0; the reason appears in the thread event and the audit chain.
+4. **Concurrent final votes**: two reviewers approve simultaneously (two txs) → exactly one `approved`/`scheduled` transition, one closed cycle, ≤1 `scheduled_publications` row (`UNIQUE(draft_id)` never violated), both votes persisted, chain verifiable.
+5. **Edit-during-review reset**: editor edits an `in_review` draft → new `post_versions` row, old cycle `superseded`, draft `needs_changes`; resubmit opens cycle n+1 with `required` re-snapshotted (change workspace config in between and prove the old cycle's snapshot held).
+6. **Reviewer removed mid-review**: remove the only remaining eligible reviewer of a quorum-2 cycle → same-tx `blocked` + recount; their old vote no longer counts (tally query with them excluded); re-add a reviewer → auto `in_review`; the removed user's session fails with `401` (stale epoch).
+7. **Deadline race both ways**: (a) quorum at `publish_at-60s` → scheduled and published; (b) quorum at `publish_at+60s` → `expired`, and `publishing_due_schedules()` returns nothing for the draft (nothing was ever created); (c) sweeper and a last-instant vote race → one outcome, no double transition.
+8. **Admin override**: override-approve a `blocked` draft with reason → `approved`/`scheduled` and **no** `review_votes` row; audit shows `review.override_granted`; override-deny on a `scheduled` draft cancels the pending schedule row in the same tx.
+9. **Chain & snapshot integrity**: run a full lifecycle (create → submit → vote ×2 → schedule → publish → hide) then `audit_verify_chain(workspace)` = true; every transition/vote has an event; every vote's `snapshot_hash` equals the approved `post_versions.content_hash`.
+10. **Immutability & DB-level state machine**: `UPDATE post_versions …`, `UPDATE review_messages …` → error (append-only); `UPDATE drafts SET workspace_id=…` → `23514` (existing trigger); direct-SQL `published → in_review` → `illegal draft transition` from `trg_drafts_legal_transition`, proving enforcement survives a service bug.
+
+---
+
+## 13. Requirements traceability (R1–R9)
+
+- **R1** — states + resubmit + expired: §4 (rows 2/9/15 close the terminal-`rejected` gap; rows 6/15 + sweeper cover expiry); archived = `published` (§1).
+- **R2** — group roles, editor/reviewer split, structural no-self-approval, admin override: §5.
+- **R3** — quorum config location/precedence/who, parallel any-N, one immutable vote, 1-deny, auto-transition + auto-schedule: §3 step 2, §6.
+- **R4** — frozen snapshots, hash in audit, reviewer sees rendered post + diff: §3 steps 3/5/6, §8.1.
+- **R5** — per-post thread with system events, vote buttons in chat, transport decision: §7.
+- **R6** — queue UI, quorum chips, filters, j/k: §8.1.
+- **R7** — archive view, hide/delete admin-only with new permissions, soft-delete choice, scope = all states: §1, §3 step 4, §8.2, §9 edge case 12.
+- **R8** — RbacGuard, FORCE RLS, `010`, chained events, epoch re-token + vote re-count: §3, §5.4, §10.
+- **R9** — no external notifications built; outbox hook designed (§3 step 8, WP-F); no mobile/per-platform/AI scope anywhere.
+
+---
+
+## 14. Confidence & risks
+
+**Least sure about:**
+
+1. **The recount trigger as written.** `review_recount_group()` is sketched with a loop for readability; the implementation should be set-based (one UPDATE over affected open cycles) and must be load-tested against the epoch trigger firing in the same statement. The subtle risk is trigger ordering inside `groups` mutations: the recount runs *after* `bump_authz_epoch`'s row update but in the same tx, which is what we want, but cascaded deletes (workspace deletion) hit it too — the `blocked` write during a workspace teardown is wasted work at best. Prototype should validate: remove-a-reviewer → blocked, re-add → reopened, all inside the admin's original request.
+2. **The `FOR UPDATE`-on-draft serialization point.** I've made the draft row the single mutex for votes, quorum evaluation, expiry, edits, and `ord` assignment. That's correct but coarse: a hot post with N reviewers serializes fully. If contention shows up, the fix is a dedicated advisory lock or moving the mutex to `review_cycles` — but only measure first; review volume is human-scale.
+3. **Blind voting + system events interplay.** Masking identity in `event_data` server-side is straightforward, but the *denied* case reveals the denier to the author immediately (deliberate — the author needs the reason's context). If a workspace wants anonymous denials too, that's a product decision hiding in what is currently an implementation detail; flag it before WP-C.
+4. **Quorum-1 self-approve carve-out.** Preserving the solo-workspace flow (`compose/page.tsx:128-131`) means the four-eyes guarantee is only real at `≥2`. I've labeled it (UI shows the resolved quorum at submit; audit stamps `selfApproved`), but a stricter reading of R2 would force `≥2` everywhere and break single-user workspaces outright. This is the decision most likely to get overturned in review — it's cheap to flip either way before WP-A.
+5. **`publish_at`/`connection_id` living on the cycle.** It makes "primed to go out" atomic with submission, but it also means a deadline can expire a review that was otherwise progressing (by design, R1). The alternative — deadline as a soft warning until scheduling — contradicts the spec, so I didn't take it, but the UX copy around `expiring soon` matters more than it looks.
+
+**What a prototype should validate first (in order):**
+
+1. Migration `010` on a copy of production-shaped data: backfill row counts, `rejected→needs_changes` rewrite, chain still verifies, old API paths keep working against the new tables (WP-A gate).
+2. The concurrency core: two racing final votes + a racing sweeper — one transition, one schedule row, no lost votes (§12 tests 4 and 7). Everything else in the design is single-transaction logic; this is the only genuinely concurrent part.
+3. Epoch/recount interaction: demote a reviewer with an open cycle and watch session invalidation, re-tally, and `blocked` land atomically (§12 test 6).
+4. Polling ergonomics: 4s cursor polls on a real thread — server load is a non-issue, but check the UI's perceived liveness and the 401→re-auth→resume path after a mid-thread membership change.
+
+---
+
+*End of proposal — `runs/wp5/proposal-glm.md`. Design only; no repo files were modified.*
diff --git a/docs/design/proposal-opus.md b/docs/design/proposal-opus.md
new file mode 100644
index 0000000..ea302d9
--- /dev/null
+++ b/docs/design/proposal-opus.md
@@ -0,0 +1,1667 @@
+# Proposal (lane: opus) — Group Review & Signoff for Posts
+
+Status: design proposal, no code changed
+Date: 2026-10-07
+Answers: `runs/wp5/spec-review-workflow.md` §5 (Q1–Q10) and §6 (parts 1–11)
+
+> **Numbering correction.** The spec asks for migration `009_*`, but `apps/api/migrations/009_video.sql` already exists. This proposal uses **`010_audit_hash_v2.sql`** (a small prerequisite, see §9.2) and **`011_review_workflow.sql`** (the feature).
+
+---
+
+## 0. Pre-existing defects this design depends on (found while reading)
+
+These are real today. The review feature makes each one worse, so each is fixed in WP5.0 (§10):
+
+| # | Where | Defect | Why it matters for review |
+|---|---|---|---|
+| D1 | `apps/scheduler/src/activities/publish.activity.ts:136-139` | `claim()` joins `drafts` but **never checks `d.state`**. It publishes `d.post` (`:141`) for any pending schedule row. | Quorum is only real if the publisher refuses anything that isn't approved, and publishes *the approved bytes*. |
+| D2 | `publish.activity.ts:79` | `claim()` runs outside the `try`, so a "not pending / not found" throw is retried by Temporal (the default retry policy has no limit). | An edit or cancel that removes a pending schedule leaves a workflow retrying forever. |
+| D3 | `001_tenants.sql:92-98,155` | `audit_hash(prev, actor, action, target_id, at)` **excludes `diff`**. | A "snapshot hash in the audit log" (R4) placed in `diff` is **not tamper-evident**. Only ordering and actor are chained. |
+| D4 | `apps/api/src/publishing/publishing.service.ts:136,175,181,307-322` | Audit is written **after commit** (`appendTenantAudit` opens its own tx, `audit.service.ts:29-37`). | A crash between a state change and its audit loses the audit row. Votes need same-tx audit, as `groups.service.ts:12-13,123-133` already does. |
+| D5 | `apps/api/src/publishing/publishing.controller.ts:113-129` + `rbac.guard.ts:64-74` | `schedule` takes `connectionId` from the **body**. `@RequireGroupAccess` only reads `:connectionId` **params**, and `schedule` doesn't use it anyway. | A non-admin can schedule through a connection outside their groups. Group-scoped review has to close this. |
+| D6 | `apps/api/src/realtime/gateway.ts:20-21,24-29` | It compares the epoch against the raw `bigint` (a string from node-postgres, so it is always "stale"). Its permission query omits `m.status = 'active'`. | This is a reason **not** to build chat on this port (Q4). |
+| D7 | `apps/web/src/lib/api-client.ts:90` + `rbac.guard.ts:46-48` | Any epoch bump (every `group_members` change, `008_groups.sql:79-80`) gives **every** user in the workspace a 401, and the client drops the token. No re-issue path exists. | Changing review roles mid-review would log reviewers out mid-vote (§8, E7). |
+| D8 | `002_rbac_seed.sql:9,25,35` | `publication.delete` is seeded to Owner, Admin, and **Publisher**, and nothing enforces it. | R7 says delete is admin-only, so this permission can't be reused (§4.1). |
+
+---
+
+## Q. Answers to the 10 open design questions (spec §5)
+
+### Q1 — Group-scoped role storage
+**Decision: one `review_role` column on `group_members`**, `text NOT NULL DEFAULT 'member' CHECK (review_role IN ('member','editor','reviewer'))`.
+
+**Justification.** A single value makes editor and reviewer **mutually exclusive by construction**, which is exactly the separation of duties in R2. A multi-role `group_member_roles` table would allow someone to be both "editor" and "reviewer", and every eligibility query would need to re-forbid that. The column also inherits everything 008 already built: the row is pinned to one tenant by composite FKs (`008_groups.sql:35-37`), RLS (`:94-96`), the workspace-immutability trigger (`:68-69`), cascade-on-leave (`:37`), and **the epoch bump, because `trg_group_member_bump_epoch` already fires on `UPDATE` (`:79-80`)**. A role change is therefore fenced exactly like a membership change, with zero new trigger code. Reusing workspace roles alone is impossible, because `memberships` is `UNIQUE(workspace_id, user_id)` with one role (`001_tenants.sql:20-27`). Workspace roles stay the *floor* (you need `draft.view` to hold any review role, §4.2).
+*Future:* if multi-role is ever needed (e.g. "reviewer in tier 2 only"), move to a table and keep the column as a view.
+
+### Q2 — Snapshot model
+**Decision: immutable `draft_versions` rows that hold a full canonical content copy *and* a DB-computed SHA-256 `content_hash`.** A version is created only at *seal points*: submit, edit-while-sealed, and admin restart. Saves in `editing` / `changes_requested` mutate `drafts.post` and do not create versions.
+
+**Justification.** Post payloads are tiny: `DraftPost` is text, asset ids, visibility, scheduledAt, and metadata (`publishing.service.ts:10-16`). Full copies cost almost nothing, while hash-only versions would make the "diff since last review" view (R4) impossible after the working copy moves on. The hash is computed **in SQL** from `jsonb::text`, which is deterministic for `jsonb`, by a BEFORE INSERT trigger. The app can't supply a wrong hash, and a trigger keeps it from ever changing. Keeping the hash separate from the content lets an admin **purge** content (R7) while the hash, vote bindings, and audit stay verifiable. Every vote row copies the hash it approved, and the publisher sends `draft_versions.content` for `approved_version_id`, never `drafts.post` (fixes D1). What reviewers approved is byte-for-byte what ships.
+
+### Q3 — Quorum config location and precedence
+**Decision: a `review_policies` table with at most one workspace row (`group_id IS NULL`) and at most one row per group.** Precedence is **group row → workspace row → built-in default**, and the first row found wins *as a whole* (no field merging). The built-in default is `required_approvals = 1, exempt_roles = {Owner,Admin}, blind_votes = true, stale_after = 30 days, min_lead = 2 min`. Only `approval.configure` (Owner and Admin, new) may write a policy. **The effective policy is captured onto each version at seal time** (`required_approvals`, `policy_source`, `blind_votes`, `deadline_at`).
+
+**Justification.** "Group" is the unit that has reviewers, so it has to be able to override. The workspace row gives admins one knob for everything without a group. Whole-row precedence is easy to explain in the UI ("this group uses its own policy"), while field-level merging creates surprising combinations. Capture-at-seal makes a round's contract fixed: lowering N can't silently push a pending post over the line, and raising N can't strand one. Admins apply a new policy to a live round explicitly with **restart review** (§3). The built-in default reproduces today's behaviour exactly (Q9): Publisher drafts need one approver who isn't the author, and Owner/Admin drafts go straight through as they do today via the compose chain (`compose/page.tsx:119-141`). This works **without seeding rows**, which would fight FORCE RLS in a migration.
+*Future:* per-connection overrides (e.g. "brand account needs 3"), as a third precedence tier.
+
+### Q4 — Chat transport
+**Decision: SSE for invalidation ("doorbells") plus REST for data, fanned out with Postgres `LISTEN/NOTIFY`.** The client's SSE reader is `fetch`-based so it can send `Authorization: Bearer`. Polling the same REST endpoints is the automatic fallback.
+
+**Justification.**
+- **Cost and complexity.** SSE is a plain Nest HTTP route (`@Sse()` returning an Observable), so it goes through the **existing `RbacGuard`** with its correct epoch normalisation (`rbac.guard.ts:42-48`) and active-membership check. WS would need `@nestjs/websockets`, a new adapter, sticky routing, and the buggy `gateway.ts` port (D6). Every write (vote, comment) is already a guarded REST call, so a bidirectional channel adds nothing. The API is bearer-only with no cookies (`apps/api/src/main.ts:15-20`), so the browser's `EventSource` can't authenticate. A ~60-line `fetch` + `ReadableStream` SSE reader in `apps/web/src/lib/` can.
+- **Ordering.** The stream carries no content, only `{draftId, kind, seq}`. Ordering lives in the DB: chat rows get a **gapless, commit-ordered per-draft `seq`**, allocated under the draft row lock (§6.1). Clients fetch `?after=<seq>`, so a lost or duplicated doorbell is harmless and reconnects need no `Last-Event-ID`.
+- **AuthZ.** `NOTIFY` is sent on commit, so there are no phantom events. The payload holds only ids, so RLS is never bypassed. Each stream caches the user's visible group ids, which is safe **because any group or role change bumps the epoch**: the stream sees the bump on its next doorbell or heartbeat, sends `event: reauth`, and closes.
+- **Polling** is the same `GET .../messages?after=` and `GET /publishing/queue`. The client switches after 3 failed reconnects, with zero extra server code.
+
+### Q5 — Deny semantics
+**Decision: one deny vetoes the round.** The draft goes `in_review → changes_requested`, and the version's `outcome = 'changes_requested'`. Other live approvals on that version are kept as history but **can never count again**, because they are bound to a version that is now closed. A resubmit always seals a new version (even with byte-identical content) and starts at 0/N. Deny needs a reason that isn't empty, enforced at three layers: DTO, service, and a DB `CHECK`.
+
+**Justification.** Four-eyes exists to stop bad posts. Under majority-deny, a post with a *known, reasoned* objection would ship anyway. A single deny is cheap to resolve: the reason lands in the chat, and the author edits or replies, then resubmits. Starting a resubmit from zero, even with unchanged content, means a deny can't be "outvoted" by quietly resubmitting. The denying reviewer still has to approve or deny again, in the open. This mirrors Hootsuite and Sprout, where rejection returns the post to the author.
+*Future:* `deny_threshold` on `review_policies`, for very large reviewer pools where one hostile reviewer could stall everything.
+
+### Q6 — Re-review after edit
+**Decision: full reset.** Any change to sealed content (text, media, visibility, `scheduledAt`, target connection) by an author, editor, or admin in `in_review`, `approved`, or `scheduled` (pending) seals version *n+1* and opens a new round at 0/N. A pending schedule is cancelled in the same tx. The draft stays or returns to `in_review`, and a system chat event lists the dismissed approvers with a diff link.
+
+**Justification.** "Approve a frozen snapshot, not a moving target" is the compliance core of R4. Scope-aware dismissal ("only a typo changed") needs a semantic diff policy that is hard to get right, and is precisely the loophole maker-checker rules close. Because dismissal is **explicit and visible** (chat event, audit event, notification hook to dismissed voters), the spec's worry about edits "silently" invalidating approvals is met: approvals are invalidated *loudly*.
+*Future:* `dismiss_scope` policy, for example keeping votes when only `scheduledAt` moves later.
+
+### Q7 — Scheduled-time race (quorum at T-1min)
+**Decision: auto-publish, no manual re-confirm.** The approved version includes `scheduledAt`, so reviewers approved *that content at that time*. When quorum completes before the deadline, the same tx inserts the `scheduled_publications` row (`publish_at = scheduledAt`), and the workflow starts after commit with the remaining delay. The race is settled by a **row lock plus `clock_timestamp()`**. Vote, expiry, and edit all take `SELECT … FOR UPDATE` on the draft. A vote that finds `clock_timestamp() >= deadline_at` **expires the draft itself and returns 409 `REVIEW_EXPIRED`**. Submissions must have `scheduledAt ≥ now() + min_lead` (2 min by default).
+
+**Justification.** A re-confirm step puts a human on the critical path at the worst moment and turns many valid approvals into expiries. Re-confirming adds no safety, since the content and time were already sealed and approved. Author and admin keep the existing cancel (`publishing.service.ts:248-273`) right up to claim. Correctness never depends on sweeper latency: the vote-time check and the claim gate (D1 fix) both enforce the deadline.
+
+### Q8 — Author is the only reviewer (deadlock)
+**Decision: submission is allowed and the deadlock is surfaced, not hidden.**
+1. At seal, the service computes `eligible` (`review_eligible_reviewers`, §5.2). If `eligible < required`, the round is flagged `reachable=false`. The UI shows a red banner ("Quorum unreachable: 0 eligible / 2 required"), the chat gets a `quorum_unreachable` event, and the notifier hook fires to Owner/Admin.
+2. There are three resolution paths, all audited:
+   - **(a)** An admin adds a reviewer to the group. Eligibility is computed live, so the round becomes reachable with no restart.
+   - **(b)** An admin who **did not contribute to the draft** uses **override approve** (`approval.override`, reason mandatory, `review.override_approved`).
+   - **(c)** An admin changes the group policy (`required_approvals = 0`, or adds an exempt role) and then **restarts review**, which recaptures the policy.
+3. A sole Owner who authored the draft can never override their own draft (contributors are excluded structurally). Their path is (c), an explicit, audited policy choice. Owner/Admin are exempt by default under the built-in policy, so solo workspaces work out of the box.
+
+**Justification.** Refusing submission would block discussion in chat and hide the cause. Auto-lowering N to `eligible` would silently weaken four-eyes. Every way out is visible, attributable, and needs someone other than the author, except the policy change, which is itself a logged governance act.
+
+### Q9 — Migrating existing single-step approvals
+**Decision: backfill in `011_review_workflow.sql`, per workspace under `set_config('app.workspace_id', …, true)`, before the guard triggers are created.**
+
+| legacy state | new state | version 1 | vote rows |
+|---|---|---|---|
+| `editing` | `editing` | none | none |
+| `in_review` | `in_review` | content = current post; `required=1`; `policy_source='default'`; `deadline_at = migration time + 30d` (legacy `scheduledAt` was advisory) | none |
+| `approved` / `scheduled` / `published` | unchanged | `outcome='approved'`; `approved_version_id = current_version_id` | `approve` by `reviewer_user_id`, `source='migrated'` |
+| `rejected` | **`changes_requested`** | `outcome='changes_requested'` | `deny` by `reviewer_user_id`; reason taken from the last `audit_log` row `action='draft.rejected'` for that draft (`publishing.service.ts:199-203` put it only there), else the literal `'Migrated from single-step review; original reason unavailable.'` |
+
+`connection_id` is backfilled from `scheduled_publications.connection_id`, else from `post->'providerMetadata'->>'connectionId'` (what compose writes, `compose/page.tsx:126`), but only if that id exists in the same workspace. `draft_contributors` gets the author. Legacy drafts where the author approved their own post (possible today through the compose chain) are **kept as-is** and counted in a per-workspace `review.migrated` audit row (`{drafts, versions, votes, selfApproved}`). They are history, not blocked. `drafts.reviewer_user_id` stays, read-only and deprecated (no longer written), and is dropped in a later migration once the web no longer reads it (`api-types.ts:81`).
+
+**Justification.** Every published post gets a provable version and approval record. `rejected` stops being a dead end (spec §2.1). Doing it inside the migration, *before* the triggers exist, avoids a bypass flag that `sp_app` could also set.
+
+### Q10 — Blind voting vs peer visibility
+**Decision: blind until your own vote or until the round closes; configurable through `review_policies.blind_votes` (default `true`).** Everyone sees the **count** ("1/3"). An eligible reviewer who hasn't voted sees approvals as "A reviewer approved" with no name. Identities appear once they vote, or for everyone once the round closes (approved, changes requested, expired, superseded). Authors, editors, and admins always see identities. Denies are never blind, because a deny closes the round.
+
+**Justification.** The research names rubber-stamping as the failure mode of multi-approver flows, and seeing two senior names on a post is the strongest anchor there is. Blind-until-voted keeps the collaborative chat (reviewers can talk; nothing is secret after they commit) without anchoring the decision itself. Redaction happens **server-side** in the messages and detail serializers, never in the client. **Stated limit:** this is a UX property, not a security property. The workspace `Approver` role has `audit.view` (`002_rbac_seed.sql:48-49`), and the audit page shows `review.vote_cast` actors. That leak is accepted and documented.
+
+---
+
+## 1. Executive summary — the 5 sharpest decisions
+
+1. **What ships is exactly what was approved, enforced in the database.** Content is sealed into immutable, hash-stamped `draft_versions`. Votes bind to a `versionId` and its hash, and a stale `versionId` returns 409. The scheduler publishes `draft_versions.content` of `approved_version_id` and refuses anything else. A `drafts` trigger refuses state transitions not in the table, refuses `approved` without a closed quorum, and refuses content changes to sealed drafts that don't seal a new version.
+2. **Separation of duties is structural, not by convention.** The group role is a single exclusive column (`member | editor | reviewer`). Eligibility excludes the author, every content contributor, and every sealer of the draft, through one SQL function used by the service, the vote trigger, and the quorum count. Admin override is a separate, reason-required action that **contributors can't use**.
+3. **Seven states, with `rejected` replaced by a resubmittable `changes_requested` and a new `expired`.** `archived` is a *derived* view of `published` plus read-only, not a new state, so the scheduler stays the only writer of terminal publication state.
+4. **Any-N-of-group-reviewers, a single-deny veto, and full reset on edit, with quorum policy captured at seal.** One SQL function computes approvals, eligibility, and the requirement live. Removing a reviewer revokes their pending votes through a trigger, under a fixed lock order (authz rows → draft → votes/messages) that prevents a deadlock this design would otherwise create (§5.6).
+5. **SSE doorbells, REST data, `LISTEN/NOTIFY` fan-out, and epoch-fenced streams.** This needs no new deps and no WS port. Chat ordering comes from a per-draft gapless `seq` allocated under the draft row lock. Epoch churn is made survivable by a `POST /auth/reissue` that re-reads live authz (fixes D7), so a role change no longer logs reviewers out mid-vote.
+
+---
+
+## 2. Data model
+
+### 2.1 Overview
+
+| object | kind | purpose |
+|---|---|---|
+| `group_members.review_role` | column | Q1: `member` / `editor` / `reviewer`, mutually exclusive |
+| `drafts.group_id, connection_id, bundle_id, revision, current_version_id, approved_version_id, chat_seq, hidden_*, deleted_*` | columns | group scoping, sealed target, optimistic concurrency, version pointers, chat ordering, moderation |
+| `draft_versions` | table, immutable | Q2: sealed snapshots, DB-computed hash, captured policy, outcome |
+| `draft_contributors` | table | everyone who ever changed content (self-approval exclusion beyond the author) |
+| `review_votes` | table, append-only except revoke/redact | one live vote per reviewer per version |
+| `review_policies` | table | Q3: workspace row plus per-group override |
+| `review_messages` | table, append-only except redaction | R5: comments plus system events, gapless per-draft `seq` |
+| `review_*` functions | SQL/plpgsql | eligibility, quorum, capabilities, policy; one source of truth for service, guard, and triggers |
+| guard triggers | plpgsql | DB-enforced state machine, sealing, vote rules (defence in depth, spec §3) |
+| `review_due_expiries()` | SECURITY DEFINER | sweeper discovery across tenants, mirroring `publishing_due_schedules()` (`006_publishing.sql:79-85`) |
+
+Conventions followed, each matching an existing file:
+- Every new table carries `workspace_id` and composite FKs (`008_groups.sql:4-12`).
+- `reject_workspace_change()` triggers (`001_tenants.sql:164-171`).
+- `ENABLE` + `FORCE ROW LEVEL SECURITY` with the exact `tenant_isolation` policy text (`006_publishing.sql:51-66`).
+- Explicit `sp_app` grants (`006_publishing.sql:68`).
+- SECURITY DEFINER functions with `SET search_path = public`, `REVOKE ALL … FROM PUBLIC`, `GRANT EXECUTE … TO sp_app` (`006_publishing.sql:72-89`).
+- Audit only through `audit_append` (`001_tenants.sql:100-121`).
+
+### 2.2 `010_audit_hash_v2.sql` (prerequisite, fixes D3)
+
+```sql
+-- 010: audit chain v2 — the row hash now covers diff, so values recorded in
+-- diff (content hashes, vote decisions, policy before/after) are tamper-evident.
+-- v1 rows keep verifying with the v1 formula; every new row is v2.
+ALTER TABLE audit_log ADD COLUMN hash_version smallint NOT NULL DEFAULT 1
+  CHECK (hash_version IN (1, 2));
+
+CREATE FUNCTION audit_hash_v2(p_prev text, p_actor uuid, p_action text, p_target_id text,
+                              p_at timestamptz, p_diff jsonb)
+RETURNS text LANGUAGE sql IMMUTABLE AS $$
+  SELECT encode(digest(
+    coalesce(p_prev, '') || '|' || coalesce(p_actor::text, '') || '|' ||
+    p_action || '|' || p_target_id || '|' || extract(epoch FROM p_at)::text || '|' ||
+    coalesce(p_diff::text, ''),            -- jsonb::text is canonical (sorted keys)
+    'sha256'), 'hex')
+$$;
+
+-- Same signature, same SECURITY DEFINER + tenant assertion as 001; only the hash changes.
+CREATE OR REPLACE FUNCTION audit_append(
+  p_workspace_id uuid, p_actor_user_id uuid, p_actor_role text, p_action text,
+  p_target_type text, p_target_id text, p_diff jsonb DEFAULT NULL
+) RETURNS uuid
+LANGUAGE plpgsql SECURITY DEFINER SET search_path = public AS $$
+DECLARE
+  v_id uuid; v_prev text; v_hash text; v_now timestamptz := clock_timestamp();
+BEGIN
+  PERFORM fn_assert_tenant(p_workspace_id);
+  -- Serialise appends per workspace: two concurrent READ COMMITTED appends could
+  -- otherwise read the same head and fork the chain (§9.2). Released at commit.
+  PERFORM pg_advisory_xact_lock(hashtext('audit:' || p_workspace_id::text));
+  SELECT hash INTO v_prev FROM audit_log
+   WHERE workspace_id = p_workspace_id ORDER BY seq DESC LIMIT 1;
+  v_hash := audit_hash_v2(v_prev, p_actor_user_id, p_action, p_target_id, v_now, p_diff);
+  INSERT INTO audit_log (workspace_id, actor_user_id, actor_role, action, target_type, target_id,
+                         diff, at, prev_hash, hash, hash_version)
+  VALUES (p_workspace_id, p_actor_user_id, p_actor_role, p_action, p_target_type, p_target_id,
+          p_diff, v_now, v_prev, v_hash, 2)
+  RETURNING id INTO v_id;
+  RETURN v_id;
+END $$;
+
+-- audit_append_system: identical change (v2 hash, hash_version 2, advisory lock on 'audit:system'),
+-- body otherwise as 001_tenants.sql:123-144.
+
+CREATE OR REPLACE FUNCTION audit_verify_chain(p_workspace_id uuid DEFAULT NULL) RETURNS boolean
+LANGUAGE plpgsql STABLE SECURITY DEFINER SET search_path = public AS $$
+DECLARE r record; v_prev text := NULL;
+BEGIN
+  FOR r IN SELECT * FROM audit_log
+            WHERE workspace_id IS NOT DISTINCT FROM p_workspace_id
+            ORDER BY seq ASC LOOP
+    IF r.prev_hash IS DISTINCT FROM v_prev THEN RETURN false; END IF;
+    IF CASE r.hash_version
+         WHEN 1 THEN audit_hash(r.prev_hash, r.actor_user_id, r.action, r.target_id, r.at)
+         ELSE audit_hash_v2(r.prev_hash, r.actor_user_id, r.action, r.target_id, r.at, r.diff)
+       END <> r.hash THEN
+      RETURN false;
+    END IF;
+    v_prev := r.hash;
+  END LOOP;
+  RETURN true;
+END $$;
+```
+
+Callers are unchanged: `appendTenantAudit` (`audit.service.ts:29-37`), `groups.service.ts:123-133`, and the scheduler's direct `audit_append` calls (`publish.activity.ts:186-188,200-203`) all keep the same signature.
+
+### 2.3 `011_review_workflow.sql`
+
+```sql
+-- 011: group review & signoff. Sections:
+--   1 columns   2 tables   3 indexes   4 immutability   5 RLS/grants
+--   6 pure functions   7 backfill (BEFORE guard triggers exist)
+--   8 guard triggers   9 vote reconciliation   10 group-delete guard
+--   11 notify   12 sweeper discovery   13 permissions
+
+-- ── 1. columns ────────────────────────────────────────────────────────────
+ALTER TABLE drafts ADD CONSTRAINT drafts_id_workspace_key UNIQUE (id, workspace_id);
+
+ALTER TABLE group_members
+  ADD COLUMN review_role text NOT NULL DEFAULT 'member'
+    CHECK (review_role IN ('member', 'editor', 'reviewer'));
+-- ADD COLUMN does not fire row triggers: no epoch bump at migration time.
+
+ALTER TABLE drafts
+  ADD COLUMN group_id uuid,
+  ADD COLUMN connection_id uuid,
+  ADD COLUMN bundle_id uuid,                       -- sibling drafts from one compose action (UI grouping only)
+  ADD COLUMN revision integer NOT NULL DEFAULT 0,  -- bumped on every content save (optimistic concurrency)
+  ADD COLUMN current_version_id uuid,
+  ADD COLUMN approved_version_id uuid,
+  ADD COLUMN chat_seq bigint NOT NULL DEFAULT 0,
+  ADD COLUMN hidden_at timestamptz,
+  ADD COLUMN hidden_by uuid REFERENCES users(id),
+  ADD COLUMN hidden_reason text,
+  ADD COLUMN deleted_at timestamptz,
+  ADD COLUMN deleted_by uuid REFERENCES users(id),
+  ADD COLUMN deleted_reason text,
+  -- PG15+ column-list SET NULL: only group_id/connection_id are nulled, workspace_id stays.
+  ADD CONSTRAINT drafts_group_fk FOREIGN KEY (group_id, workspace_id)
+    REFERENCES groups(id, workspace_id) ON DELETE SET NULL (group_id),
+  ADD CONSTRAINT drafts_connection_fk FOREIGN KEY (connection_id, workspace_id)
+    REFERENCES connections(id, workspace_id) ON DELETE SET NULL (connection_id),   -- 008_groups.sql:15
+  ADD CONSTRAINT drafts_hidden_consistent CHECK (
+    (hidden_at IS NULL AND hidden_by IS NULL AND hidden_reason IS NULL)
+    OR (hidden_at IS NOT NULL AND hidden_by IS NOT NULL AND btrim(coalesce(hidden_reason, '')) <> '')),
+  ADD CONSTRAINT drafts_deleted_consistent CHECK (
+    (deleted_at IS NULL AND deleted_by IS NULL AND deleted_reason IS NULL)
+    OR (deleted_at IS NOT NULL AND deleted_by IS NOT NULL AND btrim(coalesce(deleted_reason, '')) <> ''));
+
+-- State set: 'rejected' -> 'changes_requested', + 'expired'. Data is remapped per
+-- tenant in section 7 (FORCE RLS: an owner-level UPDATE without app.workspace_id
+-- would silently match nothing for a non-superuser owner).
+ALTER TABLE drafts DROP CONSTRAINT drafts_state_check;   -- 006_publishing.sql:7-8 (auto-named)
+
+-- ── 2. tables ─────────────────────────────────────────────────────────────
+CREATE TABLE draft_versions (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  version_no integer NOT NULL CHECK (version_no >= 1),
+  content jsonb,                               -- review_content(post, connectionId); NULL only after purge
+  content_hash text NOT NULL,                  -- set by trigger from content; never changes
+  sealed_by uuid NOT NULL REFERENCES users(id),
+  sealed_at timestamptz NOT NULL DEFAULT now(),
+  seal_kind text NOT NULL CHECK (seal_kind IN ('submit', 'edit', 'reopen', 'migrated')),
+  review_mode text NOT NULL CHECK (review_mode IN ('quorum', 'exempt', 'none')),
+  required_approvals smallint NOT NULL CHECK (required_approvals BETWEEN 0 AND 5),
+  policy_source text NOT NULL CHECK (policy_source IN ('group', 'workspace', 'default')),
+  blind_votes boolean NOT NULL,
+  deadline_at timestamptz NOT NULL,            -- LEAST(post.scheduledAt, sealed_at + stale_after)
+  outcome text CHECK (outcome IN ('approved', 'changes_requested', 'superseded', 'withdrawn',
+                                  'expired', 'overridden', 'exempt')),
+  outcome_at timestamptz,
+  outcome_by uuid REFERENCES users(id),        -- NULL = system
+  purged_at timestamptz,
+  UNIQUE (draft_id, version_no),
+  UNIQUE (id, draft_id, workspace_id),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE,
+  CHECK ((content IS NULL) = (purged_at IS NOT NULL)),
+  CHECK ((outcome IS NULL) = (outcome_at IS NULL))
+);
+
+ALTER TABLE drafts
+  ADD CONSTRAINT drafts_current_version_fk FOREIGN KEY (current_version_id, id, workspace_id)
+    REFERENCES draft_versions(id, draft_id, workspace_id),
+  ADD CONSTRAINT drafts_approved_version_fk FOREIGN KEY (approved_version_id, id, workspace_id)
+    REFERENCES draft_versions(id, draft_id, workspace_id);
+
+CREATE TABLE draft_contributors (
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  user_id uuid NOT NULL REFERENCES users(id),
+  first_contributed_at timestamptz NOT NULL DEFAULT now(),
+  last_contributed_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (draft_id, user_id),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE
+);
+
+CREATE TABLE review_votes (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  version_id uuid NOT NULL,
+  reviewer_user_id uuid NOT NULL REFERENCES users(id),
+  decision text NOT NULL CHECK (decision IN ('approve', 'deny')),
+  reason text CHECK (reason IS NULL OR char_length(reason) <= 2000),
+  content_hash text NOT NULL,                  -- copied from the version by trigger: what was approved
+  source text NOT NULL DEFAULT 'cast' CHECK (source IN ('cast', 'migrated')),
+  cast_at timestamptz NOT NULL DEFAULT now(),
+  revoked_at timestamptz,
+  revoke_cause text CHECK (revoke_cause IN ('retracted', 'membership_changed', 'role_changed')),
+  reason_redacted_at timestamptz,
+  FOREIGN KEY (version_id, draft_id, workspace_id)
+    REFERENCES draft_versions(id, draft_id, workspace_id) ON DELETE CASCADE,
+  -- R3: deny requires a reason (unless purged afterwards).
+  CHECK (decision <> 'deny' OR reason_redacted_at IS NOT NULL OR btrim(coalesce(reason, '')) <> ''),
+  CHECK ((revoked_at IS NULL) = (revoke_cause IS NULL)),
+  CHECK (revoke_cause IS DISTINCT FROM 'retracted' OR decision = 'approve')  -- only approvals are retractable
+);
+CREATE UNIQUE INDEX review_votes_one_live ON review_votes (version_id, reviewer_user_id)
+  WHERE revoked_at IS NULL;
+
+CREATE TABLE review_policies (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  group_id uuid,                                -- NULL = workspace default row
+  required_approvals smallint NOT NULL CHECK (required_approvals BETWEEN 0 AND 5),
+  exempt_roles text[] NOT NULL DEFAULT '{}',    -- validated against role_permissions by the service
+  blind_votes boolean NOT NULL DEFAULT true,
+  stale_after interval NOT NULL DEFAULT '30 days'
+    CHECK (stale_after BETWEEN interval '1 hour' AND interval '90 days'),
+  min_lead interval NOT NULL DEFAULT '2 minutes'
+    CHECK (min_lead BETWEEN interval '0' AND interval '1 day'),
+  updated_by uuid REFERENCES users(id) ON DELETE SET NULL,
+  updated_at timestamptz NOT NULL DEFAULT now(),
+  FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id) ON DELETE CASCADE
+);
+CREATE UNIQUE INDEX review_policies_workspace ON review_policies (workspace_id) WHERE group_id IS NULL;
+CREATE UNIQUE INDEX review_policies_group ON review_policies (group_id) WHERE group_id IS NOT NULL;
+
+CREATE TABLE review_messages (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  workspace_id uuid NOT NULL,
+  draft_id uuid NOT NULL,
+  seq bigint NOT NULL,                          -- assigned by trigger under the draft row lock
+  kind text NOT NULL CHECK (kind IN ('comment', 'event')),
+  author_user_id uuid REFERENCES users(id),     -- NULL for system events
+  client_message_id uuid,                       -- idempotent retries after re-auth (§8 E7)
+  version_id uuid,                              -- version the message refers to ("on v3")
+  body text CHECK (body IS NULL OR char_length(body) BETWEEN 1 AND 4000),
+  event_type text,
+  event jsonb,
+  created_at timestamptz NOT NULL DEFAULT now(),
+  redacted_at timestamptz,
+  redacted_by uuid REFERENCES users(id),
+  UNIQUE (draft_id, seq),
+  UNIQUE (draft_id, client_message_id),
+  FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE CASCADE,
+  FOREIGN KEY (version_id, draft_id, workspace_id)
+    REFERENCES draft_versions(id, draft_id, workspace_id),     -- MATCH SIMPLE: NULL version allowed
+  CHECK (
+    (kind = 'comment' AND author_user_id IS NOT NULL AND event_type IS NULL AND event IS NULL
+       AND (body IS NOT NULL OR redacted_at IS NOT NULL))
+    OR (kind = 'event' AND author_user_id IS NULL AND event_type IS NOT NULL AND event IS NOT NULL
+       AND body IS NULL))
+);
+
+-- ── 3. indexes ────────────────────────────────────────────────────────────
+CREATE INDEX drafts_queue ON drafts (workspace_id, state, updated_at DESC, id DESC)
+  WHERE deleted_at IS NULL;
+CREATE INDEX drafts_group_state ON drafts (group_id, state) WHERE group_id IS NOT NULL;
+CREATE INDEX drafts_bundle ON drafts (bundle_id) WHERE bundle_id IS NOT NULL;
+CREATE INDEX draft_versions_open_deadline ON draft_versions (deadline_at) WHERE outcome IS NULL;
+CREATE INDEX review_votes_live_version ON review_votes (version_id) WHERE revoked_at IS NULL;
+CREATE INDEX review_votes_reviewer ON review_votes (workspace_id, reviewer_user_id, cast_at DESC);
+CREATE INDEX group_members_reviewers ON group_members (group_id) WHERE review_role = 'reviewer';
+
+-- ── 4. workspace immutability (001_tenants.sql:164-171) ──────────────────────
+CREATE TRIGGER trg_draft_version_ws_immutable BEFORE UPDATE ON draft_versions
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_draft_contributor_ws_immutable BEFORE UPDATE ON draft_contributors
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_vote_ws_immutable BEFORE UPDATE ON review_votes
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_policy_ws_immutable BEFORE UPDATE ON review_policies
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+CREATE TRIGGER trg_review_message_ws_immutable BEFORE UPDATE ON review_messages
+  FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+
+-- ── 5. RLS + grants ───────────────────────────────────────────────────────
+ALTER TABLE draft_versions ENABLE ROW LEVEL SECURITY;
+ALTER TABLE draft_contributors ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_votes ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_policies ENABLE ROW LEVEL SECURITY;
+ALTER TABLE review_messages ENABLE ROW LEVEL SECURITY;
+ALTER TABLE draft_versions FORCE ROW LEVEL SECURITY;
+ALTER TABLE draft_contributors FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_votes FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_policies FORCE ROW LEVEL SECURITY;
+ALTER TABLE review_messages FORCE ROW LEVEL SECURITY;
+
+CREATE POLICY tenant_isolation ON draft_versions
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON draft_contributors
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_votes
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_policies
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+CREATE POLICY tenant_isolation ON review_messages
+  USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+  WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+
+GRANT SELECT, INSERT, UPDATE ON draft_versions, draft_contributors, review_votes,
+  review_policies, review_messages TO sp_app;
+GRANT DELETE ON review_policies TO sp_app;     -- deleting a group row = "inherit workspace policy"
+-- 003_app_role.sql:16-17 default privileges grant DELETE on every new table;
+-- history tables are append-only for the app. FK cascades (workspace deletion)
+-- run as the table owner and are unaffected.
+REVOKE DELETE ON draft_versions, draft_contributors, review_votes, review_messages FROM sp_app;
+REVOKE DELETE ON drafts FROM sp_app;          -- drafts are tombstoned, never hard-deleted (§7.4)
+
+-- ── 6. pure functions (SECURITY INVOKER: run under the caller's RLS) ─────────
+CREATE FUNCTION review_content(p_post jsonb, p_connection_id uuid) RETURNS jsonb
+LANGUAGE sql IMMUTABLE AS $$
+  SELECT jsonb_build_object('post', p_post, 'connectionId', p_connection_id)
+$$;
+
+CREATE FUNCTION review_content_hash(p_content jsonb) RETURNS text
+LANGUAGE sql IMMUTABLE AS $$
+  SELECT encode(digest(p_content::text, 'sha256'), 'hex')
+$$;
+
+CREATE FUNCTION review_effective_policy(p_workspace_id uuid, p_group_id uuid)
+RETURNS TABLE(required_approvals smallint, exempt_roles text[], blind_votes boolean,
+              stale_after interval, min_lead interval, source text)
+LANGUAGE sql STABLE AS $$
+  SELECT p.required_approvals, p.exempt_roles, p.blind_votes, p.stale_after, p.min_lead, p.source
+  FROM (
+    SELECT rp.required_approvals, rp.exempt_roles, rp.blind_votes, rp.stale_after, rp.min_lead,
+           'group'::text AS source, 1 AS rank
+      FROM review_policies rp WHERE p_group_id IS NOT NULL AND rp.group_id = p_group_id
+    UNION ALL
+    SELECT rp.required_approvals, rp.exempt_roles, rp.blind_votes, rp.stale_after, rp.min_lead,
+           'workspace', 2
+      FROM review_policies rp WHERE rp.workspace_id = p_workspace_id AND rp.group_id IS NULL
+    UNION ALL
+    SELECT 1::smallint, ARRAY['Owner', 'Admin']::text[], true, interval '30 days', interval '2 minutes',
+           'default', 3
+  ) p
+  ORDER BY p.rank
+  LIMIT 1
+$$;
+
+-- Who may vote on this draft's CURRENT round. Single source of truth for the
+-- service, review_vote_guard, review_quorum and review_capabilities.
+CREATE FUNCTION review_eligible_reviewers(p_draft_id uuid) RETURNS TABLE(user_id uuid)
+LANGUAGE sql STABLE AS $$
+  SELECT m.user_id
+  FROM drafts d
+  JOIN memberships m ON m.workspace_id = d.workspace_id AND m.status = 'active'
+  WHERE d.id = p_draft_id
+    AND m.user_id <> d.author_user_id
+    AND NOT EXISTS (SELECT 1 FROM draft_contributors c
+                    WHERE c.draft_id = d.id AND c.user_id = m.user_id)
+    AND NOT EXISTS (SELECT 1 FROM draft_versions v
+                    WHERE v.draft_id = d.id AND v.sealed_by = m.user_id
+                      AND v.seal_kind IN ('submit', 'edit'))
+    AND CASE
+      WHEN d.group_id IS NULL THEN EXISTS (           -- legacy workspace draft: approval.grant holders
+        SELECT 1 FROM role_permissions rp
+        WHERE rp.role = m.role AND rp.permission = 'approval.grant')
+      ELSE EXISTS (                                   -- group draft: group reviewers with the draft.view floor
+        SELECT 1 FROM group_members gm
+        WHERE gm.group_id = d.group_id AND gm.user_id = m.user_id AND gm.review_role = 'reviewer')
+        AND EXISTS (SELECT 1 FROM role_permissions rp
+                    WHERE rp.role = m.role AND rp.permission = 'draft.view')
+    END
+$$;
+
+-- Live count: votes from users who are no longer eligible never count, even
+-- before reconciliation materialises their revocation (§5.4).
+CREATE FUNCTION review_quorum(p_version_id uuid)
+RETURNS TABLE(approvals integer, required integer, eligible integer)
+LANGUAGE sql STABLE AS $$
+  WITH v AS (SELECT id, draft_id, required_approvals FROM draft_versions WHERE id = p_version_id),
+       e AS (SELECT r.user_id FROM v, LATERAL review_eligible_reviewers(v.draft_id) r)
+  SELECT
+    (SELECT count(*)::int FROM review_votes rv
+      WHERE rv.version_id = p_version_id AND rv.decision = 'approve' AND rv.revoked_at IS NULL
+        AND rv.reviewer_user_id IN (SELECT user_id FROM e)),
+    (SELECT required_approvals::int FROM v),
+    (SELECT count(*)::int FROM e)
+$$;
+
+CREATE FUNCTION review_capabilities(p_draft_id uuid, p_user_id uuid) RETURNS text[]
+LANGUAGE plpgsql STABLE AS $$
+DECLARE
+  d drafts%ROWTYPE;
+  v_role text; v_perms text[]; v_admin boolean; v_grole text;
+  v_author boolean; v_content boolean; v_contrib boolean; v_publisher boolean;
+  v_caps text[] := ARRAY[]::text[];
+BEGIN
+  SELECT * INTO d FROM drafts WHERE id = p_draft_id;
+  IF NOT FOUND OR d.deleted_at IS NOT NULL THEN RETURN v_caps; END IF;
+  SELECT m.role INTO v_role FROM memberships m
+   WHERE m.workspace_id = d.workspace_id AND m.user_id = p_user_id AND m.status = 'active';
+  IF v_role IS NULL THEN RETURN v_caps; END IF;
+  SELECT coalesce(array_agg(rp.permission), ARRAY[]::text[]) INTO v_perms
+    FROM role_permissions rp WHERE rp.role = v_role;
+  IF NOT ('draft.view' = ANY (v_perms)) THEN RETURN v_caps; END IF;
+  IF d.hidden_at IS NOT NULL AND NOT ('draft.hide' = ANY (v_perms)) THEN RETURN v_caps; END IF;
+  v_admin := v_role IN ('Owner', 'Admin');           -- WORKSPACE_WIDE_ROLES, groups.service.ts:21
+  IF d.group_id IS NOT NULL THEN
+    SELECT gm.review_role INTO v_grole FROM group_members gm
+     WHERE gm.group_id = d.group_id AND gm.user_id = p_user_id;
+    IF v_grole IS NULL AND NOT v_admin THEN RETURN v_caps; END IF;   -- not your group: invisible
+  END IF;
+
+  v_author := d.author_user_id = p_user_id;
+  v_content := v_admin OR ('draft.edit' = ANY (v_perms) AND CASE
+                 WHEN d.group_id IS NULL THEN true
+                 ELSE v_grole = 'editor' OR (v_author AND v_grole = 'member') END);
+  v_publisher := v_admin OR CASE
+                 WHEN d.group_id IS NULL THEN 'publication.schedule' = ANY (v_perms)
+                 ELSE v_author AND v_grole = 'member' END;
+  v_contrib := v_author
+    OR EXISTS (SELECT 1 FROM draft_contributors c WHERE c.draft_id = d.id AND c.user_id = p_user_id)
+    OR EXISTS (SELECT 1 FROM draft_versions v WHERE v.draft_id = d.id AND v.sealed_by = p_user_id
+                 AND v.seal_kind IN ('submit', 'edit'));
+
+  v_caps := ARRAY['view'];
+  IF d.hidden_at IS NOT NULL THEN                    -- frozen: moderators may only view / unhide / purge
+    v_caps := v_caps || ARRAY['hide'];
+    IF 'draft.purge' = ANY (v_perms) THEN v_caps := v_caps || ARRAY['purge']; END IF;
+    RETURN v_caps;
+  END IF;
+  IF d.state <> 'published' THEN v_caps := v_caps || ARRAY['comment']; END IF;
+  IF v_content AND d.state IN ('editing', 'changes_requested', 'in_review', 'approved', 'scheduled') THEN
+    v_caps := v_caps || ARRAY['edit'];
+  END IF;
+  IF v_content AND d.state IN ('editing', 'changes_requested')
+     AND (d.group_id IS NOT NULL OR v_admin OR 'approval.request' = ANY (v_perms)) THEN
+    v_caps := v_caps || ARRAY['submit'];
+  END IF;
+  IF (v_author OR v_admin) AND d.state IN ('in_review', 'approved', 'scheduled') THEN
+    v_caps := v_caps || ARRAY['withdraw'];
+  END IF;
+  IF d.state = 'in_review'
+     AND EXISTS (SELECT 1 FROM review_eligible_reviewers(d.id) e WHERE e.user_id = p_user_id) THEN
+    v_caps := v_caps || ARRAY['vote'];
+  END IF;
+  IF v_publisher AND d.state = 'approved' THEN v_caps := v_caps || ARRAY['release']; END IF;
+  IF v_publisher AND d.state = 'scheduled' THEN v_caps := v_caps || ARRAY['cancel_schedule', 'retry_publish']; END IF;
+  IF v_content AND d.state = 'expired' THEN v_caps := v_caps || ARRAY['reopen']; END IF;
+  IF 'approval.override' = ANY (v_perms) THEN
+    IF d.state = 'in_review' AND NOT v_contrib THEN v_caps := v_caps || ARRAY['override']; END IF;
+    IF d.state IN ('in_review', 'approved', 'scheduled') THEN v_caps := v_caps || ARRAY['restart_review']; END IF;
+  END IF;
+  IF 'draft.hide' = ANY (v_perms) THEN v_caps := v_caps || ARRAY['hide']; END IF;
+  IF 'draft.purge' = ANY (v_perms) THEN v_caps := v_caps || ARRAY['purge']; END IF;
+  RETURN v_caps;
+END $$;
+
+-- ── 7. backfill (Q9) — per tenant, before any guard trigger exists ───────────
+DO $$
+DECLARE
+  ws record; d record; v_version uuid; v_hash text; v_reason text;
+  n_versions integer; n_votes integer; n_self integer;
+BEGIN
+  FOR ws IN SELECT id FROM workspaces LOOP            -- workspaces has no RLS (001_tenants.sql:4-10)
+    PERFORM set_config('app.workspace_id', ws.id::text, true);
+    n_versions := 0; n_votes := 0; n_self := 0;
+
+    UPDATE drafts SET state = 'changes_requested' WHERE state = 'rejected';
+
+    UPDATE drafts dr SET connection_id = coalesce(
+        (SELECT sp.connection_id FROM scheduled_publications sp WHERE sp.draft_id = dr.id),
+        (SELECT c.id FROM connections c
+          WHERE c.id::text = dr.post -> 'providerMetadata' ->> 'connectionId'))
+      WHERE dr.connection_id IS NULL;
+
+    INSERT INTO draft_contributors (workspace_id, draft_id, user_id, first_contributed_at, last_contributed_at)
+      SELECT workspace_id, id, author_user_id, created_at, updated_at FROM drafts
+      ON CONFLICT DO NOTHING;
+
+    FOR d IN SELECT * FROM drafts WHERE state <> 'editing' LOOP
+      v_reason := NULL;
+      v_hash := review_content_hash(review_content(d.post, d.connection_id));
+      INSERT INTO draft_versions (workspace_id, draft_id, version_no, content, content_hash,
+          sealed_by, sealed_at, seal_kind, review_mode, required_approvals, policy_source,
+          blind_votes, deadline_at, outcome, outcome_at, outcome_by)
+      VALUES (ws.id, d.id, 1, review_content(d.post, d.connection_id), v_hash,
+          d.author_user_id, d.updated_at, 'migrated', 'quorum', 1, 'default', false,
+          CASE WHEN d.state = 'in_review' THEN now() + interval '30 days' ELSE d.updated_at END,
+          CASE d.state WHEN 'in_review' THEN NULL
+                       WHEN 'changes_requested' THEN 'changes_requested' ELSE 'approved' END,
+          CASE WHEN d.state = 'in_review' THEN NULL ELSE d.updated_at END,
+          CASE WHEN d.state = 'in_review' THEN NULL ELSE d.reviewer_user_id END)
+      RETURNING id INTO v_version;
+      n_versions := n_versions + 1;
+
+      IF d.state <> 'in_review' AND d.reviewer_user_id IS NOT NULL THEN
+        IF d.state = 'changes_requested' THEN            -- reason lived only in audit (publishing.service.ts:199-203)
+          SELECT a.diff ->> 'reason' INTO v_reason FROM audit_log a
+           WHERE a.workspace_id = ws.id AND a.action = 'draft.rejected' AND a.target_id = d.id::text
+           ORDER BY a.seq DESC LIMIT 1;
+        END IF;
+        INSERT INTO review_votes (workspace_id, draft_id, version_id, reviewer_user_id, decision,
+            reason, content_hash, source, cast_at)
+        VALUES (ws.id, d.id, v_version, d.reviewer_user_id,
+            CASE WHEN d.state = 'changes_requested' THEN 'deny' ELSE 'approve' END,
+            CASE WHEN d.state = 'changes_requested' THEN coalesce(nullif(btrim(v_reason), ''),
+                 'Migrated from single-step review; original reason unavailable.') END,
+            v_hash, 'migrated', d.updated_at);
+        n_votes := n_votes + 1;
+        IF d.reviewer_user_id = d.author_user_id THEN n_self := n_self + 1; END IF;
+      END IF;
+
+      UPDATE drafts SET current_version_id = v_version,
+             approved_version_id = CASE WHEN d.state IN ('approved', 'scheduled', 'published')
+                                        THEN v_version END
+       WHERE id = d.id;
+    END LOOP;
+
+    IF n_versions > 0 THEN
+      PERFORM audit_append(ws.id, NULL, 'sp_migration', 'review.migrated', 'workspace', ws.id::text,
+        jsonb_build_object('versions', n_versions, 'votes', n_votes, 'selfApproved', n_self));
+    END IF;
+  END LOOP;
+  PERFORM set_config('app.workspace_id', '', true);
+END $$;
+
+-- CHECK validation scans the heap directly (not subject to RLS).
+ALTER TABLE drafts ADD CONSTRAINT drafts_state_check CHECK (state IN
+  ('editing', 'in_review', 'changes_requested', 'approved', 'scheduled', 'published', 'expired'));
+
+-- ── 8. guard triggers (defence in depth; the service checks first for nice errors) ──
+-- SQLSTATEs: 23514 = invariant (as reject_workspace_change), RV001..RV004 = review rules
+-- the service maps to API codes (§5.7).
+CREATE FUNCTION review_draft_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE v record; q record;
+BEGIN
+  IF OLD.deleted_at IS NOT NULL THEN                 -- tombstones are final (FK SET NULL still allowed)
+    IF (NEW.state, NEW.post, NEW.current_version_id, NEW.approved_version_id, NEW.hidden_at, NEW.deleted_at)
+       IS DISTINCT FROM
+       (OLD.state, OLD.post, OLD.current_version_id, OLD.approved_version_id, OLD.hidden_at, OLD.deleted_at) THEN
+      RAISE EXCEPTION 'draft % is deleted', OLD.id USING ERRCODE = '23514';
+    END IF;
+    RETURN NEW;
+  END IF;
+
+  IF OLD.hidden_at IS NOT NULL AND NEW.hidden_at IS NOT NULL AND NEW.state IS DISTINCT FROM OLD.state THEN
+    RAISE EXCEPTION 'draft % is hidden; unhide before changing state', OLD.id USING ERRCODE = '23514';
+  END IF;
+
+  IF NEW.state IS DISTINCT FROM OLD.state AND (OLD.state, NEW.state) NOT IN (VALUES
+      ('editing', 'in_review'), ('editing', 'approved'),
+      ('changes_requested', 'in_review'), ('changes_requested', 'approved'),
+      ('in_review', 'approved'), ('in_review', 'changes_requested'),
+      ('in_review', 'editing'), ('in_review', 'expired'),
+      ('approved', 'scheduled'), ('approved', 'in_review'), ('approved', 'editing'),
+      ('scheduled', 'approved'), ('scheduled', 'published'),
+      ('scheduled', 'in_review'), ('scheduled', 'editing'),
+      ('expired', 'editing')) THEN
+    RAISE EXCEPTION 'illegal draft transition % -> %', OLD.state, NEW.state USING ERRCODE = '23514';
+  END IF;
+
+  IF NEW.group_id IS DISTINCT FROM OLD.group_id AND NEW.group_id IS NOT NULL AND OLD.state <> 'editing' THEN
+    RAISE EXCEPTION 'group can only change while editing' USING ERRCODE = '23514';
+  END IF;
+
+  -- Sealed content changes only together with a new version whose hash matches.
+  IF NEW.current_version_id IS DISTINCT FROM OLD.current_version_id THEN
+    SELECT dv.draft_id, dv.content_hash INTO v FROM draft_versions dv WHERE dv.id = NEW.current_version_id;
+    IF v.draft_id IS DISTINCT FROM NEW.id
+       OR v.content_hash <> review_content_hash(review_content(NEW.post, NEW.connection_id)) THEN
+      RAISE EXCEPTION 'current version does not match draft content' USING ERRCODE = '23514';
+    END IF;
+  ELSIF (NEW.post IS DISTINCT FROM OLD.post
+         OR (NEW.connection_id IS DISTINCT FROM OLD.connection_id AND NEW.connection_id IS NOT NULL))
+        AND OLD.state NOT IN ('editing', 'changes_requested')
+        AND NEW.deleted_at IS NULL THEN                -- purge redaction is the only exception
+    RAISE EXCEPTION 'draft content is sealed in state %', OLD.state USING ERRCODE = '23514';
+  END IF;
+
+  -- Entering approved needs a closed, qualifying round.
+  IF NEW.state = 'approved' AND OLD.state IN ('editing', 'changes_requested', 'in_review') THEN
+    SELECT dv.outcome, dv.review_mode INTO v FROM draft_versions dv WHERE dv.id = NEW.current_version_id;
+    IF OLD.state = 'in_review' AND v.outcome IS DISTINCT FROM 'approved' AND v.outcome IS DISTINCT FROM 'overridden' THEN
+      RAISE EXCEPTION 'approval requires a closed quorum or override' USING ERRCODE = '23514';
+    END IF;
+    IF OLD.state <> 'in_review' AND v.outcome IS DISTINCT FROM 'exempt' THEN
+      RAISE EXCEPTION 'direct approval requires an exempt version' USING ERRCODE = '23514';
+    END IF;
+    IF v.outcome = 'approved' THEN
+      SELECT * INTO q FROM review_quorum(NEW.current_version_id);
+      IF q.approvals < q.required THEN
+        RAISE EXCEPTION 'quorum not met (% of %)', q.approvals, q.required USING ERRCODE = '23514';
+      END IF;
+    END IF;
+  END IF;
+
+  IF NEW.state IN ('approved', 'scheduled', 'published')
+     AND NEW.approved_version_id IS DISTINCT FROM NEW.current_version_id THEN
+    RAISE EXCEPTION 'approved version must be the current version' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.state NOT IN ('approved', 'scheduled', 'published') AND NEW.approved_version_id IS NOT NULL THEN
+    RAISE EXCEPTION 'approved_version_id must be cleared when leaving approval' USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $$;
+CREATE TRIGGER trg_draft_review_guard BEFORE UPDATE ON drafts
+  FOR EACH ROW EXECUTE FUNCTION review_draft_guard();
+
+CREATE FUNCTION review_version_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'INSERT' THEN
+    IF NEW.content IS NULL THEN RAISE EXCEPTION 'version content required' USING ERRCODE = '23514'; END IF;
+    NEW.content_hash := review_content_hash(NEW.content);      -- never trust a caller-supplied hash
+    NEW.purged_at := NULL;
+    NEW.sealed_at := clock_timestamp();
+    IF NEW.outcome IS NOT NULL AND NOT (NEW.outcome = 'exempt' AND NEW.review_mode IN ('exempt', 'none')) THEN
+      RAISE EXCEPTION 'only exempt versions are born closed' USING ERRCODE = '23514';
+    END IF;
+    RETURN NEW;
+  END IF;
+  IF (NEW.id, NEW.draft_id, NEW.version_no, NEW.content_hash, NEW.sealed_by, NEW.sealed_at, NEW.seal_kind,
+      NEW.review_mode, NEW.required_approvals, NEW.policy_source, NEW.blind_votes, NEW.deadline_at)
+     IS DISTINCT FROM
+     (OLD.id, OLD.draft_id, OLD.version_no, OLD.content_hash, OLD.sealed_by, OLD.sealed_at, OLD.seal_kind,
+      OLD.review_mode, OLD.required_approvals, OLD.policy_source, OLD.blind_votes, OLD.deadline_at) THEN
+    RAISE EXCEPTION 'draft versions are immutable' USING ERRCODE = '23514';
+  END IF;
+  IF OLD.outcome IS NOT NULL AND (NEW.outcome, NEW.outcome_at, NEW.outcome_by)
+     IS DISTINCT FROM (OLD.outcome, OLD.outcome_at, OLD.outcome_by) THEN
+    RAISE EXCEPTION 'version outcome is final' USING ERRCODE = '23514';
+  END IF;
+  IF NEW.content IS DISTINCT FROM OLD.content AND NOT (NEW.content IS NULL AND NEW.purged_at IS NOT NULL) THEN
+    RAISE EXCEPTION 'version content can only be purged' USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $$;
+CREATE TRIGGER trg_draft_version_guard BEFORE INSERT OR UPDATE ON draft_versions
+  FOR EACH ROW EXECUTE FUNCTION review_version_guard();
+
+CREATE FUNCTION review_vote_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+DECLARE d record; v record;
+BEGIN
+  IF TG_OP = 'UPDATE' THEN
+    IF (NEW.id, NEW.draft_id, NEW.version_id, NEW.reviewer_user_id, NEW.decision, NEW.content_hash,
+        NEW.source, NEW.cast_at)
+       IS DISTINCT FROM
+       (OLD.id, OLD.draft_id, OLD.version_id, OLD.reviewer_user_id, OLD.decision, OLD.content_hash,
+        OLD.source, OLD.cast_at) THEN
+      RAISE EXCEPTION 'votes are immutable' USING ERRCODE = '23514';
+    END IF;
+    IF OLD.revoked_at IS NOT NULL
+       AND (NEW.revoked_at, NEW.revoke_cause) IS DISTINCT FROM (OLD.revoked_at, OLD.revoke_cause) THEN
+      RAISE EXCEPTION 'vote already revoked' USING ERRCODE = '23514';
+    END IF;
+    IF NEW.reason IS DISTINCT FROM OLD.reason AND NOT (NEW.reason IS NULL AND NEW.reason_redacted_at IS NOT NULL) THEN
+      RAISE EXCEPTION 'vote reason can only be redacted' USING ERRCODE = '23514';
+    END IF;
+    RETURN NEW;
+  END IF;
+
+  IF NEW.source <> 'cast' THEN RAISE EXCEPTION 'only cast votes may be inserted' USING ERRCODE = '23514'; END IF;
+  SELECT dr.state, dr.current_version_id, dr.hidden_at, dr.deleted_at, dr.author_user_id
+    INTO d FROM drafts dr WHERE dr.id = NEW.draft_id;
+  IF d.state IS DISTINCT FROM 'in_review' OR d.hidden_at IS NOT NULL OR d.deleted_at IS NOT NULL THEN
+    RAISE EXCEPTION 'round_closed' USING ERRCODE = 'RV004';
+  END IF;
+  IF NEW.version_id IS DISTINCT FROM d.current_version_id THEN
+    RAISE EXCEPTION 'version_stale' USING ERRCODE = 'RV003';
+  END IF;
+  SELECT dv.content_hash, dv.outcome INTO v FROM draft_versions dv WHERE dv.id = NEW.version_id;
+  IF v.outcome IS NOT NULL THEN RAISE EXCEPTION 'round_closed' USING ERRCODE = 'RV004'; END IF;
+  IF NEW.reviewer_user_id = d.author_user_id
+     OR EXISTS (SELECT 1 FROM draft_contributors c
+                WHERE c.draft_id = NEW.draft_id AND c.user_id = NEW.reviewer_user_id)
+     OR EXISTS (SELECT 1 FROM draft_versions dv
+                WHERE dv.draft_id = NEW.draft_id AND dv.sealed_by = NEW.reviewer_user_id
+                  AND dv.seal_kind IN ('submit', 'edit')) THEN
+    RAISE EXCEPTION 'self_approval_forbidden' USING ERRCODE = 'RV001';
+  END IF;
+  IF NOT EXISTS (SELECT 1 FROM review_eligible_reviewers(NEW.draft_id) e
+                 WHERE e.user_id = NEW.reviewer_user_id) THEN
+    RAISE EXCEPTION 'reviewer_not_eligible' USING ERRCODE = 'RV002';
+  END IF;
+  NEW.content_hash := v.content_hash;              -- bind the vote to exactly what was sealed
+  NEW.cast_at := clock_timestamp();
+  NEW.revoked_at := NULL; NEW.revoke_cause := NULL; NEW.reason_redacted_at := NULL;
+  RETURN NEW;
+END $$;
+CREATE TRIGGER trg_review_vote_guard BEFORE INSERT OR UPDATE ON review_votes
+  FOR EACH ROW EXECUTE FUNCTION review_vote_guard();
+
+-- Chat ordering: allocating seq takes the draft row lock, so concurrent writers
+-- on one draft serialise and seq order == commit order (gapless; rollbacks
+-- roll the counter back too). Readers can page with ?after=seq safely.
+CREATE FUNCTION review_message_guard() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'INSERT' THEN
+    UPDATE drafts SET chat_seq = chat_seq + 1 WHERE id = NEW.draft_id RETURNING chat_seq INTO NEW.seq;
+    IF NEW.seq IS NULL THEN RAISE EXCEPTION 'draft % not found', NEW.draft_id USING ERRCODE = '23503'; END IF;
+    NEW.created_at := clock_timestamp();
+    NEW.redacted_at := NULL; NEW.redacted_by := NULL;
+    RETURN NEW;
+  END IF;
+  IF (NEW.id, NEW.draft_id, NEW.seq, NEW.kind, NEW.author_user_id, NEW.version_id, NEW.event_type,
+      NEW.created_at, NEW.client_message_id)
+     IS DISTINCT FROM
+     (OLD.id, OLD.draft_id, OLD.seq, OLD.kind, OLD.author_user_id, OLD.version_id, OLD.event_type,
+      OLD.created_at, OLD.client_message_id)
+     OR OLD.redacted_at IS NOT NULL
+     OR (NEW.body IS DISTINCT FROM OLD.body AND NOT (NEW.body IS NULL AND NEW.redacted_at IS NOT NULL))
+     OR (NEW.event IS DISTINCT FROM OLD.event AND NEW.redacted_at IS NULL) THEN
+    RAISE EXCEPTION 'review messages are append-only (redaction excepted)' USING ERRCODE = '23514';
+  END IF;
+  RETURN NEW;
+END $$;
+CREATE TRIGGER trg_review_message_guard BEFORE INSERT OR UPDATE ON review_messages
+  FOR EACH ROW EXECUTE FUNCTION review_message_guard();
+
+-- ── 9. vote reconciliation on authz change (R8) ──────────────────────────────
+-- Materialises what review_quorum already enforces live: votes from users who
+-- stopped being eligible are revoked, with a chat event and an audit row, in
+-- the SAME transaction as the membership/role change.
+CREATE FUNCTION review_reconcile_votes(p_workspace_id uuid, p_user_id uuid, p_cause text) RETURNS void
+LANGUAGE plpgsql AS $$
+DECLARE r record;
+BEGIN
+  FOR r IN
+    UPDATE review_votes rv SET revoked_at = clock_timestamp(), revoke_cause = p_cause
+      FROM drafts d
+     WHERE rv.workspace_id = p_workspace_id AND rv.reviewer_user_id = p_user_id
+       AND rv.revoked_at IS NULL
+       AND d.id = rv.draft_id AND d.state = 'in_review' AND rv.version_id = d.current_version_id
+       AND NOT EXISTS (SELECT 1 FROM review_eligible_reviewers(d.id) e WHERE e.user_id = p_user_id)
+    RETURNING rv.id, rv.draft_id, rv.version_id
+  LOOP
+    INSERT INTO review_messages (workspace_id, draft_id, kind, version_id, event_type, event)
+    VALUES (p_workspace_id, r.draft_id, 'event', r.version_id, 'vote_revoked',
+            jsonb_build_object('reviewerUserId', p_user_id, 'cause', p_cause));
+    PERFORM audit_append(p_workspace_id, NULL, 'sp_review', 'review.vote_revoked', 'draft', r.draft_id::text,
+            jsonb_build_object('voteId', r.id, 'versionId', r.version_id,
+                               'reviewerUserId', p_user_id, 'cause', p_cause));
+  END LOOP;
+END $$;
+
+CREATE FUNCTION review_group_member_changed() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    PERFORM review_reconcile_votes(OLD.workspace_id, OLD.user_id, 'membership_changed');
+  ELSIF OLD.review_role = 'reviewer' AND NEW.review_role <> 'reviewer' THEN
+    PERFORM review_reconcile_votes(NEW.workspace_id, NEW.user_id, 'role_changed');
+  END IF;
+  RETURN NULL;
+END $$;
+CREATE TRIGGER trg_group_member_review_reconcile AFTER UPDATE OF review_role OR DELETE ON group_members
+  FOR EACH ROW EXECUTE FUNCTION review_group_member_changed();
+
+CREATE FUNCTION review_membership_changed() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF TG_OP = 'DELETE' THEN
+    PERFORM review_reconcile_votes(OLD.workspace_id, OLD.user_id, 'membership_changed');
+  ELSIF NEW.role IS DISTINCT FROM OLD.role OR NEW.status IS DISTINCT FROM OLD.status THEN
+    PERFORM review_reconcile_votes(NEW.workspace_id, NEW.user_id, 'role_changed');
+  END IF;
+  RETURN NULL;
+END $$;
+CREATE TRIGGER trg_membership_review_reconcile AFTER UPDATE OF role, status OR DELETE ON memberships
+  FOR EACH ROW EXECUTE FUNCTION review_membership_changed();
+-- Without a tenant context (e.g. system-level workspace deletion) RLS hides
+-- every draft, the UPDATE matches nothing, and audit_append is never reached.
+
+-- ── 10. a group with live reviews cannot be deleted ─────────────────────────
+CREATE FUNCTION review_block_group_delete() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM drafts d
+             WHERE d.group_id = OLD.id AND d.deleted_at IS NULL
+               AND d.state NOT IN ('editing', 'published', 'expired')) THEN
+    RAISE EXCEPTION 'group % has posts in review or scheduled', OLD.id USING ERRCODE = '55006';
+  END IF;
+  RETURN OLD;
+END $$;
+CREATE TRIGGER trg_group_review_block_delete BEFORE DELETE ON groups
+  FOR EACH ROW EXECUTE FUNCTION review_block_group_delete();
+-- Remaining editing/published/expired drafts get group_id SET NULL by the FK.
+-- Workspace deletion: runs without tenant context, so the EXISTS sees no drafts.
+
+-- ── 11. realtime doorbells (ids only; delivered at COMMIT) ─────────────────────
+CREATE FUNCTION review_notify() RETURNS trigger
+LANGUAGE plpgsql AS $$
+BEGIN
+  PERFORM pg_notify('rv_' || replace(NEW.workspace_id::text, '-', ''),
+    json_build_object(
+      'd', CASE WHEN TG_TABLE_NAME = 'drafts' THEN NEW.id ELSE NEW.draft_id END,
+      'k', CASE WHEN TG_TABLE_NAME = 'drafts' THEN 'draft' ELSE 'message' END,
+      's', CASE WHEN TG_TABLE_NAME = 'drafts' THEN NULL ELSE NEW.seq END)::text);
+  RETURN NULL;
+END $$;
+-- UPDATE OF: the chat_seq bump does not list these columns, so no double doorbell.
+CREATE TRIGGER trg_draft_review_notify
+  AFTER INSERT OR UPDATE OF state, hidden_at, deleted_at, current_version_id ON drafts
+  FOR EACH ROW EXECUTE FUNCTION review_notify();
+CREATE TRIGGER trg_review_message_notify AFTER INSERT OR UPDATE ON review_messages
+  FOR EACH ROW EXECUTE FUNCTION review_notify();
+
+-- ── 12. sweeper discovery (same pattern/owner assumption as 006:79-85) ─────────
+CREATE FUNCTION review_due_expiries() RETURNS TABLE(workspace_id uuid, draft_id uuid, deadline_at timestamptz)
+LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+  SELECT d.workspace_id, d.id, v.deadline_at
+  FROM drafts d JOIN draft_versions v ON v.id = d.current_version_id
+  WHERE d.state = 'in_review' AND d.hidden_at IS NULL AND d.deleted_at IS NULL
+    AND v.outcome IS NULL AND v.deadline_at <= now()
+  ORDER BY v.deadline_at
+  LIMIT 500
+$$;
+REVOKE ALL ON FUNCTION review_due_expiries() FROM PUBLIC;
+GRANT EXECUTE ON FUNCTION review_due_expiries() TO sp_app;
+
+-- ── 13. permissions (additive; 002 idiom) ─────────────────────────────────
+INSERT INTO role_permissions (role, permission)
+SELECT r, p
+FROM unnest(ARRAY['Owner', 'Admin']) AS r
+CROSS JOIN unnest(ARRAY['approval.override', 'approval.configure', 'draft.hide', 'draft.purge']) AS p
+ON CONFLICT DO NOTHING;
+```
+
+### 2.4 TypeScript shapes (API `publishing`/`review` modules and `apps/web/src/lib/api-types.ts`)
+
+```ts
+// replaces publishing.service.ts:8 and api-types.ts:64
+export type DraftState =
+  | "editing" | "in_review" | "changes_requested" | "approved" | "scheduled" | "published" | "expired";
+
+export type GroupReviewRole = "member" | "editor" | "reviewer";
+export type ReviewMode = "quorum" | "exempt" | "none";
+export type VersionOutcome =
+  | "approved" | "changes_requested" | "superseded" | "withdrawn" | "expired" | "overridden" | "exempt";
+
+export interface QuorumStatus {
+  versionId: string;
+  versionNo: number;
+  mode: ReviewMode;
+  approvals: number;
+  required: number;
+  eligible: number;
+  reachable: boolean;               // eligible >= required (or mode !== "quorum")
+  deadlineAt: string;
+}
+
+export interface DraftVersionSummary {
+  id: string;
+  versionNo: number;
+  contentHash: string;
+  sealedBy: string;
+  sealedAt: string;
+  sealKind: "submit" | "edit" | "reopen" | "migrated";
+  outcome: VersionOutcome | null;
+  purged: boolean;
+}
+
+export interface ReviewVoteView {
+  id: string;
+  versionNo: number;
+  reviewerUserId: string | null;    // null = blind-redacted for this viewer (Q10)
+  decision: "approve" | "deny";
+  reason: string | null;
+  castAt: string;
+  revoked: null | { at: string; cause: "retracted" | "membership_changed" | "role_changed" };
+}
+
+// DraftRecord gains (all optional on the wire for legacy rows):
+export interface DraftReviewFields {
+  groupId: string | null;
+  connectionId: string | null;
+  bundleId: string | null;
+  revision: number;
+  currentVersion: DraftVersionSummary | null;
+  approvedVersionId: string | null;
+  quorum: QuorumStatus | null;
+  capabilities: DraftCapability[];  // from review_capabilities(); the UI never recomputes
+  hidden: null | { at: string; by: string; reason: string };   // only present for draft.hide holders
+}
+
+export type ReviewEvent =
+  | { type: "submitted"; versionNo: number; contentHash: string; required: number; eligible: number }
+  | { type: "version_sealed"; versionNo: number; contentHash: string; prevVersionNo: number; dismissed: Array<string | null> }
+  | { type: "vote_approved"; versionNo: number; reviewerUserId: string | null }
+  | { type: "vote_denied"; versionNo: number; reviewerUserId: string; reason: string }
+  | { type: "vote_retracted"; versionNo: number; reviewerUserId: string | null }
+  | { type: "vote_revoked"; reviewerUserId: string | null; cause: "membership_changed" | "role_changed" }
+  | { type: "quorum_reached"; versionNo: number; approvals: number; required: number }
+  | { type: "quorum_unreachable"; required: number; eligible: number }
+  | { type: "exempt_approved"; versionNo: number; sealerRole: string }
+  | { type: "override_approved"; versionNo: number; byUserId: string; reason: string; approvalsAtOverride: number }
+  | { type: "review_restarted"; versionNo: number; byUserId: string; reason: string }
+  | { type: "withdrawn"; byUserId: string }
+  | { type: "reopened"; byUserId: string }
+  | { type: "expired"; reason: "schedule_passed" | "stale" }
+  | { type: "scheduled"; publishAt: string; auto: boolean }
+  | { type: "schedule_cancelled"; byUserId: string | null; cause: "manual" | "edit" | "hide" | "restart" | "withdraw" }
+  | { type: "publish_blocked"; reason: string }
+  | { type: "published"; remoteUrl: string | null; publicationId: string }
+  | { type: "publish_failed"; error: string };
+
+export type ReviewMessage =
+  | { kind: "comment"; id: string; seq: number; authorUserId: string; versionNo: number | null;
+      body: string | null; redacted: boolean; createdAt: string }
+  | { kind: "event"; id: string; seq: number; versionNo: number | null; event: ReviewEvent; createdAt: string };
+
+export interface ReviewPolicy {
+  scope: "workspace" | "group";
+  groupId: string | null;
+  source: "group" | "workspace" | "default";       // where the effective values come from
+  requiredApprovals: number;                       // 0..5
+  exemptRoles: string[];
+  blindVotes: boolean;
+  staleAfterHours: number;
+  minLeadMinutes: number;
+}
+
+export interface QueueItem {
+  id: string;
+  bundleId: string | null;
+  state: DraftState;
+  groupId: string | null;
+  groupName: string | null;
+  authorUserId: string;
+  excerpt: string;                                  // first 140 chars of post.text
+  connection: { id: string; provider: string; label: string } | null;
+  scheduledAt: string | null;
+  quorum: QuorumStatus | null;
+  myVote: "approve" | "deny" | null;
+  capabilities: DraftCapability[];
+  hidden: boolean;
+  lastMessageSeq: number;
+  updatedAt: string;
+}
+```
+
+---
+
+## 3. State machine
+
+### 3.1 States
+
+| state | meaning | content editable? | in queue | in archive |
+|---|---|---|---|---|
+| `editing` | working copy, not sealed | yes (`drafts.post`) | "Drafts" (own/group) | – |
+| `in_review` | sealed version *n* under vote ("primed") | yes, but **any save seals n+1** (Q6) | yes | – |
+| `changes_requested` | round closed by a deny | yes | "Needs changes" | – |
+| `approved` | quorum met (or exempt/override); not yet scheduled | yes, but a save seals n+1 → `in_review` | yes | – |
+| `scheduled` | pending `scheduled_publications` row | yes while the schedule is `pending`: the schedule is cancelled and n+1 sealed. 409 if `in_flight` | yes | – |
+| `published` | scheduler wrote the outcome | **never** (only purge redaction) | – | **yes** |
+| `expired` | deadline passed without a closed round | no; needs **reopen** → `editing` | "Expired" | – |
+
+`hidden_at` and `deleted_at` are **flags, not states** (§7.4). A hidden draft is frozen (no state change), and a deleted draft is a terminal tombstone.
+
+### 3.2 Transition table
+
+Abbreviations:
+- **A** = author.
+- **E** = group `editor` (for workspace-scoped drafts: any holder of `draft.edit`).
+- **R** = an eligible reviewer (§5.2).
+- **OA** = workspace Owner/Admin (`WORKSPACE_WIDE_ROLES`, `groups.service.ts:21`).
+- **sys** = system actor, written to audit as `actor_user_id = NULL` with `actor_role = 'sp_review'` (API) or `'sp_scheduler'` (worker), the same convention as `publish.activity.ts:186-188`.
+
+Every transition: (1) takes the lock sequence in §5.6, (2) runs a CAS `UPDATE … WHERE id=$1 AND state=$from` in the existing `transition()` style (`publishing.service.ts:275-292`), (3) appends audit **in the same tx** (§9), (4) inserts a chat `event` row in the same tx, and (5) is re-validated by `review_draft_guard` (§2.3, section 8).
+
+| # | from → to | action / endpoint | who | guards (all checked inside the tx) |
+|---|---|---|---|---|
+| T1 | ∅ → `editing` | `POST /publishing/drafts` | ws `draft.create`. For group drafts: group role `member`/`editor`, or OA | the `group_id` group exists in the tenant (composite FK). `connection_id` ∈ `group_connections` for that group, or any connection for workspace drafts (OA: `userCanUseConnection`, `groups.service.ts:447-467`) |
+| T2 | `editing` → `editing` | `PATCH /publishing/drafts/:id` | A, E, OA | `baseRevision = drafts.revision`, else 409 `REVISION_CONFLICT`. The actor is upserted into `draft_contributors` |
+| T3 | `editing`/`changes_requested` → `in_review` | `POST …/:id/submit` ("prime") | A, E, OA. Legacy workspace drafts additionally need `approval.request` (unchanged contract, `publishing.controller.ts:81-89`) | content valid. `scheduledAt` is null or ≥ `clock_timestamp() + min_lead`. Connection is allowed for the group. **Seals version n+1** with the captured policy. If `eligible < required`, flag `quorum_unreachable` |
+| T3x | `editing`/`changes_requested` → `approved` (→ `scheduled`) | same `submit` call | the sealer's ws role ∈ `exempt_roles`, or policy `required_approvals = 0` | version `review_mode IN ('exempt','none')`, `outcome='exempt'`. Auto-schedule follows the T5 rules |
+| T4 | `in_review` → `in_review` | `PATCH …/:id` (edit while sealed) | A, E, OA | `baseVersionNo = current version_no`, else 409. Seals n+1 with `seal_kind='edit'`. The old version gets `outcome='superseded'`. Event `version_sealed{dismissed:[…]}` |
+| T5 | `in_review` → `approved` [→ `scheduled`] | the N-th approving `POST …/:id/votes` | sys (caused by R) | `review_quorum(v).approvals ≥ required`. `clock_timestamp() < deadline_at`. Not hidden. Then: if `post.scheduledAt` is set **and** (group draft, **or** the legacy author holds `publication.schedule`) **and** the connection is still allowed → insert `scheduled_publications`, state `scheduled`. Otherwise stay `approved` |
+| T6 | `in_review` → `changes_requested` | `POST …/:id/votes {decision:'deny', reason}` | R | non-empty reason ≤ 2000 chars. Current `versionId` |
+| T7 | `in_review`/`approved`/`scheduled` → `editing` | `POST …/:id/withdraw` | A, OA | from `scheduled`, only if the schedule row is `pending` (it is deleted). An open version gets `outcome='withdrawn'`; an already-approved version keeps `approved` (history) and `approved_version_id` is cleared |
+| T8 | `in_review` → `expired` | sweeper, or a vote/unhide that finds the deadline passed | sys | `clock_timestamp() ≥ deadline_at`. `outcome='expired'`. `expiredReason: 'schedule_passed' \| 'stale'` |
+| T9 | `in_review` → `approved` [→ `scheduled`] | `POST …/:id/override {reason}` | OA with `approval.override`, **not** in the contributor/sealer set | reason non-empty. `outcome='overridden'`. Records `approvalsAtOverride` and `required` |
+| T10 | `in_review`/`approved`/`scheduled` → `in_review` | `POST …/:id/restart-review {reason}` | OA with `approval.override` | seals n+1 with identical content (`seal_kind='reopen'`, not counted as a contribution) and **recaptures policy**. Cancels a pending schedule. An open old version gets `outcome='superseded'`; an approved one keeps `approved` (outcomes are final) and `approved_version_id` is cleared; audit `review.restarted` |
+| T11 | `approved`/`scheduled` → `in_review` | `PATCH …/:id` (edit after approval) | A, E, OA | as T4. From `scheduled`: the schedule must be `pending` and is deleted in the same tx, else 409 `PUBLISH_IN_FLIGHT` |
+| T12 | `approved` → `scheduled` | `POST …/:id/release {publishAt?}` | group: A or OA. Legacy: holders of `publication.schedule` (unchanged, `publishing.controller.ts:113-114`) | `approved_version_id = current_version_id`. `publishAt` defaults to now. Connection still allowed. **Allowed only when the sealed `scheduledAt` is null** (otherwise T5 already scheduled it; moving the time is an edit → T11) |
+| T13 | `scheduled` → `approved` | `DELETE …/:id/schedule` (existing) | as T12 | the schedule is `pending` (existing logic, `publishing.service.ts:248-273`) |
+| T14 | `scheduled` → `published` | scheduler `complete()` | sys | claim gate (§5.5) |
+| T15 | `expired` → `editing` | `POST …/:id/reopen` | A, E, OA | none. The next submit needs a fresh `scheduledAt` |
+| T16 | `scheduled` (failed) → `scheduled` | `POST …/:id/retry-publish` | as T12 | `scheduled_publications.state='failed'`: delete it and insert a new pending row with a new idempotency key for the **same approved version** (no re-review, content unchanged) |
+| M1 | any except in-flight → same state, `hidden_at` set | `POST …/:id/hide {reason}` | `draft.hide` (OA) | if `scheduled`+`pending`: delete the schedule and set state to `approved` in the same tx, so unhide can never cause a surprise publish |
+| M2 | hidden → visible | `POST …/:id/unhide` | `draft.hide` | if `in_review` and the deadline has passed, apply T8 in the same tx |
+| M3 | any except in-flight → tombstone | `DELETE /publishing/drafts/:id {reason}` | `draft.purge` (OA) | §7.4 redaction. Pending schedule deleted |
+
+### 3.3 Allowed (from,to) pairs enforced by the DB trigger
+
+```
+editing→in_review, editing→approved,
+changes_requested→in_review, changes_requested→approved,
+in_review→approved, in_review→changes_requested, in_review→editing, in_review→expired,
+approved→scheduled, approved→in_review, approved→editing,
+scheduled→approved, scheduled→published, scheduled→in_review, scheduled→editing,
+expired→editing
+```
+Self-transitions (T4, T10 from `in_review`, T16) change `current_version_id`/`revision`, not `state`, and are covered by the content rules in `review_draft_guard`.
+
+---
+
+## 4. RBAC
+
+### 4.1 New workspace permissions (additive; the 10-role seed contract is untouched)
+
+| permission | Owner | Admin | others | gates |
+|---|---|---|---|---|
+| `approval.override` | ✓ | ✓ | – | T9, T10 |
+| `approval.configure` | ✓ | ✓ | – | `review_policies` writes |
+| `draft.hide` | ✓ | ✓ | – | M1, M2; seeing hidden drafts |
+| `draft.purge` | ✓ | ✓ | – | M3 |
+
+`publication.delete` is **not** reused (D8: Publisher holds it). It stays reserved for future *remote* retraction. Seeding follows the `002` idiom (`INSERT … SELECT … unnest … ON CONFLICT DO NOTHING`, `002_rbac_seed.sql:4-18`). `role_permissions` has no epoch trigger, and none is needed, because the guard reads permissions live (`rbac.guard.ts:50-60`).
+
+Existing permissions keep their meaning for **workspace-scoped drafts** (`group_id IS NULL`):
+- `approval.request` → submit.
+- `approval.grant` → eligible to vote.
+- `publication.schedule` → release and cancel.
+- `draft.edit` → content.
+
+For **group drafts**, group roles decide, with the workspace permission as a floor (§4.2).
+
+### 4.2 Group roles: capability matrix for group drafts
+
+| capability | `member` | `editor` | `reviewer` | OA (no group role needed) | floor (ws permission) |
+|---|---|---|---|---|---|
+| view draft and chat | ✓ | ✓ | ✓ | ✓ | `draft.view` |
+| comment | ✓ | ✓ | ✓ | ✓ | `draft.view` |
+| create in group | ✓ | ✓ | – | ✓ | `draft.create` |
+| edit content (own) | ✓ | ✓ | – | ✓ | `draft.edit` |
+| edit content (others') | – | ✓ | – | ✓ | `draft.edit` |
+| submit / resubmit | own | ✓ | – | ✓ | `draft.edit` |
+| withdraw | own | – | – | ✓ | – |
+| vote approve/deny | – | – | ✓ (if eligible) | – (use override) | `draft.view` |
+| release / cancel schedule / retry | own | – | – | ✓ | – (quorum is the authority, §4.4) |
+| override, restart review | – | – | – | ✓ | `approval.override` |
+| hide/unhide, purge | – | – | – | ✓ | `draft.hide` / `draft.purge` |
+
+The spec's rules map onto this matrix:
+- "Editors can edit, cannot post/approve": editors can't vote, release, cancel, or retry.
+- "Reviewers cannot edit": no content capability at all, even on a draft they authored before being made reviewer.
+- Assigning `reviewer`/`editor` is refused (400) if the target's workspace role lacks the floor permission (Analyst, Moderator, and the stream operator roles lack `draft.view`, `002_rbac_seed.sql:53-85`).
+
+Role assignment: `PATCH /groups/:groupId/members/:userId {reviewRole}`, `@RequirePermission("workspace.members.manage")`, the same gate as add/remove (`groups.controller.ts:82-112`). It returns `{token}` because the UPDATE bumps the epoch (`008_groups.sql:79-80`; contract in `groups.service.ts:15-18`). Audit `group.member_review_role_changed {userId, reviewRole:[before, after]}` is written in the same tx.
+
+### 4.3 One capability function, used by the guard, service, and UI
+
+```sql
+-- returns e.g. {view,comment,edit,submit,vote}; empty array = 404 to the caller
+CREATE FUNCTION review_capabilities(p_draft_id uuid, p_user_id uuid) RETURNS text[]
+LANGUAGE plpgsql STABLE AS $$ … $$;   -- full body in §2.3, section 6
+```
+
+The guard extension mirrors `RequireGroupAccess` (`rbac.guard.ts:8-19,64-74`):
+
+```ts
+// apps/api/src/rbac/rbac.guard.ts (additions)
+export const DRAFT_CAPABILITY_KEY = "required_draft_capability";
+export type DraftCapability =
+  | "view" | "comment" | "edit" | "submit" | "withdraw" | "vote" | "release"
+  | "cancel_schedule" | "retry_publish" | "reopen" | "override" | "restart_review" | "hide" | "purge";
+
+/** Gate on the caller's live capability for the route's :draftId. Fails closed without :draftId. */
+export const RequireDraftCapability = (capability: DraftCapability): MethodDecorator =>
+  SetMetadata(DRAFT_CAPABILITY_KEY, capability) as MethodDecorator;
+
+// in canActivate, after the permission check:
+//   const draftId = req.params?.draftId; isUuid(draftId) else 400
+//   const caps = await withTenant(ws, c => c.query<{ caps: string[] }>(
+//     "SELECT review_capabilities($1, $2) AS caps", [draftId, session.userId]));
+//   caps.length === 0 → NotFoundException (don't leak hidden/foreign-group drafts as 403)
+//   !caps.includes(required) → ForbiddenException(`missing draft capability: ${required}`)
+```
+
+The guard runs in its own tx, so its check is an **early 403 only**. The service re-evaluates the precise guard inside the mutation tx, under locks (§5.6). That is the same TOCTOU stance as today's guard and service split. `GET /publishing/drafts/:id` returns `capabilities: DraftCapability[]` from the same function, and the UI renders buttons from it without recomputing anything client-side.
+
+### 4.4 Self-approval exclusion (structural)
+
+There are three layers:
+1. **SQL eligibility** (`review_eligible_reviewers`, §5.2) excludes `author_user_id`, all `draft_contributors`, and all sealers of `seal_kind IN ('submit','edit')`.
+2. **The `review_vote_guard` trigger** refuses any vote insert where the reviewer isn't eligible. Self or contributor cases raise `SQLSTATE 'P0001'` with message `self_approval_forbidden`, which the service maps to 403 `{code:"SELF_APPROVAL_FORBIDDEN"}`. Other ineligibility raises `reviewer_not_eligible`.
+3. **Override** checks the same contributor set: an admin who edited the post can't force-approve it.
+
+**Quorum as the publish authority.** For group drafts, the group's approval *is* the authorization to publish through a connection assigned to that group (`group_connections` is the admin's grant). So a workspace Editor-role author with no `publication.schedule` can get a post out through quorum, which is the point of the feature. For legacy workspace drafts, auto-schedule at quorum still needs the author to hold `publication.schedule` (T5). Otherwise the draft waits in `approved` for a release by someone who holds it, exactly as today.
+
+### 4.5 Exemption is not self-approval
+
+`exempt_roles` (default `{Owner,Admin}` via the built-in policy) means **review is not required** when a user with that workspace role seals the version. No vote row is written. The version records `review_mode='exempt'`, the audit records `draft.approved {reviewMode:'exempt', sealerRole}`, and the queue shows an "exempt" chip. This preserves today's one-click Owner/Admin publish (`compose/page.tsx:121-138`) without breaking R2's rule that nobody approves their own post. Groups that want strict four-eyes set `exempt_roles = '{}'`, which is what the group-policy UI pre-fills.
+
+---
+
+## 5. Quorum engine
+
+### 5.1 Vote lifecycle
+
+```
+                cast(approve, versionId)                 retract (own approve, while in_review)
+  (no vote) ──────────────────────────────▶ LIVE APPROVE ───────────────────────────▶ REVOKED(retracted)
+      │                                         │  version superseded / round closed
+      │ cast(deny, versionId, reason)            ▼
+      └──────────────▶ LIVE DENY ──▶ round closes immediately (T6)   HISTORICAL (counts nowhere)
+                                                 ▲
+         reviewer leaves group / role changes ───┘ REVOKED(membership_changed | role_changed)  (in_review only)
+```
+
+- **One live vote per reviewer per version** (`review_votes_one_live`). After a retraction a reviewer may cast again on the same version, for example approve → retract → deny with a reason. A vote that has been cast can't be edited. Change happens by retract-then-recast, so the history reads honestly in chat and audit.
+- **Only approvals can be retracted** (CHECK in §2.3). A deny ends the round, so there's nothing left to retract.
+- **Idempotency.** `POST …/votes` with the same `(versionId, decision)` as the caller's live vote returns `200` with the existing vote. A different decision while a live vote exists returns `409 VOTE_EXISTS` ("retract first"). This makes the re-auth retry in §8 E7 safe.
+
+### 5.2 Eligibility (who counts)
+
+`review_eligible_reviewers(draft)` (§2.3, section 6) is evaluated **live** at vote time, at count time, and in the capability check:
+- the user has an active workspace membership (`007_auth.sql:12-13`)
+- **and** they aren't the author, aren't in `draft_contributors`, and never sealed a `submit`/`edit` version of this draft
+- **and** either
+  - for group drafts: their group `review_role = 'reviewer'` and their workspace role has `draft.view`
+  - for workspace drafts: their workspace role has `approval.grant` (the existing contract, `002_rbac_seed.sql:8,24,49`).
+
+`review_quorum(version)` counts live approvals **from currently eligible users only**. That makes the count correct even before reconciliation triggers fire, for example in a race (§5.6, R5).
+
+### 5.3 Snapshot and staleness semantics (R4)
+
+- **Seal points.** T3 submit, T4/T11 edit-while-sealed, and T10 restart. Each one, in one tx:
+  1. `INSERT draft_versions` (hash computed by trigger, policy captured, `deadline_at = LEAST(post.scheduledAt, now + stale_after)`).
+  2. Close the previous open version (`outcome='superseded'`).
+  3. `UPDATE drafts SET post, connection_id, current_version_id, revision = revision+1, approved_version_id = NULL, state`. The guard trigger checks that the hash matches.
+  4. If a pending schedule exists, `DELETE` it (T11), else 409 when `in_flight`.
+  5. Upsert `draft_contributors` for the sealer (`edit` and `submit`; not `reopen`).
+  6. Chat event and audit.
+- **Votes carry `versionId`.** The UI sends the id of the version it rendered. If an editor sealed n+1 in between, the vote gets `409 VERSION_STALE {currentVersionNo}`. The reviewer never approves bytes they didn't see.
+- **What reviewers see.** `GET …/versions/:n` returns the content and hash. `GET …/versions/:n/diff?against=:m` (default: the last version the caller voted on, otherwise n-1) returns a word-level diff computed server-side, so every client sees the same diff. That's a small Myers diff in `apps/api/src/review/review.diff.ts` with no new deps. Field changes to `visibility`, `scheduledAt`, `connectionId`, and `mediaAssetIds` are listed as structured key changes, the way the audit `DiffViewer` already renders `[before, after]` pairs (`apps/web/src/app/(main)/audit/page.tsx:24-40`).
+
+### 5.4 Deny handling
+
+A deny with a reason runs T6 in one tx:
+1. Vote insert (trigger-validated).
+2. Version `outcome='changes_requested', outcome_by=reviewer`.
+3. Draft → `changes_requested`.
+4. Chat `vote_denied` (reason inline), audit `review.vote_cast` + `draft.changes_requested`.
+5. Notifier `changes_requested` → author + group editors.
+
+Other live approvals on that version stay in the table as history. They're bound to a closed version, so they never count again (Q5).
+
+### 5.5 Quorum completion, auto-schedule, and the claim gate
+
+When the vote that makes `approvals ≥ required` is cast:
+
+```ts
+// apps/api/src/review/review.service.ts — inside castVote's tenant transaction, after the vote insert
+const q = await quorum(client, version.id);              // SELECT * FROM review_quorum($1)
+if (decision === "approve" && q.approvals >= q.required) {
+  await closeVersion(client, version.id, "approved", null);   // outcome_by NULL = system
+  await setState(client, draft.id, "in_review", "approved", { approvedVersionId: version.id });
+  await event(client, draft, { type: "quorum_reached", versionNo, approvals: q.approvals, required: q.required });
+  await audit(client, ws, SYSTEM_REVIEW_ACTOR, "draft.approved", draft.id, {
+    versionNo, contentHash: version.contentHash, approvals: q.approvals, required: q.required,
+    voterIds: await liveApproverIds(client, version.id), reviewMode: "quorum",
+  });
+  const schedule = await maybeAutoSchedule(client, draft, version);   // T5 rules (§3.2)
+  if (schedule !== null) afterCommit.push(() => workflowStarter.startScheduledPublish(schedule.idempotencyKey, schedule.publishAt));
+}
+```
+
+`maybeAutoSchedule` reuses the existing schedule insert (`publishing.service.ts:229-234`) and runs the existing RLS-scoped connection check (`:217-220`). It adds the group check `EXISTS group_connections(group_id, connection_id)`, which fixes D5 for this path. `startScheduledPublish` runs **after commit**, the same way and with the same failure tolerance as today (`publishing.service.ts:242-244`, sweeper `apps/scheduler/src/worker.ts:56-73`).
+
+**Claim gate** (replaces `publish.activity.ts:136-145`, fixes D1). It publishes **the approved version's content**, not the working copy:
+
+```sql
+UPDATE scheduled_publications sp SET state = 'in_flight', error = NULL
+FROM drafts d
+JOIN draft_versions v ON v.id = d.approved_version_id AND v.draft_id = d.id
+JOIN connections c ON c.id = sp.connection_id
+WHERE sp.idempotency_key = $1 AND sp.state = 'pending'
+  AND d.id = sp.draft_id
+  AND d.state = 'scheduled'
+  AND d.approved_version_id = d.current_version_id
+  AND d.hidden_at IS NULL AND d.deleted_at IS NULL
+  AND v.content IS NOT NULL
+  AND (v.content ->> 'connectionId')::uuid = sp.connection_id
+  AND (d.group_id IS NULL OR EXISTS (
+        SELECT 1 FROM group_connections gc
+        WHERE gc.group_id = d.group_id AND gc.connection_id = sp.connection_id))
+RETURNING sp.id, sp.workspace_id, sp.draft_id, sp.idempotency_key,
+          v.content -> 'post' AS post, v.content_hash,
+          c.id AS connection_id, c.provider, c.channel_id, c.fields, c.created_at,
+          (SELECT cr.id FROM credentials cr WHERE cr.connection_id = c.id
+            ORDER BY cr.created_at DESC LIMIT 1) AS credential_id
+```
+
+If no row is returned:
+- **Row missing or not `pending`:** return `{ skipped: "not_pending" }`, a non-retryable outcome (fixes D2).
+- **Row `pending` but the gate failed** (e.g. the connection was unassigned from the group): `UPDATE … SET state='failed', error='review gate: <reason>'`, write chat `publish_blocked`, audit `publication.blocked`, and return `{ skipped }`.
+
+`PublishActivity.publishScheduled` moves `claim` inside its error handling, and its return type becomes `StoredPublication | { skipped: string }`. `complete()` (`publish.activity.ts:158-191`) also inserts the chat `published` event and records `contentHash` in the `publication.published` diff.
+
+**Expiry sweeper** (new, in `apps/scheduler/src/worker.ts` beside `sweepDue`, every 30 s):
+1. `SELECT * FROM review_due_expiries()`.
+2. For each row, open a tenant tx (`inTenant`, `publish.activity.ts:234-248`).
+3. `SELECT … FOR UPDATE` the draft and re-check `state='in_review' AND deadline_at <= clock_timestamp()`.
+4. Apply T8: version `outcome='expired'`, chat `expired`, audit `draft.expired` with actor role `sp_scheduler`, notifier `expired` → author.
+
+A second query, with the same shape and `deadline_at BETWEEN now() AND now() + 2h`, drives the `expiring_soon` notifier hook. Hook delivery is idempotent per version, keyed in memory on `(versionId, "expiring_soon")`, and best-effort, since notifications are a non-goal (R9).
+
+### 5.6 Race conditions and the lock order
+
+**Lock order (mandatory for every review path):** `memberships` row → `group_members` row → `drafts` row → `review_votes` / `review_messages` / `scheduled_publications`.
+
+Why it matters: removing a reviewer locks their `group_members` row (DELETE), and the reconciliation trigger then inserts a chat event, which takes the **draft** row lock (`chat_seq`, §2.3, section 8). A vote that locked the draft first and the reviewer's `group_members` row second would deadlock against it. So `castVote`:
+1. reads `drafts.group_id` without a lock (immutable once sealed, enforced by the guard)
+2. `SELECT 1 FROM memberships WHERE workspace_id=$1 AND user_id=$2 FOR SHARE`
+3. `SELECT 1 FROM group_members WHERE group_id=$1 AND user_id=$2 FOR SHARE` (group drafts)
+4. `SELECT … FROM drafts WHERE id=$1 FOR UPDATE`, then re-validates state, version, deadline (`clock_timestamp()`), and hidden/deleted
+5. inserts the vote, evaluates quorum, transitions.
+
+`FOR SHARE` (not `FOR KEY SHARE`) is deliberate: a `review_role` UPDATE is a non-key update, which `FOR KEY SHARE` would let through.
+
+| # | race | resolution |
+|---|---|---|
+| R1 | two "final" approvals at 2/3 | both serialise on the draft lock. The second sees `state='approved'` and gets **409 `ROUND_CLOSED`**; the UI shows "already approved". The vote isn't recorded, because it would change nothing and would mislead metrics. |
+| R2 | approve vs editor's save | both lock the draft. If the seal wins, the vote's `versionId` is stale → 409 `VERSION_STALE`. If the vote wins, the seal supersedes the version and the approval becomes historical. |
+| R3 | approve vs deny | serialised. Whichever commits second sees a closed round → 409 `ROUND_CLOSED`. |
+| R4 | final approval vs deadline (Q7) | the vote tx compares `clock_timestamp()` **after** acquiring the lock (not `now()`, which is tx start). If the deadline has passed, it applies T8 and returns 409 `REVIEW_EXPIRED`. The sweeper takes the same lock. |
+| R5 | vote vs reviewer removal | removal holds `group_members` exclusively, so the vote's `FOR SHARE` waits. Then the vote re-validates eligibility (trigger) → `RV002 reviewer_not_eligible` → 403. If the vote got its lock first, the removal waits for the vote to commit, and reconciliation then sees and revokes the new vote. Neither order leaves an orphaned live vote. |
+| R6 | quorum vs author withdraw | draft lock. If withdraw wins, the vote gets `ROUND_CLOSED`. If the vote wins, withdraw from `approved`/`scheduled` is still allowed (T7). |
+| R7 | edit vs scheduler claim | the edit `DELETE`s the schedule `WHERE state='pending'`, and the claim `UPDATE`s `WHERE state='pending'`. The row lock serialises them. If the claim wins, the edit gets 409 `PUBLISH_IN_FLIGHT`. If the edit wins, the claim finds no row and skips without retrying. |
+| R8 | policy change mid-round | no race: the policy is captured at seal (Q3). |
+| R9 | two editors saving | `baseRevision` / `baseVersionNo` compare-and-set → 409 `REVISION_CONFLICT` with the server copy. |
+| R10 | chat writes vs transitions | both go through the draft lock, so `seq` is commit-ordered (§6.1). |
+
+### 5.7 Error contract
+
+The service pre-checks and returns these. DB SQLSTATEs map to the same codes, so a missed pre-check still produces a correct response.
+
+| HTTP | code | source |
+|---|---|---|
+| 403 | `SELF_APPROVAL_FORBIDDEN` | service / `RV001` |
+| 403 | `REVIEWER_NOT_ELIGIBLE` | service / `RV002` |
+| 409 | `VERSION_STALE` | service / `RV003` |
+| 409 | `ROUND_CLOSED` | service / `RV004` |
+| 409 | `REVIEW_EXPIRED`, `PUBLISH_IN_FLIGHT`, `REVISION_CONFLICT`, `VOTE_EXISTS`, `GROUP_HAS_LIVE_REVIEWS` (`55006`) | service |
+| 400 | `REASON_REQUIRED`, `SCHEDULE_TOO_SOON`, `CONNECTION_NOT_IN_GROUP` | DTO / service |
+| 500 + alert | `23514` from a guard trigger | always a service bug. Logged with the draft id. |
+
+### 5.8 API surface
+
+All routes are `@UseGuards(RbacGuard)`. The coarse permission comes first, then `@RequireDraftCapability` where a `:draftId` exists. Verbs stay within the CORS allow-list `GET, POST, PATCH, DELETE` (`main.ts:18`), which has no `PUT`.
+
+| method & path | permission / capability | notes |
+|---|---|---|
+| `GET /publishing/queue?filter=&groupId=&cursor=&limit=` | `draft.view` | filters: `needs_my_review`, `mine`, `needs_changes`, `in_review`, `approved`, `scheduled`, `expiring` (deadline < 24h), `expired`, `hidden` (`draft.hide` only). Keyset on `(updated_at, id)`. Returns `QueueItem[]` + `nextCursor` |
+| `GET /publishing/archive?groupId=&connectionId=&q=&from=&to=&cursor=` | `draft.view` | `state='published'`, visibility-filtered like the queue |
+| `POST /publishing/drafts` | `draft.create` | body gains `groupId?`, `connectionId`, `bundleId?` |
+| `GET /publishing/drafts/:draftId` | `draft.view` + `view` | `DraftRecord & DraftReviewFields` + versions + votes (blind-redacted) |
+| `PATCH /publishing/drafts/:draftId` | `draft.edit` + `edit` | `{post, connectionId?, baseRevision}` or `{…, baseVersionNo}` when sealed |
+| `POST …/:draftId/submit` | `draft.view` + `submit` | legacy drafts keep `approval.request` inside the capability |
+| `POST …/:draftId/withdraw` · `/reopen` | `draft.view` + `withdraw` / `reopen` | |
+| `GET …/:draftId/versions/:n` · `/versions/:n/diff?against=` | `draft.view` + `view` | purged → `410` |
+| `POST …/:draftId/votes` | `draft.view` + `vote` | `{versionId, decision, reason?}` |
+| `DELETE …/:draftId/votes/mine` | `draft.view` + `vote` | retract own live approval |
+| `POST …/:draftId/approve` · `/reject` (existing) | unchanged decorators | **compat shims:** approve → vote approve on current version. Reject → vote deny, and **`reason` is now required** (`publishing.controller.ts:172-177` made it optional). Logged as deprecated |
+| `POST …/:draftId/override` · `/restart-review` | `approval.override` + `override` / `restart_review` | `{reason}` required |
+| `POST …/:draftId/release` · `/retry-publish`; `DELETE …/:draftId/schedule` | `draft.view` + `release` / `retry_publish` / `cancel_schedule` | `schedule` (existing, body `connectionId`) is kept for legacy drafts but now rejects `connectionId ≠ drafts.connection_id` and group-unassigned connections (D5) |
+| `POST …/:draftId/hide` · `/unhide`; `DELETE /publishing/drafts/:draftId` | `draft.hide` / `draft.purge` + capability | `{reason}` required |
+| `GET …/:draftId/messages?after=&limit=` · `POST …/:draftId/messages` | `draft.view` + `view` / `comment` | `POST {body, clientMessageId}` is idempotent |
+| `DELETE …/:draftId/messages/:messageId` | `draft.hide` | redaction, audited |
+| `GET /review/events` (SSE) | `draft.view` | §6.3 |
+| `GET /review/policies` · `PATCH /review/policies` | `workspace.view` / `approval.configure` | workspace row. `PATCH {requiredApprovals,…}` upserts |
+| `GET /groups/:groupId/review-policy` · `PATCH` · `DELETE` | `workspace.view` / `approval.configure` | `DELETE` = inherit |
+| `PATCH /groups/:groupId/members/:userId` | `workspace.members.manage` | `{reviewRole}` → `{token}` |
+| `POST /auth/reissue` | valid HMAC + unexpired + active membership | §8 E7. Keeps the original `expiresAt` |
+
+---
+
+## 6. Review chat
+
+### 6.1 Data model
+
+`review_messages` (§2.3) holds two kinds of row:
+- **comments**: human-written, ≤ 4000 chars, immutable, admin-redactable.
+- **events**: system-written in the *same transaction* as the transition they describe, so chat can never disagree with state.
+
+`seq` is allocated by `review_message_guard` with `UPDATE drafts SET chat_seq = chat_seq + 1 … RETURNING`. That row lock serialises every writer on one draft, so **`seq` order is commit order and has no gaps** (a rolled-back insert also rolls back its increment). A reader paging `?after=41` therefore can't miss a row 42 that commits later. That would be the classic bug with identity columns or `created_at` cursors.
+
+Comments carry `version_id` (the version current when posted), so the thread can show "commented on v2" dividers. Votes are **not** a separate chat surface: each vote writes a `vote_approved`/`vote_denied` event, and the deny reason appears inline as a reviewer bubble in a danger tone.
+
+**Mentions.** `@displayName` tokens are parsed server-side against the draft's visible audience (group members + OA). Matches are stored in the event-free comment body as plain text and passed to the notifier port as `{type:"mention", userIds}`. Nothing is rendered as a link to users outside the audience.
+
+### 6.2 Event types
+
+The `ReviewEvent` union is in §2.4. Every state transition in §3.2 emits exactly one event, plus `version_sealed`, `vote_*`, `quorum_reached`/`quorum_unreachable`, `publish_blocked`, `publish_failed`, and `published` (from the scheduler). Server-side blind redaction (Q10) applies only to `vote_approved`, `vote_retracted`, and `version_sealed.dismissed`, and only for an eligible reviewer who hasn't voted on an open, blind version. In that case `reviewerUserId` is set to `null`.
+
+### 6.3 Transport (Q4) — SSE doorbells
+
+**Server** (`apps/api/src/review/review-events.controller.ts` + `review-event-hub.ts`):
+- `GET /review/events` is an `@Sse()` route behind `RbacGuard` + `@RequirePermission("draft.view")`. That means signature, **epoch** (normalised, `rbac.guard.ts:42-48`), and active membership are checked by the existing code (unlike D6).
+- `ReviewEventHub` (singleton per API instance) holds **one dedicated `pg` client** (outside the pool, `db/client.ts:6-9`) that `LISTEN`s on `rv_<workspace-uuid-hex>` while that workspace has at least one subscriber, and `UNLISTEN`s when the last one leaves.
+- On connect, a stream loads a `StreamScope` with `{workspaceId, userId, epoch, visibleGroupIds, canSeeHidden, isWorkspaceWide}` in one tenant tx. This cache is **sound only while the epoch is unchanged**, and every input to it (group membership, review role, workspace role, status) bumps the epoch (`001_tenants.sql:191-192`, `008_groups.sql:79-80`).
+- On each doorbell `{d, k, s}`, the hub checks the workspace epoch once per workspace (debounced to 1 query per 250 ms) and, if it changed, sends `event: reauth` to every stream with the old epoch and closes them. Otherwise it fetches `group_id, hidden_at, deleted_at` for `d` (one indexed query, shared across the workspace's streams) and forwards `{draftId, kind, seq}` only to streams whose scope can see it.
+- Heartbeat: a `: ping` comment every 25 s, plus an epoch check at the same cadence. Each user is capped at 5 concurrent streams; the oldest is closed.
+- **Multi-instance:** NOTIFY reaches every API instance listening on the channel, so no sticky sessions are needed.
+
+**Client** (`apps/web/src/lib/review-events.ts`, ~60 lines): `fetch("/review/events", {headers:{Authorization}})`, a `ReadableStream` line parser, and exponential backoff (1 s → 30 s). On `reauth` it calls `POST /auth/reissue` (§8 E7), then reconnects. After 3 consecutive failures it falls back to polling: the queue every 15 s, and the open draft's messages every 5 s. `useReviewDoorbell(draftId?)` triggers `reload()` on `useApiResource` (`apps/web/src/lib/use-api.ts:65`) for the queue, and `fetchAfter(seq)` for the open thread.
+
+**Rejected alternatives:**
+- **WS:** new deps, a new auth path (D6), sticky sessions, and two-way messaging nobody needs.
+- **Pure polling:** fine as the fallback, but 5 s chat latency feels broken in a "vote together" flow, and the load grows with open tabs, not with activity.
+
+### 6.4 Authz integration summary
+
+| check | where |
+|---|---|
+| connect | `RbacGuard` (`draft.view`, epoch, active) |
+| per doorbell | `StreamScope` (epoch-bounded cache) |
+| per data fetch | `review_capabilities()` through `@RequireDraftCapability("view")`, plus RLS |
+| on epoch change | stream closes; client reissues token or logs in |
+| post comment | `@RequireDraftCapability("comment")` (not hidden, not published, can view) |
+
+### 6.5 Notifier port (R9: designed, not built)
+
+```ts
+// apps/api/src/review/review.notifier.ts
+export type ReviewNotification =
+  | { type: "review_requested"; draftId: string; userIds: string[] }        // eligible reviewers at seal
+  | { type: "changes_requested"; draftId: string; userIds: string[] }       // author + group editors
+  | { type: "votes_dismissed"; draftId: string; userIds: string[] }         // previous approvers on reseal
+  | { type: "quorum_unreachable"; draftId: string; userIds: string[] }      // Owner/Admin
+  | { type: "expiring_soon" | "expired"; draftId: string; userIds: string[] }
+  | { type: "mention"; draftId: string; messageId: string; userIds: string[] };
+
+export interface ReviewNotifier { notify(n: ReviewNotification): Promise<void>; }
+export const REVIEW_NOTIFIER = Symbol("REVIEW_NOTIFIER");
+export class NoopReviewNotifier implements ReviewNotifier { async notify(): Promise<void> {} }
+```
+It's called **after commit** (fire-and-forget, the same stance as `workflowStarter`). An email or Slack adapter plugs in later without touching the review logic.
+
+---
+
+## 7. UI plan
+
+### 7.1 Screens
+
+**`/approvals` → "Review" (replaces the stub `apps/web/src/app/(main)/approvals/page.tsx`; sidebar entry at `components/shell/sidebar.tsx:13`)**, three panes:
+
+| pane | contents | reuse |
+|---|---|---|
+| **Queue** (w-96) | filter bar (`Needs my review` · `Mine` · `Needs changes` · `In review` · `Approved/Scheduled` · `Expiring` · `Expired` · `Hidden` for admins), group selector, virtualised list of `QueueRow`s. A row shows the state `Badge`, a `QuorumChip` ("2/3 ✓", warn tone if unreachable, "exempt" chip), group, platform icon, excerpt, a scheduled-time countdown (red < 1 h), the `myVote` mark, and an unread dot. Bundle siblings render as one row with ×N | `useVirtualizer` exactly as `components/streams/column.tsx:27-33,57-79` (estimateSize 96, overscan 8). `Badge`/`Button` from `components/ui/primitives.tsx`. `PlatformIcon` brand component. `useApiResource` + `OfflineBadge` for sample mode |
+| **Detail** (flex-1) | header: state, `QuorumChip`, deadline, group, connection, author. **Version strip** v1…vn with outcome dots. **Preview card** per platform (char limit badge). **Diff view** (toggle `v`): word diff and structured field changes. Edit mode (editors/authors only) mounts `PostEditor`. A banner for `quorum_unreachable`, `hidden`, or `expired` | preview card markup from `compose/page.tsx:230-245`. The tiptap setup moves from `compose/page.tsx:65-79` into a shared `components/compose/post-editor.tsx`. The key/value diff from `audit/page.tsx:15-40` handles field changes |
+| **Review panel** (w-96) | chat thread (bubbles, system events as centred timeline rows), composer, and a **vote bar** pinned at the bottom: `Approve vN` (primary) / `Deny…` (danger; expands a reason textarea; submit **disabled while `reason.trim()===""`**). It shows "You approved v3 · Retract" after voting, and nothing at all when `capabilities` lacks `vote` | two-pane conversation and bubble layout from `inbox/page.tsx:23-60`. `Avatar` primitive |
+
+**`/approvals/[draftId]`** opens the same page preselected (deep links from the notifier and the audit page).
+
+**`/archive`** (new sidebar item under Review): a virtualised list of published posts with group/platform/date filters, text search (`q` → `ILIKE` on `post->>'text'`, plus a pg_trgm index as future work), and the remote URL. Detail is read-only: the final version, the version history, and the full chat transcript (composer hidden; the "Archived" banner shows the `published_at`). Admins get a `…` menu with **Hide/Unhide** and **Delete**. Delete opens a confirm dialog that requires a reason and typing the first 8 characters of the content hash, with the copy "Removes the content from Tactical Media Broadcast Hub. It does **not** delete the post from <platform>."
+
+**Compose changes (`compose/page.tsx`):**
+- Add a **Group** select (the user's groups; "Workspace (no group)" for legacy). Target chips are filtered to the group's connections.
+- The `Approval` select (`:193-204`) is **removed**. The primary button reads from a new `GET /review/policies/effective?groupId=` → "Submit for review (needs 2)" or "Publish" (exempt).
+- The client-side `approve` chain (`:132`) is **deleted**. The server decides through policy, so the client can no longer self-approve.
+- `STATE_TONE` (`:35-42`) gains `changes_requested: "danger"` and `expired: "neutral"`; `rejected` is removed.
+- "Recent drafts" links to `/approvals/:id`.
+
+**Groups and settings.** No group UI exists in web yet (only API, `groups.controller.ts`). WP5.5 adds a Groups tab on `/team`: members with a **Review role** select (member/editor/reviewer), connections, and a **Review policy** card ("Inherit workspace" toggle, N stepper 0–5, exempt roles multiselect pre-filled empty, blind toggle, stale-after, min-lead). `/settings` gains the workspace review policy card. The role select applies the returned `{token}` via `adoptToken` (`auth-store.ts:31-32`).
+
+### 7.2 Keyboard model (queue-first, same conventions as Streams)
+
+The handler is copied from `streams/page.tsx:68-101`, including its **input/textarea/contentEditable guard (`:74-75`)**, so typing a deny reason never fires shortcuts.
+
+| key | action | gated by |
+|---|---|---|
+| `j` / `↓`, `k` / `↑` | next/prev queue row (`scrollToIndex`, `column.tsx:35-40`) | – |
+| `Enter` / `o` | focus detail | – |
+| `a` | approve the **rendered** version (confirm popover shows `vN · hash[0:8]`; `Enter` confirms) | `vote` |
+| `d` | open the deny reason box (focus); `⌘/Ctrl+Enter` submits; `Esc` cancels | `vote` |
+| `r` | retract my approval | live own approval |
+| `c` | focus chat composer | `comment` |
+| `e` | edit mode | `edit` |
+| `v` | toggle diff | – |
+| `[` / `]` | previous/next version | – |
+| `f` / `F` | cycle filter forward/back | – |
+| `?` | shortcut sheet | – |
+
+Shortcuts render from `capabilities` only. A key whose capability is missing shows a toast with the reason ("You authored this post — someone else must approve it"), mirroring the Streams capability toasts (`streams/page.tsx:83-95`).
+
+### 7.3 Empty, offline, and error states
+- Sample mode: `useApiResource` falls back to fixtures (`use-api.ts:53-57`), so the queue shows fixture rows and an `OfflineBadge`, and vote buttons are disabled with "Offline — sample mode".
+- `409 VERSION_STALE`: an inline banner "v4 was sealed while you were reading — review the changes", with the diff opened against v3.
+- `401` epoch stale: the client reissues and retries once, and the pending reason text is preserved in component state (§8 E7).
+
+### 7.4 Archive and moderation semantics (R7)
+- **Archive** is derived: `state='published'` and not deleted. It isn't a separate state, because the scheduler is the only writer of terminal publication state (`publish.activity.ts:181-184`). A second "archive" hop would add a failure point and no information. Published drafts are already immutable (guard trigger), and comments are refused on them, so "read-only, chat preserved" holds by construction.
+- **Scope:** both actions apply to **all** states (working posts and archive). Hiding a pending scheduled post cancels the schedule first (M1). Purging an `in_flight` post is refused (409) because the platform write can't be undone.
+- **Hide** (`draft.hide`): sets `hidden_at/by/reason`. Members get 404 everywhere (list, detail, SSE, archive) through `review_capabilities` returning `{}`. Admins see a "Hidden" badge and the `hidden` queue filter. A hidden draft is frozen (trigger), and the sweeper skips it. Unhide re-applies any due expiry.
+- **Delete = tombstone + content purge**, not hard delete:
+  - `drafts.post := '{}'`, `deleted_at/by/reason` set.
+  - every `draft_versions.content := NULL` (`purged_at`; **hashes kept**).
+  - every comment `body := NULL` (redacted).
+  - every vote `reason := NULL` (`reason_redacted_at`).
+  - every chat event carrying free text (`vote_denied`, `override_approved`, `review_restarted`) gets its `event` replaced by `{type, redacted: true}` (the message guard allows this only together with `redacted_at`).
+  - any pending schedule deleted.
+  - audit `draft.purged {versionHashes:[…], messagesRedacted, votesRedacted}`.
+
+  Why not hard delete:
+  - `publications.draft_id … ON DELETE CASCADE` (`006_publishing.sql:30`) would erase the record that something was published to a platform.
+  - Audit `target_id`s would dangle, and the vote and approval record would vanish.
+
+  The tombstone keeps "who approved which hash and when" (compliance) while removing the content (the user's intent). Remote retraction is future work, through the existing reserved `publication.delete`.
+- **Audit never holds content.** New events store hashes, ids, and decisions. Deny reasons are stored in audit only as `reasonSha256` + `reasonLength`, so a purge really does remove the words, while the chain (v2, §2.2) still proves a reasoned deny happened.
+
+---
+
+## 8. Edge cases (each with a concrete resolution)
+
+| # | case | resolution |
+|---|---|---|
+| E1 | **Reviewer removed from the group (or workspace) mid-review** | `trg_group_member_review_reconcile` / `trg_membership_review_reconcile` revoke their live votes on `in_review` current versions in the same tx (`cause` = `membership_changed`/`role_changed`), with a chat `vote_revoked` and audit `review.vote_revoked` (actor `sp_review`). The quorum count already excludes them live (`review_quorum`). If `eligible < required` now holds, a `quorum_unreachable` event fires. **Approvals on already-approved or scheduled posts stand**: they were valid when cast. Admins use **restart review** (T10) if the removal was for cause. |
+| E2 | Reviewer's **workspace role** changes to one without `draft.view`/`approval.grant` | same as E1 through the memberships trigger, `cause='role_changed'`. |
+| E3 | **Deadline race**: quorum at T-1 min, T+0.5 s, or exactly T | Q7 and R4: the lock + `clock_timestamp()` check in the vote tx. Before T → auto-scheduled with the remaining delay. At or after T → the vote tx expires the draft and returns `REVIEW_EXPIRED`. The claim gate makes publishing an unapproved post impossible even if the sweeper is down. `min_lead` (2 min) stops submissions that would expire on arrival (`SCHEDULE_TOO_SOON`). |
+| E4 | **Deadlock: author is the only reviewer / too few reviewers** | Q8: submission is allowed and flagged `quorum_unreachable` (banner, chat, notifier to OA). Exits: add a reviewer (live), override by a non-contributing admin, or change policy + restart. A solo Owner is exempt by default. |
+| E5 | **Admin authors a post and tries to override it** | refused: override excludes contributors (`review_capabilities`, §4.4). They must use the exemption policy or another admin. |
+| E6 | **Editor becomes reviewer after editing** | `draft_contributors` keeps them; they're ineligible on that draft forever (`RV001`). They can review other drafts. |
+| E7 | **Epoch churn mid-vote** (someone else's group change bumps the workspace epoch while a reviewer types a deny reason) | Today this logs the reviewer out (D7). New: `POST /auth/reissue` accepts a token whose HMAC is valid and which hasn't expired, re-reads **live** role and status, and mints a token with the **same `expiresAt`** (no TTL extension). A removed user gets 401 and goes to login. `api-client` on a `401` with "authorization epoch stale" calls reissue once, then retries the original request. Votes are idempotent (§5.1) and comments carry `clientMessageId`, so the retry can't double-post. The reason text lives in React state and survives. If the user's eligibility genuinely changed, the retry returns 403 `REVIEWER_NOT_ELIGIBLE` with a clear message. Open SSE streams get `reauth` and reconnect after reissue. |
+| E8 | **Policy changes mid-round** | captured at seal (Q3). The UI shows "This round requires 2 (policy now 3)" to admins with a **Restart review** button. |
+| E9 | **Edit during scheduled, `in_flight`** | 409 `PUBLISH_IN_FLIGHT`; nothing changes (R7). |
+| E10 | **Concurrent edits by two editors** | `baseRevision`/`baseVersionNo` CAS → 409 `REVISION_CONFLICT` with the server copy. The UI offers "Load theirs / Overwrite (re-applies my text on top of theirs as a new save)". |
+| E11 | **Connection unassigned from the group or deleted mid-review** | Deleted → FK `SET NULL (connection_id)`; submit/release/auto-schedule then fail with `CONNECTION_NOT_IN_GROUP`. Unassigned → the same checks at quorum and release. At claim time the gate fails the schedule with `publish_blocked`. Either way the draft stays `approved`/`scheduled` and the author re-targets through an edit (new round). |
+| E12 | **Group deleted with live reviews** | `review_block_group_delete` → `55006` → 409 `GROUP_HAS_LIVE_REVIEWS` from `GroupsService.deleteGroup` (`groups.service.ts:205-224`). Editing, published, and expired drafts fall back to `group_id NULL` (still visible to OA; their audit keeps the group id). |
+| E13 | **Author leaves the workspace** | drafts stay (`author_user_id` has no cascade, `006_publishing.sql:5`). Editors and OA can still edit, submit, and withdraw (`v_admin`). Group-draft release then needs OA. The author stays excluded from voting (they aren't a member anyway). |
+| E14 | **Deny, then resubmit with no changes** | allowed (a new version with the same hash, 0/N). The chat shows "resubmitted unchanged" (the hash equals the previous one), so the denier sees it plainly. |
+| E15 | **Publish fails after approval** | `scheduled_publications.state='failed'` (`publish.activity.ts:194-205`); the draft stays `scheduled`. The scheduler writes a chat `publish_failed` event. T16 **retry-publish** replaces the failed row for the same approved version. No re-review, since the content is unchanged. |
+| E16 | **Hidden draft whose deadline passes** | frozen: the sweeper skips it. Unhide applies T8 in the same tx if it's due. |
+| E17 | **Multi-target compose (3 platforms)** | one draft per target stays (`UNIQUE(draft_id)` on schedules, `006_publishing.sql:24`; `compose/page.tsx:114-118`), linked by `bundle_id`. The queue groups them visually. Reviewers vote per platform, because per-platform text and limits differ. "Approve all in bundle" is future work. |
+| E18 | **Blind-vote leakage** | counts are visible by design. The audit page shows actors to `audit.view` holders, including the `Approver` role (`002:48-49`). Documented as a UX property (Q10). |
+| E19 | **Legacy self-approved posts** | kept as history, counted in `review.migrated.selfApproved` (Q9). New self-approval is impossible. |
+| E20 | **Very long-lived review** | `stale_after` (default 30 d, max 90 d) → `expired(stale)`. This matches the research's "90-day auto-reject" but is configurable lower. |
+
+---
+
+## 9. Audit & security
+
+### 9.1 Event catalogue
+
+All of these are written with `audit_append` on the **same tenant client** as the change (`groups.service.ts:123-133` style), which fixes D4 for review paths. `targetType` is `"draft"` unless noted. Diff keys must never contain `password|secret|token|key|credential|stream_key|refresh`, because `scrub()` would redact them (`audit.service.ts:9-18`). For example, it's `idempotency`, not `idempotencyKey`.
+
+| action | actor | diff |
+|---|---|---|
+| `draft.created` (exists) | user | `{state, groupId, connectionId}` |
+| `draft.updated` (exists) | user | `{state, revision}`. No content |
+| `draft.submitted` (exists) | user | `{from, to, versionNo, contentHash, required, eligible, policySource, reviewMode}` |
+| `draft.version_sealed` | user | `{versionNo, contentHash, prevVersionNo, prevContentHash, sealKind, dismissedVoteIds}` |
+| `review.vote_cast` | reviewer | `{versionNo, contentHash, decision, reasonSha256?, reasonLength?}` |
+| `review.vote_retracted` | reviewer | `{voteId, versionNo}` |
+| `review.vote_revoked` | `sp_review` (NULL user) | `{voteId, versionId, reviewerUserId, cause}` |
+| `draft.approved` (exists) | `sp_review` | `{from, to, versionNo, contentHash, approvals, required, voterIds, reviewMode}`; exempt adds `sealerRole` |
+| `draft.changes_requested` | reviewer | `{versionNo, contentHash, deniedBy}` |
+| `draft.withdrawn` · `draft.reopened` | user | `{from, to, versionNo}` |
+| `draft.expired` | `sp_scheduler` / `sp_review` | `{versionNo, reason, deadlineAt}` |
+| `review.override_approved` | admin | `{versionNo, contentHash, approvalsAtOverride, required, reasonSha256, reasonLength}` |
+| `review.restarted` | admin | `{fromVersionNo, toVersionNo, contentHash, reasonSha256}` |
+| `review.quorum_unreachable` | `sp_review` | `{versionNo, required, eligible}` |
+| `publication.scheduled` (exists) | user / `sp_review` | adds `{versionNo, contentHash, auto}` |
+| `publication.retried` · `publication.blocked` | user / `sp_scheduler` | `{idempotency, reason?}` |
+| `publication.published` (exists) | `sp_scheduler` | adds `{contentHash}` |
+| `review.policy_changed` (target `group` or `workspace`) | admin | `{scope, groupId, before, after}` |
+| `group.member_review_role_changed` (target `group`) | admin | `{userId, reviewRole:[before, after]}` |
+| `draft.hidden` · `draft.unhidden` | admin | `{reasonSha256, cancelledSchedule}` |
+| `draft.purged` | admin | `{versionHashes, messagesRedacted, votesRedacted, reasonSha256}` |
+| `review.message_redacted` (target `review_message`) | admin | `{draftId, seq}` |
+| `review.migrated` (target `workspace`) | `sp_migration` | `{versions, votes, selfApproved}` |
+
+Comments aren't individually audited (volume). They're append-only by trigger, and only their **redaction** is audited.
+
+### 9.2 Chain integration
+- `010` makes the chain cover `diff` (D3). After it, `contentHash`, `decision`, and `voterIds` are tamper-evident through `audit_verify_chain`. Without 010, R4's "snapshot hash in audit log" would be decorative.
+- The same-tx `audit_append` means a vote and its audit row commit or roll back together.
+- The chain head is a per-workspace hotspot: `audit_append` reads the last hash (`001:114-115`) under READ COMMITTED, so **two concurrent appends can fork the chain** (both read the same `prev`). This is pre-existing, but review adds high-concurrency appends (parallel votes). **Mitigation proposed in 010:** `audit_append` takes `pg_advisory_xact_lock(hashtext('audit:' || p_workspace_id))` before reading the head. The lock is transaction-scoped and released at commit, so appends to one workspace serialise. That's cheap at this volume.
+
+### 9.3 RLS and tenancy notes
+- All 5 new tables: `ENABLE` + `FORCE` RLS, `tenant_isolation` USING + WITH CHECK, workspace-immutability trigger, explicit grants, and `DELETE` revoked on history tables.
+- Composite FKs (`(x_id, workspace_id)`) make cross-tenant references impossible even through FK checks, which bypass RLS (the comment at `publishing.service.ts:217-218` notes the same hazard).
+- The review functions are SECURITY INVOKER, so they see only the caller's tenant. The only DEFINER is `review_due_expiries()`, which returns ids only and is then followed by tenant-scoped work. It shares `publishing_due_schedules`'s assumption that the function owner bypasses RLS (superuser/owner in migrations, `003_app_role.sql:1-4`). **A production owner that isn't a superuser would see zero rows under FORCE RLS**, which is pre-existing for 006 as well. That's flagged in Risks.
+- Hidden and foreign-group drafts return **404, not 403** (no existence oracle).
+- `review_capabilities` reads the role from `memberships`, **never from the token** (same principle as `userCanUseConnection`, `groups.service.ts:443-446`).
+- SSE scope caching is sound only because every input to it bumps the epoch (§6.3).
+
+---
+
+## 10. Phased implementation plan
+
+Each WP lands green on `typecheck + vitest + integration` before the next one starts. These are the same gates the repo used for WP3 and Level 2.
+
+| WP | scope | test gate (see §11) |
+|---|---|---|
+| **5.0 Prereqs** (S) | D1 claim gate + `{skipped}` non-retryable (D2). `010_audit_hash_v2.sql` + advisory lock. Publishing transitions → same-tx audit (D4). `POST /auth/reissue` + `api-client` retry (D7). `schedule` rejects connections outside the user's groups (D5) | T7, chain-verify test, reissue test (removed user → 401; TTL not extended) |
+| **5.1 Schema** (M) | `011_review_workflow.sql` complete (§2.3). TS types (§2.4). `PublishingService` keeps working on the new columns (legacy path) | T9, T10, trigger unit tests via direct SQL as `sp_app` |
+| **5.2 Review service** (L) | `apps/api/src/review/`: seal / vote / retract / deny / withdraw / reopen / override / restart / release / retry. `RequireDraftCapability`. Policies API. `PATCH group member reviewRole`. Error contract §5.7. Compat shims for `/approve`, `/reject` | T1–T5 |
+| **5.3 Scheduler integration** (M) | auto-schedule at quorum, claim from version, expiry sweeper + expiring-soon hook, `published`/`publish_failed` chat events | T6, T7 (extended) |
+| **5.4 Chat + realtime** (M) | messages API, `ReviewEventHub` (LISTEN), SSE route, client reader + polling fallback, blind redaction, notifier port (noop) | ordering test (100 concurrent comments → gapless seq), SSE reauth-on-epoch test, blind-redaction test |
+| **5.5 UI** (L) | `/approvals` 3-pane, keyboard model, compose changes, `PostEditor` extraction, Groups tab with review roles and policy, workspace policy settings | Playwright smoke: j/k nav, deny button disabled without reason, quorum chip updates on a second user's vote (two browser contexts), sample mode renders |
+| **5.6 Archive + moderation** (M) | archive API/UI, hide/unhide, purge, message redaction | T8 |
+| **5.7 Cleanup** (S) | stop writing `reviewer_user_id`; migration `012` drops it after web stops reading it; metrics queries (cycle time, approvals per reviewer) documented for analytics | full regression |
+
+Critical path: 5.0 → 5.1 → 5.2 → (5.3 ∥ 5.4) → 5.5 → 5.6. WP5.6's backend can run in parallel with 5.5.
+
+---
+
+## 11. Test plan — the 10 tests that catch the worst regressions
+
+All are integration tests against Postgres as `sp_app` (pattern: `apps/api/src/groups/groups.integration.test.ts`, `db/tenancy.integration.test.ts`) unless marked unit.
+
+1. **Self-approval is structurally impossible.** Author, an editor who saved content, and a former editor promoted to reviewer each `POST …/votes` → 403 `SELF_APPROVAL_FORBIDDEN`. Then, **bypassing the service**, a raw `INSERT INTO review_votes` as `sp_app` for the author raises `RV001`. An admin who edited the draft gets no `override` capability, and a direct override call returns 403.
+2. **Quorum N=2 happy path with auto-schedule.** Group policy N=2, `scheduledAt = now+10 min`. Reviewer A approves → 1/2 and still `in_review`. Reviewer B approves → `approved` → `scheduled` in the same tx. `scheduled_publications.publish_at = scheduledAt`. The chat has `submitted, vote_approved×2, quorum_reached, scheduled` with seq 1..5. `audit_verify_chain(ws)` is true, and the `draft.approved` diff has both voter ids and the content hash.
+3. **Stale-version vote.** A reviewer GETs v1; an editor PATCHes (seals v2); the reviewer approves `versionId=v1` → 409 `VERSION_STALE`. Quorum for v2 is 0/N, and the v1 approval cast earlier doesn't count toward v2. The `version_sealed` event lists the dismissed voter.
+4. **Deny requires a reason and resets the round.** Empty or whitespace reason → 400. A raw insert of a deny with a NULL reason fails the CHECK. A valid deny → `changes_requested`, and the reason is visible in chat to the author. Resubmit → v2 at 0/N. The legacy `/reject` without a reason → 400.
+5. **Reviewer removal mid-review, plus no deadlock.** A 1/2 approval, then `removeMember(reviewer)` → the vote is revoked (`membership_changed`), the quorum is 0/2, and a `vote_revoked` chat row and audit row exist in the same tx as `group.member_removed`. **Concurrency:** 50 iterations of `Promise.all([castVote(R), removeMember(R)])` → no `40P01` deadlock, and each run ends either with the vote revoked or the vote refused (never a live vote from a non-member).
+6. **Deadline race.** `scheduledAt = now + min_lead + 1 s` (test policy `min_lead = 0`). A 1/2 approval, then wait past the deadline, then the final approve → 409 `REVIEW_EXPIRED`, state `expired`, no `scheduled_publications` row. **Concurrency:** run the sweeper's expire and the final vote in parallel 50× → exactly one of {`approved`, `expired`} per run, never both, never `published`.
+7. **The claim gate publishes only the approved bytes.** (a) A raw `UPDATE drafts SET post = …` on a `scheduled` draft is rejected by the trigger. (b) A test-only owner connection forces `drafts.state='approved'` while a pending schedule exists; `claim` returns `{skipped}` and the connector's `publish` is never called. (c) The happy path: the connector receives `draft_versions.content->'post'` of the approved version, and the published diff hash equals the vote's `content_hash`. (d) Unassign the connection from the group after scheduling → the claim marks the schedule failed with `publish_blocked`.
+8. **Hide and purge.** A hidden draft is 404 for a group member on detail, queue, archive, and messages, and the SSE stream gets no doorbell for it. Admins see it. Hiding a scheduled draft deletes the pending schedule. Purge: the version content is NULL but the hashes remain, comment bodies and vote reasons are NULL, the `publications` row still exists, `audit_verify_chain` is true, and a non-admin `DELETE` gets 403. A raw `DELETE FROM drafts` as `sp_app` fails with a permission error.
+9. **Tenancy and RLS on every new table.** With tenant B's context, `SELECT` from each of the 5 tables returns 0 rows of tenant A. An insert with A's `workspace_id` fails WITH CHECK. A `drafts.group_id` from another tenant fails the composite FK. Changing `workspace_id` on any new row raises `23514`. `review_due_expiries()` returns ids only, and `review_capabilities` for a user from another tenant returns `{}`.
+10. **Migration backfill fidelity.** Seed a fixture DB at migration 009 with drafts in every legacy state: `rejected` with a reason in audit, `rejected` without one, an `approved` self-approved draft, a `published` draft with a publication, and an `in_review` draft with a past `scheduledAt`. Run 010+011, then assert:
+    - states are mapped and versions/votes exist with matching hashes
+    - `review_quorum` is consistent
+    - the `review.migrated` counts are right (`selfApproved=1`)
+    - the `in_review` draft's deadline is now+30 d, not the past `scheduledAt`
+    - the triggers are active afterwards (a raw illegal transition fails)
+    - **legacy flows still work:** an Owner composes and publishes in one click (exempt), and a Publisher's draft needs an Approver (1/1), with the Publisher unable to approve it.
+
+Additional fast unit tests: the word diff (`review.diff.ts`), blind redaction in the serializer, policy precedence (`review_effective_policy` group → workspace → default), and the SSE line parser.
+
+---
+
+## Confidence & risks
+
+**Most confident:** the sealed-version + claim-gate core (§5.5). It's small, it's enforced in SQL, and it closes a hole (D1) that exists today regardless of this feature. Same for the lock-order analysis (§5.6), which is mechanical once you see that the chat `seq` bump touches the draft row.
+
+**Least sure, in order. A prototype should validate these first:**
+
+1. **Trigger weight on hot paths.** `review_eligible_reviewers` runs inside `review_vote_guard`, `review_quorum`, `review_capabilities` (on every guarded request), and `review_reconcile_votes` (once per in-review draft on every membership change). It's fine for groups of tens; untested for workspaces with hundreds of in-review drafts. **Prototype:** seed 500 in-review drafts and 50 reviewers, then measure `removeMember` latency and `GET /publishing/queue?filter=needs_my_review` p95. Fallback: materialise eligibility into a per-version `review_eligibility` table refreshed by the same triggers.
+2. **The epoch is workspace-wide (D7).** Every review-role change still invalidates every session in the workspace. `/auth/reissue` makes that survivable, but it's a security-relevant endpoint, and it changes the "re-authenticate" contract stated in `session.ts:3-8`. It needs an explicit security review: reissue must re-read the live role and status, must not extend `expiresAt`, and should be rate-limited. The longer-term fix (per-user epochs) is out of scope.
+3. **Audit hash v2 + advisory lock (010)** touches `001`'s core functions. If any external tool recomputes hashes with the v1 formula, it breaks for new rows. The fork-on-concurrent-append issue (§9.2) should be confirmed with a stress test **before** adding the lock, so the change is justified by evidence.
+4. **SECURITY DEFINER owner assumption.** `review_due_expiries` (like `publishing_due_schedules`) only works if the function owner bypasses FORCE RLS. Confirm the production migration role. If it isn't a superuser, both sweepers silently return nothing, and the fix is an owner with `BYPASSRLS` used only for these functions.
+5. **Exempt-by-default for Owner/Admin.** This preserves today's behaviour and solo workspaces, but a reader of R2 might see it as a loophole. It's a product call. The alternative is a strict default (`exempt_roles = {}`) plus a migration banner. I chose compatibility. Confirm with the user.
+6. **Group drafts publish on quorum even if the author lacks `publication.*`** (§4.4). That's intended ("the group's approval is the authority"), but it's a real change in who can cause publication. Confirm with the user.
+7. **`REVOKE DELETE ON drafts`** may break existing tests that clean up as `sp_app`. Check `publishing.service.test.ts` and the integration fixtures. They should clean up as the owner or through workspace deletion.
+8. **`ON DELETE SET NULL (col)`** needs PG ≥ 15. The repo says Postgres 16; confirm in `docker-compose` or CI before relying on it.
+9. **SSE through the deployment's proxy.** Buffering (nginx `proxy_buffering`) and idle timeouts can silently break streams. The 25 s heartbeat plus polling fallback cover correctness, but latency should be checked in the real ingress.
+
+**Prototype first (1–2 days):** migration 011 on a copy of dev data + tests 1, 5, 6, and 7 against it. That exercises triggers, eligibility, lock order, the deadline race, and the claim gate: everything whose failure would be silent. The UI and SSE are conventional by comparison.
diff --git a/docs/design/proposal-sol.md b/docs/design/proposal-sol.md
new file mode 100644
index 0000000..e492bdf
--- /dev/null
+++ b/docs/design/proposal-sol.md
@@ -0,0 +1,588 @@
+# Group Review & Signoff for Posts — design proposal
+
+Status: proposal only. Migration names, endpoints, and types below are proposed, not present code. The current implementation has a single reviewer field and a direct in_review → approved transition, with no vote records [apps/api/migrations/006_publishing.sql:2-12; apps/api/src/publishing/publishing.service.ts:179-205].
+
+## 1. Executive summary
+
+1. A post belongs to exactly one group and one target connection for a review cycle. The existing scheduler already binds one draft to one connection and enforces UNIQUE(draft_id), while Compose expands multiple targets into multiple drafts [apps/api/migrations/006_publishing.sql:14-25; apps/web/src/app/(main)/compose/page.tsx:114-139]. Preserve that unit of approval.
+2. Group members get one explicit editorial role: member, editor, or reviewer. Editors edit and submit; reviewers vote but cannot edit. Workspace Owner/Admin can manage policy, moderate, and use a reasoned override. A post's author can never cast an approval or override it.
+3. Every edit creates a full immutable version. Submission pins one version, target, deadline, and quorum. Editing an in-review or approved post starts a new cycle; old votes remain historical and count for no later submission. This replaces the mutable post plus reviewer_user_id as the authority [apps/api/migrations/006_publishing.sql:6-11].
+4. Any one denial with a trimmed nonempty reason sends the submission to needs_changes. Parallel distinct approvals automatically satisfy a frozen quorum of 2 or 3; the final vote schedules the already specified publication if its deadline is still in the future. A missed deadline expires, with no remote publish.
+5. The review thread is an ordered database event log delivered by SSE. HTTP handles writes. This uses the existing session/epoch gate pattern without pretending the current realtime gateway is a transport: it is an authorization function only [apps/api/src/realtime/gateway.ts:3-31].
+
+### The ten decisions requested in spec §5
+
+**Q1 — Store one role on group_members.** Add review_role text with member/editor/reviewer values and default member. A single role makes editor and reviewer mutually exclusive for a group post, and reuses the existing unique group_id,user_id membership and epoch trigger [apps/api/migrations/008_groups.sql:27-38,75-80]. A separate roles table could support combined duties later but adds a second authorization surface and makes the stated separation easier to violate. Workspace roles remain intact as route admission and administrator authority, not substitutes for a group role; memberships currently has one role per workspace [apps/api/migrations/001_tenants.sql:20-32].
+
+**Q2 — Store full immutable content per version, with a hash.** A hash alone cannot reproduce the exact rendered content or show a trustworthy diff after drafts.post changes. draft_versions therefore holds the complete normalized DraftPost and SHA-256 of canonical JSON plus target ID; review_submissions points to one version. This follows the current JSONB post model [apps/api/migrations/006_publishing.sql:2-11] and gives the renderer an immutable payload. Deduplicated blobs may be future storage work.
+
+**Q3 — Workspace default 2, group override 2 or 3, frozen on submit.** Owner/Admin sets workspaces.review_quorum_default (2 or 3) and optional groups.review_quorum_override. Effective value is COALESCE(group override, workspace default), copied into each submission. This lets a workspace start safely with one setting while sensitive groups require three; later setting changes affect only future submissions. The current groups table has no review policy [apps/api/migrations/008_groups.sql:17-25]. Per-connection policy is future work because a reviewed draft already has one group and target.
+
+**Q4 — SSE for thread delivery, HTTP for mutations.** Use one EventSource connection for the selected post, with replay from a per-draft sequence and a short database polling loop; queue counts refresh by HTTP. SSE is cheaper to wire than a bidirectional WS gateway for a read-heavy thread, while preserving order through a row-locked per-draft sequence. The existing gateway only authorizes stream.view subscriptions and has no transport or topic implementation [apps/api/src/realtime/gateway.ts:3-31]. WS fanout can replace SSE later without changing the event schema.
+
+**Q5 — One denial closes the round.** Denial requires a reason and moves the draft to needs_changes immediately. Already cast approvals remain immutable historical votes, displayed in the thread, but do not count in a resubmission. This is a clear author-facing repair path and avoids publishing content one qualified reviewer explicitly objected to. Majority denial can be a future policy if product evidence calls for it; today's reject reason is optional and only stored in an audit diff [apps/api/src/publishing/publishing.controller.ts:30-32,172-177; apps/api/src/publishing/publishing.service.ts:197-204].
+
+**Q6 — Full reset on edit.** Editing during review or after approval first supersedes the submission, then moves to editing, creates a version, and requires resubmit. Reviewers see a diff from the prior submitted version. Retaining votes for allegedly unchanged fields would need a defensible semantic diff of text, media, visibility, target, and provider metadata; the current post is one JSONB value [apps/api/src/publishing/publishing.service.ts:10-16]. Partial dismissal is future work.
+
+**Q7 — Auto-schedule if quorum lands before the deadline.** The final vote uses database clock time while holding the draft row lock. If clock_timestamp() is before publish_at, create the pending scheduled_publications row in the same transaction; at or after the time, expire and require a new deadline plus fresh submission. A T−1 minute quorum therefore schedules automatically, with no manual reconfirmation. The current Temporal starter can accept startDelay and its pending row is durable [apps/api/src/publishing/publishing.service.ts:82-106,216-245].
+
+**Q8 — Deadlock requires another person.** A sole reviewer who authored the draft cannot vote. A different Owner/Admin may use a reasoned override, which records a separate override action and does not masquerade as a reviewer vote; a sole human admin author also cannot override. The UI offers Invite reviewer / Ask another admin, never a self-approve button. This preserves the four-eyes rule in spec §3 while retaining administrator rescue for small groups.
+
+**Q9 — Grandfather completed old approvals; re-prime unfinished ones.** Backfill version 1 for every existing draft, retain reviewer_user_id as historical metadata only, and record a migration provenance audit event per changed draft. Existing approved/scheduled/published rows remain valid legacy outcomes; do not fabricate multiple votes from one reviewer. Existing in_review and rejected rows become needs_changes and require group assignment, an editor, and a fresh submission. This is honest about the one-reviewer current model [apps/api/migrations/006_publishing.sql:7-10; apps/api/src/publishing/publishing.service.ts:188-205]. The old direct approve/reject routes become compatibility aliases to vote actions only for a valid group submission, never direct state setters.
+
+**Q10 — Show prior votes and identities.** Reviewers see who has approved, denied, or had a vote revoked before voting. The thread already needs system approval events; hiding names there would be inconsistent and would obscure duplicate/reassignment handling. Mitigate peer pressure by making the rendered snapshot and diff the visual focus and requiring an explicit individual confirmation. Blind voting can be tested later as an organization policy, but the audit trail remains attributed.
+
+## 2. Data model and migration 009 sketch
+
+### 2.1 Relational shape
+
+The SQL below is the intended shape for apps/api/migrations/009_group_review.sql. It follows direct workspace_id predicates, FORCE RLS, immutability triggers, composite group FKs, and sp_app grants from 006 and 008 [apps/api/migrations/006_publishing.sql:44-68; apps/api/migrations/008_groups.sql:14-15,66-104]. Run as a migration transaction; backfill existing rows before enabling the final state guard. Values for content_sha256 are calculated from jsonb::text and the target UUID by the database function shown below, rather than trusting client bytes.
+
+    BEGIN;
+    ALTER TABLE workspaces ADD COLUMN review_quorum_default smallint NOT NULL DEFAULT 2
+      CHECK (review_quorum_default IN (2, 3));
+    ALTER TABLE groups ADD COLUMN review_quorum_override smallint
+      CHECK (review_quorum_override IN (2, 3));
+    ALTER TABLE group_members ADD COLUMN review_role text NOT NULL DEFAULT 'member'
+      CHECK (review_role IN ('member', 'editor', 'reviewer'));
+    -- The existing group_members AFTER UPDATE trigger bumps authz_epoch for role changes.
+    ALTER TABLE drafts ADD COLUMN group_id uuid;
+    ALTER TABLE drafts ADD COLUMN review_round integer NOT NULL DEFAULT 0 CHECK (review_round >= 0);
+    ALTER TABLE drafts ADD COLUMN review_event_seq bigint NOT NULL DEFAULT 0 CHECK (review_event_seq >= 0);
+    ALTER TABLE drafts ADD COLUMN hidden_at timestamptz;
+    ALTER TABLE drafts ADD COLUMN hidden_by uuid REFERENCES users(id);
+    ALTER TABLE drafts ADD COLUMN deleted_at timestamptz;
+    ALTER TABLE drafts ADD COLUMN deleted_by uuid REFERENCES users(id);
+    ALTER TABLE drafts ADD CONSTRAINT drafts_id_workspace_key UNIQUE (id, workspace_id);
+    ALTER TABLE drafts ADD CONSTRAINT drafts_group_workspace_fk
+      FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id) ON DELETE RESTRICT;
+    ALTER TABLE drafts DROP CONSTRAINT drafts_state_check; -- resolve actual generated name in migration
+    ALTER TABLE drafts ADD CONSTRAINT drafts_state_check CHECK (state IN
+      ('editing','primed','in_review','needs_changes','approved','scheduled',
+       'published','archived','expired'));
+    ALTER TABLE drafts ADD CONSTRAINT drafts_deleted_hidden_check
+      CHECK (deleted_at IS NULL OR hidden_at IS NOT NULL);
+    ALTER TABLE scheduled_publications ADD COLUMN claim_eligibility_checked_at timestamptz;
+
+    CREATE TABLE draft_versions (
+      id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      draft_id uuid NOT NULL,
+      version_no integer NOT NULL CHECK (version_no > 0),
+      post jsonb NOT NULL,
+      connection_id uuid,
+      content_sha256 text NOT NULL CHECK (content_sha256 ~ '^[0-9a-f]{64}$'),
+      made_by uuid REFERENCES users(id),
+      created_at timestamptz NOT NULL DEFAULT now(),
+      UNIQUE (draft_id, version_no), UNIQUE (id, draft_id, workspace_id),
+      FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE RESTRICT,
+      FOREIGN KEY (connection_id, workspace_id) REFERENCES connections(id, workspace_id) ON DELETE RESTRICT
+    );
+    CREATE TABLE review_submissions (
+      id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      draft_id uuid NOT NULL,
+      group_id uuid NOT NULL,
+      round integer NOT NULL CHECK (round > 0),
+      version_id uuid NOT NULL,
+      required_approvals smallint NOT NULL CHECK (required_approvals IN (2, 3)),
+      publish_at timestamptz,
+      status text NOT NULL CHECK (status IN
+        ('primed','in_review','approved','denied','superseded','expired')),
+      submitted_by uuid NOT NULL REFERENCES users(id),
+      submitted_at timestamptz NOT NULL DEFAULT now(),
+      closed_at timestamptz,
+      UNIQUE (draft_id, round), UNIQUE (id, workspace_id),
+      FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE RESTRICT,
+      FOREIGN KEY (group_id, workspace_id) REFERENCES groups(id, workspace_id) ON DELETE RESTRICT,
+      FOREIGN KEY (version_id, draft_id, workspace_id)
+        REFERENCES draft_versions(id, draft_id, workspace_id) ON DELETE RESTRICT
+    );
+    CREATE TABLE review_votes (
+      id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      submission_id uuid NOT NULL,
+      voter_user_id uuid NOT NULL REFERENCES users(id),
+      decision text NOT NULL CHECK (decision IN ('approve','deny')),
+      reason text,
+      snapshot_sha256 text NOT NULL CHECK (snapshot_sha256 ~ '^[0-9a-f]{64}$'),
+      cast_at timestamptz NOT NULL DEFAULT now(),
+      revoked_at timestamptz,
+      revoked_reason text,
+      UNIQUE (submission_id, voter_user_id),
+      CHECK (decision <> 'deny' OR (reason IS NOT NULL AND btrim(reason) <> '')),
+      CHECK (revoked_at IS NULL OR (revoked_reason IS NOT NULL AND btrim(revoked_reason) <> '')),
+      FOREIGN KEY (submission_id, workspace_id)
+        REFERENCES review_submissions(id, workspace_id) ON DELETE RESTRICT
+    );
+    CREATE TABLE review_overrides (
+      id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+      workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      submission_id uuid NOT NULL,
+      admin_user_id uuid NOT NULL REFERENCES users(id),
+      reason text NOT NULL CHECK (btrim(reason) <> ''),
+      snapshot_sha256 text NOT NULL CHECK (snapshot_sha256 ~ '^[0-9a-f]{64}$'),
+      at timestamptz NOT NULL DEFAULT now(),
+      UNIQUE (submission_id),
+      FOREIGN KEY (submission_id, workspace_id)
+        REFERENCES review_submissions(id, workspace_id) ON DELETE RESTRICT
+    );
+    CREATE TABLE review_events (
+      workspace_id uuid NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+      draft_id uuid NOT NULL,
+      seq bigint NOT NULL CHECK (seq > 0),
+      submission_id uuid,
+      kind text NOT NULL CHECK (kind IN
+        ('message','submitted','edited','approved','denied','vote_revoked',
+         'quorum_met','quorum_lost','needs_changes','scheduled','expired','published','archived',
+         'hidden','unhidden','deleted','override')),
+      actor_user_id uuid REFERENCES users(id),
+      body text,
+      data jsonb NOT NULL DEFAULT '{}',
+      at timestamptz NOT NULL DEFAULT now(),
+      PRIMARY KEY (draft_id, seq),
+      FOREIGN KEY (draft_id, workspace_id) REFERENCES drafts(id, workspace_id) ON DELETE RESTRICT,
+      FOREIGN KEY (submission_id, workspace_id)
+        REFERENCES review_submissions(id, workspace_id) ON DELETE RESTRICT,
+      CHECK (kind <> 'message' OR (body IS NOT NULL AND btrim(body) <> ''))
+    );
+    CREATE INDEX drafts_review_queue ON drafts (workspace_id, group_id, state, updated_at DESC, id)
+      WHERE deleted_at IS NULL;
+    CREATE INDEX review_submissions_due ON review_submissions (publish_at, id)
+      WHERE status = 'in_review' AND publish_at IS NOT NULL;
+    CREATE INDEX review_votes_live ON review_votes (submission_id, voter_user_id)
+      WHERE revoked_at IS NULL AND decision = 'approve';
+    CREATE INDEX review_events_replay ON review_events (workspace_id, draft_id, seq);
+
+    CREATE FUNCTION review_content_hash(p_post jsonb, p_connection_id uuid) RETURNS text
+    LANGUAGE sql IMMUTABLE AS $$
+      SELECT encode(digest(p_post::text || '|' || coalesce(p_connection_id::text, 'unassigned'), 'sha256'), 'hex')
+    $$;
+    REVOKE ALL ON FUNCTION review_content_hash(jsonb, uuid) FROM PUBLIC;
+    GRANT EXECUTE ON FUNCTION review_content_hash(jsonb, uuid) TO sp_app;
+
+    CREATE FUNCTION review_version_sealed() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      IF TG_OP <> 'INSERT' THEN
+        RAISE EXCEPTION 'draft versions are immutable' USING ERRCODE = '23514';
+      END IF;
+      IF NEW.content_sha256 <> review_content_hash(NEW.post, NEW.connection_id) THEN
+        RAISE EXCEPTION 'version hash mismatch' USING ERRCODE = '23514';
+      END IF;
+      IF NEW.connection_id IS NULL AND EXISTS
+        (SELECT 1 FROM drafts WHERE id = NEW.draft_id AND group_id IS NOT NULL) THEN
+        RAISE EXCEPTION 'review version needs a target connection' USING ERRCODE = '23514';
+      END IF;
+      RETURN NEW;
+    END $$;
+    CREATE TRIGGER trg_draft_version_sealed BEFORE INSERT OR UPDATE OR DELETE ON draft_versions
+      FOR EACH ROW EXECUTE FUNCTION review_version_sealed();
+    CREATE FUNCTION review_vote_frozen() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      IF TG_OP = 'DELETE' OR
+         (TG_OP = 'UPDATE' AND ((NEW.id, NEW.workspace_id, NEW.cast_at,
+           NEW.decision, NEW.reason, NEW.snapshot_sha256,
+           NEW.voter_user_id, NEW.submission_id) IS DISTINCT FROM
+           (OLD.id, OLD.workspace_id, OLD.cast_at,
+           OLD.decision, OLD.reason, OLD.snapshot_sha256,
+           OLD.voter_user_id, OLD.submission_id) OR
+           OLD.revoked_at IS NOT NULL OR NEW.revoked_at IS NULL)) THEN
+        RAISE EXCEPTION 'vote decision is immutable' USING ERRCODE = '23514';
+      END IF;
+      RETURN COALESCE(NEW, OLD);
+    END $$;
+    CREATE TRIGGER trg_review_vote_frozen BEFORE UPDATE OR DELETE ON review_votes
+      FOR EACH ROW EXECUTE FUNCTION review_vote_frozen();
+    CREATE FUNCTION review_reject_update_delete() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      RAISE EXCEPTION 'review evidence is append-only' USING ERRCODE = '23514';
+    END $$;
+    CREATE TRIGGER trg_review_override_sealed BEFORE UPDATE OR DELETE ON review_overrides
+      FOR EACH ROW EXECUTE FUNCTION review_reject_update_delete();
+    CREATE TRIGGER trg_review_event_sealed BEFORE UPDATE OR DELETE ON review_events
+      FOR EACH ROW EXECUTE FUNCTION review_reject_update_delete();
+    CREATE TRIGGER trg_draft_version_ws_immutable BEFORE UPDATE ON draft_versions
+      FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+    CREATE TRIGGER trg_review_submission_ws_immutable BEFORE UPDATE ON review_submissions
+      FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+    CREATE TRIGGER trg_review_vote_ws_immutable BEFORE UPDATE ON review_votes
+      FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+    CREATE TRIGGER trg_review_override_ws_immutable BEFORE UPDATE ON review_overrides
+      FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+    CREATE TRIGGER trg_review_event_ws_immutable BEFORE UPDATE ON review_events
+      FOR EACH ROW EXECUTE FUNCTION reject_workspace_change();
+    ALTER TABLE draft_versions ENABLE ROW LEVEL SECURITY;
+    ALTER TABLE review_submissions ENABLE ROW LEVEL SECURITY;
+    ALTER TABLE review_votes ENABLE ROW LEVEL SECURITY;
+    ALTER TABLE review_overrides ENABLE ROW LEVEL SECURITY;
+    ALTER TABLE review_events ENABLE ROW LEVEL SECURITY;
+    ALTER TABLE draft_versions FORCE ROW LEVEL SECURITY;
+    ALTER TABLE review_submissions FORCE ROW LEVEL SECURITY;
+    ALTER TABLE review_votes FORCE ROW LEVEL SECURITY;
+    ALTER TABLE review_overrides FORCE ROW LEVEL SECURITY;
+    ALTER TABLE review_events FORCE ROW LEVEL SECURITY;
+    CREATE POLICY tenant_isolation ON draft_versions
+      USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+      WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+    CREATE POLICY tenant_isolation ON review_submissions
+      USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+      WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+    CREATE POLICY tenant_isolation ON review_votes
+      USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+      WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+    CREATE POLICY tenant_isolation ON review_overrides
+      USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+      WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+    CREATE POLICY tenant_isolation ON review_events
+      USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+      WITH CHECK (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid);
+    GRANT SELECT, INSERT, UPDATE, DELETE ON draft_versions, review_submissions,
+      review_votes, review_overrides, review_events TO sp_app;
+    COMMIT;
+
+The ALTER that drops the old state check must discover its generated PostgreSQL name during migration, or 006 should first be inspected with pg_constraint. All new mutable tenant tables have the same trigger, FORCE RLS policy, and grants as 006. draft_versions is append-only despite UPDATE/DELETE grants because its trigger rejects those operations. A later migration may narrow grants after existing runtime role assumptions are checked. Current audit_append is SECURITY DEFINER and asserts app.workspace_id, so new services invoke it on their withTenant client [apps/api/migrations/001_tenants.sql:72-86,100-121; apps/api/src/db/client.ts:11-33].
+
+### 2.2 Additional database guards and backfill
+
+009 also installs a drafts BEFORE UPDATE trigger named enforce_review_transition. It rejects any state pair outside the table in §3; rejects post/group changes except while entering or in editing; rejects approved unless the latest active submission has valid distinct approvals at its frozen required_approvals or a non-author admin override row; rejects scheduled unless the row's version hash still matches drafts.post; and rejects published unless a same-draft schedule is done. Its SQL predicate for a valid approval is a count of review_votes joined to active memberships and group_members(review_role='reviewer'), excluding revoked_at, the draft author, and any vote whose snapshot_sha256 differs from the submission version. A legacy row with group_id IS NULL is exempt only for approved/scheduled/published → later legacy states, and cannot enter a new review without group assignment. This is the database half of the state machine; service-side checks return useful 400/403/409 errors. The scheduler currently updates a draft to published without checking the affected row count, so that call must assert one row and roll back on failure [apps/scheduler/src/activities/publish.activity.ts:158-190].
+
+The security-critical predicate and trigger shape are:
+
+    CREATE FUNCTION review_valid_approval_count(p_submission uuid) RETURNS integer
+    LANGUAGE sql STABLE AS $$
+      SELECT count(DISTINCT v.voter_user_id)::integer
+      FROM review_votes v
+      JOIN review_submissions s ON s.id = v.submission_id
+      JOIN draft_versions ver ON ver.id = s.version_id
+      JOIN drafts d ON d.id = s.draft_id
+      JOIN memberships m ON m.workspace_id = s.workspace_id
+        AND m.user_id = v.voter_user_id AND m.status = 'active'
+      JOIN group_members gm ON gm.group_id = s.group_id
+        AND gm.user_id = v.voter_user_id AND gm.review_role = 'reviewer'
+      WHERE s.id = p_submission AND v.decision = 'approve'
+        AND v.revoked_at IS NULL AND v.voter_user_id <> d.author_user_id
+        AND v.snapshot_sha256 = ver.content_sha256
+    $$;
+    REVOKE ALL ON FUNCTION review_valid_approval_count(uuid) FROM PUBLIC;
+    GRANT EXECUTE ON FUNCTION review_valid_approval_count(uuid) TO sp_app;
+    CREATE FUNCTION review_vote_eligible() RETURNS trigger LANGUAGE plpgsql AS $$
+    DECLARE v_author uuid; v_hash text; v_state text; v_group uuid;
+    BEGIN
+      SELECT d.author_user_id, ver.content_sha256, d.state, s.group_id
+        INTO v_author, v_hash, v_state, v_group
+      FROM review_submissions s JOIN drafts d ON d.id = s.draft_id
+      JOIN draft_versions ver ON ver.id = s.version_id
+      WHERE s.id = NEW.submission_id AND s.workspace_id = NEW.workspace_id;
+      IF v_state <> 'in_review' OR v_author = NEW.voter_user_id OR
+         v_hash IS DISTINCT FROM NEW.snapshot_sha256 OR
+         NOT EXISTS (SELECT 1 FROM memberships m JOIN group_members gm
+           ON gm.workspace_id = m.workspace_id AND gm.user_id = m.user_id
+           WHERE m.workspace_id = NEW.workspace_id AND m.user_id = NEW.voter_user_id
+             AND m.status = 'active' AND gm.group_id = v_group
+             AND gm.review_role = 'reviewer') THEN
+        RAISE EXCEPTION 'ineligible or stale review vote' USING ERRCODE = '23514';
+      END IF;
+      RETURN NEW;
+    END $$;
+    CREATE TRIGGER trg_review_vote_eligible BEFORE INSERT ON review_votes
+      FOR EACH ROW EXECUTE FUNCTION review_vote_eligible();
+    CREATE FUNCTION review_override_eligible() RETURNS trigger LANGUAGE plpgsql AS $$
+    DECLARE v_author uuid; v_hash text; v_state text;
+    BEGIN
+      SELECT d.author_user_id, ver.content_sha256, d.state
+        INTO v_author, v_hash, v_state
+      FROM review_submissions s JOIN drafts d ON d.id = s.draft_id
+      JOIN draft_versions ver ON ver.id = s.version_id
+      WHERE s.id = NEW.submission_id AND s.workspace_id = NEW.workspace_id;
+      IF v_state <> 'in_review' OR v_author = NEW.admin_user_id OR
+         v_hash IS DISTINCT FROM NEW.snapshot_sha256 OR
+         NOT EXISTS (SELECT 1 FROM memberships m WHERE m.workspace_id = NEW.workspace_id
+           AND m.user_id = NEW.admin_user_id AND m.status = 'active'
+           AND m.role IN ('Owner','Admin')) THEN
+        RAISE EXCEPTION 'ineligible or stale review override' USING ERRCODE = '23514';
+      END IF;
+      RETURN NEW;
+    END $$;
+    CREATE TRIGGER trg_review_override_eligible BEFORE INSERT ON review_overrides
+      FOR EACH ROW EXECUTE FUNCTION review_override_eligible();
+
+The final transition trigger uses the exact allowed (OLD.state,NEW.state) pairs in §3. Its critical branch is:
+
+    CREATE FUNCTION enforce_review_transition() RETURNS trigger LANGUAGE plpgsql AS $$
+    DECLARE v_round review_submissions%ROWTYPE; v_hash text; v_override boolean;
+    BEGIN
+      IF OLD.review_round > 0 AND NEW.group_id IS DISTINCT FROM OLD.group_id THEN
+        RAISE EXCEPTION 'review group is sealed' USING ERRCODE = '23514';
+      END IF;
+      IF NEW.post IS DISTINCT FROM OLD.post AND NEW.state <> 'editing' THEN
+        RAISE EXCEPTION 'post content is sealed outside editing' USING ERRCODE = '23514';
+      END IF;
+      IF NEW.state IS DISTINCT FROM OLD.state AND NOT (
+        (OLD.state, NEW.state) IN (
+          ('editing','primed'), ('needs_changes','primed'), ('expired','primed'),
+          ('primed','in_review'), ('in_review','needs_changes'),
+          ('in_review','approved'), ('in_review','expired'),
+          ('in_review','editing'), ('approved','editing'),
+          ('approved','scheduled'), ('approved','expired'),
+          ('approved','in_review'), ('scheduled','in_review'),
+          ('approved','needs_changes'), ('scheduled','needs_changes'),
+          ('scheduled','approved'), ('scheduled','editing'),
+          ('scheduled','published'), ('published','archived'))
+      ) THEN
+        RAISE EXCEPTION 'illegal review transition' USING ERRCODE = '23514';
+      END IF;
+      IF NEW.group_id IS NOT NULL AND NEW.state IN ('approved','scheduled') THEN
+        SELECT s, ver.content_sha256 INTO v_round, v_hash
+          FROM review_submissions s JOIN draft_versions ver ON ver.id = s.version_id
+          WHERE s.draft_id = NEW.id AND s.round = NEW.review_round;
+        IF NOT FOUND OR v_round.status <> 'approved' OR
+           review_content_hash(NEW.post, (SELECT connection_id FROM draft_versions
+             WHERE id = v_round.version_id)) IS DISTINCT FROM v_hash THEN
+          RAISE EXCEPTION 'approved snapshot missing or changed' USING ERRCODE = '23514';
+        END IF;
+        SELECT EXISTS (SELECT 1 FROM review_overrides o
+          JOIN memberships m ON m.workspace_id = o.workspace_id
+            AND m.user_id = o.admin_user_id AND m.status = 'active'
+            AND m.role IN ('Owner','Admin')
+          WHERE o.submission_id = v_round.id AND o.snapshot_sha256 = v_hash
+            AND o.admin_user_id <> OLD.author_user_id) INTO v_override;
+        IF review_valid_approval_count(v_round.id) < v_round.required_approvals
+           AND NOT v_override THEN
+          RAISE EXCEPTION 'review quorum missing' USING ERRCODE = '23514';
+        END IF;
+      END IF;
+      IF NEW.state = 'published' AND OLD.state = 'scheduled' AND NOT EXISTS
+        (SELECT 1 FROM scheduled_publications sp WHERE sp.draft_id = NEW.id
+          AND sp.state = 'done' AND
+          (NEW.group_id IS NULL OR sp.claim_eligibility_checked_at IS NOT NULL)) THEN
+        RAISE EXCEPTION 'publication not complete' USING ERRCODE = '23514';
+      END IF;
+      RETURN NEW;
+    END $$;
+    CREATE TRIGGER trg_enforce_review_transition BEFORE UPDATE ON drafts
+      FOR EACH ROW EXECUTE FUNCTION enforce_review_transition();
+
+This branch is supplemented by a priming guard that requires a current group/version/connection and by a submission trigger that rejects UPDATE of draft_id, group_id, round, version_id, required_approvals, publish_at, submitted_by, or submitted_at; only status and closed_at may change along the status sequence in §3. Legacy group_id NULL rows are allowed only for their grandfathered approved/scheduled/published transitions. The service writes submission status approved before updating draft state. At claim, the scheduler sets claim_eligibility_checked_at only after its current quorum/hash/target check, then enters in_flight before calling the provider. A later reviewer removal cannot undo that external call; completion validates the claim proof rather than recounting live membership. The scheduler writes schedule state done before publishing, matching its current update order [apps/scheduler/src/activities/publish.activity.ts:177-184].
+
+Backfill one draft_versions row for each draft, taking its current post and its target from providerMetadata.connectionId when present. Existing drafts with no unambiguous target keep NULL connection_id in that legacy version and must choose a target before a new submission; review_version_sealed refuses a NULL target for group drafts. This avoids inventing a target for old multi-target drafts; Compose's saved draft path currently stores targetConnectionIds while the publish path stores connectionId [apps/web/src/app/(main)/compose/page.tsx:108-110,125-127]. On rollout, convert rejected/in_review to needs_changes with a migration audit event; leave approved/scheduled/published grandfathered. Background migration archives already published rows with a distinct publication.archived audit entry. Keep reviewer_user_id read-only historical metadata; never derive quorum from it.
+
+The scheduler's existing publishing_due_schedules() returns pending rows [apps/api/migrations/006_publishing.sql:79-89]. Add narrow SECURITY DEFINER functions, matching publishing_schedule_workspace's restricted grants:
+
+    CREATE FUNCTION review_due_deadlines() RETURNS TABLE(submission_id uuid)
+    LANGUAGE sql VOLATILE SECURITY DEFINER SET search_path = public AS $$
+      SELECT id FROM review_submissions
+      WHERE status = 'in_review' AND publish_at <= clock_timestamp()
+      ORDER BY publish_at, id
+    $$;
+    CREATE FUNCTION review_submission_workspace(p_submission_id uuid) RETURNS uuid
+    LANGUAGE sql STABLE SECURITY DEFINER SET search_path = public AS $$
+      SELECT workspace_id FROM review_submissions WHERE id = p_submission_id
+    $$;
+    REVOKE ALL ON FUNCTION review_due_deadlines() FROM PUBLIC;
+    REVOKE ALL ON FUNCTION review_submission_workspace(uuid) FROM PUBLIC;
+    GRANT EXECUTE ON FUNCTION review_due_deadlines(),
+      review_submission_workspace(uuid) TO sp_app;
+
+A periodic worker uses those functions, enters withTenant, locks the draft, and expires an in_review round whose deadline is at or before DB clock. No pending scheduled_publications row exists until quorum. This avoids making an unapproved post visible to the existing sweeper.
+
+## 3. State machine
+
+Primed is a short, durable state after an editor seals the version and before the server opens review; the same request normally advances primed → in_review. Keeping it visible allows recovery of a transaction interrupted between an external workflow start and the durable submission (Temporal start remains after commit). Published is a short successful result, then archived in the same completion transaction; both transitions get events. The current state CHECK and TS union must be extended together [apps/api/migrations/006_publishing.sql:7-8; apps/api/src/publishing/publishing.service.ts:8; apps/web/src/lib/api-types.ts:64].
+
+| From → to | Initiator | Required guard and action |
+| --- | --- | --- |
+| create → editing | group editor or Owner/Admin | Group and target connection exist in same workspace; group owns connection; create version 1. |
+| editing/needs_changes/expired → primed | editor or Owner/Admin | Lock draft; valid target; nonempty content; at least N eligible non-author reviewers or a declared admin escalation; future deadline if supplied; increment round, snapshot post/target/quorum/deadline. |
+| primed → in_review | service | Same transaction or idempotent recovery; event and audit; no votes yet. |
+| in_review → needs_changes | eligible reviewer | Deny with nonempty reason; close submission denied. |
+| in_review → approved | service | Distinct currently eligible non-author approvals reach frozen quorum before deadline, or non-author admin override with reason. |
+| in_review → expired | deadline worker or final vote | DB clock >= publish_at without quorum; close round, no schedule row. |
+| in_review/approved → editing | editor or Owner/Admin | Supersede round, retain history, clear schedule intent; approved has no active schedule. |
+| approved → scheduled | service or Publisher/Admin | Recount current votes/override; version/target unchanged; connection still assigned; pending schedule insert. If no desired time, authorized Publisher/Admin chooses publish time after approval. |
+| approved → expired | service | Stored desired publish_at passed before scheduling. |
+| scheduled → approved | authorized scheduler-canceller | Only pending schedule, cancel/delete row as current service does [apps/api/src/publishing/publishing.service.ts:248-272]. |
+| approved/scheduled → in_review | membership reconciliation | Quorum lost before remote claim; cancel pending schedule, reopen same sealed round, and preserve remaining votes. |
+| in_review/approved/scheduled → needs_changes | connection/group reconciliation | Target is no longer valid; cancel pending schedule and require editor to choose a valid target and resubmit. |
+| scheduled → editing | editor or Owner/Admin | First cancel pending schedule, then supersede; reject if in_flight/done. |
+| scheduled → published | scheduler | Claim pending only when due, current quorum and hash still valid; remote success; idempotency key matches. |
+| published → archived | scheduler | Same completion transaction, preserving publication row and review history. |
+| any nondeleted → same state, hidden/unhidden | Owner/Admin | Admin moderation; hide applies to working and archive views. |
+| any except in_flight scheduled → tombstoned | Owner/Admin | Admin soft delete with mandatory reason; pending schedule cancelled; no physical cascade. |
+
+No direct editing → approved, needs_changes → approved, or expired → scheduled path exists. A denied post re-enters review only via a new version/submission, even if text is unchanged. A schedule request at a timestamp already passed is rejected; immediate publication is represented by publish_at=clock_timestamp() only after approval. Existing schedule is CAS on approved and inserts one scheduled_publications row [apps/api/src/publishing/publishing.service.ts:216-235].
+
+## 4. RBAC and API contract
+
+The guard currently checks signed session, live workspace authz_epoch, then workspace role_permissions inside withTenant [apps/api/src/rbac/rbac.guard.ts:33-62]. Keep that order. Add RequireReviewGroupAccess(action) as a second decorator, analogous to RequireGroupAccess for connectionId [apps/api/src/rbac/rbac.guard.ts:8-19,64-74]. It reads :draftId or :groupId and performs a tenant-scoped draft/group/active membership check, returning 404 for invisible group drafts. Every write service repeats the check after SELECT ... FOR UPDATE because epoch or group membership may change between guard and mutation.
+
+Exact permission additions to role_permissions (no new workspace role names):
+
+    INSERT INTO role_permissions(role, permission)
+    SELECT r, p FROM unnest(ARRAY[
+      'Owner','Admin','Publisher','Editor','Approver','Analyst','Moderator',
+      'VideoPublisher','StreamOperator','BroadcastOperator']) AS r
+    CROSS JOIN unnest(ARRAY[
+      'review.view','review.comment','review.submit','review.edit','review.vote']) AS p
+    ON CONFLICT DO NOTHING;
+    INSERT INTO role_permissions(role, permission)
+    SELECT r, p FROM unnest(ARRAY['Owner','Admin']) AS r
+    CROSS JOIN unnest(ARRAY[
+      'review.config.manage','review.override','post.hide','post.delete']) AS p
+    ON CONFLICT DO NOTHING;
+
+These route permissions admit an active workspace member to the group-role decision; they do not independently grant editorial actions. This is necessary because group reviewer may currently have any one of the ten workspace roles, while approval.grant today belongs only to Owner/Admin/Approver and approval.request to Owner/Admin/Publisher [apps/api/migrations/002_rbac_seed.sql:4-50]. Keep existing approval.grant/approval.request for legacy callers, but new group review routes require the review.* permission plus exact group role. Group member may view/comment; editor may view/comment/create/edit/submit but cannot vote or schedule/publish; reviewer may view/comment/vote but cannot change content; Owner/Admin may manage policy, hide/delete, and override with a reason. Publisher workspace role alone cannot bypass group role or quorum. The existing publication.schedule permission is still required for manual scheduling after approval; automatic scheduling is a server action caused by the authorized final vote.
+
+Proposed Nest controller shape (each handler also validates DTOs and uses the service transaction):
+
+    @Get('groups/:groupId/review') @RequirePermission('review.view') @RequireReviewGroupAccess('view')
+    listReviewQueue(...): Promise<ReviewQueuePage>;
+    @Post('publishing/drafts/:draftId/prime') @RequirePermission('review.submit') @RequireReviewGroupAccess('submit')
+    prime(...): Promise<ReviewDetail>;
+    @Post('publishing/drafts/:draftId/votes') @RequirePermission('review.vote') @RequireReviewGroupAccess('vote')
+    vote(@Body() dto: { submissionId: string; versionId: string;
+      snapshotSha256: string; decision: 'approve' | 'deny'; reason?: string }): Promise<ReviewDetail>;
+    @Post('publishing/drafts/:draftId/override') @RequirePermission('review.override')
+    override(@Body() dto: { submissionId: string; reason: string }): Promise<ReviewDetail>;
+    @Post('publishing/drafts/:draftId/messages') @RequirePermission('review.comment') @RequireReviewGroupAccess('comment')
+    comment(@Body() dto: { body: string }): Promise<ReviewEvent>;
+    @Patch('publishing/drafts/:draftId/moderation') @RequirePermission('post.hide')
+    setHidden(@Body() dto: { hidden: boolean; reason: string }): Promise<ReviewDetail>;
+    @Delete('publishing/drafts/:draftId') @RequirePermission('post.delete')
+    tombstone(@Body() dto: { reason: string }): Promise<void>;
+
+The new vote endpoint accepts submission/version/hash as optimistic preconditions and returns 409 on mismatch; the server derives actor and role from its session, never request JSON. Self approval is checked in the service AND in a DB vote guard: NEW.voter_user_id <> drafts.author_user_id; the override table/record uses the same exclusion. Reusing the direct current approve endpoint without this change would bypass quorum [apps/api/src/publishing/publishing.controller.ts:91-110]. Group role/policy mutations already bump the workspace epoch through group_members AFTER UPDATE; group settings and connection assignment changes need these additional triggers:
+
+    CREATE TRIGGER trg_group_review_policy_epoch
+      AFTER UPDATE OF review_quorum_override ON groups
+      FOR EACH ROW WHEN (OLD.review_quorum_override IS DISTINCT FROM NEW.review_quorum_override)
+      EXECUTE FUNCTION bump_authz_epoch();
+    CREATE TRIGGER trg_group_connection_review_epoch
+      AFTER INSERT OR DELETE ON group_connections
+      FOR EACH ROW EXECUTE FUNCTION bump_authz_epoch();
+    CREATE FUNCTION bump_review_default_epoch() RETURNS trigger LANGUAGE plpgsql AS $$
+    BEGIN
+      IF NEW.review_quorum_default IS DISTINCT FROM OLD.review_quorum_default THEN
+        NEW.authz_epoch := OLD.authz_epoch + 1;
+      END IF;
+      RETURN NEW;
+    END $$;
+    CREATE TRIGGER trg_workspace_review_default_epoch
+      BEFORE UPDATE OF review_quorum_default ON workspaces
+      FOR EACH ROW EXECUTE FUNCTION bump_review_default_epoch();
+
+These mutations mint the caller a replacement token inside the transaction, matching GroupsService [apps/api/src/groups/groups.service.ts:12-18,226-267].
+
+## 5. Quorum engine and integrity
+
+One submission has one vote per reviewer enforced by UNIQUE(submission_id,voter_user_id). Votes cannot change within that submission; a mistaken decision is handled by an editor resubmission, with a reason and clear history. A denial closes the round immediately. Quorum is COUNT(DISTINCT voter_user_id) among approvals that are unrevoked, from active workspace and reviewer group memberships, excluding the author and matching the sealed hash. The round's required_approvals never changes. Config edits affect the next round. The repository already uses CAS transitions, so the quorum transaction locks the draft row and then writes vote, count, state, review event, and audit entry atomically [apps/api/src/publishing/publishing.service.ts:275-292]. All review votes, role changes, and scheduler claims lock the workspace row first, then draft, then schedule, so an epoch-changing membership mutation and a remote claim have a defined serialization point. A claim that wins the lock may publish; a removal that wins first forces the claim to recheck and fail.
+
+    type VoteInput = {
+      submissionId: string; versionId: string; snapshotSha256: string;
+      decision: 'approve' | 'deny'; reason?: string;
+    };
+    async function castVote(client: PoolClient, draftId: string, actor: Actor, input: VoteInput) {
+      const draft = await lockDraft(client, draftId); // SELECT ... FOR UPDATE
+      assertLiveEpochAndGroupReviewer(client, draft, actor);
+      assert(draft.authorUserId !== actor.userId, 'SELF_APPROVAL_FORBIDDEN');
+      assert(draft.state === 'in_review', 'REVIEW_CLOSED');
+      const round = await activeSubmission(client, draft);
+      assert(round.id === input.submissionId && round.versionId === input.versionId &&
+        round.contentSha256 === input.snapshotSha256, 'STALE_SNAPSHOT');
+      if (round.publishAt !== null && await dbNow(client) >= round.publishAt) return expire(client, draft, round);
+      if (input.decision === 'deny') assert(input.reason?.trim(), 'DENIAL_REASON_REQUIRED');
+      await insertVoteAndEventAndAudit(client, draft, round, actor, input);
+      if (input.decision === 'deny') return closeNeedsChanges(client, draft, round);
+      if (await validApprovalCount(client, round) >= round.requiredApprovals) {
+        await markApprovedAndAudit(client, draft, round);
+        if (round.publishAt !== null) await scheduleIfFuture(client, draft, round);
+      }
+      return readReviewDetail(client, draft.id);
+    }
+
+The hash covers all JSONB post fields and the target connection. The reviewer detail response uses draft_versions.post, never drafts.post, to render the proposed publication; it includes previous submitted version and a structured diff for text, media IDs, visibility, target, and provider metadata. The current scheduler reads d.post at claim time [apps/scheduler/src/activities/publish.activity.ts:133-145]; change that query to join the approved submission/version and use its post. Also require d.state='scheduled', sp.publish_at <= clock_timestamp(), a current quorum/override, and the approved version hash at claim. This is the final guard against edits, role removals, and early Temporal wakeups. Claims must be idempotent and use the pending→in_flight state as today [apps/scheduler/src/activities/publish.activity.ts:133-155].
+
+The review_overrides table in §2 carries a nonempty reason and immutable snapshot hash. It is valid only while the admin retains active Owner/Admin status, is not the author, and the hash matches. It satisfies the approval gate but is labeled Override, never 2/3. One valid denial closes the round before an override can be applied; admin must return the post to an editor for a new submission. A second different admin can rescue a one-reviewer group; no override can waive the self-approval exclusion.
+
+## 6. Review chat and delivery
+
+review_events is the durable, per-post thread. Message bodies are plain text (escape on render), length limited by API to 4,000 characters, and not editable or deletable by ordinary members. System events carry structured IDs, version numbers, hashes, old/new state, reason, and quorum counts in data; do not put secrets or access tokens in it. The current audit scrubber redacts keys matching secret/token/credential, so event-to-audit diff construction must use the same scrub helper [apps/api/src/audit/audit.service.ts:9-18]. Events are written with the state mutation in the same tenant transaction. Increment drafts.review_event_seq under the draft row lock, then insert (draft_id,seq); this serializes commit order per draft and makes Last-Event-ID safe.
+
+SSE endpoint GET /publishing/drafts/:draftId/events uses @RequirePermission('review.view') and group access. It sends rows after a validated integer cursor, then polls for new rows every 2 seconds, heartbeat every 15 seconds, and rechecks live epoch/group access at least each heartbeat; on change it sends auth_revoked and closes. Reconnect fetches the gap with Last-Event-ID. For native EventSource bearer-token limits, use fetch streaming with Authorization: Bearer rather than cookie or token in URL. The server caps replay pages and asks the client to resync detail when cursor is too old. SSE can lag but cannot grant action rights: every vote/comment still crosses RbacGuard and the transaction check. The existing realtime authz port compares epoch but assumes a numeric DB epoch; the new SSE path should normalize bigint as RbacGuard does [apps/api/src/realtime/gateway.ts:19-23; apps/api/src/rbac/rbac.guard.ts:42-47].
+
+System event type shape:
+
+    type ReviewEventKind = 'message' | 'submitted' | 'edited' | 'approved' |
+      'denied' | 'vote_revoked' | 'quorum_met' | 'scheduled' | 'expired' |
+      'published' | 'archived' | 'hidden' | 'unhidden' | 'deleted' | 'override';
+    interface ReviewEvent { draftId: string; seq: number; kind: ReviewEventKind;
+      actorUserId: string | null; submissionId: string | null;
+      body: string | null; data: Record<string, unknown>; at: string; }
+
+## 7. UI plan
+
+Replace the ten-line Approvals stub with a queue/detail surface; Compose remains the editor entry point. Compose already has tiptap, target chips, visibility, a schedule field, and state badges [apps/web/src/app/(main)/compose/page.tsx:65-88,151-220,247-265]. Remove its current create→submit→self-approve→schedule loop for group posts, since it permits an author with approval.grant to approve the post they just created [apps/web/src/app/(main)/compose/page.tsx:114-139]. Creation requires a group and exactly one target per draft; multiple targets produce linked sibling drafts, each independently reviewed. Submit opens the sealed review detail. The schedule field becomes a deadline/desired publish time included in the submission, explicitly labeled; if empty, approved posts await an authorized scheduler.
+
+The queue uses cursor pagination (updated_at DESC,id DESC) and virtual rows via the existing StreamColumn useVirtualizer pattern [apps/web/src/components/streams/column.tsx:28-39,56-78]. Each row shows group, target, preview, state, required/current count, author, due time, and an expired/needs_changes label. Filters: needs my review (eligible, not author, no vote), created by me, needs changes, expiring soon, approved awaiting schedule, and archive. Use j/k and arrow navigation, Enter to open, and preserve focus/scroll on return, following Streams' existing keyboard scheme [apps/web/src/app/(main)/streams/page.tsx:77-80]. Do not bind shortcuts while focus is in Tiptap, an input, or a chat composer.
+
+Detail has the immutable rendered post preview, target/visibility/schedule, version selector and diff, quorum progress with named votes, then the thread with Approve and Deny+reason buttons for eligible reviewers. The buttons submit the displayed submission/version/hash preconditions, disable while pending, and handle 409 by refreshing detail. An editor sees Edit and Resubmit; a reviewer sees no content edit control. Admin controls Hide/Unhide and Delete appear on working and archive posts. Hidden posts are omitted from member queue/archive/search, but admins see a Hidden badge and full record. Archive is read-only for content and comments, with preserved review history and publication link; admin moderation remains available. The current Published state is already a draft state but has no archive UI [apps/api/migrations/006_publishing.sql:7-8; apps/web/src/app/(main)/compose/page.tsx:35-42].
+
+## 8. Edge cases and exact resolutions
+
+| Case | Resolution |
+| --- | --- |
+| Reviewer leaves group or loses reviewer role before quorum | Existing group_members change bumps epoch; a same-transaction reconciliation marks their votes revoked_at/reason, emits vote_revoked and audit entries, then recalculates count. New tokens are minted for the mutator; stale sessions get 401 [apps/api/migrations/008_groups.sql:75-80; apps/api/src/groups/groups.service.ts:226-267]. |
+| Workspace membership is removed/suspended | Membership epoch trigger invalidates sessions [apps/api/migrations/001_tenants.sql:180-192]. Team mutation must call the same reconciliation; claim and every vote independently join active membership, so a missed callback cannot publish. |
+| Quorum had been met, but reviewer leaves before pending schedule claims | Reconciliation cancels a pending schedule, returns scheduled/approved to in_review, emits quorum_lost and audit, and alerts the queue. If claim already set in_flight, its pre-call gate wins; once remote call began, treat completion as published and log the exact eligibility change timestamp. No attempt to pretend a remote publish can be rolled back. |
+| Final vote and deadline worker race | Both lock drafts row. DB clock is checked after lock. Vote first before deadline may schedule; worker later sees approved/scheduled and does nothing. Worker first at/after deadline expires; vote gets REVIEW_CLOSED. |
+| Final vote at T−1 minute | Auto-schedule pending row for T, start Temporal after commit. If Temporal wakes early, claim rejects until publish_at; sweeper picks it up when due. |
+| Quorum arrives at/after deadline | Expire instead of approve. Editor chooses a new future time, creates a new round, and all reviewers vote anew. No auto-publish of stale content. |
+| Author is sole reviewer | Prime is blocked with insufficient independent reviewers, unless a different Owner/Admin is available for reasoned override. The author, even as Owner/Admin, cannot vote/override. |
+| Reviewer goes on vacation | Admin changes group reviewer assignment or adds another group member with reviewer role; epoch invalidates old sessions, pending votes from removed reviewers revoke, and the current round can continue if enough eligible people remain. Delegation is an explicit role change, not token sharing. |
+| Editor changes text/media/visibility/target during review | Action supersedes round and its votes; new immutable version and diff are required. Existing vote requests fail 409. |
+| Editor changes approved post | Reopen to editing; if pending scheduled first cancel it atomically. In_flight/done cannot be reopened; create a new draft instead. |
+| Duplicate vote or concurrent final votes | Unique submission/reviewer plus draft row lock yields one live count and one schedule. Duplicate returns 409 with current detail; retries with an idempotency request key may return prior result. |
+| Epoch changes after guard but before vote | Transaction reads epoch again while holding draft lock and checks active group/role; mismatch fails 401 with no vote. |
+| Group/connection unassigned mid-review | Prime/vote/schedule recheck assignment. On unassignment, active round becomes needs_changes and pending schedule cancels; editor chooses a valid target and resubmits. Existing group_connections mutations currently audit assignment but do not bump epoch, so 009 adds an epoch trigger on that table too [apps/api/src/groups/groups.service.ts:271-314]. |
+| Group deleted with working drafts | New draft group FK uses ON DELETE RESTRICT, so admin must tombstone/reassign drafts first; this deliberately prevents review evidence cascading with group deletion, unlike current group children [apps/api/migrations/008_groups.sql:27-60]. |
+| Hidden or deleted post has a pending schedule | Hide is internal only and does not cancel publication by itself; UI explicitly warns that scheduling continues. Delete cancels pending schedule and tombstones; reject delete if in_flight, and on published archive tombstone only the internal record. Remote provider deletion is a separate future integration. |
+| Scheduler failure after remote call | Preserve current idempotency_key and publication lookup, reconcile by remote result, and never automatically retry with a new key; audit publication.failed and show retry state. Current activity first checks publication by key [apps/scheduler/src/activities/publish.activity.ts:75-90,123-130]. |
+| Old rejected/in_review row | Migration moves to needs_changes and demands group/target selection before prime; never count reviewer_user_id as a vote. |
+
+The same-transaction reconciliation is a change to GroupsService, TeamService, and group connection mutation paths, not a background-only cleanup. DB transition and claim guards remain fail closed even if an application path forgets to call it. For direct SQL/cascades, add an AFTER DELETE/UPDATE trigger on group_members and memberships that invokes a narrow review_reconcile_member(workspace_id,user_id,group_id) function under tenant context; it updates affected vote revocations and pending draft states and appends audit events. Because a cascade can delete the parent before the child trigger runs, the function uses group_members' denormalized OLD.workspace_id and OLD.group_id, following the existing epoch design [apps/api/migrations/008_groups.sql:4-12].
+
+## 9. Audit, moderation, and security
+
+Every state transition, vote, revocation, override, config/role change, message, hide/unhide, and tombstone gets audit_append in the SAME tenant transaction as the corresponding rows, as GroupsService already does [apps/api/src/groups/groups.service.ts:12-13,123-133]. Current PublishingService appends audit after the mutation commits, which leaves a gap; migrate its review paths to same-tx audit [apps/api/src/publishing/publishing.service.ts:127-138,307-322]. Scheduler already appends publication.published in its completion transaction with actor_role sp_scheduler [apps/scheduler/src/activities/publish.activity.ts:158-190]. Never call audit_append_system from a tenant workflow; the DB distinguishes tenant/system by app.workspace_id [apps/api/migrations/001_tenants.sql:88-121,123-144].
+
+Event names: review.primed, review.submitted, review.version_created, review.vote_approved, review.vote_denied, review.vote_revoked, review.quorum_met, review.quorum_lost, review.expired, review.needs_changes, review.overridden, publication.scheduled, publication.schedule_cancelled, publication.published, publication.archived, post.hidden, post.unhidden, post.deleted, review.message_added, review.policy_changed, review.role_changed. Audit diff includes draftId, groupId, round, versionId, contentSha256, target connection ID, frozen quorum, deadline, old/new state, actor and decision/reason when relevant. audit_hash currently chains actor/action/target/time, while diff is stored but not part of the hash input [apps/api/migrations/001_tenants.sql:55-67,92-121]. Prototype should verify whether regulatory expectations require diff integrity; if so, use a separately versioned audit hash migration and verifier, not a silent change to existing hashes.
+
+Moderation is workspace Owner/Admin only, irrespective of group role; new post.hide/post.delete permissions are seeded only to those two roles. Hide toggles hidden_at/hidden_by, keeps all rows and remote content intact, and excludes the post from non-admin list/detail/event endpoints; an admin sees a badge. Soft delete sets deleted_at/deleted_by, hidden_at, reason in audit, cancels pending work, and retains versions, votes, thread, and publication rows for verification. The DELETE HTTP verb therefore means tombstone, not a SQL DELETE. A published post may remain remote, so the UI says Remove from this workspace and does not promise deletion at the provider. Archive remains read-only for normal group members. RLS isolates workspaces; group visibility is an explicit guard/service condition because workspace RLS alone cannot hide another group's draft [apps/api/migrations/006_publishing.sql:58-66; apps/api/migrations/008_groups.sql:91-104].
+
+No API accepts caller-supplied actor role, vote tally, or audit hash. FK checks can bypass RLS, so draft/group/connection lookups must be RLS-scoped before insert, as the current schedule method explains [apps/api/src/publishing/publishing.service.ts:216-220]. The hash and preview are bound to the version; responses use optimistic preconditions. Read endpoints must filter hidden/deleted before loading events. Admin reads are still tenant-scoped.
+
+## 10. Phased implementation plan and gates
+
+1. **WP1 — Migration and compatibility.** Add 009 schema, constraints, RLS, role seed additions, backfill/version hash, and transition guard. Gate: migrate a fixture DB containing all six old states, confirm no fabricated votes, FORCE RLS isolation, valid legacy scheduling, and audit chain verification.
+2. **WP2 — Group policy and authz.** Group role/config endpoints, epoch triggers and replacement tokens, draft group/connection scope, guard decorator. Gate: role matrix, self-approval DB rejection, cross-group 404, stale token 401, and cascade reconciliation.
+3. **WP3 — Snapshot/quorum services.** Prime, edit/resubmit, votes, denial, override, transactional event+audit, version diff API. Gate: concurrent last votes create one schedule; denial reason and stale version fail; no author vote.
+4. **WP4 — Scheduler/deadlines.** Due deadline worker, claim eligibility/hash/time check, automatic schedule, archive on completion, failure/idempotency behavior. Gate: deadline/claim race and remote call exactly once under retries.
+5. **WP5 — Queue/detail/archive UI and SSE.** Compose handoff, virtualized queue, keyboard model, thread replay, buttons, moderation. Gate: keyboard and focus checks, 409 refresh, hidden visibility, SSE reconnect/epoch revocation. Email/external notification hook can emit an outbox row for future workers, without sending in this phase (spec R9).
+
+## 11. Ten regression tests
+
+1. **Self approval:** author with group reviewer role and Owner permission cannot vote or override; another eligible reviewer can.
+2. **Two final votes race:** both requests serialize; one state transition, one scheduled_publications row, two votes, valid audit chain.
+3. **Denial reason:** blank/whitespace denied at DTO and DB; valid denial closes round and previous approvals cannot count on resubmit.
+4. **Edit staleness:** after a reviewer loads version V, editor edits/resubmits V+1; vote with V/hash fails 409, and V remains viewable.
+5. **Role removal and epoch:** group reviewer removal revokes pending vote, reduces count, invalidates old token, and blocks schedule/claim.
+6. **Deadline serialization:** vote at T−1s schedules; vote at/after T expires; worker and final vote in parallel never publish an unapproved post.
+7. **Scheduler claim:** early Temporal wake, stale hash, missing quorum, and unassigned connection all fail before connector.publish; retry by same key does not duplicate a successful remote post.
+8. **Tenant and group isolation:** FORCE RLS with missing/foreign app.workspace_id returns zero rows; cross-group member gets 404 on detail/SSE and cannot vote via guessed IDs.
+9. **Migration:** old approved/scheduled/published remain grandfathered; old in_review/rejected become needs_changes; reviewer_user_id creates no fake vote; audit_verify_chain stays true.
+10. **Moderation/archive:** ordinary group member cannot hide/delete; admin tombstone cancels pending schedule, preserves audit/thread; published completion creates archived state and hides internal posts from member lists.
+
+The live-DB tests should follow the existing groups integration pattern for RLS/FKs/epoch and the scheduler repository's idempotency behavior, rather than only mock SQL calls [apps/api/src/groups/groups.integration.test.ts:217-245; apps/scheduler/src/activities/publish.activity.ts:75-90].
+
+## Confidence & risks
+
+The strongest risk is the boundary between a pending schedule, an in_flight remote call, and a reviewer role removal: once a provider call starts, local revocation cannot retract it. Prototype that race first with a controllable connector and assert the claim gate's exact lock order. The second risk is migration of old drafts without a unique target; inspect real providerMetadata shapes before finalizing the nullable backfill window. The third is throughput of per-post SSE polling and audit append contention; measure with many open review tabs before choosing polling intervals or a broker. The existing audit chain does not hash diff content [apps/api/migrations/001_tenants.sql:92-121], so a separate audit-hardening decision is needed if signoff evidence must be tamper-evident down to the snapshot hash and denial reason.
diff --git a/docs/design/spec-review-workflow.md b/docs/design/spec-review-workflow.md
new file mode 100644
index 0000000..f01bc3d
--- /dev/null
+++ b/docs/design/spec-review-workflow.md
@@ -0,0 +1,153 @@
+# Spec — Group Review & Signoff for Posts ("Editorial Workflow")
+
+Status: DRAFT for proposals
+Owner: product owner
+Date: 2026-10-07
+Inputs: user requirements, codebase inventory (explore agent), background research (Hootsuite/Sprout approval features, four-eyes/maker-checker compliance patterns)
+
+## 1. What the user asked for (verbatim intent)
+
+1. Posts can be **primed to go out**, then reviewed and edited by others in the group.
+2. Roles: **editors** (can edit, can NOT post/approve) and **reviewers** (give the OK).
+3. System configurable so **2–3 people sign off** on a post before it publishes.
+4. Reviewers can **approve, or deny with reasoning** (reason mandatory).
+5. A **parallel chat** per post with voting/approval buttons.
+6. Easy **scrolling through existing working posts** (the in-review queue).
+7. When posts publish, they are **archived**.
+8. Ability to make our own posts **invisible or delete** them — **admin-only** features.
+9. Think through the whole system; spec the needs.
+
+## 2. Current system (facts from codebase inventory)
+
+### 2.1 Publishing state machine
+- States in DB CHECK (`migrations/006_publishing.sql:7-8`): `editing, in_review, approved, rejected, scheduled, published`. TS mirrors: `publishing.service.ts:8`, web `api-types.ts:64`.
+- Transitions are guarded CAS UPDATEs (`WHERE id=$1 AND state=$4`) via `transition()` helper (`publishing.service.ts:275-292`):
+  - `editing→in_review` submitForReview (perm `approval.request`)
+  - `in_review→approved` approve (perm `approval.grant`, stamps `reviewer_user_id`)
+  - `in_review→rejected` reject (perm `approval.grant`; reason goes ONLY into audit diff, not the draft row)
+  - `approved→scheduled` schedule (inserts `scheduled_publications`, perm `publication.schedule`)
+  - `scheduled→approved` cancelSchedule
+  - `scheduled→published` by scheduler activity (`publish.activity.ts:181-184`)
+- **Approval record: NONE.** Only `drafts.reviewer_user_id` (single reviewer, last-writer-wins) + audit events. No quorum structure exists.
+- **`rejected` is terminal** — there is NO resubmit path today. This feature must add one.
+- Temporal: one workflow `scheduledPublish(idempotencyKey)` proxying one activity, **no signals/queries**. API starts it fire-and-forget with `startDelay`; durable `scheduled_publications` row (pending/in_flight/done/failed) is source of truth; sweeper `publishing_due_schedules()` re-starts missed workflows.
+
+### 2.2 Data model
+- `drafts(id, workspace_id, author_user_id, post jsonb, state, reviewer_user_id, created_at, updated_at)` — post payload = `{text, mediaAssetIds[], visibility, scheduledAt?, providerMetadata}`. **No soft-delete, no hidden flag, no delete endpoint at all.**
+- `scheduled_publications` — `UNIQUE(draft_id)` (one schedule per draft). `publications` — outcome rows (remote_id, idempotency_key).
+- All tables: FORCE RLS tenant_isolation on `app.workspace_id` + workspace-immutability triggers + `sp_app` grants. **Drafts are workspace-scoped only — no group column.**
+
+### 2.3 RBAC
+- 10 roles seeded (`002_rbac_seed.sql`): Owner, Admin, Publisher, Editor, Approver, Analyst, Moderator, VideoPublisher, StreamOperator, BroadcastOperator.
+- `approval.grant`: only Owner/Admin/Approver. `approval.request`: Owner/Admin/Publisher.
+- Enforcement: `RbacGuard` + `@RequirePermission()` decorator; guard verifies HMAC session → workspace `authz_epoch` (fail-closed 401 on mismatch) → permission via `role_permissions JOIN memberships(status='active')` inside `withTenant`.
+- **Roles are per-workspace only** (`memberships.role`, UNIQUE(workspace_id,user_id) — one role per user per workspace). **`group_members` has NO role column** — no per-group roles exist.
+
+### 2.4 Groups
+- Tables (`008_groups.sql`): groups, group_members (no role), group_connections, group_assets. Denormalized workspace_id + composite FKs prevent cross-tenant groups.
+- Epoch: any group_members change fires `bump_authz_epoch()`; sessions carry authzEpoch; guard compares live. Membership mutations mint a replacement token in the same tx (`{token}` response pattern).
+- Connection scoping: `getVisibleConnections` — Owner/Admin see all; others see union of group connections via their memberships. Guard-side `userCanUseConnection` reads role from DB.
+
+### 2.5 Realtime & chat
+- **No WS transport exists.** `realtime/gateway.ts` is an authz port only (`authorizeSubscription` checks session, workspace, epoch, `stream.view`). No topics, no client code.
+- Web Inbox is a fixtures-only two-pane chat UI (conversation list + thread bubbles + reply box). Reusable as visual pattern, no backend.
+
+### 2.6 Frontend
+- Compose (`compose/page.tsx`): tiptap editor, target chips, visibility, approval select, schedule; `publish()` chains `create→submit→[approve]→[schedule]` gated on `can()`; "Recent drafts" sidebar with STATE_TONE badges is the only post list today.
+- `/approvals` is a 10-line stub; `/calendar` stub.
+- Streams columns (`components/streams/column.tsx`): `@tanstack/react-virtual` useVirtualizer, j/k keyboard nav — reusable pattern for the working-posts queue.
+- Audit page (236 lines) with diff viewer exists.
+
+### 2.7 Audit
+- `audit_log` hash-chained per workspace (`audit_hash = sha256(prev|actor|action|target_id|epoch)`), SECURITY DEFINER append fns, `audit_verify_chain`. Services write via `appendTenantAudit` (after-commit) or same-tx `SELECT audit_append(...)`. Scheduler writes with `actor_role='sp_scheduler'`.
+
+## 3. Background research — patterns to draw from
+
+### Social tools (Hootsuite, Sprout)
+- Workflow shapes: **linear, tiered (multi-level), parallel, conditional**. Sprout steps support **Any vs All** sign-off ("any 1 of step's approvers" / "all must approve").
+- **Post-locking after approval**: any post-approval edit re-triggers the chain. Hootsuite: "Once approved, the post is locked; changes send it back through approval."
+- **Expired queue**: if not approved by scheduledAt, publish FAILS, post moves to Expired (author re-schedules + resubmits). 90-day auto-reject of stale pending items.
+- Rejected → author edits → resubmits. Rejection notes surface to author.
+- **Approval Activity** panel: every edit (who/when) + threaded internal comments + current step; approvers can edit-before-approve; tag members; notifications (digest + hourly reminders).
+- Approvals inbox filters: Assigned-to-me, Created-by-me, Rejected, Expired.
+- Teams of approvers (not individuals) to avoid bottlenecks; duplicate-reviewer skip.
+
+### Four-eyes / maker-checker (compliance-grade)
+- **Self-approval must be structurally impossible** — server-side check `approver ≠ author`, dedicated error, not policy.
+- **Approve a frozen snapshot, not a moving target**: submit seals content (hash); edits after submit = new submission + new approval cycle; prior snapshots stay in audit trail. Reviewer sees the real diff.
+- **Deny requires non-empty reason** (empty reason refused); approvals/denials recorded with actor+timestamp+snapshot hash.
+- Eligibility re-checked at every transition (not just submit).
+- Parallel double-approval (Signavio): parallel split/join, either order, automatic gateway; enforce distinct reviewers at assignment.
+- Edge cases to model explicitly: reviewer leaves mid-review (votes revoked? reassigned?), vacation delegation, emergency admin override (logged as override), conflict discovered late.
+- State machine enforced in BOTH app logic and DB triggers (defense in depth).
+- Metrics: approval cycle time, approvals per reviewer (rubber-stamp detection).
+
+## 4. Requirements (normative for proposals)
+
+### R1 Lifecycle
+- New/extended states covering: draft/editing → **primed/submitted for review** → in-review → approved (quorum met) → scheduled → published → **archived**; deny → **needs-changes** (back to author/editor with reasons); **resubmit** path (currently missing — `rejected` is terminal today).
+- If a scheduled time passes without quorum → **expired** state (post does NOT publish; author notified; re-prime after re-approval).
+
+### R2 Roles & permissions
+- **Editor**: can edit group posts (content), cannot approve, cannot publish.
+- **Reviewer**: can approve/deny with mandatory reason, cannot edit content.
+- Roles must be assignable **per group** (group-scoped), coexisting with workspace roles. Author can never approve their own post (structural, server-side). Admin/Owner retain override power (logged as override).
+- Existing `approval.grant`/`approval.request` permissions are the workspace-level seeds; extend, don't break, current 10-role model.
+
+### R3 Quorum signoff
+- Configurable **N approvals required** (2–3 typical) — decide where config lives (workspace default + per-group override? per-connection?) and who sets it (admin-only).
+- Parallel (any-N-of-eligible) semantics by default; justify if you add tiered/sequential mode.
+- Vote rules: one live vote per reviewer per submission; vote change allowed while in-review (with new reason) or immutable — pick and justify. Deny = single vote sends to needs-changes. Quorum met → auto-transition approved (→ scheduling continues if schedule set).
+
+### R4 Staleness & integrity
+- Content edits during review must NOT silently invalidate approvals: pick a model (frozen snapshot + new cycle on edit, vs edit-with-approval-dismissal + diff shown) and justify. Snapshot hash in audit log.
+- Reviewer must always see exactly what they're approving (rendered post + diff since last review).
+
+### R5 Review chat
+- Per-post thread: messages from group members + **system events** (submitted, edits, approvals/denials with reasons, state changes) rendered inline.
+- **Approve / Deny+reason buttons in the chat surface** for eligible reviewers.
+- Realtime delivery: no WS transport exists today — propose transport (WS gateway wiring, SSE, or polling) with epoch/authz integration; justify choice.
+
+### R6 Working-posts queue (UI)
+- Scrollable list of in-flight posts: state chips, quorum progress (e.g. "2/3 ✓"), filters (needs-my-review, needs-changes, expiring soon), keyboard-friendly (j/k pattern from Streams).
+- Post detail: rendered post preview + version diff + chat/vote panel + schedule info.
+
+### R7 Archive & moderation
+- Published posts land in an **archive view** (read-only, chat history preserved for record).
+- **Hide** (invisible to members; badge for admins) and **delete** (hard or soft — justify) of posts — **space-admin-only**, new permissions, hash-chained audit events, epoch-safe.
+- Decide moderation scope: archive-only or also drafts/working posts.
+
+### R8 Security & audit (mandatory repo patterns)
+- Everything through existing RbacGuard/`@RequirePermission`, FORCE RLS + tenant isolation on new tables, sequential migration `009_*`, hash-chained audit events for every state transition and vote, epoch re-token where membership/role changes affect pending reviews (reviewer removed from group → their pending votes must be revoked/re-counted).
+
+### R9 Non-goals (this phase)
+- Email/external notifications (design the hook, don't build), mobile-specific UI, per-platform conditional routing, AI-assisted review.
+
+## 5. Open design questions (proposals must answer explicitly)
+
+1. Group-scoped role storage: column on `group_members` vs separate `group_member_roles` table vs reusing workspace roles — tradeoffs?
+2. Snapshot model: full content copies per version vs content-hash + immutable version rows?
+3. Where does quorum config live and what's the precedence (workspace default → group override)?
+4. Chat transport: WS (wire the existing authz port) vs SSE vs polling — cost/complexity/ordering guarantees?
+5. Deny semantics: 1-deny-returns-to-author vs majority-deny vs configurable; what happens to other cast approvals on deny?
+6. Re-review after edit: full reset vs dismiss-only-changed-scope (recommend one, note the other as future)?
+7. Scheduled-time race: quorum completes at T-1min to scheduledAt — auto-publish or require manual re-confirm?
+8. Author is also the only reviewer in a tiny group — deadlock handling (admin override path)?
+9. Migration path for existing single-step approvals (`reviewer_user_id` backfill)?
+10. Should reviewers see who else approved before them (peer pressure) or vote blind until quorum?
+
+## 6. Proposal deliverable format (each lane produces `runs/wp5/proposal-<lane>.md`)
+
+1. Executive summary — the 5 sharpest decisions you make.
+2. Data model — migration SQL sketch (009+, following repo conventions: FORCE RLS, tenant isolation, immutability triggers, sp_app grants, audit fns reuse).
+3. State machine — full state/transition table with guards and who can fire each.
+4. RBAC — new permissions, group-role mechanism, self-approval exclusion, admin override.
+5. Quorum engine — vote lifecycle, staleness/snapshot semantics, deny handling, race conditions.
+6. Review chat — data model, event types, transport decision, authz integration.
+7. UI plan — screens (queue, detail, archive), reuse of existing components, keyboard model.
+8. Edge cases — the ugly ones (reviewer leaves, deadline race, deadlock, epoch churn mid-vote).
+9. Audit & security — event list, chain integration, RLS notes.
+10. Phased implementation plan — WP-sized chunks with test gates.
+11. Test plan sketch — the 10 tests that would catch the worst regressions.
+
+Constraints: NestJS + Postgres 16 + Temporal patterns as in repo; TS strict, no `as any`; follow existing naming/style; do not break the 10-role seed contract; proposals are designs — do NOT implement.
diff --git a/docs/design/streaming-architecture.md b/docs/design/streaming-architecture.md
new file mode 100644
index 0000000..1c934d8
--- /dev/null
+++ b/docs/design/streaming-architecture.md
@@ -0,0 +1,540 @@
+# Streaming Architecture — Control Room, Overlays, Fallback, Chat, Telegram Ingest
+
+Status: decision document (synthesis of four WP4 research reports). No code was changed while writing it.
+Date: 2026-10-07
+Inputs:
+- **[flash]** `runs/wp4/control-room-research-flash.md`
+- **[glm]** `runs/wp4/control-room-research-glm.md`
+- **[as]** (integration research, kept outside the repository)
+- **[tg]** `runs/wp4/telegram-amplify-research.md` (WP15 middle)
+- **[scope]** `runs/wp4/control-room-scope.md`; **[dm]** `docs/design/design-merged.md`; **[wb]** `docs/work-breakdown.md` WP9–WP13, WP15; **[prop]** `docs/proposal.md` §4.4/§4.5
+
+**Provenance legend.** `[flash]`, `[glm]`, `[as]`, `[tg]` mark the report a decision comes from. `[both]` means flash and glm agree. `[SYN]` marks a decision this document makes where neither report settled the question, or where the two disagree. Each `[SYN]` explains why it wins.
+
+---
+
+## 0. Decisions at a glance
+
+| # | Question | Decision | Source |
+|---|---|---|---|
+| D1 | Where is program composited? | **On the server**, in the media worker's FFmpeg compositor. The browser is a control surface and a preview consumer only. | [both] |
+| D2 | One FFmpeg process per channel, or split processes? | **Split**: ingest×N → compositor (replaceable) → **frame gate** (clock master) → persistent encoder → push relays. A graph change starts a new compositor (A/B swap). The encoder and the RTMP session are never restarted. | [SYN] over [flash]'s one-process invariant |
+| D3 | Multiview | Every tile plays the worker's **preview tap**, never the remote source. 2x1/2x2 tiles are live LL-HLS. 3x3/4x4 tiles are thumbnails, with live LL-HLS only on the PGM tile and the focused tile. Hard cap of **4 live decodes on desktop and 1 on mobile**. | [both]; caps [SYN] |
+| D4 | Audio | **Monitor mix** runs in the browser (one shared `AudioContext`, gain per tile, same-origin preview audio). **Program mix** runs in the compositor (`amix` with weights from desired state, gain in 3 dB steps). | [both]; steps [glm] |
+| D5 | Overlay rendering | **Pre-rendered assets.** The API renders an SVG template to a PNG with alpha. The worker composites it with `overlay`. A chyron is one wide PNG strip scrolled by an `overlay` x-expression. FFmpeg never sees user text. | [flash] over [glm]'s `drawtext`+`textfile` |
+| D6 | Playlist fallback | **On the worker.** A playlist is an ordinary ingest kind feeding a SLATE/PLAYLIST scene into the same encoder. PeerTube runs as `permanentLive`. PeerTube-native playlists are only the programming source of truth. | [both]; "Tier-2 PeerTube-only mode" from [glm] deferred |
+| D7 | Auto Director | **Rules only**: a priority ladder over monitor states, plus dwell time per source class, ending in the fallback scene. Automation writes the same buses through the same transaction as a human TAKE. | [both]; dwell-by-class [glm] |
+| D8 | PGM/PST transitions | v1 ships **CUT**. FADE follows behind a gate, as a transition graph swapped twice (old+new with `xfade`, then new only). The transition is part of desired state, not an imperative command. | [SYN] from [flash] Q6 + [glm] Q6 |
+| D9 | Chat transport to the app | **WebSocket**: subscribe/ack, auth sent in the first frame, `lastSeq` resume from a server ring buffer. REST cursor polling (`?after=seq`) is the fallback. **No FCM.** | [as]; polling fallback aligned with [dm] §7 |
+| D10 | Telegram "join and amplify" | Bot-as-channel-admin webhook → `archived_feed_items` → review draft → existing `amplify()`. MTProto stays a flagged Phase 2 and is not in this plan. | [tg] |
+
+---
+
+## 1. THE composition decision
+
+### 1.1 Options
+
+- **(A) Server-side FFmpeg compositor.** Runs inside `apps/media-worker` under the supervisor and receives commands over the existing Ed25519 signed-snapshot bus.
+- **(B) Browser-composited program** (the StreamYard model). The browser draws onto a canvas, then `captureStream()`/WebCodecs → WebRTC/WHIP upstream → the worker transcodes to RTMP.
+
+### 1.2 Evidence
+
+| Criterion | (A) server compositor | (B) browser compositor | Source |
+|---|---|---|---|
+| **Operator laptop sleeps, tab crashes, Wi-Fi drops** | Program keeps running. The supervisor, output lease and reconcile loop already live on the worker. | **Program ends.** For a self-hosted product there is no cloud fallback, so the operator's machine becomes a single point of failure for a 24/7 channel. | [flash] Q3.1, [glm] Q3 |
+| **24/7 premise** (scope item 5: a playlist plays when nothing is live) | Fallback is just another scene, and the encoder never idles. | Unattended hours have no browser to run in, so a second, server-side path is needed anyway. | [glm] Q3 "disqualifying on its own" |
+| **Mobile (later)** | The phone is a pure control-plane client sending desired-state commands. No media runs on the device. | `HTMLMediaElement.captureStream` is `false` on Safari. WebCodecs `AudioEncoder` arrives only in Safari 26. Firefox Android has no `VideoEncoder`. | [flash] Q3 (BCD), [glm] Q3 (BCD) |
+| **Signed command bus** | Fits 1:1. A TAKE writes a bus row, bumps `desiredVersion`, writes an outbox row and publishes a signed full snapshot. The worker converges idempotently. The fence, seen-set, reconcile and assignment epochs all carry over unchanged. | Needs a second "what is program" authority in the browser, a WHIP ingest trust boundary, and a WebRTC signalling path outside egress mediation, secret handling and the reconcile gate. | [flash] Q3.2, [glm] Q3 "Fit with the signed-command worker" |
+| **Latency at the viewer** | Adds about one encode generation. | Can be under a second from glass to RTMP. | Both say **PeerTube's live→HLS chain dominates** (latency modes 1/2/3), so the gap mostly disappears at the viewer. [flash] Q3.4, Q5 |
+| **CPU placement** | Server decodes and encodes. This is already priced in encoder units by WP9 admission. | Moves CPU to the operator machine. | [glm] Q3 |
+| **Security** | Secrets, sandbox and egress pinning stay server-side, where the proposal already solved them. | The browser must decode every source at full quality, which breaks the "operator never pulls the remote source" rule. | [glm] Q3, [prop] §4.4 previews |
+
+### 1.3 Decision — (A), server-side compositor [both]
+
+The worker composes. The browser only watches previews and sends desired-state commands [glm]. A WebRTC/WHIP low-latency path, if ever needed, enters as **one more source kind** feeding the server compositor. Composition stays server-side either way [flash].
+
+**Dissenting view (recorded).** Option (B) is the right answer for *interactive call-in shows*: sub-second guest interaction, zero server encode cost, and WYSIWYG editing on the operator's screen. StreamYard/Restream ship it (their internals are not verified in either report). We reject it because our product is a continuous Virtual Channel, not a studio session. If call-in guests become a requirement, the shape is vMix Call's [glm]: browsers *contribute* sources over WHIP, and the mix still happens on our worker.
+
+### 1.4 Where the two reports disagree inside (A): process topology [SYN]
+
+- **[flash]** proposes the invariant "**one FFmpeg process per channel**", with every TAKE, layout or overlay change rebuilding the graph.
+- **[glm]** and **[prop] §4.4** use separate ingest / compositor / persistent encoder / pusher processes: "scene switch = graph rewiring… encoder and pushers are never restarted".
+
+**Decision: split topology, plus a frame gate.** FFmpeg cannot rewire a running filtergraph. Runtime commands only change parameters of filters that already exist. So in flash's single process, *every* scene change restarts the encoder and the RTMP publish. That breaks WP9's "output that does not stop" and the WP11/WP12 continuity acceptance. flash's own Risk 2 ("a bad rebuild drops frames or kills program") is the symptom. The split topology moves the rebuild away from the encoder:
+
+```
+ingest_i (normalize → raw video + PCM over pipes, per source; also emits preview taps)
+        │  (N inputs, plus a playlist ingest and overlay asset inputs)
+        ▼
+compositor[A]  ── active graph for desiredVersion v
+compositor[B]  ── started for v+1, warmed until its first frame is ready
+        │ rawvideo (yuv420p, fixed frame size) + s16le 48 kHz (fixed bytes per frame)
+        ▼
+FRAME GATE  (clock master: paced at the profile fps; on compositor stall it repeats the
+             last frame and writes silence; switches A→B at a frame boundary once B
+             has produced K frames; then SIGTERMs A)
+        ▼
+encoder (persistent; reads gate pipes; never restarted by scene changes)
+        ▼
+push relay ×M (WP9/WP13: lease-bound key over fd, pinned destination)
+```
+
+- **Why the gate is the clock master.** Raw video and PCM have fixed byte sizes per frame, so the gate needs no demuxer and no timestamp parsing. Frames are counted, and the encoder sees a perfectly regular input with no gaps. Sync between audio and video holds by construction.
+- **Cost.** About 93 MB/s of raw 1080p30 through one more pipe hop, plus a brief doubled compositor CPU during each swap. The doubled CPU is admission-accounted as a transient burst inside the worker's 20 % failover reserve.
+- **Spike gate (first task of S2).** A gate written in Node with preallocated ring buffers must sustain 1080p60 at under 5 % of a core with no GC pauses above one frame interval. If it fails, the gate becomes a small static Rust binary behind the same pipe contract. The WP9 GStreamer decision gate ([wb] WP9) is folded into this spike: if A/B swap with the gate is not frame-continuous across 1 000 swaps, escalate to GStreamer `input-selector`.
+
+flash's argument for a single process was simplicity and keeping "WP11's continuity risk class" in one place. The gate keeps that risk in one place, the gate, while making continuity a property of the design instead of a hope about rebuild speed.
+
+---
+
+## 2. Multiview + audio spec
+
+### 2.1 What a tile plays [both]
+
+Tiles never touch remote HLS. Each active ingest emits one **shared preview tap** ([prop] §4.4):
+- a JPEG thumbnail, every 2 s by default (configurable 1–10 s);
+- an on-demand **360p / ≤500 kbps LL-HLS** rendition;
+- **[SYN] an on-demand audio-only rendition** (AAC 64 kbps LL-HLS). Thumbnails carry no audio, so without it a 4x4 operator could not hear a thumbnail tile.
+
+These are served from the authenticated preview endpoint with `ETag`, single-flight fill, and an LRU of 6 segments or fewer per source. The endpoint is **same-origin with correct CORS**. This is load-bearing: a cross-origin `MediaElementAudioSourceNode` outputs silence per the Web Audio spec [flash] Q2 and [glm] Q2.
+
+The **program tap** is the same mechanism applied to the gate output (one extra tap per channel). The PGM tile always shows what the encoder actually receives.
+
+### 2.2 Grid tiers and the decode budget
+
+No browser documents a hard limit on concurrent decoders; both reports flag this as **not verified**. The binding constraints are pixel throughput, per-tab MSE memory and mobile hardware-decoder sessions [glm] Q1. Budget: **live decodes ≤ 4 on desktop, ≤ 1 on mobile** [SYN]. This is flash's "never more than 4" plus glm's mobile "thumbnails + one live tile".
+
+| Layout | Desktop tiles | Live (LL-HLS 360p) tiles | Mobile |
+|---|---|---|---|
+| 2x1 | 2 | both live | PGM live, other thumbnail |
+| 2x2 | 4 | all 4 live | PGM live, others thumbnail |
+| 3x3 | 9 | **PGM + focused** live; the other 7 are thumbnails | 1 live (PGM or focused) |
+| 4x4 | 16 | **PGM + focused** live; the other 14 are thumbnails | 1 live (PGM or focused) |
+
+Additional rules:
+- **"Upgrade more tiles"** is an explicit user action, capped at 4 total, with a capability warning [glm].
+- **Thumbnail cadence**: 2 s by default and 1 s for the PST-selected tile. Off-screen tiles stop polling (`IntersectionObserver` + `visibilitychange`) [prop].
+- **hls.js config per tile** [glm] Q1:
+  - `lowLatencyMode: true`;
+  - `maxBufferLength: 4`, `maxMaxBufferLength: 8`, `backBufferLength: 4` (the default `Infinity` is wrong for a multiview);
+  - `liveSyncDurationCount: 2`.
+- **Player selection** [flash] Q1: if `Hls.isSupported()`, use MSE. Otherwise, if `ManagedMediaSource` exists and `canPlayType(m3u8)`, use native HLS (Safari/iOS 17.1+). Otherwise the client is thumbnail-only.
+- **Autoplay**: every tile boots `muted` + `playsinline`. One "Arm audio" gesture unlocks the shared `AudioContext` [flash] Q1.
+- **Tile chrome**: monitor badge (`LIVE/UNSTABLE/OFFLINE/…` from the live-monitor WS fan-out), tally border (red = PGM, green = PST), and a tile-state label ("thumbnail · 2 s", "live preview").
+  - **Tally reflects only state stamped with `observed_version`.** It is never optimistic [glm] Q6, Risk 4.
+- **PST rendering** [SYN] (adopting [glm] Q3's browser *preview* compositor):
+  - The PST monitor is rendered **client-side** onto a canvas, from the preview taps of the slots in the PST scene plus the scene's overlay SVGs. These are the same SVGs the server rasterizes (§4), so the look matches.
+  - The worker does **not** composite a second (preview) program. That would double compositor CPU for every channel.
+  - Caveat shown in the UI: "PST is a look-ahead; PGM is the truth".
+
+### 2.3 Audio: two mixes, two owners [both]
+
+**Monitor mix** (what the operator hears; browser):
+- **Graph**: one `AudioContext` per page. Each audible tile's media element → `MediaElementAudioSourceNode` → its own `GainNode` → master `GainNode` → destination [glm] Q2.
+- **Modes**:
+  - *Follow program* (default): plays the program tap's audio, which is exactly what viewers hear, delayed by roughly the tap latency.
+  - *Solo source X*: plays that source's audio rendition.
+  - *Custom monitor mix*: up to 4 sources with independent faders. These are continuous UI faders, because the mix is local.
+- **Bounds**: never more than 4 audio renditions plus the program tap. Thumbnails gain audio by attaching the audio-only rendition (§2.1).
+- **Privacy**: per operator and never sent to the server, so no command traffic.
+- **Mobile**: the monitor collapses to "the one tile you are watching" [glm].
+
+**Program mix** (what viewers hear; compositor):
+- **Per-slot audio intent**: `scene_slots.audio_mode ∈ off|on|primary`, with at most one `primary` per scene (partial unique index, [prop] §4.4). The default is primary-only, meaning one feed's audio. "Mix N feeds" means several `on` slots.
+- **Graph**: `volume` per input → `amix inputs=N duration=longest dropout_transition=2 normalize=1` [glm] Q2. A dead source fades out instead of cutting.
+- **Gain** is desired state, in **3 dB steps from −24 to 0 dB**. No continuous program fader, because continuous faders would turn the signed bus into a UI-rate control channel [glm] Q2.
+- **Applying a change**: a program gain change bumps `desiredVersion` and triggers an A/B compositor swap (§1.4). It is inaudible because the gate splices at a frame boundary.
+- **Deferred optimization**: `amix`/`volume` runtime commands via `azmq` on an `ipc://` socket in job scratch [flash] Q2. **Not verified**: whether our pinned FFmpeg has libzmq, and whether it is compatible with the seccomp profile.
+
+---
+
+## 3. Chat unification contract (Opticast ↔ Tactical Media Broadcast Hub)
+
+### 3.1 Roles [as] §2.1
+
+**Tactical Media Broadcast Hub is the chat aggregation authority.** Connectors ingest server-side into a normalized stream. A new `chat-hub` module persists, dedupes, sequences and fans out. Opticast, the web Control Room and the Tactical Media Broadcast Hub mobile web shell are all **thin authenticated realtime clients**. The phone never holds Twitch/YouTube/PeerTube credentials.
+
+The privacy pledge in Opticast's README ("no network access beyond the configured server") remains true. The integration is opt-in and off by default, and the only endpoint is a user-configured, self-hosted Tactical Media Broadcast Hub.
+
+### 3.2 Ingestion (platform → `LiveChatMessage`) [as] §2.3
+
+| Platform | Read | Reply | Moderate | Mechanism / governance |
+|---|---|---|---|---|
+| Twitch | ✅ | ✅ | delete, timeout, ban | EventSub WS `channel.chat.message` plus delete/clear events. Helix `POST /chat/messages` for replies; Helix moderation and ban endpoints. **No replay after a WS drop.** The hub ring buffer covers clients; the platform gap is accepted and marked with a `system` gap message. Token bucket of 100 per 30 s (elevated). |
+| YouTube | ✅ | ✅ | delete, ban | `liveChatMessages.list` long-poll honouring `pollingIntervalMillis`, **one shared poller per broadcast**. Quota ledger: list = 1 unit, insert/delete/ban = 50, 10 000 per day by default. Quota exhaustion is a first-class `paused:quota` state. |
+| PeerTube + livechat plugin, C2S on | ✅ | ✅ | MUC moderation | Server-side XMPP client joins as the streamer with the livechat long-term token, which is **"not officially supported"** per the plugin docs. |
+| PeerTube, embed only | read-only | ❌ | ❌ | Read-only embed pane, web only. |
+| PeerTube, no plugin | comments | comment reply | ✅ | Existing `getComments` on the connector, labelled "comments". |
+| Mastodon | mentions | status reply | delete own | Streaming `/api/v1/streaming` (user), `source: "social-reply"`. |
+| Mock livestream | ✅ | ✅ | ✅ | Contract and E2E harness. |
+
+**Capability probing.** Each connection carries a probed capability row, with `pt-chat: xmpp-c2s | readonly-embed | comments-only | none` for PeerTube.
+
+**Storage.** `live_chat_messages` is partitioned monthly per the [wb] retention row. `live_chat_seen_events` uses `ON CONFLICT DO NOTHING`, mirroring `monitor_seen_events`. Dedup key: `(workspace_id, provider, provider_message_id)`. **Ordering**: a per-live monotonic `seq` assigned at hub ingress. Provider timestamps are display-only, because clocks skew [as] §2.4.
+
+**Local display filters.** Hide `!commands`, hide bots, mute user, word filter. These run once, hub-side, so web and mobile inherit them [as] §2.8.
+
+### 3.3 Transport decision [SYN] (from [as] §2.5 + [dm] §7)
+
+| Option | Verdict |
+|---|---|
+| **WebSocket** (subscribe/ack + resume) | **Primary.** Chat volume is far beyond review-chat volume. OkHttp WS on Android can authenticate in the first frame. The existing `authorizeSubscription` port is the gate. |
+| SSE | Rejected. `EventSource` cannot send our Bearer header ([dm] §7 rationale), and it offers no upstream channel for acks. |
+| REST cursor polling | **Fallback** for constrained clients and for resync after `RESYNC_REQUIRED`. It uses the same `after=seq` semantics as [dm] `review_events`, so one cursor discipline applies across the codebase. |
+| FCM push | **Rejected** for v1, because it breaks Opticast's privacy pledge. A later opt-in UnifiedPush or self-hosted web-push is possible. |
+
+**WS lifetime on the phone.** The socket stays open only while the chat sheet is open, or while `StreamingService`, the existing camera/mic foreground service, is live. There is no background socket when idle. Backoff from 1 s to 8 s mirrors `ReconnectController` [as] §2.5, Risk 4.
+
+**Fan-out.** The hub publishes to Redis `chat:{workspaceId}:{liveId}`. The gateway subscribes only to authorized and viewed topics, using WP11 fan-out rules: bounded per-socket queues, `RESYNC_REQUIRED` on overflow. **Prerequisite:** the API-side `RespControlRedis` has PUBLISH but not SUBSCRIBE, so a subscribe-capable client must land first [as] §2.2.
+
+### 3.4 Device pairing [SYN]
+
+Opticast authenticates with a **device token**, not a user session cookie.
+1. The web UI calls `POST /devices/pairings` and shows a QR code containing `{serverUrl, pairingCode}` (TTL 5 min, single use).
+2. The app redeems the code with `POST /devices/pairings/redeem` and receives a device token. The token is bound to `(workspaceId, userId)`, scoped to `livechat.view|send|moderate` + `stream.view`, epoch-gated, and revocable from the web UI.
+3. The app stores the token in `EncryptedSecretStore` [as] §4 Phase 2.
+
+### 3.5 Endpoint shapes (both apps implement)
+
+Routes follow repo convention: no `/workspaces/{wid}` prefix, because the workspace comes from the session or device token; compare `@Controller("publishing/drafts")`. [as] Phase 0 shapes are adapted accordingly.
+
+```
+REST (Tactical Media Broadcast Hub API; RbacGuard + RLS; Idempotency-Key on POSTs)
+GET  /live-chat/lives                                   → { items: LiveSummary[] }               # stream.view
+GET  /live-chat/lives/{liveId}/messages?after=<seq>&limit=<1..500, default 100>&platform=<p>
+     → { items: ChatMessage[], nextCursor?: number }                                            # livechat.view
+POST /live-chat/lives/{liveId}/messages
+     body { text (1..500 chars), targets: "all" | connectionId[], replyTo?: messageId }
+     → 202 { message: ChatMessage, delivery: Delivery[] }                                       # livechat.send
+POST /live-chat/lives/{liveId}/messages/{messageId}/moderation
+     body { action: "delete"|"timeout"|"ban", durationSeconds?: 1..1209600 }
+     → 202 { delivery: Delivery[] }   (audited via audit_append)                                # livechat.moderate
+GET  /live-chat/lives/{liveId}/capabilities
+     → [{ connectionId, provider, read, reply, moderate, state: "ok"|"paused:quota"|"paused:rate"|"degraded", reason? }]
+POST /devices/pairings                 → { pairingCode, qrPayload, expiresAt }                  # session user
+POST /devices/pairings/redeem          body { pairingCode, deviceName } → { deviceToken, workspaceId }
+DELETE /devices/{deviceId}             (revoke; bumps the device's epoch)
+
+Delivery = { connectionId, provider, status: "queued"|"sent"|"failed"|"unsupported", error?: string }
+
+WS  /realtime   (one socket, multiplexed topics; also used by the Control Room)
+C→S { op:"auth", token }                                     # first frame; never in the URL
+S→C { op:"ready" } | { op:"close", reason }
+C→S { op:"subscribe", id, topic:"livechat", liveId, lastSeq? }
+C→S { op:"subscribe", id, topic:"channel", channelId }       # Control Room: buses/monitor/observed
+S→C { op:"ack", id, fromSeq } | { op:"nack", id, reason }    # reason ∈ authorizeSubscription reasons
+S→C { op:"msg", topic, seq, type, payload }
+    type ∈ chat.message | chat.moderated | chat.delivery | chat.gap | stream.state | capability
+S→C { op:"resync", topic }                                   # client re-fetches via REST ?after=
+C→S { op:"unsubscribe", id } | { op:"ping" }  S→C { op:"pong" }
+
+ChatMessage = { seq, id, liveStreamId, connectionId, provider, providerMessageId,
+                author: { handle, displayName?, avatarUrl?, badges?: string[], color },
+                text, sentAt, receivedAt, isModerated, replyTo?, source: "live-chat"|"social-reply"|"system" }
+```
+
+Contract rules:
+- **Resume.** `lastSeq` replays from a ring buffer of the last 500 messages per live, held in Redis. If `lastSeq` is older than the ring, the server sends `resync` and the client pages via REST.
+- **Epoch.** An authz-epoch bump (role change, device revoke) closes every socket of that principal within 5 s, matching the WP11 revocation SLO.
+- **Reply semantics.** The composer target defaults to "All capable". An incapable target is refused client-side with its reason. Delivery ticks per target reconcile from `chat.delivery` events, following Restream's pattern [as] §2.7.
+- **Identity.** No cross-platform identity fusion. The author colour is a hash of `provider:handle` [as] §2.6.
+- **Licensing.** Opticast is GPLv3 and the Tactical Media Broadcast Hub licence is **not verified**. The relationship stays API-only, with no shared code [as] Risk 5.
+
+### 3.6 Opticast UX (for the client slice) [as] §3
+
+- Chat is a bottom sheet on `LiveScreen` with snap points at 40/70/100 %. It is not a third route.
+- One unified list with platform badges, filter chips `All · Twitch · YouTube · PeerTube · Mentions`, and swipe moderation (left = delete, right = ban; long-press for timeout).
+- A "↓ N new" pill appears when scrolled up.
+- A `ChatViewModel` sits beside `StreamViewModel`. Streaming code is untouched.
+- **Opticast as a camera source** for the Control Room needs a push ingest kind (`rtmp-push`/`srt-listen`) that Tactical Media Broadcast Hub lacks today (`source.kind` is `"hls"` only). It is **out of scope for this plan** and listed as a follow-on in §6.4.
+
+---
+
+## 4. Overlay system
+
+### 4.1 The disagreement
+
+- **[glm] `drawtext` + `textfile` + `reload=1`.** Text edits land without a graph restart, and scrolling uses `x = main_w − mod(t·speed, main_w + text_w)`. [prop] §4.4 also mentions "overlay text → written to a `textfile`".
+- **[flash] pre-rendered assets.** SVG template → PNG with alpha (via resvg/sharp) → `overlay`. The chyron is one wide strip scrolled by an `overlay` x-expression. FFmpeg never sees text.
+
+### 4.2 Decision — pre-rendered assets [flash], with glm's no-restart property recovered by the A/B swap [SYN]
+
+Why pre-rendered assets win:
+1. **Same pixels in PST and PGM.** The browser PST look-ahead (§2.2) renders the *same SVG* the server rasterizes. With `drawtext`, the browser would have to imitate FreeType layout and would never match.
+2. **Brand-quality typography.** The geometric design language (#FF1610, solid disk mark, rounded/angled boxes) is trivial in SVG and painful in `drawtext` box parameters.
+3. **Smaller attack surface inside the sandbox.** `drawtext` needs freetype, harfbuzz, fontconfig and fribidi in the pinned FFmpeg, plus font files mounted into every compositor. [glm] Risk 3 itself names "font bombs". Rasterizing once in an API-side sandboxed job keeps fonts and SVG parsing out of the 24/7 process.
+4. **Cost and determinism.** A static PNG overlay is cheaper than per-frame glyph rendering. [glm] flags `drawtext` scroll CPU at 1080p60 as a risk, and its own fallback is "render the band into a strip", which is flash's design. PNGs are also golden-frame deterministic.
+5. **glm's advantage is no longer needed.** glm's argument for `drawtext` (an edit without a graph restart) matters only if restarts are visible. With the frame gate (§1.4), a graph swap is frame-continuous, so an overlay edit is just another `desiredVersion`.
+
+`drawtext` survives in one narrow role: a **server-generated clock/countdown** using `expansion=normal` with `localtime`. The format string is a typed enum, never user text.
+
+### 4.3 Pipeline
+
+```
+Operator edits a lower third (web/mobile)
+   │  POST /production/overlays/{overlayId}  { templateId, fields: {title ≤ 80, subtitle ≤ 120}, style enum }
+   ▼
+API validation: length, Unicode category allowlist, no control characters → overlay_revisions row
+   ▼
+render job (sandboxed WP4 probe class): SVG template (server-owned, typed field slots, bundled fonts)
+   → resvg (no scripts, no external fetch) → PNG with alpha at output resolution
+   → StorageService (sha256 key, dedup) → asset id
+   ▼
+1 tx: scene overlay slot → new assetId + desired_version++ + outbox row   (same path as a TAKE)
+   ▼
+signed snapshot → worker → compositor B built with the new overlay input → gate swap at a frame boundary
+```
+
+Overlay kinds:
+- **Lower third**: PNG composited with `overlay=x:y`. There is no timed `enable=` expression. Toggling is a slot flag in desired state, so the next graph simply includes or omits it.
+- **Chyron**: render the *whole ticker strip* (all items with separators) as one wide PNG. The height of the band is fixed. Width is capped at **16 384 px** [SYN]; longer text is split into a carousel of strips. Scroll with `overlay=x='W-mod(t*S\,w+W)':y=Y`, where speed S is a typed integer of 40–400 px/s.
+  - A chyron text edit renders a new strip and swaps graphs. The scroll position restarts, and that is accepted.
+- **Logo from an SVG input**: a tenant upload goes through the WP4 sandboxed probe and is rasterized once per asset version at 1×/2× sizes. Position and size are typed values (corner enum + margin, or explicit numbers).
+
+Security gates:
+- **Injection.** Overlay text never reaches argv or a graph, because the graph references `assetId` only. The injection tests from [wb] WP12 apply to the render job too: SVG text nodes are XML-escaped, and the template engine is typed field-slot substitution, not string concatenation.
+- **Worker storage access.** The worker fetches assets through presigned GETs scoped to its assignment ([prop] §4.5 object-storage tenant ACLs).
+
+**Not verified:**
+- resvg and sharp APIs. flash fetched the resvg README; glm did not verify either. **Pick resvg-js.**
+- Whether the image2 demuxer re-reads a file on `-loop 1`. flash and glm do not discuss it. It is **no longer needed**, because edits go through the swap.
+
+---
+
+## 5. Playlist fallback + Auto Director
+
+### 5.1 Fallback venue [both]
+
+**Decision: worker-side fallback.** The PeerTube live is `permanentLive: true`, so the channel URL stays live forever. "Nothing is live" means the director puts the **FALLBACK scene** on program.
+- No live/VOD flapping, no RTMP reconnect, and no change of PeerTube latency mode. Overlays and program audio stay consistent [flash] Q5, [glm] Q5.
+- There is no PeerTube API to play a playlist into a live [flash] Q5 (verified absence). Switching a channel between live and VOD relies on unverified viewer-UI behaviour [glm] Q5.
+- `permanentLive` and `saveReplay` are mutually exclusive (verified 400 error). Fallback channels therefore run **without replay**, and the channel config UI says so [flash] Risk 5.
+
+**Deferred.** [glm]'s **Tier-2 mode** ("live windows + PeerTube playlist page", where the worker stops pushing when dark) is a cost-saving option for channels that do not need continuity. It is **not in this plan**. Revisit it after we have measured the 24/7 encoder cost.
+
+**Mechanics** [SYN] (fits the WP9 sandbox: FFmpeg reads only pipes):
+- **A playlist is a source kind** (`kind: "playlist"`). A worker-side **asset feeder** walks the ordered asset list:
+  - assets are presigned GETs through the ingest egress relay;
+  - they are piped one after another into a normal ingest process (`-re`, normalize stage);
+  - the compositor sees a continuous input like any other source.
+  - Asset boundaries are hidden by the ingest normalize stage plus the gate (PTS regenerated). Concat-protocol tricks are not used; they are banned by the WP9 protocol rules.
+- **Assets are pre-normalized at upload** to the channel profile by the existing WP4 video pipeline. Loops never transcode. Pricing therefore follows the [glm] "normalize-on-ingest, not in the loop" note.
+- **Programming source of truth.** The FALLBACK scene's playlist is either a local asset list or **mirrored from a PeerTube channel playlist** through the connector (`GET /video-playlists/{id}/videos`), downloaded to S3 and normalized [flash] Q5.
+- **Slate floor.** A static slate (logo + "back soon" + optional clock) is generated by the overlay renderer. It is always available, independent of asset availability. When the playlist ingest is unhealthy (asset missing, decode error), the scene degrades to the slate automatically.
+
+### 5.2 Auto Director rules [both]
+
+The evaluation context and plumbing already exist and are not redesigned here:
+- **Monitor states**: the reducer emits `OFFLINE|PROBING|LIVE|UNSTABLE|ERROR`, with STARTING/ENDING/UNKNOWN added in the DB. Hysteresis: `liveConfirmations=2`, `offlineConfirmations=3`, `noMediaMs=10 s`, `minHoldMs=2 s`, `cooldownMs=10 s` (`apps/api/src/live-monitor/reducer.ts`).
+- **Evaluation plumbing**: WP10's 250 ms debounce, one evaluation in flight per channel, and `continue-as-new`.
+
+Rule ladder, evaluated top-down. The first match writes program.
+
+1. **Program lock / operator override** (four WP10 release modes). Automation never undoes a human TAKE while an override or lock holds [both].
+2. **Media-health failover**: if the program source's media-health tier reports failure, the debounce is bypassed. Fail over to the next eligible source, otherwise to FALLBACK. This works during an API outage (WP10).
+3. **Scheduled windows**: WP13 schedules can force a scene inside a window.
+4. **Priority list**: the highest-priority source in `LIVE` wins. A source already on program that turns `UNSTABLE` keeps program until `noMediaMs` plus confirmations expire.
+5. **Terminal**: the FALLBACK scene (playlist, else slate).
+
+Anti-flap at the director level [glm] Q7:
+- **Dwell time by source class.** Defaults: a live source holds at least 15 s; FALLBACK holds at least 60 s before a newly LIVE source may preempt it, unless that source's priority is "interrupt". This complements, and does not duplicate, monitor hysteresis.
+- **Cooldown** of 10 s per source after it leaves program before it may return automatically.
+- Out of scope: "real direction" such as audio-activity speaker switching or content-aware cuts. Future work adds it as new *conditions* in the rule `condition` jsonb, not as a new engine [both].
+
+**Monitor-state integration in the Control Room.** The UI renders:
+- AUTO/MANUAL/LOCKED status;
+- for each rule, a "**would fire now**" indicator computed from the same monitor snapshot, so operators see *why* the director acted [flash] Q7;
+- a dwell countdown on the program tile;
+- **RETURN TO AUTO**, which re-arms the ladder.
+
+Every automated action uses the same bus transaction as a human TAKE: one `desired_version` bump and one outbox row. Automation has no special-cased path [glm] Q7.
+
+### 5.3 PGM/PST control set (web now, same commands on mobile later) [both]
+
+The v1 control set:
+- **PST select** (tile or scene);
+- **CUT** (TAKE, `transition: {type:"cut"}`);
+- **overlay on/off** for each overlay slot (armed on PST, live after TAKE);
+- **program audio** primary pick and gain steps;
+- **monitor audio** (local only);
+- **LOCK**;
+- **RETURN TO AUTO**.
+
+Layout picker, position swap and PIP all operate on the **PST scene** and reach program only through TAKE [flash] Q6.
+
+FADE (`{type:"fade", ms: 300|500|1000|2000}`) is added in S4 behind the continuity gate (D8). If a fade graph fails to start within 1 s, the worker degrades to CUT and reports `TRANSITION_DEGRADED` [flash] Risk 2.
+
+Every command carries an `Idempotency-Key` and is checked against `director.*`. The target is under 300 ms from command to observed (WP11).
+
+Mobile "go live from preview" is the same PST select followed by TAKE. It needs no new server surface.
+
+---
+
+## 6. Phased build plan
+
+Six dispatchable slices. Migration numbers are **pre-assigned** so parallel slices do not collide. `011` stays reserved for the review workflow ([dm] §4), and `012` exists.
+
+Default gate for every slice: `pnpm typecheck && pnpm test` green from the repo root (turbo), plus the slice-specific gates below. Each slice writes `runs/<wp>/<slice>-report.md`.
+
+```
+         ┌── S2 worker compositor ──┐
+S1 ──────┤                          ├── S4 fallback + director + FADE
+         └── S3 control room ───────┘
+S5 chat hub + contract   (independent; starts day 1)  ── S5b Opticast client (anarchostreamer repo, after S5 contract freeze)
+S6 telegram WP15 middle  (independent; starts day 1)
+```
+
+**Parallelism:** S1, S5 and S6 can start together. S2 and S3 run in parallel once S1 lands. S3 develops against a fake worker that echoes realized versions. S4 needs both S2 and S3.
+
+### S1 — Desired-state v2 + production schema (small; blocks S2/S3)
+
+- **Scope:**
+  - Extend `DesiredChannel`/`DesiredSpec` from a single `source:{kind:"hls"}` to `{ scenes, buses, sources[], overlays[], transition, audio }`. Old v1 snapshots must still validate.
+  - Keep the strict key allowlist and secret rejection.
+  - Add migration `013_production.sql`: `production_scenes`, `scene_slots` (layout enum, geometry CHECKs, `audio_mode` with the one-primary partial unique index, `gain_db` in −24…0 in steps of 3), `production_buses` (preview|program, unique per channel), `overlay_slots`/`overlay_revisions` (by asset id), and `source.kind` gaining `playlist`.
+  - All tables use channel-scoped composite FKs for the same-channel invariant, plus RLS.
+- **Files:** `apps/api/src/media-control/spec.ts`, `wire.ts`, `apps/media-worker/src/types.ts`, `apps/api/migrations/013_production.sql`, plus tests.
+- **Gates:**
+  - Old snapshots round-trip.
+  - The [wb] WP12 same-channel invariant tests fail at the DB constraint.
+  - Injection payloads in labels (`;[,'`, `movie=`) are rejected by the type layer.
+  - The RLS denial suite covers the new tables.
+
+### S2 — Worker compositor + frame gate + taps (XL, highest risk; after S1, ∥ S3)
+
+- **Scope:**
+  - The **frame-gate spike** comes first (§1.4 gate: Node vs Rust; 1 000-swap continuity).
+  - `MediaCommandBuilder` graph builders emit `xstack` (2x1/2x2/3x3/4x4 plus custom), PIP `overlay`, overlay asset inputs, chyron x-expression, and `volume`+`amix`, all from typed params only.
+  - Ingest×N normalize stage; compositor A/B lifecycle in the supervisor; persistent encoder fed by the gate; playlist feeder ingest.
+  - Preview taps: JPEG, 360p LL-HLS, audio-only, and the program tap.
+  - The supervisor/bus/fence stay **untouched** apart from the meaning of a RUNNING snapshot [glm] Phase 1.
+- **Files:** `apps/media-worker/src/compositor/*` (new), `src/gate/*` (new), `src/relay/ffmpeg.ts` (generalized), `src/supervisor/index.ts` (A/B lifecycle), `src/preview/*` (new).
+- **Gates:**
+  - Golden-frame hashes for each layout.
+  - **Zero gap at the encoder input** across 1 000 scripted scene, overlay and gain swaps (frame counter plus PCM continuity check).
+  - A 4-input 1080p30 CPU budget test on the reference host.
+  - `kill -9` of the compositor mid-swap leaves the encoder and RTMP session up.
+  - The ≥8 h soak is wired into the nightly run (not blocking merge).
+  - Existing WP9 sandbox, bus and secret-leak suites stay green.
+
+### S3 — Control plane + Control Room UI + overlay pipeline (XL; after S1, ∥ S2)
+
+- **Scope:**
+  - **Bus writes**: TAKE/CUT/PST-select/lock/override in `media-control.service.ts`. One tx = bus write + `desired_version++` + outbox, with `Idempotency-Key` and `director.*`.
+  - **Preview endpoint**: ETag, single-flight fill, same-origin, signed short TTL.
+  - **Realtime gateway**:
+    - wire `/realtime` for real, including the **subscribe-capable Redis client**, which is shared with S5;
+    - **S3 owns the gateway** and S5 builds on it;
+    - if S5 starts first, S5 lands the gateway and S3 rebases.
+  - **Web**: multiview tiers per §2.2, Web Audio monitor per §2.3, PST canvas look-ahead, tally from observed state only, overlay editor.
+  - **Overlay pipeline**: SVG templates → resvg-js render job → StorageService → asset id → desired-state bump.
+- **Files:** `apps/api/src/media-control/*`, `apps/api/src/realtime/*`, `apps/api/src/production/*` (new: scenes, overlays, preview), `apps/web/src/app/control-room/*`, `apps/web/src/components/control-room/*`.
+- **Gates:**
+  - Idempotency matrix: duplicate, concurrent duplicate, crash mid-tx.
+  - Command → observed under 300 ms against the fake worker.
+  - Playwright E2E: PST → CUT → tally flips only on observed state.
+  - Grid tier caps enforced: a 5th live tile is refused.
+  - Overlay injection tests through the render job.
+  - Revocation evicts the operator within 5 s.
+
+### S4 — Fallback scene + Auto Director v1 + FADE (L; after S2 + S3)
+
+- **Scope:**
+  - FALLBACK scene: playlist source mirrored from a PeerTube channel playlist via `packages/connector-peertube`, plus the slate floor.
+  - `permanentLive` wiring and the replay conflict surfaced in channel config.
+  - Rule ladder per §5.2 with dwell-by-class and cooldown, consuming live-monitor outbox events (WP10 intake rules).
+  - "Would fire now" indicators and RETURN TO AUTO.
+  - FADE via the two-swap transition graph, degrading to CUT.
+- **Files:** `apps/api/src/director/*` (new), `apps/scheduler/*` (Temporal evaluator workflow), `packages/connector-peertube/src/*` (playlist mirror), `apps/media-worker/src/compositor/transition.ts`, and the Control Room AUTO panel.
+- **Gates:**
+  - [wb] WP10 matrix: 0/1/2/3+ live, high-priority interrupt, TAKE not undone, lock stability, flap damping, failover without output kill, API-outage scenario.
+  - Event-storm test (50 sources at 10 Hz → ≤4 evaluations/s).
+  - Playlist asset removed mid-loop → slate within 2 s with no output gap.
+  - FADE continuity holds across 200 fades.
+
+### S5 — Chat hub + unified contract + web chat panel (L; independent)
+
+- **Scope:**
+  - **Phase 0 contract** (§3.5) frozen in `packages/core` as types and JSON schema.
+  - Migration `014_live_chat.sql`: `live_chat_messages` partitioned monthly, `live_chat_seen_events`, `devices`, `device_pairings`.
+  - `apps/api/src/live-chat/` (new):
+    - Twitch EventSub WS and YouTube shared-poller ingestion;
+    - seq assignment and ring buffer;
+    - send governors (token buckets, YT quota ledger);
+    - reply fan-out and moderation fan-out with per-target `Delivery`;
+    - display filters.
+  - Twitch connector gains Helix send/moderate.
+  - Device pairing.
+  - Web chat panel in the Control Room.
+  - PeerTube XMPP adapter = **S5 phase 2**. Ship capability-probe + read-only-embed + comments first.
+- **Files:** `apps/api/src/live-chat/*`, `apps/api/src/devices/*`, `apps/api/src/realtime/*` (shared with S3, see S3), `packages/connector-twitch/src/index.ts`, `packages/connector-mock-livestream/*`, `apps/web/src/components/live-chat/*`, `apps/api/migrations/014_live_chat.sql`.
+- **Gates:**
+  - Mock-livestream E2E: ingest → hub → Redis → WS → client, including `lastSeq` resume and the `resync` path.
+  - Dedupe: the same provider id twice gives one row.
+  - Authz-epoch bump closes sockets within 5 s.
+  - The YT quota ledger refuses a send below budget and surfaces `paused:quota`.
+  - Delivery `unsupported` per target never fails the batch.
+  - Retention sweep test per the [wb] cross-cutting row.
+- **S5b — Opticast client** (separate repo `anarchostreamer`; dispatch after the S5 contract freeze):
+  - OkHttp (its only new network dependency), a pairing settings screen, `ChatViewModel` + bottom sheet, WS lifetime tied to `StreamingService`, the composer with target pill, and swipe moderation.
+  - Gate: `testDebugUnitTest assembleDebug` green, plus a contract test against a recorded S5 WS transcript.
+
+### S6 — WP15 Telegram middle (M; independent)
+
+- **Scope** [tg] §5 Phase 1:
+  - Migration `015_archive.sql`: `feed_subscriptions` (`{type:"telegram_channel", connectionId, channelId}`) and `archived_feed_items` (RLS; dedup on `(workspace_id, remote_ref=chat_id:message_id)` and content hash).
+  - Channel-post normalizer: `media_group_id` album debounce of 2 s, `edited_channel_post` → revision, `forward_origin` and `author_signature` kept as attribution.
+  - `my_chat_member` → subscription health ("bot removed").
+  - Media harvest via `getFile` into StorageService. Files over 20 MB are recorded as "Bot API cannot fetch", not failed.
+  - "Create draft from archived item" → the existing review states in `publishing.service.ts`.
+  - Approval calls the existing `amplify()`. Protected content shows "amplify unavailable".
+  - Rights note in the UI, and attribution on by default.
+  - No MTProto.
+- **Dependency note.** The draft binding targets today's `editing → in_review → approved` states. When the review workflow (`011`, [dm] WP5.1–5.2) lands, the archived-item draft enters the review cycle unchanged, because it is just a draft. Amplifying others' content must **never auto-publish** [tg] §2.3.
+- **Files:** `apps/api/src/archive/*` (new), `packages/connector-telegram/src/index.ts` (normalizer hook only), `apps/api/src/publishing/*` (draft-from-item), `apps/web/src/app/archive/*`, `apps/api/migrations/015_archive.sql`.
+- **Gates:**
+  - Webhook fixture → one archived row for a 3-photo album.
+  - The same post via two subscriptions → one row.
+  - The same image → one blob.
+  - Tenant B cannot read tenant A's rows despite a shared blob.
+  - A protected-content forward surfaces `ConnectorError`.
+  - E2E: post → archive → draft → approve → `forwardMessage` on the mock.
+
+### 6.4 Not in this plan (follow-ons)
+
+- Opticast as a camera **source**: an `rtmp-push`/`srt-listen` ingest kind with per-channel ingest keys.
+- WHIP guest contribution.
+- Tier-2 PeerTube-playlist mode.
+- MTProto grabber ([tg] Phase 2: flagged, ToS disclosure).
+- Chat relay bot.
+- Runtime `azmq` gain control.
+- Mobile Control Room screens. These reuse the S3 endpoints and need no new server surface.
+
+---
+
+## 7. Top risks and mitigations
+
+| # | Risk | Likelihood / impact | Mitigation |
+|---|---|---|---|
+| 1 | **The frame gate / A/B swap is not frame-continuous**, or costs too much CPU. Every TAKE, overlay and gain change depends on it. | Medium / critical | It is the first task of S2 and gates the whole slice: 1 000-swap continuity plus a CPU budget; a Rust gate if Node fails; GStreamer `input-selector` as the escalation path (the WP9 decision gate). The transient doubled-compositor CPU is reserved inside the 20 % failover headroom. |
+| 2 | **Multiview expectations versus browser physics.** Users expect 16 live tiles. Decode limits are undocumented ([both]: not verified), and iPhone MSE exists only from 17.1. | High / medium | Thumbnail-default tiers with a hard cap of 4 (1 on mobile) and explicit tile-state copy. Run a device-matrix test before any marketing claim. Tiles never decode remote sources. |
+| 3 | **Worker CPU at scale.** A 1080p30 N-input grid plus overlays and `amix`, plus an always-on fallback encoder 24/7 for every channel. | High / high | Input caps per profile in admission. Playlist assets pre-normalized, never transcoded in the loop. FALLBACK priced in capacity units, not treated as free. Tier-2 "dark" mode as the documented future cost lever. CI CPU-budget test in S2. |
+| 4 | **Chat platform fragility**: Twitch has no EventSub replay and harsh rate enforcement; the YouTube quota is 10k/day; the PeerTube livechat plugin varies by instance and its bot token is unsupported. | High / medium | Ring-buffer resume plus `chat.gap` markers. Token buckets and the quota ledger with `paused:*` states. Capability probe with tiered PeerTube degradation (C2S → read-only embed → comments). Request a YouTube quota increase for production. |
+| 5 | **PeerTube coupling**: `permanentLive` excludes replay, Small latency disables P2P, and live↔VOD switching is unmeasured. | Medium / high | Worker-side FALLBACK from day one. Replay and latency mode are explicit channel config with in-UI consequences. Measure live-end→reconnect on a test instance before promising Tier-2. |
+| 6 | **Overlay and asset attack surface**: SVG parsing, fonts, render-job resource exhaustion. | Medium / high | Server-owned templates with typed field slots. resvg with no scripts and no external fetch, run in the WP4 sandbox with time and memory limits. Rendered PNGs are content-addressed and cached. FFmpeg only ever sees asset ids. Injection tests in S1 and S3. |
+| 7 | **Telegram amplification ethics and ToS**: re-posting others' content, protected channels, the 20 MB bot cap. | Certain / medium | A human review gate is mandatory. Attribution is on by default. Protected content and oversize media are surfaced honestly. MTProto stays out of this plan. |
+| 8 | **Opticast privacy pledge erosion**: pressure to add FCM, analytics or a cloud relay. | Medium / medium | The contract offers no push and only the self-hosted endpoint. The integration is opt-in and off by default. Any push must be UnifiedPush/self-hosted and opt-in. The relationship stays API-only, so the unresolved GPLv3 question remains moot. |
+
+---
+
+## Appendix — where the two control-room reports disagree
+
+| Topic | [flash] | [glm] | Pick | Why |
+|---|---|---|---|---|
+| Process topology | One FFmpeg per channel | Split ingest/compositor/encoder/pusher ([prop]) | **Split + frame gate** | FFmpeg cannot rewire graphs, so a single process restarts the RTMP session on every change. |
+| Overlay text | Pre-rendered PNG (SVG→resvg) | `drawtext` + `textfile` `reload` | **PNG** | PST/PGM pixel parity, brand typography, fonts kept out of the 24/7 sandbox, cheaper CPU. glm's no-restart edge is covered by the A/B swap. |
+| Live tile cap at 3x3/4x4 | Focused + PST live (≤4 total) | 1–2 live (focus + PGM) | **PGM + focused live, cap 4 on explicit upgrade** | The PGM tile must be real, so its truth comes from the program tap. PST is a client-side look-ahead, not a decoded stream. |
+| Fallback modes | Worker-side only | Worker-side Tier 1 + PeerTube-playlist Tier 2 | **Tier 1 now, Tier 2 deferred** | Tier 2 depends on unverified PeerTube UI behaviour; it stays as a later cost lever. |
+| Program gain changes | `amix` runtime commands | Desired-state bump in coarse 3 dB steps | **3 dB steps via swap; runtime commands later** | `azmq` availability is unverified, and swaps are already continuous. |
+| PST rendering | Not specified (implied worker) | Browser preview compositor (canvas) | **Browser canvas look-ahead** | Avoids a second server composite for each channel. |
+| Transitions | CUT plus FADE presets; fall back to CUT | CUT plus 300 ms fade default | **CUT in v1; FADE in S4, degrading to CUT** | FADE needs a two-swap transition graph and must be proven continuous first. |
diff --git a/docs/engineering-guide.md b/docs/engineering-guide.md
new file mode 100644
index 0000000..fc86e23
--- /dev/null
+++ b/docs/engineering-guide.md
@@ -0,0 +1,151 @@
+# Tactical Media Broadcast Hub — Engineering Guide
+
+**Covers:** everything built as of `499c9fe` (WP0–WP3-in-flight), plus Level-2 systems as marked *(planned)*. Companion docs: [admin-guide.md](./admin-guide.md) · [user-guide.md](./user-guide.md).
+
+---
+
+## 1. System overview
+
+Tactical Media Broadcast Hub is a self-hosted, multi-tenant social-media management platform (Level 1: post & schedule) growing into a video/livestream master-control system (Level 2, planned). Three planes:
+
+```
+CONTROL PLANE                     MEDIA PLANE (planned, WP9+)
+  apps/web  (Next.js UI)            media-worker: ingest → compositor →
+  apps/api  (NestJS)                  persistent encoder → outputs
+  apps/scheduler (Temporal)        FFmpeg-first; never through the API
+  PostgreSQL · Redis · Temporal
+STORAGE PLANE
+  S3-compatible object storage (MinIO dev / any S3 prod)
+  ALL media client-side encrypted; content-addressed
+```
+
+Hard rules enforced in code: media bytes never transit API processes; provider branching outside connector packages fails lint; passwords never transit the system (OAuth tokens / bot tokens only); every tenant table is RLS-isolated with `FORCE ROW LEVEL SECURITY`.
+
+## 2. Repository layout
+
+```
+apps/
+  web/            Next.js 14 App Router frontend (all screens, mock-registry layer)
+  api/            NestJS control plane (health, auth, rbac, vault, audit, publishing, storage)
+  scheduler/      Temporal worker (publish workflow + activities)
+  media-worker/   health-only stub (WP9 fills it)
+packages/
+  core/           normalized domain types (permissions, connections, publishing, VC family)
+  connector-sdk/  PlatformConnector interface, manifest, registry, HTTP client, contract kits
+  connector-example/ connector-mock-social/ connector-mock-video/ connector-mock-livestream/
+  connector-mastodon/ connector-telegram/          (WP3, in flight)
+  testing/        live-source simulator (dod-flap scenario) + mock RTMP sink
+infra/            docker-compose (postgres:5433, redis, temporal, minio, otel, prometheus, grafana)
+docs/             this documentation set
+```
+
+Monorepo: pnpm workspaces + Turborepo. `pnpm lint|typecheck|build|test` at root runs all 13+ packages.
+
+## 3. Identity, tenancy & security (WP2)
+
+### 3.1 Database roles — two-pool discipline
+- **Owner pool** (`SUPER_DATABASE_URL`, the postgres superuser in dev): runs migrations, provisions. Never serves requests.
+- **App pool** (`DATABASE_URL`, role `sp_app`): neither superuser nor table owner → `FORCE ROW LEVEL SECURITY` binds for real. Created by migration `003_app_role.sql` with table/sequence grants + default privileges.
+
+### 3.2 Row-level security
+Every tenant table (memberships, connections, credentials, audit_log, drafts, publications, scheduled_publications) has:
+```sql
+USING (workspace_id = NULLIF(current_setting('app.workspace_id', true), '')::uuid)
+```
+`NULLIF` matters: pooled sessions carry an empty-string GUC placeholder after `SET LOCAL` commits; without it the cast throws instead of failing closed. Tenant context is set per-transaction via `withTenant(workspaceId, fn)` (`apps/api/src/db/client.ts`) using `set_config(..., true)` — transaction-local, cannot leak.
+
+### 3.3 SECURITY DEFINER discipline (audit finding #3)
+Cross-tenant functions take an explicit `p_workspace_id` and call `fn_assert_tenant()`, which asserts the parameter against the session's tenant context. No unguarded `EXECUTE` grants for `sp_app`.
+
+### 3.4 Continuous authorization (audit finding #2)
+Any membership insert/update/delete fires `bump_authz_epoch()` — `COALESCE(NEW.workspace_id, OLD.workspace_id)` (OLD is NULL on INSERT; the original bug silently no-oped). Sessions embed the epoch at issue; `RbacGuard` compares against the live `workspaces.authz_epoch` and fails closed (`401, epoch stale`) on mismatch. Revocation propagates to live sessions without waiting for re-login.
+
+### 3.5 Sessions & OIDC
+HMAC-SHA256 signed tokens (`apps/api/src/auth/session.ts`), 12h TTL, constant-time verify. OIDC: generic code flow + PKCE S256, discovery-document driven (`auth/oidc.ts`) — Authentik/Keycloak/any compliant issuer via `OIDC_*` env.
+
+### 3.6 Credential vault
+Envelope encryption (`vault/vault.ts`): per-workspace DEK (AES-256-GCM) wrapped by master KEK (`SUPERPOSTER_KEK`, 32B base64; production-required). Rotation re-wraps; old DEK dropped → pre-rotation ciphertext unreadable (tested). Connectors receive opaque `CredentialRef` handles via `CredentialAccessor` — never ciphertext, never raw tokens.
+
+### 3.7 Audit log
+Hash-chained per branch (`audit_append` for tenant rows, `audit_append_system` for workspaceless events). Branch selection is by **tenant-context presence, never by role** (findings #1/#6 — `sp_scheduler` with tenant context appends to the tenant chain). `audit_verify_chain(workspace)` recomputes hashes — tampering is detectable (tested). Secret-shaped keys are scrubbed to `[REDACTED]` before append (`audit/audit.service.ts`).
+
+### 3.8 Storage encryption (user mandate)
+`storage/storage.ts` — client-side envelope: body = `SPENC1 | iv(12) | KEK-wrapped CEK(48) | AES-256-GCM ciphertext+tag`. `S3_KEK` required in production. SSE-at-rest header set additionally. Keys are the **plaintext** sha256 (`sha256/<hash>.<ext>`), so put-dedup survives; `getObject` re-verifies the hash → storage tampering throws. Cross-workspace media dedup is storage-level only; row visibility stays tenant-scoped.
+
+## 4. Connector architecture (WP1)
+
+### 4.1 The contract
+`PlatformConnector` (`connector-sdk/src/types.ts`): `manifest()`, `authorize()`, `getIdentity()`, optional `publish/uploadMedia/uploadVideo/getFeed/getComments/reply/getMessages/amplify/unamplify/subscribeWebhooks/handleWebhook/...`. Every list method returns `Page<T, cursor>`.
+
+### 4.2 Manifest & capabilities
+`ConnectorManifest` declares `id`, `displayName`, `capabilities` (30+ booleans incl. `amplifyRepost/amplifyQuote/amplifyShare`), `connectionFields` (e.g. Mastodon `instanceUrl`, Telegram `botToken` secret), `oauth` flavor. **The manifest validator rejects password fields outright.** UI renders strictly from capabilities — an undeclared capability renders nothing, never a grayed-out lie.
+
+### 4.3 Registry & the no-branching rule
+`ConnectorRegistry.register/get` — unknown provider throws `UnknownProviderError`. The ESLint rule `no-restricted-syntax` (root `eslint.config.mjs`) fails any provider string literal outside `packages/connector-*/`, `packages/testing/`, and `apps/web/src/lib/` (the mock-registry boundary standing in for the real registry until the API wires up — same discipline, documented in the config).
+
+### 4.4 HTTP discipline
+`RateLimitedHttpClient`: per-host token bucket (default 1 rps; Mastodon 0.5), exponential backoff with jitter on 429/5xx, `Retry-After` honored.
+
+### 4.5 Amplify truth table (verified per platform, 2026)
+| Platform | Repost | Quote | Share | Notes |
+|---|---|---|---|---|
+| Mastodon | ✅ reblog | ✅ `quoted_status_id` (≥4.5) | — | native scheduling via `scheduled_at` |
+| Telegram | — | — | ✅ forward/copy | `has_protected_content` blocks |
+| Facebook | ⚠️ no native reshare API | — | link-share approximation | manifest marks degraded |
+| Instagram | ❌ | ❌ | own-media stories only | API exposes no amplify |
+| Bluesky / Threads / LinkedIn | ✅ / ✅ / ✅(reshare w/ commentary) | ✅ / ✅ / — | — | Level 1b wave |
+| Reddit | — | — | crosspost (stable-but-undocumented) + vote | no vote automation ever |
+| X | ✅ (metered) | ❌ self-serve (Apr 2026) | — | deferred; pay-per-post model when added |
+
+### 4.6 Contract test kits
+`connectorContractTests / videoConnectorContractTests / livestreamConnectorContractTests` — capability-aware: declared capability without implementing method = FAIL; methods behind undeclared capabilities must be absent. Kits caught two real violations during development.
+
+## 5. Publishing pipeline (WP3, sol-delivered & verified)
+
+- **State machine** (`publishing.service.ts`): `editing → in_review → approved → scheduled → published` (+ `rejected`, `cancelled`). Every transition permission-checked (`approval.request` / `approval.grant` / `publication.schedule`) and audited.
+- **Durability** (`006_publishing.sql`): `scheduled_publications` carries a `UNIQUE idempotency_key`; the DB row commits first; if Temporal is unreachable the row stays `pending` and the worker's startup sweep picks it up.
+- **Temporal** (`scheduler/src/workflows/publish.workflow.ts`): `scheduledPublish(id)` activity (5-min timeout) claims pending-only, resolves the connector via registry, publishes, records the publication, idempotent on re-run.
+
+## 6. Frontend (apps/web)
+
+Tailwind v4 `@theme` tokens (dark-first OKLCH, `@theme inline` brand hook for tenant theming), hand-rolled primitives, cmdk palette, TanStack Virtual streams (500+ items/column, scroll-into-view), Tiptap compose with per-platform char counters/previews. **Streams flagship:** capability-gated amplify bars, keyboard `j/k` navigate, `r` repost, `q` quote. All data from `src/lib/` mock-registry (fixtures are seeded-deterministic). QA: `apps/web/scripts/visual-qa.mjs` — 14 states, 0 console errors; byte-diff confirms every interaction renders.
+
+## 7. Testing strategy
+
+| Suite | What it proves | Runs |
+|---|---|---|
+| connector contract kits | connectors don't lie about capabilities | CI, always |
+| pure units (vault, session, oidc, scrub, storage-crypto, key-scheme) | crypto/format invariants incl. tamper detection | CI, always |
+| `tenancy.integration.test.ts` | RLS isolation, tenant-branch audit, epoch bump, chain tamper, immutability triggers | needs `DATABASE_URL` (sp_app) + `SUPER_DATABASE_URL` (owner), else skips |
+| `storage.integration.test.ts` | S3 roundtrip, dedup, presign | needs `S3_ENDPOINT`, else skips |
+| visual-qa (playwright) | screens render, interactions fire, console clean | local/CI with chromium |
+
+Live-DB invocation (from repo root, postgres on :5433):
+```
+DATABASE_URL='postgresql://sp_app:sp_app_dev@localhost:5433/tmbh' \
+SUPER_DATABASE_URL='postgresql://tmbh:tmbh_dev@localhost:5433/tmbh' \
+pnpm --filter @tactical-media-broadcast-hub/api test
+```
+
+## 8. Observability & ops surface
+
+`/healthz` (liveness), `/readyz` (TCP probes: postgres/redis/temporal with per-component status). OTel OTLP tracing skeleton (disabled-safe without collector). Structured pino logs with credential-key redaction. Grafana (3001) provisioned against Prometheus (9090). Full metrics rollout is WP14.
+
+## 9. Level 2 systems *(planned — designs in proposal.md §4.4)*
+
+Live Source Monitor (adaptive polling, anti-flapping, per-host budgets); media engine (persistent encoder, graph-rewire switching, GStreamer decision gate); Auto Director (policies/rules/override/program-lock); control room (Preview/Program, TAKE/CUT); archive/grabber/crosspost (S3-mandated, encrypted, content-deduped).
+
+## 10. Key file map
+
+| Concern | Path |
+|---|---|
+| Tenant context / pools | `apps/api/src/db/client.ts` |
+| Migrations 001–006 | `apps/api/migrations/` |
+| Vault / storage crypto | `apps/api/src/vault/vault.ts`, `apps/api/src/storage/storage.ts` |
+| Sessions / OIDC | `apps/api/src/auth/` |
+| RBAC guard | `apps/api/src/rbac/rbac.guard.ts` |
+| Audit chain | `migrations/001_tenants.sql` (SQL) + `apps/api/src/audit/` |
+| Publishing | `apps/api/src/publishing/`, `apps/scheduler/src/` |
+| Connector SDK | `packages/connector-sdk/src/` |
+| Frontend mock-registry | `apps/web/src/lib/` |
+| Lint: no-provider-branching | `eslint.config.mjs` |
diff --git a/docs/manual/screenshots/desktop-analytics.png b/docs/manual/screenshots/desktop-analytics.png
new file mode 100644
index 0000000..4af92bb
Binary files /dev/null and b/docs/manual/screenshots/desktop-analytics.png differ
diff --git a/docs/manual/screenshots/desktop-approvals.png b/docs/manual/screenshots/desktop-approvals.png
new file mode 100644
index 0000000..e20806a
Binary files /dev/null and b/docs/manual/screenshots/desktop-approvals.png differ
diff --git a/docs/manual/screenshots/desktop-audit-diff-open.png b/docs/manual/screenshots/desktop-audit-diff-open.png
new file mode 100644
index 0000000..9199046
Binary files /dev/null and b/docs/manual/screenshots/desktop-audit-diff-open.png differ
diff --git a/docs/manual/screenshots/desktop-audit-sample.png b/docs/manual/screenshots/desktop-audit-sample.png
new file mode 100644
index 0000000..d8a32bf
Binary files /dev/null and b/docs/manual/screenshots/desktop-audit-sample.png differ
diff --git a/docs/manual/screenshots/desktop-audit.png b/docs/manual/screenshots/desktop-audit.png
new file mode 100644
index 0000000..63caf55
Binary files /dev/null and b/docs/manual/screenshots/desktop-audit.png differ
diff --git a/docs/manual/screenshots/desktop-calendar.png b/docs/manual/screenshots/desktop-calendar.png
new file mode 100644
index 0000000..62c5d64
Binary files /dev/null and b/docs/manual/screenshots/desktop-calendar.png differ
diff --git a/docs/manual/screenshots/desktop-command-palette.png b/docs/manual/screenshots/desktop-command-palette.png
new file mode 100644
index 0000000..891fd5e
Binary files /dev/null and b/docs/manual/screenshots/desktop-command-palette.png differ
diff --git a/docs/manual/screenshots/desktop-compose-draft-saved.png b/docs/manual/screenshots/desktop-compose-draft-saved.png
new file mode 100644
index 0000000..44fef26
Binary files /dev/null and b/docs/manual/screenshots/desktop-compose-draft-saved.png differ
diff --git a/docs/manual/screenshots/desktop-compose-empty.png b/docs/manual/screenshots/desktop-compose-empty.png
new file mode 100644
index 0000000..b272ff9
Binary files /dev/null and b/docs/manual/screenshots/desktop-compose-empty.png differ
diff --git a/docs/manual/screenshots/desktop-compose-sample.png b/docs/manual/screenshots/desktop-compose-sample.png
new file mode 100644
index 0000000..35d43b3
Binary files /dev/null and b/docs/manual/screenshots/desktop-compose-sample.png differ
diff --git a/docs/manual/screenshots/desktop-compose-typed.png b/docs/manual/screenshots/desktop-compose-typed.png
new file mode 100644
index 0000000..d9346dc
Binary files /dev/null and b/docs/manual/screenshots/desktop-compose-typed.png differ
diff --git a/docs/manual/screenshots/desktop-connections-capacity-popover.png b/docs/manual/screenshots/desktop-connections-capacity-popover.png
new file mode 100644
index 0000000..c163855
Binary files /dev/null and b/docs/manual/screenshots/desktop-connections-capacity-popover.png differ
diff --git a/docs/manual/screenshots/desktop-connections-live-empty.png b/docs/manual/screenshots/desktop-connections-live-empty.png
new file mode 100644
index 0000000..b87a6ec
Binary files /dev/null and b/docs/manual/screenshots/desktop-connections-live-empty.png differ
diff --git a/docs/manual/screenshots/desktop-connections-sample.png b/docs/manual/screenshots/desktop-connections-sample.png
new file mode 100644
index 0000000..d4afc82
Binary files /dev/null and b/docs/manual/screenshots/desktop-connections-sample.png differ
diff --git a/docs/manual/screenshots/desktop-inbox.png b/docs/manual/screenshots/desktop-inbox.png
new file mode 100644
index 0000000..cea7c71
Binary files /dev/null and b/docs/manual/screenshots/desktop-inbox.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-connect-simulated.png b/docs/manual/screenshots/desktop-onboarding-connect-simulated.png
new file mode 100644
index 0000000..92b13ce
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-connect-simulated.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-connect.png b/docs/manual/screenshots/desktop-onboarding-connect.png
new file mode 100644
index 0000000..d80c2d3
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-connect.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-done.png b/docs/manual/screenshots/desktop-onboarding-done.png
new file mode 100644
index 0000000..37f9a76
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-done.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-invite.png b/docs/manual/screenshots/desktop-onboarding-invite.png
new file mode 100644
index 0000000..87dcfd1
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-invite.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-register-filled.png b/docs/manual/screenshots/desktop-onboarding-register-filled.png
new file mode 100644
index 0000000..e52075b
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-register-filled.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-register.png b/docs/manual/screenshots/desktop-onboarding-register.png
new file mode 100644
index 0000000..cc57494
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-register.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-sample.png b/docs/manual/screenshots/desktop-onboarding-sample.png
new file mode 100644
index 0000000..ba79b89
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-sample.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-signed-in.png b/docs/manual/screenshots/desktop-onboarding-signed-in.png
new file mode 100644
index 0000000..9c8d4c3
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-signed-in.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-signin-error.png b/docs/manual/screenshots/desktop-onboarding-signin-error.png
new file mode 100644
index 0000000..b297b8a
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-signin-error.png differ
diff --git a/docs/manual/screenshots/desktop-onboarding-signin.png b/docs/manual/screenshots/desktop-onboarding-signin.png
new file mode 100644
index 0000000..e316e4c
Binary files /dev/null and b/docs/manual/screenshots/desktop-onboarding-signin.png differ
diff --git a/docs/manual/screenshots/desktop-settings.png b/docs/manual/screenshots/desktop-settings.png
new file mode 100644
index 0000000..930d199
Binary files /dev/null and b/docs/manual/screenshots/desktop-settings.png differ
diff --git a/docs/manual/screenshots/desktop-streams-quote-modal.png b/docs/manual/screenshots/desktop-streams-quote-modal.png
new file mode 100644
index 0000000..33c703c
Binary files /dev/null and b/docs/manual/screenshots/desktop-streams-quote-modal.png differ
diff --git a/docs/manual/screenshots/desktop-streams-repost-toast.png b/docs/manual/screenshots/desktop-streams-repost-toast.png
new file mode 100644
index 0000000..ba32a8d
Binary files /dev/null and b/docs/manual/screenshots/desktop-streams-repost-toast.png differ
diff --git a/docs/manual/screenshots/desktop-streams-selected.png b/docs/manual/screenshots/desktop-streams-selected.png
new file mode 100644
index 0000000..c5448e2
Binary files /dev/null and b/docs/manual/screenshots/desktop-streams-selected.png differ
diff --git a/docs/manual/screenshots/desktop-streams.png b/docs/manual/screenshots/desktop-streams.png
new file mode 100644
index 0000000..d903033
Binary files /dev/null and b/docs/manual/screenshots/desktop-streams.png differ
diff --git a/docs/manual/screenshots/desktop-team-sample.png b/docs/manual/screenshots/desktop-team-sample.png
new file mode 100644
index 0000000..51963c3
Binary files /dev/null and b/docs/manual/screenshots/desktop-team-sample.png differ
diff --git a/docs/manual/screenshots/desktop-team.png b/docs/manual/screenshots/desktop-team.png
new file mode 100644
index 0000000..a02f7e6
Binary files /dev/null and b/docs/manual/screenshots/desktop-team.png differ
diff --git a/docs/manual/screenshots/desktop-video-after-delete.png b/docs/manual/screenshots/desktop-video-after-delete.png
new file mode 100644
index 0000000..1813697
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-after-delete.png differ
diff --git a/docs/manual/screenshots/desktop-video-after-refresh.png b/docs/manual/screenshots/desktop-video-after-refresh.png
new file mode 100644
index 0000000..b1ad97d
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-after-refresh.png differ
diff --git a/docs/manual/screenshots/desktop-video-delete-confirm.png b/docs/manual/screenshots/desktop-video-delete-confirm.png
new file mode 100644
index 0000000..8b9e999
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-delete-confirm.png differ
diff --git a/docs/manual/screenshots/desktop-video-detail-drawer.png b/docs/manual/screenshots/desktop-video-detail-drawer.png
new file mode 100644
index 0000000..6f9937f
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-detail-drawer.png differ
diff --git a/docs/manual/screenshots/desktop-video-empty.png b/docs/manual/screenshots/desktop-video-empty.png
new file mode 100644
index 0000000..5a40648
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-empty.png differ
diff --git a/docs/manual/screenshots/desktop-video-library.png b/docs/manual/screenshots/desktop-video-library.png
new file mode 100644
index 0000000..e5052e4
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-library.png differ
diff --git a/docs/manual/screenshots/desktop-video-sample.png b/docs/manual/screenshots/desktop-video-sample.png
new file mode 100644
index 0000000..1d3ba4c
Binary files /dev/null and b/docs/manual/screenshots/desktop-video-sample.png differ
diff --git a/docs/manual/screenshots/mobile-analytics.png b/docs/manual/screenshots/mobile-analytics.png
new file mode 100644
index 0000000..c0b66cf
Binary files /dev/null and b/docs/manual/screenshots/mobile-analytics.png differ
diff --git a/docs/manual/screenshots/mobile-approvals.png b/docs/manual/screenshots/mobile-approvals.png
new file mode 100644
index 0000000..884f0c6
Binary files /dev/null and b/docs/manual/screenshots/mobile-approvals.png differ
diff --git a/docs/manual/screenshots/mobile-audit.png b/docs/manual/screenshots/mobile-audit.png
new file mode 100644
index 0000000..38c4801
Binary files /dev/null and b/docs/manual/screenshots/mobile-audit.png differ
diff --git a/docs/manual/screenshots/mobile-calendar.png b/docs/manual/screenshots/mobile-calendar.png
new file mode 100644
index 0000000..644c492
Binary files /dev/null and b/docs/manual/screenshots/mobile-calendar.png differ
diff --git a/docs/manual/screenshots/mobile-compose.png b/docs/manual/screenshots/mobile-compose.png
new file mode 100644
index 0000000..0fd2206
Binary files /dev/null and b/docs/manual/screenshots/mobile-compose.png differ
diff --git a/docs/manual/screenshots/mobile-connections.png b/docs/manual/screenshots/mobile-connections.png
new file mode 100644
index 0000000..f855a8e
Binary files /dev/null and b/docs/manual/screenshots/mobile-connections.png differ
diff --git a/docs/manual/screenshots/mobile-inbox.png b/docs/manual/screenshots/mobile-inbox.png
new file mode 100644
index 0000000..3a4145c
Binary files /dev/null and b/docs/manual/screenshots/mobile-inbox.png differ
diff --git a/docs/manual/screenshots/mobile-onboarding-register.png b/docs/manual/screenshots/mobile-onboarding-register.png
new file mode 100644
index 0000000..77544d6
Binary files /dev/null and b/docs/manual/screenshots/mobile-onboarding-register.png differ
diff --git a/docs/manual/screenshots/mobile-onboarding-signin.png b/docs/manual/screenshots/mobile-onboarding-signin.png
new file mode 100644
index 0000000..5672462
Binary files /dev/null and b/docs/manual/screenshots/mobile-onboarding-signin.png differ
diff --git a/docs/manual/screenshots/mobile-onboarding.png b/docs/manual/screenshots/mobile-onboarding.png
new file mode 100644
index 0000000..d3ee0b0
Binary files /dev/null and b/docs/manual/screenshots/mobile-onboarding.png differ
diff --git a/docs/manual/screenshots/mobile-settings.png b/docs/manual/screenshots/mobile-settings.png
new file mode 100644
index 0000000..128a492
Binary files /dev/null and b/docs/manual/screenshots/mobile-settings.png differ
diff --git a/docs/manual/screenshots/mobile-streams.png b/docs/manual/screenshots/mobile-streams.png
new file mode 100644
index 0000000..160201c
Binary files /dev/null and b/docs/manual/screenshots/mobile-streams.png differ
diff --git a/docs/manual/screenshots/mobile-team.png b/docs/manual/screenshots/mobile-team.png
new file mode 100644
index 0000000..ead2732
Binary files /dev/null and b/docs/manual/screenshots/mobile-team.png differ
diff --git a/docs/manual/screenshots/mobile-video.png b/docs/manual/screenshots/mobile-video.png
new file mode 100644
index 0000000..c5c8982
Binary files /dev/null and b/docs/manual/screenshots/mobile-video.png differ
diff --git a/docs/manual/user-manual-v2.pdf b/docs/manual/user-manual-v2.pdf
new file mode 100644
index 0000000..c493d30
Binary files /dev/null and b/docs/manual/user-manual-v2.pdf differ
diff --git a/docs/matrix-setup.md b/docs/matrix-setup.md
new file mode 100644
index 0000000..c90ffdd
--- /dev/null
+++ b/docs/matrix-setup.md
@@ -0,0 +1,41 @@
+# Matrix Setup — Tactical Media Broadcast Hub team chat
+
+OccupyMedia storage phase one adds [group attachment/archive contracts](occupymedia-storage.md)
+and an [independent files/docs scaffold](../infra/occupymedia/files/README.md).
+Live `occ-chat` remains conduwuit v0.5.0 with its existing local state/media;
+no volume or image switch is part of this phase. Future Tuwunel native R2 media
+requires a separate rehearsal and authorized upgrade. Archive mirroring is
+restricted to explicitly mapped **unencrypted archive rooms**; encrypted rooms
+are excluded. Collaborative ODT editing uses oCIS/Collabora WOPI, not Matrix.
+
+Matrix (conduwuit homeserver) is the **team/internal** chat plane. Stream viewer chat stays on the S5 hub (`docs/design/streaming-architecture.md` §3). Division of labor:
+
+| Plane | Tech | Who it serves |
+|---|---|---|
+| Team chat, DMs, bridged Telegram channels | Matrix (conduwuit + bridges) | editors, reviewers, admins |
+| Stream viewer chat | S5 hub → /realtime WS | Opticast app + control room |
+| Review threads (per-post) | Tactical Media Broadcast Hub native (WP5.1) | editorial workflow |
+
+## Deploy
+1. `cp infra/matrix/.env.example infra/matrix/.env` — set `MATRIX_SERVER_NAME` (permanent!) and a registration token
+2. Point your reverse proxy at :6167 with HTTPS (federation requires valid TLS)
+3. `docker compose -f infra/matrix/docker-compose.yml up -d`
+4. First account: temporarily set `MATRIX_ALLOW_REGISTRATION=true`, register the admin via any Matrix client (Element), then lock it back. Share the token for invites.
+
+## Rich text
+Conduwuit supports formatted bodies natively — clients (Element et al.) give Markdown, media, reactions, edits, replies, threads. **As good as Telegram** out of the box, plus E2E encryption.
+
+## Telegram bridge (feeds WP15 — join channels & amplify)
+`mautrix-telegram` runs alongside. One-time setup:
+1. `docker compose run --rm mautrix-telegram` — first boot writes `/data/config.yaml`; set homeserver + bridge admin
+2. In Matrix, DM `@telegrambot:your-server`, send `login` + the phone/code → your Telegram account is bridged
+3. Telegram channels you join appear as Matrix rooms; posts arrive as rich messages. The WP15 grabber (phase 2) reads those rooms → archive → review → amplify — no custom MTProto client needed, and the bridge is the battle-tested path
+4. Two-way: replying in the Matrix room posts to Telegram (subject to the same rights/attribution rules as S6)
+
+## Branding
+Element Web (if self-hosted as the client) accepts custom CSS — the same propagation rule as PeerTube: repo is the source of truth, a sync script pushes (accent #FF1610 on black, solid disk mark) after any brand change. Native clients keep their own themes; brand consistency applies to web surfaces.
+
+## Tactical Media Broadcast Hub integration points (follow-ups)
+- **Inbox screen**: swap fixtures for Matrix client-sdk (matrix-js-sdk) — DMs + team rooms render in-app
+- **Review notifications**: WP5.1 posts approval-needed events into a team room
+- **WP15**: grabber consumes bridged Telegram rooms (above)
diff --git a/docs/oauth-connect.md b/docs/oauth-connect.md
new file mode 100644
index 0000000..c84a1ac
--- /dev/null
+++ b/docs/oauth-connect.md
@@ -0,0 +1,51 @@
+# Connecting platform accounts
+
+The API resolves authorization behavior through connector methods and manifests. It currently registers Mastodon, PeerTube, and Telegram. Other providers are not offered as connectable until a connector implements the same authorization surface.
+
+## Configuration
+
+| Environment variable | Meaning |
+| --- | --- |
+| `APP_URL` | Web origin used for the final `/connections?connect=success` or `failure` redirect. Default `http://localhost:3000`; set `http://localhost:3001` when running the repository's usual API-on-3000/web-on-3001 setup. |
+| `API_URL` | Public API base. Default `http://localhost:3000`. |
+| `CONNECTIONS_CALLBACK_URL` | Optional exact callback URI override; default `${API_URL}/connections/callback`. Register this exact URI with configured provider applications. |
+| `CORS_ORIGINS` | Comma-separated permitted browser origins. Include the web origin; cookie credentials are enabled only for these explicit origins. |
+| `REDIS_URL` | Pending authorization store; default `redis://localhost:6379`. Production should use an authenticated `rediss://` URL. |
+| `SUPERPOSTER_KEK` | Production-required 32-byte base64 envelope encryption key. Keep it stable across replicas/restarts and secure its backups. The existing development key fallback is unsuitable for production. |
+| `MASTODON_INSTANCE_URL` | Instance origin to which the configured Mastodon client belongs. |
+| `MASTODON_CLIENT_ID`, `MASTODON_CLIENT_SECRET` | Optional pre-registered Mastodon application credentials, used only for `MASTODON_INSTANCE_URL`. |
+| `PEERTUBE_INSTANCE_URL` | Instance origin to which the configured PeerTube bridge client belongs. |
+| `PEERTUBE_CLIENT_ID`, `PEERTUBE_CLIENT_SECRET` | Optional credentials for that instance. Otherwise the connector discovers the local client through `/api/v1/oauth-clients/local`. |
+| `PEERTUBE_AUTHORIZE_PATH`, `PEERTUBE_TOKEN_PATH` | Required to enable a PeerTube redirect bridge. Both must be paths beginning with `/`, without a second leading slash, on the selected instance origin. |
+
+Use HTTPS and the same browser site for the web and API (for example `app.example.org` and `api.example.org`), or proxy the API under the web origin. The callback binding cookie is HttpOnly, SameSite=Lax, and Secure in production. For development, consistently use `localhost` or consistently use `127.0.0.1` for both web and API; mixing the two breaks browser cookie delivery.
+
+### Mastodon
+
+Without a configured client for the selected instance, the connector registers an application using `POST /api/v1/apps`, with the exact callback URI and `read write:statuses write:media` scopes. This is the supported path for arbitrary self-hosted instances; there is no universal client secret shared by all instances. Reconnect reuses that connection's registered client. Both legs use S256 PKCE. [Mastodon's OAuth documentation](https://docs.joinmastodon.org/methods/oauth/) describes the authorization-code grant and PKCE support (Mastodon 4.3+).
+
+### PeerTube limitation and bridge contract
+
+Stock PeerTube documents local OAuth client discovery followed by a **password grant**, rather than an authorization-code consent flow. The connect API never accepts account passwords, so the default PeerTube connect button is disabled with an explanation. See the [official PeerTube authentication guide](https://docs.joinpeertube.org/api/rest-getting-started).
+
+An instance administrator can enable a compatible OAuth bridge, then configure the two paths above. Its authorize endpoint must preserve `state`, register/validate the redirect URI, support `response_type=code` and S256 PKCE, and redirect back with a one-use code. Its token endpoint must validate `client_id`, `client_secret`, `redirect_uri`, `code`, and `code_verifier`, returning **actual PeerTube API** `access_token` and `refresh_token` values. Identity, refresh, and revoke then use PeerTube's native `/api/v1/users/me`, `/api/v1/users/token`, and `/api/v1/users/revoke-token` endpoints. These settings do not add an authorization-code grant to a stock instance, and an OIDC identity token alone is insufficient. The mock integration test proves this adapter contract; no third-party bridge is included in this change.
+
+### Telegram
+
+Create a bot in BotFather and enter its bot token. The connector validates it with `getMe`, then stores the token through the same encrypted vault envelope as OAuth credentials. Optionally supply a chat/channel ID (`@channel` or a numeric chat ID); add the bot to the target and grant any necessary posting rights. Identity health confirms token validity, not permission to publish to every chat. Reconnect accepts a replacement bot token for the same bot and rotates the credential row in place. Telegram's Bot API cannot revoke its own bot token: Remove clears local authorization; revoke/rotate the token through BotFather when needed.
+
+## API and storage behavior
+
+- `GET /connections/providers` returns available connectors, connect support, required instance/target fields, limitations, and real manifest capabilities.
+- `POST /connections/authorize` accepts `{ provider, instanceUrl? }`, validates connection-management permission, returns `{ redirectUrl }`, and sets the callback binding cookie.
+- `GET /connections/callback` is intentionally outside the bearer guard. It requires the random state and matching browser/workspace binding, rechecks the initiating user's current membership/epoch/permission, exchanges the code, validates identity, and redirects with a fixed success/failure result. Provider error messages never reach the redirect or API logs.
+- `POST /connections/telegram/bot-token` accepts `{ token, channelId?, connectionId? }`. `connectionId` rotates the existing bot connection instead of creating another.
+- `POST /connections/:connectionId/reconnect` reauthorizes the existing account and instance. A different provider identity is rejected; failed consent/exchange leaves the previous credential intact.
+- `DELETE /connections/:connectionId` locks the connection, revokes supported provider credentials, and deletes the connection and cascaded credential row. It also removes local schedules/publication records required by existing restrictive foreign keys; published provider posts remain. The UI asks for confirmation with this consequence. If a provider is unavailable, local removal is retained for retry; already-invalid credentials can be removed.
+- `GET /connections` probes provider identity: `healthy`, `needs_credentials`, or `unavailable`, and returns capability names without credentials. Automatic token refreshes are encrypted and persisted with a compare-and-swap fence against concurrent reconnects.
+
+Pending authorizations are random 256-bit state keys with a ten-minute Redis TTL. The Redis value is encrypted, including app secrets, PKCE verifier, initiating session context, and redirect configuration. Atomic compare-and-delete permits only one callback across replicas. Credentials use a persistent AES-256-GCM envelope in the existing `credentials.ciphertext` column, with its DEK wrapped by the existing KEK and authenticated tenant/handle binding. No database migration or dependency addition is needed. Audit mutations and credential writes share a tenant transaction; audits contain only the provider identifier/action, never credentials. Bot request URLs and callback URLs are excluded from HTTP tracing, and API structured logs redact token fields and request bodies/query/cookie/authorization data.
+
+## Verification
+
+`apps/api/src/connections/connections.integration.test.ts` runs real Nest routes, real connector auth/identity/revoke code, a PKCE-checking mock authorization server, TTL-faithful pending storage, and encrypted connection storage through in-process HTTP. It needs no open TCP ports, PostgreSQL, or Redis. Persistence unit tests independently exercise the real SQL repository's parameterization, tenant context, revocation ordering, and ciphertext-only audit writes. Existing live database integration suites still require their documented database environment variables.
diff --git a/docs/occupymedia-storage.md b/docs/occupymedia-storage.md
new file mode 100644
index 0000000..9955e90
--- /dev/null
+++ b/docs/occupymedia-storage.md
@@ -0,0 +1,142 @@
+# OccupyMedia shared files, documents and pads — phase one
+
+**Implemented: contracts, config validation and independent compose scaffolding.**
+No services, Matrix upgrade, archive bot, index API, database migration or UI have
+been deployed/implemented by this phase. Existing API/media-worker storage paths
+and deployment edits are preserved. [Deployment steps and resources](../infra/occupymedia/files/README.md)
+are the next operator runbook. Design input: `runs/wp4/fileshare-research.md`.
+
+## Storage ownership
+
+| Payload bucket | Exclusive owner | Status |
+|---|---|---|
+| `occupymedia-matrix-media` | Future Tuwunel native S3 media | Existing bucket; live conduwuit still local |
+| `occupymedia-files-blobs` | oCIS S3NG, working files/docs and pad exports | Proposed new bucket; inventory/provision first |
+| `occupymedia-media-encrypted` | Tactical Media Broadcast Hub media/library, existing envelope format | Existing configuration; preserve KEK |
+| `occupymedia-peertube-videos` | PeerTube video objects | Existing dedicated bucket |
+| `occupymedia-peertube-playlists` | PeerTube playlists | Existing dedicated bucket |
+
+Verify actual inventory; names here are ownership contracts, not proof of
+provisioning. Do not let the bot write directly into oCIS's opaque bucket. It must
+upload via authorized WebDAV/CS3 so metadata and ACLs remain coherent. Each
+product uses its own scoped credentials; bucket prefixes are not isolation.
+
+The target is **R2-only durable file/media payloads, minimal local metadata/config
+allowed, no local payload cache by design**. POSIX oCIS metadata, Matrix
+RocksDB/state, Hub metadata rows, identity/config and keys remain local and need
+backups. Source files, document bodies, thumbnails, extracted full text, pad
+revisions, attachments and staging/cache copies are payloads. Calling pad text
+or full-text extraction a database column does not turn it into metadata.
+Bounded transient RAM processing is allowed; disk/swap/core-dump payload copies
+are not. This phase does not make existing local Matrix bytes disappear.
+
+## Telegram-like group file contract
+
+The shared TypeScript boundary is `packages/core/src/shared-files.ts`; future
+HTTP/DB adapters must validate these shapes at runtime. Use stable
+`workspaceId + groupId` (existing Hub groups) and immutable `roomId` to map to an
+oCIS `spaceId + folderId`. Start with one restricted Space per group; allow
+multiple rooms to map explicitly to that group. Never infer identity/ACL from
+room names, aliases or bridge membership. Membership changes must reconcile
+both Matrix and file grants; mismatches suspend sharing/mirroring until corrected.
+
+A `GroupFile` records room/group/workspace, sender MXID (not a display name),
+Matrix event ID, origin (`matrix`, provider-described `bridge`, direct `upload`,
+or `pad-export`), original name, MIME, verified byte size, SHA-256, UTC ISO
+`createdAt` and `indexedAt`, stable library resource/version, share link,
+retention and availability. For bridged sources preserve both Matrix sender
+and provider/remote event attribution when supplied by the trusted bridge;
+do not invent attribution. Original `createdAt` comes from event time or accepted
+upload time, not the replay/index time. Direct uploads and exports use null event
+IDs until a room announcement supplies one. Hash actual bytes while streaming;
+S3 ETags, claimed Matrix MIME/size and filenames are not proof. Normalize a safe
+display filename and sniff MIME; reject over-limit transfers, including when
+Content-Length is missing or lies.
+
+Default links require current group membership; downloads/edit launches must
+recheck ACLs and retention. Public links require an explicit group grant and
+expiry; revoke them on removal. Persist library links/share IDs and expiry, not
+presigned object URLs, WOPI tokens or passwords. Keep retention policy separate
+from link expiry: `keep` is the phase-one default with no automated purge;
+`until` requires an explicit timestamp, `legalHold` prevents deletion.
+Future policy must account for source Matrix media and library copies separately;
+one message redaction does not authorize deleting a blob used by another record.
+
+## Metadata index and hub-archive seam
+
+Future `chat_media_archive` persistence is metadata-only. Required constraints:
+unique `(workspace_id, room_id, event_id)` for attachment events, stable file
+identity/version, indexes on `(workspace_id, group_id, created_at, id)`,
+sender, MIME class, name and checksum. List/search return only available,
+unexpired rows visible through current group/file ACLs. Use a `(createdAt,id)`
+cursor scoped to workspace/group. Filename/MIME/sender/date/origin queries and
+oCIS metadata search are the initial searchable/retrievable media experience.
+Full-text/OCR/Tika is deferred: neither a local text index nor an extra JVM is
+silently included. Archive rows never contain file bodies or encrypted-file keys.
+
+`HubArchivePort` defines future archive/revoke operations. A plain sync-loop bot
+(not an appservice) uses a narrowly scoped Matrix account and a scoped oCIS
+service identity. Required processing contract:
+
+1. Load an explicitly enabled group mapping and current room encryption state.
+   Exclude own bot/reply events to prevent loops. Abort on unknown state, lost
+   membership/ACL, redaction, encrypted events or `content.file` attachments.
+2. Accept only `m.room.message` attachments (`m.file`, `m.image`, `m.audio`,
+   `m.video`) with a valid `mxc://` URI. Use authenticated Matrix media download
+   endpoints (with version negotiation), never arbitrary user-supplied HTTP URLs.
+   Validate any redirect to the configured R2 endpoint and drop Matrix credentials
+   before following; never forward bearer auth to the object store.
+3. Claim `attachmentArchiveKey(workspace,room,event)` durably. Use a deterministic
+   upload destination/resource lookup and reconcile partial retries to avoid
+   duplicate files across crashes. Stream bounded bytes/hash to WebDAV/CS3;
+   **no temp files on local disk**. Record the committed library reference,
+   verified metadata and a durable reply/outbox entry before advancing the
+   stored Matrix sync cursor. Advancing past a failed event requires a durable
+   retry record; R2/ACL failures must not lose attachments.
+4. Reply once with an authenticated file link using a stable Matrix transaction
+   ID derived from the replay key. Search is an index query; retrieve by library
+   resource through current ACLs. An encrypted Tactical Media Broadcast Hub library copy, if
+   needed for publishing, goes through the existing encryption path into its
+   own bucket; no cross-product object-key reuse.
+5. On redaction/retention or membership removal, revoke links and mark the index
+   unavailable; stop serving immediately. A later audited deletion workflow
+   handles library versions/trash, references, source media and legal holds.
+   Backfill, retries and live sync obey the same policy and idempotency rules.
+
+No implementation of this loop or SQL table is present in phase one; config's
+`HUB_ARCHIVE_*` variables reserve its interface. `canArchiveAttachment` is a
+tested pure eligibility check, not complete authorization or byte validation.
+
+## Encryption policy
+
+**Encrypted Matrix rooms cannot be server-side mirrored by this architecture.**
+No bot encryption keys, decryption engine or silent downgrade is added. Group
+admins designate a separate **unencrypted archive room**, tell members its
+attachments enter the shared library, and enable its immutable room mapping
+explicitly. Users may deliberately upload/share a file there; encrypted rooms
+remain untouched. Treat bridged rooms the same: verify encryption state instead
+of assuming the bridge made them plaintext. If an archive room becomes encrypted,
+or its state cannot be established, mirroring stops. R2 can retain encrypted
+Matrix media as ciphertext in a future Tuwunel deployment, but that does not
+make it server-searchable or give the bot access to plaintext.
+
+## Collaborative ODT and pad boundaries
+
+ODT editing is **oCIS file -> collaboration WOPI host -> Collabora -> save/version
+back through oCIS -> R2**. Matrix posts links and notifications; it does not edit
+ODT. The editor gets short-lived, permission-scoped launch tokens and file locks.
+Test simultaneous edits, reconnects, saves, versions and grant revocation; keep
+Collabora's working files in transient RAM and block launch if that cannot be
+guaranteed for the selected image.
+
+`SharedPad` / `PadExportPort` allow Etherpad- or HedgeDoc-compatible group pad
+links and revision exports. Pad content, revisions and attachments must be
+durable R2 payloads; local storage may retain only identifiers, ACLs and session
+metadata. Standard pad deployments typically persist document text/revisions
+in their database: they need a separately validated R2 persistence adapter or
+another compliant service. R2 attachment support or periodic exports alone is
+insufficient. Consequently there is **no running pad service** in this scaffold,
+and `PADS_ENABLED=false`. Approved exports become ordinary versioned oCIS
+resources with checksums and group retention; live ODT collaboration remains
+Collabora's responsibility. This preserves the lightweight pad option without
+introducing an incompatible local payload database.
diff --git a/docs/peertube-setup.md b/docs/peertube-setup.md
new file mode 100644
index 0000000..50d6879
--- /dev/null
+++ b/docs/peertube-setup.md
@@ -0,0 +1,41 @@
+# PeerTube Setup — Tactical Media Broadcast Hub's video/live backbone
+
+PeerTube runs as a **subproject** (`infra/peertube/`) on a **different server** than the Tactical Media Broadcast Hub API/web. It stores all media in **S3** and carries the **Tactical Media Broadcast Hub brand**, propagated from this repo.
+
+## Deploy (on the media server)
+1. `cp infra/peertube/.env.example infra/peertube/.env` — fill in hostname, S3 keys (dedicated buckets: `tactical-media-broadcast-hub-peertube-{videos,playlists,redundancy}`), DB password
+2. `docker compose -f infra/peertube/docker-compose.yml up -d`
+3. Put the instance behind HTTPS (nginx/caddy) — federation + OAuth require it
+4. First boot creates the admin account (PEERTUBE_ADMIN_EMAIL)
+
+## S3 storage
+PeerTube's object-storage env handles ALL media (videos, playlists, redundancy). Point it at the same S3-compatible infra the Tactical Media Broadcast Hub media plane uses (MinIO or cloud), with dedicated buckets + credentials. The Tactical Media Broadcast Hub API never proxies PeerTube bytes — both speak S3 natively.
+
+## Branding — propagation rule
+**Source of truth: this repo** (`apps/web/public/brand/` + design tokens in `apps/web/src/app/globals.css`). After ANY brand change:
+```
+infra/peertube/brand-sync/sync-brand.sh
+```
+It pushes instance name, custom CSS (accent #FF1610 on black), and the solid disk mark to the instance via PeerTube's config API (needs `PEERTUBE_URL` + `PEERTUBE_TOKEN` with settings scope). Idempotent — run it whenever the brand moves. (Later: a "Sync branding" button in Tactical Media Broadcast Hub settings that calls the same API.)
+
+## Connecting Tactical Media Broadcast Hub → PeerTube
+- **OAuth bridge**: stock PeerTube exposes a password grant only. Our connect flow (docs/oauth-connect.md) supports a same-instance OAuth bridge when configured; otherwise use an instance with a bridge plugin or a token-entry connection. The connector (`packages/connector-peertube`) handles publish, livestream keys, per-instance federation.
+- **Live ingest**: the media worker's compositor pushes RTMP to `<host>:1935` (opened in the compose file). Livestream keys flow through the connector.
+- **Live chat**: install the **livechat plugin** (peertube-plugin-livechat) on the instance — S5's chat hub consumes chat via the XMPP/plugin surface (phase 2 of S5, per the streaming architecture doc).
+
+## Different-server topology
+```
+[app server]                     [media server]
+apps/api  apps/web  scheduler    peertube (+redis +postfix)
+media-worker  compose (pg,       S3 buckets (dedicated peertube-*)
+  redis, temporal...)              │
+        └────── RTMP :1935 ───────┘
+        └────── OAuth/API over HTTPS ──┘
+```
+Firewall: app server → media server :443 (API) and :1935 (RTMP). Nothing else required between them; S3 is the shared storage plane.
+
+## Settings checklist (instance admin UI, after first boot)
+- Enable live + allow replay + transcode lives
+- Registration: closed (users join via Tactical Media Broadcast Hub)
+- Federation: follow only trusted instances (moderated homepage)
+- Plugins: peertube-plugin-livechat (chat), optionally peertube-plugin-rtc
diff --git a/docs/s27-brief.pdf b/docs/s27-brief.pdf
new file mode 100644
index 0000000..0fe01a4
Binary files /dev/null and b/docs/s27-brief.pdf differ
diff --git a/docs/s27-broadcast-station-brief.md b/docs/s27-broadcast-station-brief.md
new file mode 100644
index 0000000..c5e66b3
--- /dev/null
+++ b/docs/s27-broadcast-station-brief.md
@@ -0,0 +1,40 @@
+# Tactical Media Broadcast Hub
+
+*A horizontal coordination platform for media analysis, production, and diffusion — self-hosted, multi-platform, no algorithm in between.*
+
+The Hub is built for one thing: **letting many people run many media outlets together, in real time.** Dozens of contributors, dozens of social accounts across Mastodon, Telegram, PeerTube, Bluesky, Instagram, Twitch and more — one shared newsroom where the collective edits, decides, and publishes as a single coordinated force. It is not a scheduling tool with a broadcast feature attached; coordination IS the product. The rest — live mixing, the 24/7 channel, the archives — grows out of that spine.
+
+## The newsroom loop: analysis → production → diffusion
+
+**ANALYZE — see everything, together.** Live feeds from every connected account flow into shared columns. Telegram channels the collective follows are mirrored automatically into a review archive. Every draft, clip, and statement lives in one encrypted library. The room sees what's happening across the whole footprint at once — and what the movement is saying everywhere else.
+
+**PRODUCE — collective editing in real time.** Many hands, one voice. Any editor can draft into any account; every change is versioned. Nothing publishes in the collective's name alone: the **review workflow** puts each post before the group — a configurable quorum (2-of-3, 3-of-5) must sign off, with roles that can be delegated per account (this crew approves the press account, that crew the stream channel). Votes are transparent, denials require a reason, and the whole trail is tamper-evident. Decisions are made by whoever is present, in the open, in minutes — not routed through one admin's phone.
+
+**DIFFUSE — smart quoting across platforms.** One approval fans a post out everywhere, native to each platform. Cross-posting uses **smart quotes**: where a platform has native quoting (Mastodon quote posts, Bluesky, Telegram forwards), it's used; where it doesn't, the system generates a proper attributed quote — author, instance, link back — never a silent copy-paste. Amplifying sister collectives' work keeps their names on it by default. Scheduling, rate-awareness, and per-account timing come along for free.
+
+## Real-time story production
+
+Breaking events don't wait for consensus rounds. The Hub is built for **speed with accountability**: an editor stages a developing story, reviewers approve from their phones, updates go out as quote-chained revisions. Meanwhile the live layer runs: field streamers push cameras from the **Opticast** Android app straight to our server; a director in the browser **Control Room** watches every feed in a multiview grid, mixes audio, cuts between scenes, burns lower-thirds and scrolling chyrons; the mixed program goes to our **PeerTube channel** — and when no one is live, the channel keeps broadcasting a scheduled playlist. An **Auto-Director** can switch sources by priority rules so the station never goes dark mid-action. Unified chat from every platform lands in one place — viewers heard, moderators acting, the streamer focused on the shot.
+
+## The archive: memory that can't be purged
+
+Everything the collective produces — text, photos, video, streams — lands in an **encrypted archive** on our own storage: client-side encrypted, content-addressed, deduplicated. Platforms purge; the Hub remembers. The archive feeds back into production: yesterday's footage is tomorrow's playlist, a deleted thread is still citable, and Telegram-channel history becomes reviewable material with attribution intact.
+
+## Security & trust model
+
+Self-hosted, end to end — no corporate cloud, no accounts needed to run the system itself. Multi-tenant with row-level security; platform credentials in an encrypted vault the database never sees in plaintext; every editorial action in a hash-chained audit log; anonymous-infrastructure friendly (the host carries boxes, not content — storage is ciphertext).
+
+## What we need from you
+
+| Piece | Spec | Notes |
+|---|---|---|
+| App server | 4 vCPU / 8 GB / 100 GB | API, newsroom web, scheduler, live compositor (ffmpeg), Postgres, Redis |
+| Media server (optional, same box OK) | 4 vCPU / 8 GB + S3 storage | PeerTube channel + VODs; RTMP ingest :1935 |
+| Object storage | S3-compatible, 500 GB+ | MinIO works; content is client-side encrypted |
+| Domain + DNS | you have it | newsroom / channel / chat subdomains; anonymous registration |
+| Uplink | 100 Mbps+ recommended | streaming out |
+| Optional | tiny Matrix box (1 vCPU/1 GB) | encrypted team chat + Telegram bridge |
+
+**Status, honestly:** publishing + review + archive + connectors + OAuth connecting (Mastodon full, Telegram bots) run today; multi-signoff quorum, live compositor, control-room UI, unified chat and auto-director are landing now. Bring the servers and the domain — the collective brings the newsroom.
+
+*— the Tactical Media Broadcast Hub collective (Tactical Media Broadcast Hub × Opticast × PeerTube)*
diff --git a/docs/tactical-media-broadcast-hub-brief.md b/docs/tactical-media-broadcast-hub-brief.md
new file mode 100644
index 0000000..a213247
--- /dev/null
+++ b/docs/tactical-media-broadcast-hub-brief.md
@@ -0,0 +1,169 @@
+# Tactical Media Broadcast Hub
+
+## Many collectives. Many minds. Many signals.
+
+Media activists often face the same problem: a group wants to work together, but the tools are organized around individual accounts.
+
+One person ends up holding the passwords. A few people become bottlenecks. New contributors cannot help without being given dangerous levels of access. Work gets scattered across chats, documents, drives, and platform dashboards.
+
+The Tactical Media Broadcast Hub is designed to change that.
+
+It gives collectives a shared place to organize, create, review, and publish media without turning one person into the gatekeeper of every account.
+
+**Speak with us, not for us.**
+
+## What Groups Can Do
+
+### Work together without sharing passwords
+
+People get the access they need for the work they are doing, not the keys to everything.
+
+A contributor can be allowed to:
+
+- Prepare a post.
+- Edit a video description.
+- Review another person’s work.
+- Publish to a specific channel.
+- Manage a group or project.
+- Remove their own access when they move on.
+
+The group can see who has access and change it when responsibilities change.
+
+### Organize around projects and campaigns
+
+Create groups for a campaign, a local action, a publication, a show, or a temporary media team.
+
+Each group can have its own members, conversations, files, drafts, approval process, and publishing permissions. Groups can work independently while still sharing material and supporting one another.
+
+### Create channels together
+
+Groups can build media channels that span several platforms instead of treating every platform as a separate job.
+
+The same team can coordinate:
+
+- Video and livestreams.
+- Social posts and threads.
+- Telegram and Matrix conversations.
+- Press statements and newsletters.
+- Archives, show notes, and background material.
+
+The Hub helps people adapt work for each place without losing track of the original source, the people who made it, or the decisions around publication.
+
+### Produce livestreams and TV-style channels
+
+Groups can produce more than individual posts. They can operate live and scheduled channels with:
+
+- Multiple live sources and remote contributors.
+- Playlists, scheduled programs, and looping broadcasts.
+- Scene layouts, picture-in-picture, shared screens, and source changes.
+- Lower thirds, logos, chyrons, clocks, and other on-air graphics.
+- Preview and program feeds so a team can prepare the next moment before taking it live.
+- Live switching, source replacement, and graceful recovery when a source drops.
+- Simultaneous distribution to PeerTube and other supported platforms.
+- Recordings, replays, clips, and show archives after the broadcast.
+
+This makes a group channel feel like a small community television station: live when something is happening, scheduled when it is not, and built from the work of many contributors.
+
+### Edit documents together
+
+Groups can work together on statements, articles, scripts, captions, briefings, and press materials.
+
+Office documents such as ODT files can be edited collectively. People can review changes, prepare a final version, and keep the publication history with the project instead of passing files around in private messages.
+
+### Use shared pads for fast work
+
+Every project also needs a lightweight space for unfinished thoughts.
+
+Shared pads are useful for:
+
+- Live event notes.
+- Breaking-news coordination.
+- Interview preparation.
+- Production schedules.
+- Run sheets and checklists.
+- Meeting notes.
+- Quick drafts that do not need a full document workflow.
+
+Pads are for moving quickly. Documents are for work that needs editing, review, and a lasting home.
+
+### Find group files and media
+
+Files should not disappear into one person’s private drive.
+
+Groups can keep shared images, audio, video, documents, exports, source material, and finished work together with useful context:
+
+- Which group owns or manages it.
+- Where it came from.
+- Who contributed it.
+- When it was created.
+- What project or campaign it belongs to.
+- Whether it is a draft, approved, published, or archived.
+
+Members should be able to find the file connected to a conversation, a campaign, or a published piece without searching through somebody else’s account.
+
+### Curate and amplify voices
+
+The Hub is for finding, organizing, contextualizing, and amplifying work made by people and communities.
+
+It is not a machine for speaking on behalf of them. Attribution, consent, authorship, and editorial decisions remain visible to the people doing the work.
+
+## How A Group Uses It
+
+1. A collective creates a group for a project, campaign, channel, or event.
+2. Members receive roles that match their responsibilities.
+3. The group gathers conversations, files, source material, and drafts.
+4. Members edit and review work together.
+5. The group decides what is ready to publish.
+6. Approved work is adapted for the platforms where people will see it.
+7. The group keeps a record of what was made, who contributed, and where it went.
+
+## What This Is Not
+
+- Not a replacement for the communities using it.
+- Not a single centralized newsroom.
+- Not a reason to hand one administrator every password.
+- Not an advertising or engagement farm.
+- Not a system that hides editorial decisions behind one organization.
+- Not a request for someone else to provide or operate servers.
+
+## A Network Of Independent Collectives
+
+Each collective should be able to decide how it works, who it trusts, where it stores its material, and what it shares.
+
+The Hub helps groups cooperate without requiring them to become one organization. A local media team, a campaign group, a publication, and a network of independent channels can all coordinate while keeping their own identities and responsibilities.
+
+The long-term aim is a horizontally coordinated network of media-making communities:
+
+**Many collectives. Many minds. Many signals.**
+
+## For Groups Who Want To Run It Themselves
+
+The Hub can be run independently by a collective or network. They do not need to depend on the original maintainers for access to their own work.
+
+An independent operator needs:
+
+- A reliable computer or hosted machine.
+- A stable internet connection and a domain name.
+- A secure place for shared files and media.
+- Someone responsible for updates, backups, and member access.
+- A clear agreement about who can publish, administer, and recover the system.
+
+The system is designed so large files and media live in durable object storage rather than filling the application machine. Small records about groups, permissions, conversations, and file locations still need to be protected and backed up.
+
+For a larger deployment, it is best to separate the everyday coordination tools from heavy video processing. A group can begin small and add dedicated capacity for livestreaming, video production, collaborative documents, and search as its work grows.
+
+Self-hosting should include:
+
+- Separate storage areas for chat media, shared files, and application media.
+- Regular backups of both the files and the records that describe them.
+- Secure delegated connections to publishing platforms.
+- Clear rules for access, departures, moderation, and recovery.
+- A policy for which group conversations can have files copied into the shared library.
+
+Encrypted conversations need special care: a server cannot automatically read or archive files from a conversation it cannot decrypt. Groups can choose designated archive spaces for material that needs to be searchable and shared across the wider media system.
+
+## Closing
+
+**Tools to curate and amplify voices.**
+
+**Speak with us, not for us.**
diff --git a/docs/tactical-media-broadcast-hub-brief.pdf b/docs/tactical-media-broadcast-hub-brief.pdf
new file mode 100644
index 0000000..27911e1
Binary files /dev/null and b/docs/tactical-media-broadcast-hub-brief.pdf differ
diff --git a/docs/tactical-media-broadcast-hub-technical-brief.md b/docs/tactical-media-broadcast-hub-technical-brief.md
new file mode 100644
index 0000000..2ecf927
--- /dev/null
+++ b/docs/tactical-media-broadcast-hub-technical-brief.md
@@ -0,0 +1,268 @@
+# Tactical Media Broadcast Hub
+
+## Independent Self-Hosting: Technical Brief
+
+This document describes what an independent collective needs to operate its own Tactical Media Broadcast Hub.
+
+It is intentionally separate from the public presentation brief. The public brief explains what people can do with the Hub; this document explains the systems, storage, security, and operational responsibilities behind it.
+
+## 1. Operating Principle
+
+The Hub should keep user file and media payloads in durable object storage, not on the application host.
+
+The practical boundary is:
+
+- **R2/S3:** user files, media, document payloads, pad exports, and large objects.
+- **Local service state:** small metadata databases, indexes, room state, configuration, queues, and temporary processing data.
+
+A literally zero-local-state deployment is not supported by every component. The goal is zero local storage for user payloads, with the remaining metadata protected by backups and volume snapshots.
+
+## 2. Recommended System Layout
+
+### Control plane
+
+- Tactical Media Broadcast Hub web application.
+- API and authentication.
+- PostgreSQL.
+- Redis.
+- Temporal or an equivalent workflow service.
+- Scheduler and media-worker control services.
+
+### Conversation plane
+
+- Tuwunel Matrix homeserver.
+- mautrix-telegram bridge.
+- Element or another Matrix client.
+- A small archive bot for approved rooms and attachments.
+
+The current deployment uses Conduwuit, but Conduwuit is archived and does not provide the native S3 media storage needed for the long-term design. Plan a controlled Conduwuit-to-Tuwunel migration before moving Matrix media to R2.
+
+### Media plane
+
+- PeerTube.
+- RTMP/RTMPS ingest.
+- Transcoding and broadcast workers.
+- Preview and archive processing.
+
+The media plane should be separate from the files/docs plane when the collective runs sustained livestreams or video processing.
+
+The broadcast system supports persistent virtual channels rather than only one-off uploads. A channel can combine live sources, playlists, and prepared programs into a continuous output.
+
+Core production capabilities include:
+
+- Source ingest from live feeds, PeerTube, files, and playlists.
+- Scene composition with grids, picture-in-picture, shared sources, and custom layouts.
+- Preview and program buses for preparing and taking a source live.
+- A/B switching and frame-continuous source replacement.
+- Lower thirds, chyrons, logos, clocks, and other typed overlays.
+- Per-source audio selection, gain, mixing, and master output control.
+- Scheduled playlists with slate fallback when an asset is unavailable.
+- RTMP/RTMPS output to PeerTube and other supported destinations.
+- JPEG and low-latency HLS preview taps for operators and control-room clients.
+- Recording, replay, archive, and later clip/export workflows.
+
+The media worker is the production engine. The control plane owns channel state, permissions, schedules, and signed commands; it should not carry raw video bytes.
+
+### Files and documents plane
+
+- ownCloud Infinite Scale (oCIS) for folders, group files, search, versions, and share links.
+- Collabora CODE or OnlyOffice for collaborative ODT and office-document editing.
+- Tika or equivalent content extraction if full-text search is required.
+
+oCIS is the recommended primary files layer because its S3NG storage driver keeps file blobs in R2 while retaining only necessary metadata on a local POSIX volume.
+
+### Pad plane
+
+- Etherpad or HedgeDoc for fast shared pads.
+- Pads are for live notes, run sheets, planning, and event coordination.
+- Pad text and revisions should remain in the pad service, with exports stored in R2 when retained as formal project records.
+
+Matrix is the conversation layer, not the office editor or files library.
+
+## 3. R2 Bucket Layout
+
+Use separate buckets. Do not share an exclusive or opaque application bucket between services.
+
+The initial dedicated buckets are:
+
+| Bucket | Purpose |
+|---|---|
+| `hub-matrix-media` | Matrix/Tuwunel media payloads |
+| `hub-files-blobs` | oCIS file and document blobs |
+| `hub-media-library` | Tactical Media Broadcast Hub working media and library assets |
+| `hub-pads` | Retained pad exports and attachments |
+
+Each service needs its own scoped R2 S3 credential. Cloudflare account API credentials are not the same thing as R2 S3 access keys.
+
+Do not place credentials in Git. Store them in an encrypted secret manager or protected deployment environment.
+
+## 4. Group File Contract
+
+Every archived group file should retain enough context to answer: what is this, who contributed it, where did it come from, and who may use it?
+
+Minimum metadata:
+
+- `workspaceId`
+- `groupId`
+- `roomId`
+- `eventId`
+- `senderId`
+- `origin` such as Matrix, Telegram bridge, upload, or application
+- `filename`
+- `mimeType`
+- `sizeBytes`
+- `sha256`
+- `createdAt`
+- `storageKey`
+- `shareUrl` when one exists
+- `retention`
+- `status` such as pending, archived, published, revoked, or deleted
+
+The Hub database stores metadata and indexing information. The file bytes live in the appropriate R2 bucket.
+
+Archive writes must be idempotent on the combination of workspace, room, and event ID. A retried sync event must not create duplicate files.
+
+## 5. Matrix and Telegram Media Flow
+
+1. Telegram content enters through mautrix-telegram.
+2. The Matrix room remains the conversation and attribution source.
+3. An archive bot watches designated rooms.
+4. For eligible file/image/video/audio events, the bot streams the payload into the files platform or R2-backed archive.
+5. The bot records room, sender, event, origin, checksum, and retention metadata.
+6. The bot can post a share link back to the room instead of duplicating the file.
+
+### Archive policy
+
+Encrypted rooms cannot be read by a server-side archive bot without a deliberate decryption path. The default safe policy is:
+
+- Archive only designated unencrypted archive rooms.
+- Do not silently decrypt or mirror private E2E rooms.
+- Make the archive policy visible to room members.
+- Preserve attribution and the original event ID.
+
+The first implementation should be a plain sync-loop bot using matrix-js-sdk, not a full appservice. An appservice can be considered later if room volume requires it.
+
+## 6. Collaborative ODT Editing
+
+ODT and other office documents should be stored in oCIS and opened through a WOPI-compatible editor such as Collabora or OnlyOffice.
+
+The Hub should store:
+
+- The document identity.
+- The owning group and workspace.
+- The current share or launch reference.
+- Review and publication status.
+- A rendered export or snapshot when a document is approved.
+
+The Hub should not copy the full document revision history into its own database. The files platform and office editor remain responsible for collaborative editing and document versions.
+
+## 7. Shared Pads
+
+Pads should have a small integration boundary:
+
+- Group and room ownership.
+- Pad URL and service identity.
+- Membership and access policy.
+- Export-to-file action.
+- Optional retention policy.
+
+Pad content stays with the pad service during editing. When a pad becomes an official project artifact, export it to ODT, Markdown, HTML, or PDF and store the export in R2-backed group files.
+
+## 8. Access and Security
+
+- Use group roles rather than shared account passwords.
+- Prefer OAuth/OIDC/delegated authorization for external platforms.
+- Scope each platform connection to the smallest useful permission set.
+- Keep publishing, reviewing, editing, and administration as separate capabilities.
+- Record access changes and publication actions in the audit trail.
+- Rotate credentials when a member leaves or a platform connection changes.
+- Use separate R2 credentials per bucket and service.
+- Do not put R2 secrets, Matrix registration tokens, or platform refresh tokens in the repository.
+
+## 9. Compute and Capacity
+
+### Small pilot
+
+- 4 vCPUs and 8 GB RAM is a comfortable starting point for control, chat, and files without heavy video processing.
+- 2 vCPUs and 4 GB RAM can support a reduced pilot, but not the full stack with Collabora, search, PeerTube, and sustained livestreaming.
+- Keep large media processing on a separate host whenever possible.
+
+### Full deployment
+
+The honest target for the complete Hub is approximately 4 vCPUs and 8 GB RAM or more. The main elastic components are:
+
+- Collabora/OnlyOffice document sessions.
+- Tika content extraction.
+- PeerTube transcoding.
+- Live broadcast workers.
+- Initial search/indexing jobs.
+
+Disk capacity is less important than keeping payloads in R2. A self-hosting operator should still maintain enough local space for metadata volumes, temporary processing, logs, and recovery snapshots.
+
+## 10. Domains and Network
+
+At minimum, an independent deployment needs:
+
+- One main web domain.
+- Separate hostnames for API, Matrix, files, collaboration, pads, and video.
+- HTTPS for every public service.
+- A tunnel or reverse proxy.
+- Long upload and WebDAV/WOPI timeouts.
+
+Large-upload hostnames should not use a proxy path with a low request-size limit. Use a tunnel or grey-cloud DNS path, or use chunked/TUS uploads.
+
+## 11. Backups and Recovery
+
+Back up both payloads and the metadata that makes them meaningful:
+
+| Artifact | Backup |
+|---|---|
+| R2 buckets | Replication, lifecycle protection, or a second-account backup |
+| Tuwunel room state | Volume snapshot and config backup |
+| oCIS metadata volume | Volume snapshot; use a filesystem suited to the service |
+| Hub PostgreSQL | Regular `pg_dump` plus tested restore |
+| Redis/Temporal | Rebuildable state documented; preserve durable workflow data where required |
+| Deployment config | Versioned config with secrets stored separately |
+
+Test restoring a group, its files, document links, and publication history onto a clean host. R2 durability alone does not protect against a bad lifecycle rule, deleted metadata, or leaked credentials.
+
+## 12. Deployment Phases
+
+### Phase 1: Foundation
+
+- Create separate R2 buckets and scoped S3 credentials.
+- Deploy the files platform without migrating existing Matrix or PeerTube data.
+- Establish group/file metadata contracts.
+- Add backup and restore procedures.
+- Add a basic pad service.
+
+### Phase 2: Collaboration
+
+- Add Collabora or OnlyOffice.
+- Connect ODT launch and export flows.
+- Add group library views and share links.
+- Add Matrix room-to-group mappings.
+
+### Phase 3: Archive integration
+
+- Upgrade Conduwuit to Tuwunel with the permanent server name preserved.
+- Enable Tuwunel media storage providers for R2.
+- Run the archive bot for designated unencrypted rooms.
+- Add event-to-file indexing and share-link replies.
+
+### Phase 4: Production hardening
+
+- Add OIDC or another shared identity layer.
+- Add retention and deletion workflows.
+- Add search extraction and indexing.
+- Run restore drills and permission audits.
+- Separate heavy media processing onto its own host.
+
+## 13. Explicit Non-Goals
+
+- Do not run Nextcloud AIO as the default; it is local-datadir-oriented and wants to own the Docker host.
+- Do not use Seafile CE if R2 storage and content search are requirements.
+- Do not make Matrix the files library.
+- Do not run a second chat platform beside Matrix.
+- Do not migrate live Matrix data to R2 until the Tuwunel migration is planned and backed up.
+- Do not claim that user payloads are R2-backed until the service has been configured with real scoped R2 credentials and verified with an upload/restore test.
diff --git a/docs/tactical-media-broadcast-hub-technical-brief.pdf b/docs/tactical-media-broadcast-hub-technical-brief.pdf
new file mode 100644
index 0000000..ca5c3b7
Binary files /dev/null and b/docs/tactical-media-broadcast-hub-technical-brief.pdf differ
diff --git a/docs/tmbh-promo.pdf b/docs/tmbh-promo.pdf
new file mode 100644
index 0000000..fbabce0
Binary files /dev/null and b/docs/tmbh-promo.pdf differ
diff --git a/docs/tweetdeck-on-steroids-ES.md b/docs/tweetdeck-on-steroids-ES.md
new file mode 100644
index 0000000..e33926a
--- /dev/null
+++ b/docs/tweetdeck-on-steroids-ES.md
@@ -0,0 +1,34 @@
+# TweetDeck con Esteroides
+
+**Un newsroom multiplataforma autoalojado para colectivos — un muro de columnas que vigila todas las plataformas a la vez, conectado a un pipeline completo de transmisión en vivo.**
+
+TweetDeck murió cuando X cerró sus puertas. Construimos lo que debió reemplazarlo: columnas que vigilan Mastodon, Telegram, Bluesky, PeerTube, Twitch y más — conectadas a publicación, aprobaciones, mezcla en vivo y un archivo que no se puede purgar. Autoalojado, sin algoritmo, sin plataformas guardando tus llaves.
+
+## Cómo trabajamos juntos
+
+- **El muro es la sala.** Columnas en vivo vigilan todas tus cuentas conectadas a la vez — cada post renderizado seguro, media proxy, duplicados deduplicados al archivo. Todo el colectivo ve la misma imagen.
+- **Redacta una vez, aprueben juntos, publiquen en todas partes.** Cualquiera redacta en cualquier cuenta. Cada borrador pasa por aprobación configurable del grupo antes de moverse. Al aprobarse, se distribuye nativo por plataforma — citas correctas, atribución intacta, auditoría a prueba de manipulación de quién decidió qué.
+- **Roles, no contraseñas.** Editores redactan, revisores aprueban, publicadores publican — por cuenta, por canal. Enlaces de invitación integran a la gente; irse quita el acceso. Sin logins compartidos, sin cuellos de botella.
+- **Programa como una estación.** Posts programados con zona horaria correcta y motor resistente al horario de verano. Cancela, revisa, reprograma.
+- **Sala de control en el navegador.** Cuadrícula multivista, TAKE/CUT, preview/programa, lower-thirds y chyrons, mezcla de audio — el programa sale a tu canal de PeerTube, playlist 24/7 cuando estás apagado. Funciona desde una laptop.
+- **Auto-Director.** Reglas de prioridad cambian fuentes automáticamente para que el stream nunca muera en medio de la acción.
+- **Chats de todas las plataformas** puenteados a un solo overlay — espectadores escuchados, moderadores actuando, el streamer enfocado en el shot.
+- **Workers de transcodificación propios.** Laptops y GPUs como workers de render por Tailscale — una RTX 3090 ya transcodifica trabajos reales de PeerTube con NVENC. Más workers, más canales.
+- **Un archivo que no se puede purgar.** Cifrado, deduplicado, direccionado por contenido. Las plataformas eliminan; el archivo recuerda.
+
+
+## Lo que viene — y dónde necesitamos manos
+
+- **Columnas de búsqueda entre plataformas.** Una consulta ("acampada26") como columna en vivo que extrae de cada red que lo permita — diseño listo, esquema en construcción.
+- **Chats dirigidos por la asamblea.** Encuestas dentro del chat puenteado: "¿publicamos esto?" — pasa con x/y administradores o x/y participantes, configurable por encuesta — y un bot publica automáticamente al aprobarse.
+- **Bots de publicación configurables.** Cada cuenta tiene sus propias reglas: inmediato, por quórum, solo administradores. Por tema, por tipo de contenido.
+- **Subchats con equipos.** Temas de foro como grupos de trabajo; cuentas asignadas a temas; cada tema con sus propias reglas de publicación.
+- **El chat es el control remoto.** Bots de Telegram manejan la transmisión: /take, /cut, cambiar fuentes — mapeados a tu rol, con confirmación, todo auditado.
+- **Archivos del chat al almacenamiento.** Lo que se publica en el chat llega al almacenamiento del grupo; admins lo organizan en carpetas por comando del bot o pantalla móvil; busca en toda la biblioteca desde el chat.
+- **Más puertas:** conectores de YouTube y TikTok, crossposting con citas inteligentes, y un bot de ingesta comunitaria — reenvía un URL, lo fetchamos y archivamos.
+
+**Stack:** Next.js + NestJS + Postgres (RLS) + Temporal + Redis + S3 + FFmpeg/PeerTube. Autoalojado de punta a punta, multi-tenant, todo auditado.
+
+## Buscamos: testers y hackers de ingesta
+
+Prueba todo el flujo con tus feeds y cuentas reales. Y ayúdanos con el **problema difícil: ingesta a escala** — formas confiables de extraer contenido de las plataformas cerradas sin quemar cuentas. Si has construido scrapers o corrido pipelines de ingesta, queremos tu diseño.
diff --git a/docs/tweetdeck-on-steroids.md b/docs/tweetdeck-on-steroids.md
new file mode 100644
index 0000000..f931863
--- /dev/null
+++ b/docs/tweetdeck-on-steroids.md
@@ -0,0 +1,26 @@
+# TweetDeck on Steroids
+
+**A self-hosted, multi-platform broadcast newsroom for collectives — a column wall that watches every platform at once, wired into a full live broadcast pipeline.**
+
+TweetDeck died when X locked its doors. We built what should have replaced it: columns that watch Mastodon, Telegram, Bluesky, PeerTube, Twitch and more in one wall — wired into publishing, approvals, live mixing, and an archive that can't be purged. Self-hosted. No algorithm in between. No platform holding your keys.
+
+## How people work together in it
+
+- **The wall is the room.** Live columns watch all your connected accounts at once — every post rendered safe, media proxied, duplicates deduplicated into the archive. The whole collective sees the same picture.
+- **Draft once, approve together, publish everywhere.** Anyone can draft into any account. Every draft goes through configurable group approval before it moves. On sign-off it fans out natively per platform — proper quotes, attribution intact, tamper-evident audit of who decided what.
+- **Roles, not passwords.** Editors draft, reviewers approve, publishers publish — per account, per channel. Invite links bring people in; leaving removes access. No shared logins, no bottlenecks.
+- **Schedule like a station.** Timezone-correct scheduled posts with a DST-proof occurrence engine. Cancel, review, re-schedule — the calendar survives clock changes.
+- **Live control room in the browser.** Multiview grid, TAKE/CUT, preview/program, lower-thirds and chyrons, audio mixing — program out to your PeerTube channel, 24/7 playlist when you're dark. Works from a laptop.
+- **Auto-Director.** Priority rules switch sources automatically so the stream never dies mid-action.
+- **Chat from every platform** bridged into one overlay — viewers heard, moderators acting, the streamer focused on the shot.
+- **Your own transcode workers.** Laptops and GPUs join as render workers over Tailscale — an RTX 3090 laptop is already transcoding real PeerTube jobs. More workers, more channels, all self-hosted.
+- **An archive that can't be purged.** Content-addressed, encrypted, deduplicated. Platforms purge; the archive remembers. Deleted threads stay citable.
+- **Analytics.** Month-by-month snapshots: what published where, what failed, what got archived.
+
+## What we need: testers and scrapers
+
+We're looking for **testers** across the flow — post through approvals, run a column wall against your real feeds, mix a stream, break the scheduler across timezones. And we're looking for help on the **hard problem: intake at scale.** Watching RSS, the fediverse and Telegram is solved. What we want next: reliable ways to pull from the locked platforms — hashtags, accounts, search columns — without burning accounts. If you've built scrapers, run intake pipelines, or know the platform-integrity arms race from the inside, help us design the intake layer: per-URL fetchers, community-submitted links, archive harvesters, bridge services.
+
+## Stack
+
+Next.js + NestJS + Postgres (RLS) + Temporal + Redis + S3 + FFmpeg/PeerTube. Self-hosted end to end, multi-tenant, everything audited.
diff --git a/docs/user-guide.md b/docs/user-guide.md
new file mode 100644
index 0000000..a642cfc
--- /dev/null
+++ b/docs/user-guide.md
@@ -0,0 +1,79 @@
+# Tactical Media Broadcast Hub — User Guide
+
+Post, schedule, monitor, and amplify across your social platforms from one dark, keyboard-friendly console. Admin setup help: [admin-guide.md](./admin-guide.md).
+
+---
+
+## 1. Getting started (onboarding)
+
+The 3-step wizard (Onboarding screen):
+
+1. **Name your workspace** — the tenant boundary for accounts, drafts, and the audit trail.
+2. **Invite your team** — comma-separated emails; roles are assigned after they accept.
+3. **Connect your first accounts** — pick platforms and Connect.
+
+Only OAuth tokens (or bot tokens, for Telegram) are ever stored — **the system never asks for or keeps platform passwords**. Tokens live encrypted in the workspace vault; you can rotate or revoke them any time.
+
+## 2. Streams — your monitoring console
+
+The Streams screen is TweetDeck-style columns:
+
+- **Columns** track a feed per platform (Home, Mentions, saved searches). *(Configurable per-column subscriptions — accounts, lists, search terms — arrive with the archive/grabber update.)*
+- **Cards** show author, age, text, and engagement. Hover or navigate to a card and its **amplify bar** appears.
+- **Amplify buttons are honest:** each platform's API is different, so each column shows only what that platform truly supports. Mastodon: **Boost** and **Quote**. Telegram: **Forward**. Some platforms show *"no amplify — this platform's API exposes no reshare action"*. That's not a bug; it's us not pretending.
+
+### Keyboard first
+| Key | Action |
+|---|---|
+| `j` / `↓` | next item |
+| `k` / `↑` | previous item |
+| `r` | repost/boost the selected item |
+| `q` | quote the selected item (opens composer popover with char limit) |
+| `Esc` | close popover |
+| `⌘K` / `Ctrl+K` | command palette — jump anywhere, quick actions |
+
+## 3. Compose — write once, adapt everywhere
+
+- Rich editor with markdown shortcuts; **per-platform character counters** — add targets (Mastodon, Telegram, Facebook, Instagram) and the limit shown is the *tightest* one; each preview pane shows its own count and turns red when over.
+- **Visibility** (public / followers / private), **approval state** (draft / submit for review / approved), and **scheduling** (date-time) per post.
+- Right pane previews each target platform.
+
+## 4. The approval flow
+
+If your workspace uses approvals: write → **Submit for review** → an Approver gets it in Approvals → **Grant** (or reject with comments) → schedule or publish. Every step is permission-checked and lands in the audit trail. (Permissions are set by your workspace admin — see the roles table in the admin guide.)
+
+## 5. Inbox — DMs and conversations
+
+All direct-message conversations across connected accounts in one list (unread badges, assignees). Open a thread, reply inline. Note the honesty footer: messaging APIs allow replies within each platform's message window (e.g., 24h for Meta platforms); outside it, options narrow — we show you exactly what's possible rather than failing silently.
+
+## 6. Channels — your connected accounts
+
+Each account card shows: platform, handle, **capability chips** (what this connection can do), and health. A **token expiring** badge means reconnect soon. The "Connect" flow for new accounts is OAuth — you authenticate on the platform's own page; we only ever receive a token.
+
+## 7. Team — members, roles, assets
+
+- **Members:** change roles from the 10 seeded roles (Owner, Admin, Publisher, Editor, Approver, Analyst, Moderator, VideoPublisher, StreamOperator, BroadcastOperator). Removing a member takes effect immediately — their live sessions fail closed.
+- **Asset library:** shared media grouped by collection (Brand, Launch, PR…). Items marked **group-locked** are scoped to a group; members outside it see the lock, not the file.
+
+## 8. Audit trail — who did what
+
+Every meaningful action (post published, role changed, connection added, credential rotated, approval granted…) is recorded in a **tamper-evident hash chain**. Filter by actor or action; click a row to open the **diff viewer** — what changed, field by field, with removed/added values. Secret values always show as `[REDACTED]`: keys and tokens are never written into the audit log, by construction. Export to CSV for compliance.
+
+## 9. What's real vs. coming
+
+**Now (Level 1):** monitoring streams, compose with previews, approvals, scheduling, publishing pipeline, encrypted credential vault, audit trail. *(The screens currently run on representative sample data while the backend wiring lands.)*
+
+**Coming:**
+- **Archive & Grabber** — your search subscriptions run server-side; every matching post is archived with media downloaded (encrypted, deduplicated) and searchable; videos included.
+- **Crosspost** — one action moves content across platforms with your commentary (an Instagram image quoted into Mastodon, a Mastodon video into Facebook), flowing through approvals.
+- **Level 2** — video uploads, livestreams, the Virtual Channel / Auto Director master-control system, and the operator Control Room.
+
+## 10. FAQ
+
+**Why can't I retweet on some columns?** That platform's API doesn't expose resharing. We render only real capabilities.
+
+**Why did everyone get logged out after a role change?** Security: authorization epochs bump and stale sessions fail closed. One re-login.
+
+**Where are my passwords?** Nowhere. We store tokens only, envelope-encrypted. If you want to cut access, revoke the connection in-app or on the platform.
+
+**Who can see my stream keys / tokens?** Nobody through the UI — not even workspace Owners; they're redacted from every screen, log, and audit entry by construction.
diff --git a/docs/user-manual-v2.md b/docs/user-manual-v2.md
new file mode 100644
index 0000000..991b276
--- /dev/null
+++ b/docs/user-manual-v2.md
@@ -0,0 +1,374 @@
+# Tactical Media Broadcast Hub — User Manual v2
+
+*Your platform. Their feeds. No algorithm in between.*
+
+| | |
+|---|---|
+| Build documented | commit `6d5dc7e` (main), web production build |
+| Verified on | 2026-10-07, against a running API, Postgres, Redis and Temporal |
+| Screenshots | `docs/manual/screenshots/` (1440×900 desktop, 390×844 mobile) |
+| Method | Every claim marked **live** was exercised end-to-end. See [§15 Capability table](#15-capability-table--what-actually-works) |
+
+> **How to read this manual.** Each feature has one of four labels:
+>
+> - **live**: we ran a real round-trip through the UI and/or the API and checked the result.
+> - **sample data**: the screen shows built-in fixtures. Sometimes that happens only when the API is unreachable, and sometimes it always happens (this is noted).
+> - **partial**: the request works, but part of the pipeline behind it isn't wired yet.
+> - **stub**: a placeholder screen or an inert control.
+>
+> Nothing in this manual is described as working unless we exercised it.
+
+---
+
+## Contents
+
+1. [Quickstart](#1-quickstart)
+2. [The shell: sidebar, session bar, command palette](#2-the-shell)
+3. [Onboarding: create a workspace, sign in](#3-onboarding)
+4. [Streams](#4-streams)
+5. [Compose](#5-compose)
+6. [Channels (Connections)](#6-channels-connections)
+7. [Video](#7-video)
+8. [Team](#8-team)
+9. [Audit](#9-audit)
+10. [Inbox](#10-inbox)
+11. [Calendar, Approvals, Analytics, Settings](#11-calendar-approvals-analytics-settings)
+12. [Telegram](#12-telegram)
+13. [Offline / sample-data mode](#13-offline--sample-data-mode)
+14. [Mobile](#14-mobile)
+15. [Capability table](#15-capability-table--what-actually-works)
+
+---
+
+## 1. Quickstart
+
+1. **Open the app** and you land on **Onboarding**. Any protected screen redirects there when you have no session (verified: an anonymous visit to `/streams` is sent to `/onboarding`).
+2. **Create a workspace.** Enter a workspace name, your name, email, and a password of at least 10 characters, then press **Continue**. This creates the workspace, your owner account and your session in one step (**live**).
+3. **Invite your team (optional).** Enter comma-separated emails. Each invitee is added as **Editor** with status *invited* (**live**). Email delivery and invite acceptance are not wired yet, so invitees can't sign in.
+4. **Connect accounts.** This step is **simulated**: the buttons only flip a "connected" badge locally. Nothing is stored. Press **Finish setup**.
+5. **Write a post** in **Compose** and press **Save draft**. The draft is stored and appears under *Recent drafts* (**live**). Publishing needs a connected channel, and channels can't be connected from the UI yet (see §6).
+6. **Register a video** in **Video** by dropping an MP4/WebM/MOV file. The asset and a queued processing job are created (**partial**: processing doesn't start, see §7).
+7. **Check Audit.** Every action above appears in the hash-chained audit trail (**live**).
+
+> **What you can't do yet:** connect a real social account from the UI, publish to a platform from the UI, read real feeds/DMs, or use Calendar, Approvals, Analytics or Settings.
+
+---
+
+## 2. The shell
+
+![Desktop shell with Streams](manual/screenshots/desktop-streams.png)
+
+- **Sidebar.** Lists Streams (⌘1), Compose (⌘2), Calendar, Video, Inbox, Approvals, Analytics, Channels, Team, Audit, Onboarding and Settings, with the workspace name under the logo. The **3** next to Inbox and the **2** next to Approvals are fixture counts, not live counts. The footer card reads *"Level 1 · posting — Videos & Live arrive in Level 2"*.
+- **Session bar (top right).** Shows a green dot, your email and your role, plus **Sign out** (**live**). When the API is unreachable it reads *"offline — sample data"* instead.
+- **Command palette.** Press **⌘K / Ctrl+K** to jump to Streams, Compose, Video, Inbox, Channels, Team, Audit or Onboarding (**live**: navigation only, no actions).
+
+![Command palette](manual/screenshots/desktop-command-palette.png)
+
+**Session safety (live).** Changing a role, inviting or removing a member bumps the workspace's *authorization epoch*. Every older session token is then rejected with *"authorization epoch stale — re-authenticate"*. The web client automatically exchanges a stale token for a fresh one (`/auth/reissue`), so you stay signed in. We verified this: an old token returned 401 after a role change, and the client recovered transparently on the next screen load.
+
+---
+
+## 3. Onboarding
+
+| Step | Screenshot | Status |
+|---|---|---|
+| Register (blank) | ![](manual/screenshots/desktop-onboarding-register.png) | **live** |
+| Register (filled) | ![](manual/screenshots/desktop-onboarding-register-filled.png) | **live** |
+| Invite team | ![](manual/screenshots/desktop-onboarding-invite.png) | **live** (creates *invited* members; no email is sent) |
+| Connect accounts | ![](manual/screenshots/desktop-onboarding-connect.png) | **stub**: simulated toggle |
+| After clicking Connect on Telegram | ![](manual/screenshots/desktop-onboarding-connect-simulated.png) | **stub**: badge is local state only |
+| Done | ![](manual/screenshots/desktop-onboarding-done.png) | **live** (shows the real workspace name) |
+| Sign in | ![](manual/screenshots/desktop-onboarding-signin.png) | **live** |
+| Sign in, wrong password | ![](manual/screenshots/desktop-onboarding-signin-error.png) | **live**: *"invalid email or password"* |
+| Visiting Onboarding while signed in | ![](manual/screenshots/desktop-onboarding-signed-in.png) | **live**: shows your email, role and workspace, with *Sign out* and *Continue to Streams* |
+
+**How to use it**
+
+- **Create a workspace.** All four fields are required (the password needs at least 10 characters). **Continue** stays disabled until they are valid.
+- **Sign in.** Click **I already have an account**, then enter your email and password. On success you go to Streams.
+- **Session expiry.** If your session expires or is revoked, the app sends you back here with a notice: *"Your session ended (expired, or your role changed). Sign in again."*
+- **Platform list.** The *Connect* step lists five fixture platforms: Mastodon, Telegram, "Limited API" (a demo placeholder), Facebook and Instagram. The connector packages cover more providers (Bluesky, Discord, Slack, PeerTube, Reddit, LinkedIn, Threads, Twitch…), but none of them are connectable from this screen.
+
+---
+
+## 4. Streams
+
+**Status: sample data (always).** Streams columns are generated fixtures, even when you are signed in. The column headers say "live", but the content is not real feed data, and the screen shows no offline badge.
+
+![Streams](manual/screenshots/desktop-streams.png)
+
+**What it is.** A TweetDeck-style multi-column console. The columns are *Home* (Mastodon), *Mentions* (Telegram) and *Saved: product* (Limited API). Each column states its amplification honesty line, for example *"no native reshare on this API — Quote… with attribution still works"*.
+
+**Keyboard (works on the fixtures):**
+
+| Key | Action |
+|---|---|
+| `j` / `↓` | select next card (highlighted, shows **Boost** / **Quote** buttons) |
+| `k` / `↑` | select previous card |
+| `r` | repost/boost the selected card (shows a toast; nothing is sent) |
+| `q` | open the quote modal |
+| `Esc` | close the modal |
+
+| Selected card | Repost toast | Quote modal |
+|---|---|---|
+| ![](manual/screenshots/desktop-streams-selected.png) | ![](manual/screenshots/desktop-streams-repost-toast.png) | ![](manual/screenshots/desktop-streams-quote-modal.png) |
+
+**+ Column** and **Layout** are inert (**stub**).
+
+---
+
+## 5. Compose
+
+**Status: live (drafts) · partial (publish).**
+
+| Empty | Typed | Draft saved |
+|---|---|---|
+| ![](manual/screenshots/desktop-compose-empty.png) | ![](manual/screenshots/desktop-compose-typed.png) | ![](manual/screenshots/desktop-compose-draft-saved.png) |
+
+**What it does**
+
+- **Editor.** A rich-text (Tiptap) editor with a live character counter (`133 / 500`). The limit is the tightest one among the selected targets, or 500 when no target is selected.
+- **Targets.** When signed in, the target chips are your workspace's real connections (`GET /connections`). In a fresh workspace there are none, so the screen shows *"No channels connected — add one under Channels to publish"* and **Publish** stays disabled.
+- **Visibility.** public / followers / private.
+- **Approval.** draft / submit for review / approved.
+- **Schedule.** A date-time picker. Setting it turns **Publish** into **Schedule**.
+- **Save draft (live).** Stores the post and shows *"Draft saved."*. The draft appears under **Recent drafts** with its state badge (`editing`), and clicking a recent draft loads its text back into the editor. All verified in the UI; saving was also verified via the API.
+- **Publish (partial).** For each selected target, Publish runs create → submit → approve → schedule, stopping early if you lack a permission or choose *submit for review*.
+  - Verified via the API: create (`editing`) → submit (`in_review`) → approve (`approved`). Scheduling against a connection that doesn't exist is correctly refused (404 *connection … not found*).
+  - **Not verified:** publishing to a real platform. No workspace can obtain a real connection through the UI, and the dev seeding route `POST /demo/connections` currently returns 500. We couldn't create a target, so the publish button was never enabled during testing.
+- **Previews pane.** Shows one preview per selected target with its own counter. It is empty when there are no targets.
+
+---
+
+## 6. Channels (Connections)
+
+**Status: live list (read-only) · stub for Connect/Reconnect/Remove · capacity chips need sample data or a real connection.**
+
+| Live workspace (no channels yet) | Sample data (API unreachable) |
+|---|---|
+| ![](manual/screenshots/desktop-connections-live-empty.png) | ![](manual/screenshots/desktop-connections-sample.png) |
+
+**What it does**
+
+- **Live.** Reads `GET /connections` for the workspace. A new workspace shows *"No channels connected yet"*, followed by one dashed *not connected* card per known platform.
+- **Connect buttons.** **Connect account**, **Connect**, **Reconnect** and **Remove** are **disabled when live**. Their tooltip reads: *"OAuth connect flows arrive with the connector wiring phase"*. **There is no way to add a channel from the UI today.**
+- **Each connected card** (seen in sample mode) shows:
+  - a health badge (*healthy*, *token expiring*, *needs credentials*)
+  - capability chips (`publishText`, `amplifyRepost`, `feed`, `directMessages`, `comments`…)
+  - an *Amplify* line naming the platform's real reshare verbs (Mastodon: Boost · Quote; Telegram: Forward; Facebook: Share link; "not exposed by this API" where there is none)
+
+### Capacity chips and popover
+
+![Capacity popover](manual/screenshots/desktop-connections-capacity-popover.png)
+
+The chip on each connection reads either **`258/300 posts left`** or **`15 today · no cap`**. Click it to open the **Rolling 24h capacity** popover, which shows:
+
+- a usage bar with *used / cap / remaining*
+- either *"slots available now — each post holds its slot for 24h, then frees it"* or *"next slot frees in …"*
+- a tier note, and a warning when a configured cap exceeds the platform's documented standard
+
+The math is real: it uses the connector SDK's `capacitySnapshot` rate policy. In a live workspace the chip uses the connection's real `recentPublishes`. **We could only exercise the popover on sample data**, because no live connection could be created (see §6 above).
+
+---
+
+## 7. Video
+
+**Status: live (register, list, detail, delete) · partial (processing).**
+
+| Empty library | After upload: detail drawer |
+|---|---|
+| ![](manual/screenshots/desktop-video-empty.png) | ![](manual/screenshots/desktop-video-detail-drawer.png) |
+
+| Library grid | Delete confirmation | After delete |
+|---|---|---|
+| ![](manual/screenshots/desktop-video-library.png) | ![](manual/screenshots/desktop-video-delete-confirm.png) | ![](manual/screenshots/desktop-video-after-delete.png) |
+
+**How to use it**
+
+1. **Add a video.** Drop a file on *Drop a video here*, paste one, or click **Browse files**. MP4, WebM and MOV are accepted. Other types are refused (verified: a `.txt` file gave *"not-a-video.txt: not a video file (text/plain)"*). Drag-drop and paste use the same code path as Browse; we exercised only Browse.
+2. **What happens on upload.** The browser computes the file's SHA-256 and registers it with the API as `sha256/<hash>.<ext>` (`POST /video/upload`). The response creates a **video asset** and a **processing job** in state **queued** (**live**, verified twice in the UI and once via the API).
+3. **Detail drawer.** The drawer opens automatically after upload; close it with **Esc**. It shows:
+   - the pipeline: **Queued → Probing (ffprobe) → Transcoding → Ready**
+   - probe metadata (MIME type and size are filled in; duration, resolution, codecs and bitrate stay "–" until the probe runs)
+   - publications
+   - the asset ID
+4. **Auto-refresh.** The library refreshes every 6 seconds while any asset is in flight, and **Refresh** reloads it manually.
+5. **Delete.** Click **Delete** on a card to open the confirmation dialog: *"This removes the asset, its processing jobs, and its probe metadata… Published posts that reference it are not deleted."* Click **Delete video** to remove it and show *"Video deleted."* (**live**). The deletion appears in Audit as `video.deleted`.
+
+**Why it's partial.** The API registers the asset but never receives the file bytes: there is no multipart upload route. The bytes are meant to reach object storage through the media-worker ingest path, which isn't wired. As a result:
+
+- every job stays **queued at 0%** (verified 8 minutes after upload, and across auto-refresh cycles, as shown in `desktop-video-after-refresh.png`)
+- no probe metadata is ever filled in
+- no thumbnail is generated (cards show the logo placeholder)
+- cards show the hash, not the original filename
+
+---
+
+## 8. Team
+
+**Status: live (members, invite, role change, remove) · sample data (asset library, always).**
+
+![Team](manual/screenshots/desktop-team.png)
+
+**Members table (live):**
+
+| Feature | What happened in testing |
+|---|---|
+| List | Shows member, role and status (*active* / *invited*) |
+| Invite | Entering an email + role and clicking **Send invite** gives *"Invited … as Editor."* and adds an *invited* row. Verified in the UI and via the API |
+| Change role | Uses the per-row dropdown. Verified via the API (Editor → Approver); the old session token was then rejected and the reissued token worked |
+| Remove | **Remove** → **Confirm remove**. Verified via the API (the UI button itself was not clicked) |
+| Roles | Admin, Analyst, Approver, BroadcastOperator, Editor, Moderator, Owner, Publisher, StreamOperator, VideoPublisher. Only an Owner can assign or modify Owner |
+
+Invite emails and invite acceptance are **not wired**. The page says so itself.
+
+**Asset library (lower half): sample data, always.** These six fixture files are not your workspace's assets. Real video assets live on the **Video** screen.
+
+---
+
+## 9. Audit
+
+**Status: live · Export CSV is a stub.**
+
+| Trail | Expanded entry (diff) |
+|---|---|
+| ![](manual/screenshots/desktop-audit.png) | ![](manual/screenshots/desktop-audit-diff-open.png) |
+
+- **What it shows.** Every workspace action, newest first: actor (email, or `system` for API-side events such as `video.uploaded`), action, target and age. We saw these actions recorded by our own test run:
+  - `workspace.created`
+  - `membership.invited`
+  - `draft.created` / `draft.submitted` / `draft.approved`
+  - `video.uploaded` / `video.deleted`
+  - `membership.role_changed` / `membership.removed` / `session.created` (from the API-driven run)
+- **Diff.** Click a row to expand its diff (for example `role "Editor"`, `email "…"`).
+- **Filters.** The **All actors** / **All actions** dropdowns narrow the list. Verified: filtering to `draft.approved` cut 11 rows to 1. *Load more* pages through older entries (not exercised: our test workspaces never exceeded one page).
+- **Integrity.** The trail is labelled *hash-chained · tamper-evident*, and secret-shaped keys render as `[REDACTED]`.
+- **Export CSV** has no handler. It is a **stub**.
+
+---
+
+## 10. Inbox
+
+**Status: sample data (always).** Fixture conversations are shown even when signed in. DMs are Level 2: the connector `getMessages()` path isn't wired to the API. You can type in the reply box, but nothing is sent.
+
+![Inbox](manual/screenshots/desktop-inbox.png)
+
+---
+
+## 11. Calendar, Approvals, Analytics, Settings
+
+**Status: stub.** Each of these four screens is a placeholder reading *"Arrives with WP3 (publishing pipeline)."*
+
+| Calendar | Approvals |
+|---|---|
+| ![](manual/screenshots/desktop-calendar.png) | ![](manual/screenshots/desktop-approvals.png) |
+
+| Analytics | Settings |
+|---|---|
+| ![](manual/screenshots/desktop-analytics.png) | ![](manual/screenshots/desktop-settings.png) |
+
+The approval *state machine* does exist in the API: drafts move editing → in_review → approved, verified in §5. There is just no review-queue screen yet.
+
+---
+
+## 12. Telegram
+
+**Status: connector-level only. There is no UI connect flow.**
+
+- **What exists.** The `@tactical-media-broadcast-hub/connector-telegram` package publishes to channels and amplifies by **forwarding**:
+  - `forwardMessage` for a plain forward
+  - `copyMessage` when you add commentary, because a forward cannot carry a caption
+  - removing an amplification is supported
+- **Auth.** Telegram uses a **bot token** created with @BotFather, not OAuth.
+- **Tests.** Its contract test suite passes (34/34, run on 2026-10-07). The tests run against a mocked Bot API, not a real bot.
+- **In the UI.** Telegram appears as a fixture column in Streams, a fixture card in Channels sample mode (capability `amplifyShare`, *Amplify: Forward*), and a simulated toggle in Onboarding. **None of these talk to Telegram.** There is no screen to enter a bot token, so a Telegram channel can't be connected from the app today.
+
+---
+
+## 13. Offline / sample-data mode
+
+If the browser can't reach the API at all, the session bar shows *offline — sample data*, and the screens built on the API (Channels, Compose, Video, Team, Audit) render fixtures with an **"offline — showing sample data"** badge. Sample data is read-only: actions answer *"Offline — sample data is read-only."* or *"Offline — sample mode, nothing was sent."*. This mode is a development convenience, not a feature.
+
+| Channels | Video | Team | Audit |
+|---|---|---|---|
+| ![](manual/screenshots/desktop-connections-sample.png) | ![](manual/screenshots/desktop-video-sample.png) | ![](manual/screenshots/desktop-team-sample.png) | ![](manual/screenshots/desktop-audit-sample.png) |
+
+Compose and Onboarding in this mode: `desktop-compose-sample.png`, `desktop-onboarding-sample.png`.
+
+---
+
+## 14. Mobile
+
+**Status: a mobile PWA is in progress. Today, the mobile experience is the desktop site on a phone.**
+
+At 390×844 the full desktop sidebar stays fixed and takes roughly half the width. The content column is squeezed:
+
+- Streams columns are a few characters wide.
+- **The Compose editor is collapsed to zero usable width.** Our automated test couldn't click into it at all ("element is not visible").
+- The onboarding inputs are only **84 px wide**, so registering or signing in on a phone is cramped at best.
+
+Treat phones as **read-only, at best** until the PWA ships.
+
+| Streams | Compose | Video | Onboarding (register) |
+|---|---|---|---|
+| ![](manual/screenshots/mobile-streams.png) | ![](manual/screenshots/mobile-compose.png) | ![](manual/screenshots/mobile-video.png) | ![](manual/screenshots/mobile-onboarding-register.png) |
+
+Other mobile captures:
+
+- `mobile-connections.png`
+- `mobile-team.png`
+- `mobile-audit.png`
+- `mobile-inbox.png`
+- `mobile-calendar.png`
+- `mobile-approvals.png`
+- `mobile-settings.png`
+- `mobile-analytics.png`
+- `mobile-onboarding.png` (signed in)
+- `mobile-onboarding-signin.png`
+
+---
+
+## 15. Capability table — what actually works
+
+| Feature | Status | Evidence |
+|---|---|---|
+| Register workspace + owner | **live** | UI registration and API `POST /auth/register` → 201 |
+| Sign in / wrong-password error | **live** | UI sign-in → /streams; wrong password → 401 "invalid email or password" |
+| Sign out | **live** | Session bar button: token cleared from storage; next protected route → /onboarding |
+| Auth gate (anonymous → onboarding) | **live** | Anonymous `/streams` redirected to `/onboarding` |
+| Epoch fail-closed + auto reissue | **live** | Old token → 401 "authorization epoch stale" after a role change; client reissued automatically |
+| Onboarding invite step | **live** | 2 invites → 201 each; members appear as *invited* |
+| Invite email delivery / acceptance | **stub** | Not wired (stated in the UI) |
+| Onboarding "Connect accounts" | **stub** | Simulated local toggle |
+| Streams columns, j/k/r/q | **sample data** (always) | Fixtures; repost/quote don't call any API |
+| Streams + Column / Layout | **stub** | Inert buttons |
+| Compose editor, counters, previews | **live** (client-side) | Exercised in the UI |
+| Save draft / Recent drafts | **live** | UI "Draft saved." + `GET /publishing/drafts` |
+| Draft submit → approve (state machine) | **live** (API only) | `in_review` → `approved` via the API |
+| Schedule / publish to a platform | **partial**, not exercised end-to-end | No connection obtainable; schedule against an unknown connection → 404 as designed |
+| Channels list | **live** (read-only) | `GET /connections` → `[]` for a new workspace |
+| Connect / Reconnect / Remove channel | **stub** | Disabled when live ("OAuth connect flows arrive with the connector wiring phase") |
+| Capacity chip + 24h popover | **sample data** in testing | Real rate-policy math; no live connection to show it on |
+| `POST /demo/connections` (dev seed) | **broken** | Returns 500 |
+| Video register (upload) | **live** | 2 UI uploads + 1 API upload → asset + job `queued` |
+| Video library, detail drawer, refresh | **live** | `GET /video`, `GET /video/:id/status` |
+| Video delete (confirm modal) | **live** | `DELETE /video/:id` → 200, "Video deleted.", audit `video.deleted` |
+| Video probe / transcode / thumbnails | **partial** | Job stays `queued 0%`; bytes never reach storage (no ingest path) |
+| Team list / invite / role change / remove | **live** | UI invite; API role change + remove |
+| Team asset library | **sample data** (always) | Fixtures |
+| Audit trail, diffs, filters | **live** | Our own actions recorded with actor/diff; action filter `draft.approved` narrowed 11 rows → 1 |
+| Audit Export CSV | **stub** | Button has no handler |
+| Command palette (⌘K) | **live** (navigation only) | Opened and listed routes |
+| Inbox | **sample data** (always) | Fixtures; reply doesn't send |
+| Calendar | **stub** | Placeholder "Arrives with WP3" |
+| Approvals screen | **stub** | Placeholder (approval API exists, see above) |
+| Analytics | **stub** | Placeholder |
+| Settings | **stub** | Placeholder |
+| Telegram publish + forward-amplify | **connector-level only** | Contract tests 34/34 against a mocked Bot API; no UI connect (bot-token entry) flow |
+| Other connectors (Mastodon, Bluesky, Discord, Slack, PeerTube…) | **connector-level only** | Not exercised here; none connectable from the UI |
+| Offline sample-data mode | **sample data** | API blocked → fixtures + "offline" badge |
+| Mobile | **in progress** | Desktop site on a phone; Compose unusable at 390px |
+
+---
+
+*Generated from a verification run; details, logs and the screenshot inventory are in `runs/manual/screenshots-manual-report.md`.*
diff --git a/docs/wiki/EN/getting-started.md b/docs/wiki/EN/getting-started.md
new file mode 100644
index 0000000..7fb003d
--- /dev/null
+++ b/docs/wiki/EN/getting-started.md
@@ -0,0 +1,29 @@
+---
+title: Getting Started
+lang: en
+---
+
+# Getting Started
+
+## 1. Create your account
+
+Go to `app.occupymedia.cc/onboarding` and fill in your display name, username, and password. Registering creates a personal workspace for you automatically — you are the Owner.
+
+## 2. Understand your roles
+
+The Hub has roles that control what each person can do:
+
+| Role | Can do | Cannot do |
+|------|--------|-----------|
+| **Owner** | Everything, including deleting the workspace | — |
+| **Admin** | Manage members, connections, and content | Delete the workspace |
+| **Editor** | Draft, edit, and review content | Publish without approval |
+| **Viewer** | Read-only access | Change anything |
+
+## 3. Invite your crew
+
+Go to **More → Team** and use the invite link. Share the link with your crew — they join the workspace with the role you assigned. No passwords shared, no admin phone in the loop.
+
+## 4. Connect your first accounts
+
+Go to **Connections** and add your platform accounts (Mastodon, Telegram, Bluesky, etc.). Each account's credentials are stored in an encrypted vault — the database never sees a plaintext key.
diff --git a/docs/wiki/ES/getting-started.md b/docs/wiki/ES/getting-started.md
new file mode 100644
index 0000000..400821c
--- /dev/null
+++ b/docs/wiki/ES/getting-started.md
@@ -0,0 +1,29 @@
+---
+title: Primeros pasos
+lang: es
+---
+
+# Primeros pasos
+
+## 1. Crea tu cuenta
+
+Ve a `app.occupymedia.cc/onboarding` y completa tu nombre visible, nombre de usuario y contraseña. Al registrarte se crea automáticamente un espacio de trabajo personal — eres el propietario.
+
+## 2. Entiende los roles
+
+El Hub tiene roles que controlan lo que cada persona puede hacer:
+
+| Rol | Puede hacer | No puede hacer |
+|-----|------------|----------------|
+| **Propietario** | Todo, incluyendo borrar el espacio | — |
+| **Administrador** | Gestionar miembros, conexiones y contenido | Borrar el espacio |
+| **Editor** | Redactar, editar y revisar contenido | Publicar sin aprobación |
+| **Observador** | Solo lectura | Cambiar nada |
+
+## 3. Invita a tu equipo
+
+Ve a **Más → Equipo** y usa el enlace de invitación. Comparte el enlace con tu equipo — se unen al espacio con el rol que asignaste. Sin compartir contraseñas, sin teléfonos de administrador en el medio.
+
+## 4. Conecta tus primeras cuentas
+
+Ve a **Conexiones** y agrega tus cuentas (Mastodon, Telegram, Bluesky, etc.). Las credenciales de cada cuenta se guardan en una bóveda cifrada — la base de datos nunca ve una clave en texto plano.
diff --git a/eslint.config.mjs b/eslint.config.mjs
new file mode 100644
index 0000000..da5e8d6
--- /dev/null
+++ b/eslint.config.mjs
@@ -0,0 +1,48 @@
+import tseslint from "typescript-eslint";
+
+const PROVIDER_IDS =
+  "youtube|facebook|instagram|threads|linkedin|mastodon|bluesky|reddit|tiktok|twitch|peertube|discord|slack|telegram";
+
+/** Provider branching belongs in connector packages only — never in core/app code. */
+const noProviderBranching = {
+  files: ["**/*.ts", "**/*.tsx"],
+  ignores: [
+    "packages/connector-*/**",
+    "packages/testing/**",
+    // apps/web/src/lib is the mock-registry boundary: manifest-shaped data that
+    // stands in for ConnectorRegistry until the real registry feeds the UI —
+    // same standing as packages/testing. Pages must import from here, never
+    // declare provider literals inline.
+    "apps/web/src/lib/**",
+    "**/*.test.ts",
+  ],
+  rules: {
+    "no-restricted-syntax": [
+      "error",
+      {
+        selector: `Literal[value=/${PROVIDER_IDS}/]`,
+        message:
+          "Provider string literal outside a connector package — resolve via ConnectorRegistry instead of branching on provider names.",
+      },
+    ],
+  },
+};
+
+export default tseslint.config(
+  { ignores: ["**/dist/**", "**/.next/**", "**/*.config.mjs"] },
+  ...tseslint.configs.recommended.map((config) => ({
+    ...config,
+    files: ["**/*.ts", "**/*.tsx"],
+  })),
+  {
+    files: ["**/*.ts", "**/*.tsx"],
+    rules: {
+      "@typescript-eslint/no-explicit-any": "error",
+      "@typescript-eslint/no-unused-vars": [
+        "error",
+        { argsIgnorePattern: "^_" },
+      ],
+    },
+  },
+  noProviderBranching,
+);
diff --git a/infra/docker-compose.yml b/infra/docker-compose.yml
new file mode 100644
index 0000000..1821433
--- /dev/null
+++ b/infra/docker-compose.yml
@@ -0,0 +1,108 @@
+name: tactical-media-broadcast-hub
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: superposter
+      POSTGRES_PASSWORD: superposter_dev
+      POSTGRES_DB: superposter
+    ports: ["5433:5432"]
+    volumes: [pgdata:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U superposter"]
+      interval: 5s
+      retries: 10
+
+  redis:
+    image: redis:7-alpine
+    ports: ["6379:6379"]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      retries: 10
+
+  temporal:
+    image: temporalio/auto-setup:1.24
+    depends_on:
+      postgres:
+        condition: service_healthy
+    environment:
+      DB: postgres12
+      DB_PORT: 5432
+      POSTGRES_USER: superposter
+      POSTGRES_PWD: superposter_dev
+      POSTGRES_SEEDS: postgres
+    ports: ["7233:7233"]
+
+  minio:
+    image: minio/minio:latest
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: superposter
+      MINIO_ROOT_PASSWORD: superposter_dev
+    ports: ["9000:9000", "9001:9001"]
+    volumes: [miniodata:/data]
+
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    volumes:
+      - ./otel/otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
+    ports: ["4317:4317", "4318:4318"]
+
+  prometheus:
+    image: prom/prometheus:latest
+    volumes:
+      - ./prometheus/prometheus.yml:/etc/prometheus/prometheus.yml:ro
+    ports: ["9090:9090"]
+
+  grafana:
+    image: grafana/grafana:latest
+    environment:
+      GF_AUTH_ANONYMOUS_ENABLED: "true"
+      GF_AUTH_ANONYMOUS_ORG_ROLE: Admin
+    volumes:
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+    ports: ["3001:3000"]
+
+  mock-rtmp-sink:
+    image: tiangolo/nginx-rtmp:latest
+    volumes:
+      - ./mock-rtmp/nginx-rtmp.conf:/etc/nginx/nginx.conf:ro
+    ports: ["1935:1935"]
+    profiles: ["dev"]
+
+  media-worker:
+    build:
+      context: ..
+      dockerfile: infra/media-worker.Dockerfile
+    environment:
+      PORT: "3100"
+      REDIS_HOST: redis
+      MEDIA_WORKER_ID: media-worker-dev
+      MEDIA_FENCE_PATH: /var/lib/media-worker/fence.json
+      POSTGRES_HOST: postgres
+      TEMPORAL_HOST: temporal:7233
+      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
+    ports: ["3100:3100"]
+    volumes:
+      - mediaworkerstate:/var/lib/media-worker
+    depends_on:
+      redis:
+        condition: service_healthy
+    profiles: ["dev"]
+
+  mock-live-source:
+    image: jrottenberg/ffmpeg:6-alpine
+    entrypoint: ["/bin/sh", "-c"]
+    command:
+      - "ffmpeg -re -f lavfi -i testsrc2=size=640x360:rate=30 -f lavfi -i sine=frequency=440 -c:v libx264 -preset veryfast -tune zerolatency -c:a aac -f flv rtmp://mock-rtmp-sink/mock/A-live"
+    depends_on:
+      - mock-rtmp-sink
+    profiles: ["dev"]
+
+volumes:
+  pgdata:
+  miniodata:
+  mediaworkerstate:
diff --git a/infra/grafana/provisioning/datasources/datasource.yml b/infra/grafana/provisioning/datasources/datasource.yml
new file mode 100644
index 0000000..86fd346
--- /dev/null
+++ b/infra/grafana/provisioning/datasources/datasource.yml
@@ -0,0 +1,8 @@
+apiVersion: 1
+
+datasources:
+  - name: Prometheus
+    type: prometheus
+    access: proxy
+    url: http://prometheus:9090
+    isDefault: true
diff --git a/infra/matrix/.env.example b/infra/matrix/.env.example
new file mode 100644
index 0000000..b476719
--- /dev/null
+++ b/infra/matrix/.env.example
@@ -0,0 +1,3 @@
+MATRIX_SERVER_NAME=chat.example.com
+MATRIX_ALLOW_REGISTRATION=false
+MATRIX_REGISTRATION_TOKEN=generate-a-long-random-token
diff --git a/infra/matrix/conduwuit.toml b/infra/matrix/conduwuit.toml
new file mode 100644
index 0000000..d007b83
--- /dev/null
+++ b/infra/matrix/conduwuit.toml
@@ -0,0 +1,10 @@
+# Conduwuit config — see docs/matrix-setup.md before changing
+[global]
+server_name = "chat.example.com"        # MUST match MATRIX_SERVER_NAME — permanent
+port = 6167
+database_path = "/var/lib/conduwuit"
+allow_registration = false              # flip via env only during initial setup
+registration_token = "change-me"
+allow_federation = true
+allow_encryption = true
+rich_text = true                        # markdown/HTML in messages
diff --git a/infra/matrix/docker-compose.yml b/infra/matrix/docker-compose.yml
new file mode 100644
index 0000000..5576b2f
--- /dev/null
+++ b/infra/matrix/docker-compose.yml
@@ -0,0 +1,34 @@
+# Matrix homeserver (conduwuit) for Tactical Media Broadcast Hub team chat — runs on the app or media server.
+# Lightweight Rust server: single container, SQLite or RocksDB backend, no postgres required.
+# Docs: docs/matrix-setup.md (branding, bridges, Tactical Media Broadcast Hub integration)
+
+services:
+  conduwuit:
+    image: girlbossceo/conduwuit:latest
+    restart: unless-stopped
+    ports:
+      - "6167:6167"          # client/API + federation (put behind HTTPS reverse proxy)
+    volumes:
+      - conduwuit_data:/var/lib/conduwuit
+      - ./conduwuit.toml:/etc/conduwuit/conduwuit.toml:ro
+    environment:
+      CONDUWUIT_SERVER_NAME: ${MATRIX_SERVER_NAME}   # e.g. chat.example.com — CHANGES ARE PERMANENT
+      CONDUWUIT_DATABASE_PATH: /var/lib/conduwuit
+      CONDUWUIT_PORT: 6167
+      CONDUWUIT_ALLOW_REGISTRATION: ${MATRIX_ALLOW_REGISTRATION:-false}  # open only for the first admin, then lock
+      CONDUWUIT_REGISTRATION_TOKEN: ${MATRIX_REGISTRATION_TOKEN}         # invite-code style registration
+      CONDUWUIT_MAX_ROOM_MEMBERSHIP: 5000
+
+  # Telegram user-bridge (WP15: join/amplify from Telegram channels; DMs; two-way)
+  # Requires a one-time interactive login: docker compose run --rm mautrix-telegram
+  mautrix-telegram:
+    image: dock.mau.dev/mautrix/telegram:latest
+    restart: unless-stopped
+    volumes:
+      - mautrix_telegram_data:/data
+    depends_on:
+      - conduwuit
+
+volumes:
+  conduwuit_data:
+  mautrix_telegram_data:
diff --git a/infra/media-worker.Dockerfile b/infra/media-worker.Dockerfile
new file mode 100644
index 0000000..8cf90d2
--- /dev/null
+++ b/infra/media-worker.Dockerfile
@@ -0,0 +1,21 @@
+# Native helpers (frame gate + source bus): std-only Rust, built reproducibly on a pinned toolchain
+# (apps/media-worker/scripts/build-helpers.sh; same rustc ⇒ same SHA256SUMS). musl on Alpine, so
+# the binaries are static and need nothing from the runtime image.
+FROM rust:1.97.1-alpine AS helpers
+WORKDIR /build
+COPY apps/media-worker/src/gate/rust apps/media-worker/src/gate/rust
+COPY apps/media-worker/scripts/build-helpers.sh apps/media-worker/scripts/build-helpers.sh
+RUN sh apps/media-worker/scripts/build-helpers.sh /out
+
+FROM node:22-alpine
+WORKDIR /app
+RUN corepack enable
+RUN apk add --no-cache ffmpeg
+COPY pnpm-workspace.yaml package.json tsconfig.base.json ./
+COPY apps/media-worker/package.json apps/media-worker/
+RUN pnpm install --filter @tactical-media-broadcast-hub/media-worker... --no-frozen-lockfile
+COPY apps/media-worker apps/media-worker
+COPY --from=helpers /out /opt/media-helpers
+# src/gate/binary.ts resolves the helpers here; nothing is compiled at runtime.
+ENV MEDIA_HELPER_DIR=/opt/media-helpers
+CMD ["pnpm", "--filter", "@tactical-media-broadcast-hub/media-worker", "dev"]
diff --git a/infra/mock-rtmp/nginx-rtmp.conf b/infra/mock-rtmp/nginx-rtmp.conf
new file mode 100644
index 0000000..86488b7
--- /dev/null
+++ b/infra/mock-rtmp/nginx-rtmp.conf
@@ -0,0 +1,25 @@
+worker_processes auto;
+events {
+  worker_connections 1024;
+}
+rtmp {
+  server {
+    listen 1935;
+    application mock {
+      live on;
+      record off;
+    }
+  }
+}
+http {
+  server {
+    listen 8080;
+    location /stat {
+      rtmp_stat all;
+      rtmp_stat_stylesheet static/stat.xsl;
+    }
+    location /static {
+      root /www;
+    }
+  }
+}
diff --git a/infra/occupymedia/.env.example b/infra/occupymedia/.env.example
new file mode 100644
index 0000000..5b7e538
--- /dev/null
+++ b/infra/occupymedia/.env.example
@@ -0,0 +1,27 @@
+# occupymedia.cc deployment secrets — copy to .env on the box, fill every :? value.
+# NEVER commit the filled .env.
+
+# --- Cloudflare (already provisioned; tunnel + DNS + R2 buckets exist) ---
+CLOUDFLARE_ACCOUNT_ID=e50adafec3c6aee02a328f28b967f699
+CLOUDFLARE_TUNNEL_TOKEN=<fromkeepass-or-ask-coordinator>   # occupymedia tunnel e5695d8b-…
+
+# --- R2 (S3 API token: dashboard → R2 → Manage API Tokens → Object Read & Write,
+#     scoped to the four occupymedia-* buckets) ---
+R2_ACCESS_KEY=<paste R2 Access Key ID>
+R2_SECRET_KEY=<paste R2 Secret Access Key>
+
+# --- Database ---
+POSTGRES_PASSWORD=<generate: openssl rand -hex 24>
+# Runtime-only role provisioned by migration 003. Set its production password
+# with owner access; never reuse POSTGRES_PASSWORD or the development default.
+DATABASE_URL=postgres://sp_app:<runtime-password>@postgres:5432/occupymedia
+SCHEDULER_DATABASE_URL=postgres://sp_app:<runtime-password>@postgres:5432/occupymedia
+# SUPER_DATABASE_URL is passed only to the offline migration CLI, never services.
+PEERTUBE_DB_PASSWORD=<generate: openssl rand -hex 24>   # also paste into peertube.env
+SESSION_SECRET=<generate: openssl rand -base64 32>
+
+# --- Client-side envelope encryption for the media archive ---
+# One random 32-byte base64 key. It wraps EVERY stored blob (DEK/KEK envelope).
+# Lose it = archive unreadable. Rotate = full re-encrypt. Store in the password manager.
+S3_KEK=<generate ONCE: openssl rand -base64 32>
+SUPERPOSTER_KEK=<same bytes as S3_KEK, base64>
diff --git a/infra/occupymedia/DEPLOY.md b/infra/occupymedia/DEPLOY.md
new file mode 100644
index 0000000..21712ab
--- /dev/null
+++ b/infra/occupymedia/DEPLOY.md
@@ -0,0 +1,130 @@
+# Deploy — occupymedia.cc
+
+**Storage phase-one addendum:** the current deployment uses separate app/chat/
+PeerTube CTs. New files/docs work is an independent, undeployed scaffold;
+see [files runbook](files/README.md) and [storage contracts](../../docs/occupymedia-storage.md).
+The older one-box instructions below do not deploy that stack. Live conduwuit
+v0.5.0 still has local media; its volumes require backup. R2 durability alone
+does not back up media or the metadata needed to resolve it.
+
+One box, everything behind the Cloudflare tunnel (already provisioned: zone
+`occupymedia.cc`, tunnel `occupymedia` with ingress app/api/tube/chat, R2
+buckets `occupymedia-media-encrypted`, `-peertube-videos`, `-peertube-playlists`,
+`-matrix-media`). No inbound ports. All local ports bind to 127.0.0.1.
+
+## WP3 release on the app CT (150)
+
+Use `docker compose -f docker-compose.app.yml` in this directory. Before
+syncing source, create and verify an owner `pg_dump` in
+`/opt/tactical-media-broadcast-hub/backups/`. Preserve the previous source for rollback.
+
+Both `DATABASE_URL` and `SCHEDULER_DATABASE_URL` in the CT `.env` must connect
+as `sp_app`, without superuser or BYPASSRLS privileges. Provision its password
+with owner access and keep real values only in the CT `.env`. Keep the
+existing `SUPERPOSTER_KEK`; scheduler inherits it and `TEMPORAL_ADDRESS`.
+
+Stop the old scheduler, then run the new API migration CLI offline with
+`SUPER_DATABASE_URL` set to the owner URL:
+`pnpm --filter @tactical-media-broadcast-hub/api exec tsx src/db/migrate.cli.ts --dir migrations`.
+The CLI skips recorded migrations; 019 tracks resumable transactional, batch,
+and concurrent-index phases. Confirm 018 and 019 in `schema_migrations` and
+check `assertPublishingSchema` using the runtime URL before starting new code.
+
+Build `api scheduler web`, then run `up -d --no-deps api`, followed by
+`scheduler` and `web`. Verify API health/readiness, invite regressions, an
+existing username/password login, scheduler readiness and Temporal connectivity,
+and the public web app. Defer production publish tests until explicitly requested.
+For rollback, restore source from the previous commit, re-sync, rebuild and
+restart the three services; do not undo migrations automatically.
+
+## 0. Prerequisites on the box
+
+- Debian 12 / Ubuntu 24.04, 4+ vCPU, 8 GB RAM, 100 GB disk
+- Docker Engine + compose plugin (`curl -fsSL https://get.docker.com | sh`)
+- git
+
+## 1. Get the code + secrets
+
+```bash
+git clone git@gitlab.example.com:mediatools/tacticalmediahub.git
+cd tactical-media-broadcast-hub/infra/occupymedia
+
+cp .env.example .env
+# Fill: CLOUDFLARE_TUNNEL_TOKEN, R2_ACCESS_KEY, R2_SECRET_KEY (dashboard → R2 →
+# Manage API Tokens → Object Read & Write, scoped to the occupymedia-* buckets),
+# POSTGRES_PASSWORD, PEERTUBE_DB_PASSWORD, S3_KEK (openssl rand -hex 32 — ONE TIME,
+# it wraps every stored blob; lose it = archive unreadable)
+
+# peertube.env: set both PEERTUBE_DB_PASSWORD / POSTGRES_PASSWORD lines to the
+# value from .env, and set a registration/SMTP sender if you have them.
+```
+
+## 2. Build + start the core
+
+```bash
+docker compose build api scheduler web media-worker
+docker compose up -d postgres redis temporal peertube-postgres
+```
+
+## 3. Apply API migrations (ordered, once)
+
+```bash
+cd ../..
+for f in apps/api/migrations/*.sql; do
+  docker compose -f infra/occupymedia/docker-compose.yml exec -T postgres \
+    psql -U "$(grep -oP '(?<=POSTGRES_USER:)\S+' infra/occupymedia/docker-compose.yml | head -1 | tr -d '${:-occupymedia}')" \
+    -d occupymedia -v ON_ERROR_STOP=1 < "$f" || { echo "FAILED at $f"; break; }
+done
+```
+
+(If psql errors on an already-applied migration — re-runs are idempotent-safe
+for most files; check the failing file before continuing.)
+
+## 4. Bring everything up
+
+```bash
+docker compose -f infra/occupymedia/docker-compose.yml up -d
+docker compose ps   # everything Up/healthy
+```
+
+## 5. First-boot steps
+
+1. **Tunnel**: `docker compose logs cloudflared` — should show 4 connections
+   registered. Then `https://app.occupymedia.cc` (control room), `/healthz` on
+   api., tube., chat. should all answer.
+2. **PeerTube admin**: `docker compose logs peertube 2>&1 | grep -i -A3 password`
+   — random root password printed ONCE. Log in at tube.occupymedia.cc, change
+   it, then run the brand sync (`docs/peertube-setup.md`) and create the live
+   channel.
+3. **Matrix admin**: register the first account at chat.occupymedia.cc with the
+   token from conduwuit.toml, then set `allow_registration = false` and
+   `docker compose restart conduwuit`. Configure Element as client
+   (`docs/matrix-setup.md`).
+4. **Telegram bridge** (optional now): `docker compose --profile bridges run --rm
+   mautrix-telegram` → interactive login with the bot/user token; then
+   `docker compose --profile bridges up -d mautrix-telegram`.
+
+## 6. Live ingest (deferred)
+
+RTMP/SRT cannot traverse the tunnel. Options documented in the session notes:
+tiny relay VPS + WireGuard to this box (recommended; keeps the home IP out of
+DNS), or direct port-forward. Until then the 24/7 channel runs playlists/VOD
+(media-worker pushes to PeerTube internally over the docker network).
+
+## 7. Operations
+
+- **Backup**: `docker compose exec postgres pg_dump -U occupymedia occupymedia |
+  gzip > backup-$(date +%F).sql.gz` + `tar` the named volumes (pgdata,
+  peertube_pgdata, conduwuit_data). Media itself is in R2 (durable) — KEK
+  backup matters more than volume backup.
+- **Update**: `git pull && docker compose build api scheduler web media-worker &&
+  docker compose up -d` (migrations: repeat step 3 for NEW files only).
+- **Logs**: `docker compose logs -f --tail=100 <service>`.
+
+## Known simplifications (first-production-pass)
+
+- observability (otel/prometheus/grafana) not included — add from
+  infra/docker-compose.yml services when needed
+- single app instance per service (no horizontal scaling — intended at this size)
+- file-sharing/collab layer: oCIS S3NG + optional Collabora scaffold in
+  `files/compose.yml`; deployment and Matrix migration remain separate prerequisites
diff --git a/infra/occupymedia/Dockerfile b/infra/occupymedia/Dockerfile
new file mode 100644
index 0000000..378a1e8
--- /dev/null
+++ b/infra/occupymedia/Dockerfile
@@ -0,0 +1,25 @@
+# Monorepo app builder for occupymedia.cc — APP build-arg: api | scheduler | web
+# (media-worker has its own image: ../../infra/media-worker.Dockerfile)
+FROM node:22-slim
+ARG APP
+ARG NEXT_PUBLIC_API_URL=https://api.occupymedia.cc
+ENV APP_MODE=${APP} NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
+WORKDIR /app
+RUN corepack enable
+COPY . .
+# Full workspace tree present so every workspace:* dependency resolves.
+# Do NOT "optimize" to a filtered install — scheduler/web builds broke on
+# missing build tools (tsc) and missing workspace manifests (connector-sdk).
+RUN NODE_ENV=development npx --yes pnpm@9.12.0 install --frozen-lockfile
+# egress is native-imported by path at runtime (NOT a package.json dep), so the
+# --filter app build never builds it — skip this line and the api crashes at boot.
+RUN npx --yes pnpm@9.12.0 --filter @tactical-media-broadcast-hub/egress build
+RUN npx --yes pnpm@9.12.0 --filter @tactical-media-broadcast-hub/${APP}... build
+ENV NODE_ENV=production
+EXPOSE 3000
+CMD ["sh", "-c", "case \"$APP_MODE\" in \
+  api)       exec node /app/apps/api/dist/apps/api/src/main.js ;; \
+  scheduler) exec node /app/apps/scheduler/dist/worker.js ;; \
+  web)       cd /app/apps/web && exec node ./node_modules/next/dist/bin/next start -H 0.0.0.0 -p \"${PORT:-3001}\" ;; \
+  *) echo \"unknown APP $APP_MODE\" && exit 1 ;; \
+esac"]
diff --git a/infra/occupymedia/conduwuit.toml b/infra/occupymedia/conduwuit.toml
new file mode 100644
index 0000000..c9c5d37
--- /dev/null
+++ b/infra/occupymedia/conduwuit.toml
@@ -0,0 +1,27 @@
+# Conduwuit — Matrix homeserver for occupymedia.cc (chat plane)
+# Mounted read-only by infra/occupymedia/docker-compose.yml.
+# Docs: docs/matrix-setup.md (branding, bridges, Tactical Media Broadcast Hub integration)
+
+[global]
+server_name = "chat.occupymedia.cc"   # user IDs become @name:chat.occupymedia.cc — PERMANENT
+address = "0.0.0.0"
+port = 6167                            # mapped to 127.0.0.1:8448 → Cloudflare tunnel (chat.occupymedia.cc)
+
+database_path = "/var/lib/conduwuit"
+database_backend = "rocksdb"
+
+# 20 MB uploads (Matrix media). Bigger files belong in the file-sharing layer.
+max_request_size = 20_000_000
+
+# First deploy: register the admin account with the token, then set
+# allow_registration = false and `docker compose restart conduwuit`.
+allow_registration = true
+registration_token = "CHANGE-ME-on-deploy"
+
+# Federation: on = your users can join rooms on other homeservers, other servers
+# can join yours (via chat.occupymedia.cc through the tunnel). Set false for a
+# closed chat island (restart required).
+allow_federation = true
+allow_room_creation = true
+
+# Rate limiting defaults are sane; tune only under load.
diff --git a/infra/occupymedia/docker-compose.app.yml b/infra/occupymedia/docker-compose.app.yml
new file mode 100644
index 0000000..f19e777
--- /dev/null
+++ b/infra/occupymedia/docker-compose.app.yml
@@ -0,0 +1,148 @@
+# occupymedia.cc — APP CT (occ-app, CT 150, tailscale 100.78.162.2)
+# Control room: postgres/redis/temporal + api/scheduler/web/media-worker + the tunnel.
+# Ports bind 0.0.0.0 in the CT: public access is ONLY via the Cloudflare tunnel
+# (ingress: app/api → 100.78.162.2). LAN/tailnet can reach them directly.
+
+name: occ-app
+
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-occupymedia}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?}
+      POSTGRES_DB: ${POSTGRES_DB:-occupymedia}
+    volumes: [pgdata:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-occupymedia}"]
+      interval: 5s
+      retries: 10
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes: [redisdata:/data]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      retries: 10
+    restart: unless-stopped
+
+  temporal:
+    image: temporalio/auto-setup:1.24
+    depends_on:
+      postgres: { condition: service_healthy }
+    environment:
+      DB: postgres12
+      DB_PORT: 5432
+      POSTGRES_USER: ${POSTGRES_USER:-occupymedia}
+      POSTGRES_PWD: ${POSTGRES_PASSWORD:?}
+      POSTGRES_SEEDS: postgres
+    restart: unless-stopped
+
+  api:
+    build:
+      context: ../..
+      dockerfile: infra/occupymedia/Dockerfile
+      args: { APP: api }
+    environment: &appenv
+      PORT: "3000"
+      # Runtime pools use the non-owner role; owner access is offline only.
+      DATABASE_URL: ${DATABASE_URL:?Set the sp_app runtime URL}
+      REDIS_HOST: redis
+      REDIS_URL: redis://redis:6379
+      POSTGRES_HOST: postgres
+      POSTGRES_PORT: "5432"
+      TEMPORAL_HOST: temporal
+      TEMPORAL_PORT: "7233"
+      TEMPORAL_ADDRESS: "temporal:7233"
+      S3_ENDPOINT: https://${CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com
+      S3_REGION: auto
+      S3_ACCESS_KEY: ${R2_ACCESS_KEY:-unset}
+      S3_SECRET_KEY: ${R2_SECRET_KEY:-unset}
+      S3_BUCKET: occupymedia-media-encrypted
+      S3_KEK: ${S3_KEK:?}
+      SUPERPOSTER_KEK: ${SUPERPOSTER_KEK:?}
+      SESSION_SECRET: ${SESSION_SECRET:?}
+      CORS_ORIGINS: https://app.occupymedia.cc
+      PUBLIC_ORIGIN: https://app.occupymedia.cc
+      WEB_ORIGIN: https://app.occupymedia.cc
+      API_PUBLIC_URL: https://api.occupymedia.cc
+      # OAuth routing: providers redirect the browser to CONNECTIONS_CALLBACK_URL
+      # after consent; the API then lands it on APP_URL. Both must be public —
+      # unset, both default to localhost and the flow breaks silently.
+      APP_URL: https://app.occupymedia.cc
+      CONNECTIONS_CALLBACK_URL: https://api.occupymedia.cc/connections/callback
+      PEERTUBE_INSTANCE_URL: https://tube.occupymedia.cc
+      PEERTUBE_AUTHORIZE_PATH: /oauth/authorize
+      PEERTUBE_TOKEN_PATH: /api/v1/users/token
+    ports: ["3000:3000"]
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+    restart: unless-stopped
+
+  scheduler:
+    build:
+      context: ../..
+      dockerfile: infra/occupymedia/Dockerfile
+      args: { APP: scheduler }
+    environment:
+      <<: *appenv
+      PORT: "3010"
+      SCHEDULER_DATABASE_URL: ${SCHEDULER_DATABASE_URL:?Set the sp_app runtime URL}
+      SCHEDULER_HEALTH_PORT: "8081"
+    healthcheck:
+      test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:8081/readyz').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
+      interval: 10s
+      timeout: 5s
+      start_period: 30s
+      retries: 3
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      temporal: { condition: service_started }
+    restart: unless-stopped
+
+  web:
+    build:
+      context: ../..
+      dockerfile: infra/occupymedia/Dockerfile
+      args:
+        APP: web
+        NEXT_PUBLIC_API_URL: https://api.occupymedia.cc
+    environment:
+      <<: *appenv
+      PORT: "3001"
+    ports: ["3001:3001"]
+    depends_on: [api]
+    restart: unless-stopped
+
+  media-worker:
+    build:
+      context: ../..
+      dockerfile: infra/media-worker.Dockerfile
+    environment:
+      <<: *appenv
+      PORT: "3100"
+      MEDIA_WORKER_ID: worker-1
+      MEDIA_FENCE_PATH: /var/lib/media-worker/fence.json
+      POSTGRES_HOST: postgres
+      REDIS_HOST: redis
+      # cross-CT: peertube RTMP on occ-tube via tailscale
+      PEERTUBE_PUSH_URL: rtmp://100.92.231.98:1935/live
+    volumes: [mediaworkerstate:/var/lib/media-worker]
+    depends_on:
+      redis: { condition: service_healthy }
+    restart: unless-stopped
+
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    command: ["tunnel", "--no-autoupdate", "run", "--token", "${CLOUDFLARE_TUNNEL_TOKEN:?}"]
+    restart: unless-stopped
+
+volumes:
+  pgdata:
+  redisdata:
+  mediaworkerstate:
diff --git a/infra/occupymedia/docker-compose.chat.yml b/infra/occupymedia/docker-compose.chat.yml
new file mode 100644
index 0000000..c3fa605
--- /dev/null
+++ b/infra/occupymedia/docker-compose.chat.yml
@@ -0,0 +1,36 @@
+# occupymedia.cc — CHAT CT (occ-chat, CT 152, tailscale 100.117.210.52)
+# Matrix plane: conduwuit (+ optional Telegram bridge, one-time interactive login).
+
+name: occ-chat
+
+services:
+  conduwuit:
+    image: girlbossceo/conduwuit:latest
+    environment:
+      CONDUWUIT_SERVER_NAME: chat.occupymedia.cc
+      CONDUWUIT_ADDRESS: 0.0.0.0
+      CONDUWUIT_PORT: "6167"
+      CONDUWUIT_DATABASE_PATH: /var/lib/conduwuit
+      CONDUWUIT_DATABASE_BACKEND: rocksdb
+      CONDUWUIT_MAX_REQUEST_SIZE: "20000000"
+      CONDUWUIT_ALLOW_REGISTRATION: "true"
+      CONDUWUIT_REGISTRATION_TOKEN: "${MATRIX_REGISTRATION_TOKEN:?}"
+      CONDUWUIT_ALLOW_FEDERATION: "true"
+      CONDUWUIT_ALLOW_ROOM_CREATION: "true"
+    volumes:
+      - conduwuit_data:/var/lib/conduwuit
+    ports:
+      - "6167:6167"   # tunnel: chat.occupymedia.cc → 100.117.210.52:6167
+    restart: unless-stopped
+
+  # First run is interactive: docker compose run --rm mautrix-telegram
+  mautrix-telegram:
+    image: dock.mau.dev/mautrix/telegram:latest
+    volumes: [mautrix_telegram_data:/data]
+    depends_on: [conduwuit]
+    profiles: ["bridges"]
+    restart: unless-stopped
+
+volumes:
+  conduwuit_data:
+  mautrix_telegram_data:
diff --git a/infra/occupymedia/docker-compose.tube.yml b/infra/occupymedia/docker-compose.tube.yml
new file mode 100644
index 0000000..40d6105
--- /dev/null
+++ b/infra/occupymedia/docker-compose.tube.yml
@@ -0,0 +1,52 @@
+# occupymedia.cc — TUBE CT (occ-tube, CT 151, tailscale 100.92.231.98)
+# PeerTube plane: peertube + dedicated postgres + redis + postfix relay.
+# Day 1: local storage on the CT volume (500G thin). Flip to R2 by setting
+# PEERTUBE_OBJECT_STORAGE_ENABLED=true + keys in peertube.env, then recreate.
+
+name: occ-tube
+
+services:
+  peertube-postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: peertube
+      POSTGRES_PASSWORD: ${PEERTUBE_DB_PASSWORD:?}
+      POSTGRES_DB: peertube
+    volumes: [peertube_pgdata:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U peertube"]
+      interval: 5s
+      retries: 10
+    restart: unless-stopped
+
+  peertube-redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+
+  postfix:
+    image: mwader/postfix-relay
+    environment:
+      - POSTFIX_myhostname=tube.occupymedia.cc
+    restart: unless-stopped
+
+  peertube:
+    image: chocobozzz/peertube:production-bookworm
+    env_file: peertube.env
+    ports:
+      - "9000:9000"   # tunnel: tube.occupymedia.cc → 100.92.231.98:9000
+      - "1935:1935"   # RTMP ingest from media-worker (cross-CT via tailscale)
+    volumes:
+      - peertube_config:/app/config
+      - peertube_assets:/app/storage/client-overrides
+      - peertube_data:/app/storage
+    depends_on:
+      peertube-postgres: { condition: service_healthy }
+      peertube-redis: { condition: service_started }
+      postfix: { condition: service_started }
+    restart: unless-stopped
+
+volumes:
+  peertube_pgdata:
+  peertube_config:
+  peertube_assets:
+  peertube_data:
diff --git a/infra/occupymedia/docker-compose.yml b/infra/occupymedia/docker-compose.yml
new file mode 100644
index 0000000..acf68d3
--- /dev/null
+++ b/infra/occupymedia/docker-compose.yml
@@ -0,0 +1,185 @@
+# Production deployment — occupymedia.cc
+# One box, everything behind the Cloudflare tunnel (no inbound ports).
+# See DEPLOY.md. Ports bind to 127.0.0.1 ONLY — the tunnel reaches them on localhost.
+
+name: occupymedia
+
+services:
+  # ---------- core ----------
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER:-occupymedia}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set in .env}
+      POSTGRES_DB: ${POSTGRES_DB:-occupymedia}
+    volumes: [pgdata:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-occupymedia}"]
+      interval: 5s
+      retries: 10
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    command: ["redis-server", "--appendonly", "yes"]
+    volumes: [redisdata:/data]
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      retries: 10
+    restart: unless-stopped
+
+  temporal:
+    image: temporalio/auto-setup:1.24
+    depends_on:
+      postgres: { condition: service_healthy }
+    environment:
+      DB: postgres12
+      DB_PORT: 5432
+      POSTGRES_USER: ${POSTGRES_USER:-occupymedia}
+      POSTGRES_PWD: ${POSTGRES_PASSWORD:?}
+      POSTGRES_SEEDS: postgres
+    restart: unless-stopped
+
+  # ---------- app (built from the repo; see Dockerfile) ----------
+  api:
+    build:
+      context: ../..
+      dockerfile: infra/occupymedia/Dockerfile
+      args: { APP: api }
+    environment: &appenv
+      PORT: "3000"
+      DATABASE_URL: postgres://${POSTGRES_USER:-occupymedia}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB:-occupymedia}
+      REDIS_HOST: redis
+      TEMPORAL_HOST: temporal:7233
+      S3_ENDPOINT: https://${CLOUDFLARE_ACCOUNT_ID}.r2.cloudflarestorage.com
+      S3_REGION: auto
+      S3_ACCESS_KEY: ${R2_ACCESS_KEY:?}
+      S3_SECRET_KEY: ${R2_SECRET_KEY:?}
+      S3_BUCKET: occupymedia-media-encrypted
+      S3_KEK: ${S3_KEK:?generate once, never rotate casually — it wraps every stored blob}
+      WEB_ORIGIN: https://app.occupymedia.cc
+      API_PUBLIC_URL: https://api.occupymedia.cc
+    ports: ["127.0.0.1:3000:3000"]
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+    restart: unless-stopped
+
+  scheduler:
+    build:
+      context: ../..
+      dockerfile: infra/occupymedia/Dockerfile
+      args: { APP: scheduler }
+    environment:
+      <<: *appenv
+      PORT: "3010"
+    depends_on:
+      postgres: { condition: service_healthy }
+      redis: { condition: service_healthy }
+      temporal: { condition: service_started }
+    restart: unless-stopped
+
+  web:
+    build:
+      context: ../..
+      dockerfile: infra/occupymedia/Dockerfile
+      args:
+        APP: web
+        NEXT_PUBLIC_API_URL: https://api.occupymedia.cc
+    environment:
+      <<: *appenv
+      PORT: "3001"
+    ports: ["127.0.0.1:3001:3001"]
+    depends_on: [api]
+    restart: unless-stopped
+
+  media-worker:
+    build:
+      context: ../..
+      dockerfile: infra/media-worker.Dockerfile
+    environment:
+      <<: *appenv
+      PORT: "3100"
+      MEDIA_WORKER_ID: worker-1
+      MEDIA_FENCE_PATH: /var/lib/media-worker/fence.json
+      POSTGRES_HOST: postgres
+      REDIS_HOST: redis
+      PEERTUBE_PUSH_URL: rtmp://peertube:1935/live   # internal; live ingest only
+    volumes: [mediaworkerstate:/var/lib/media-worker]
+    depends_on:
+      redis: { condition: service_healthy }
+    restart: unless-stopped
+
+  # ---------- front door ----------
+  cloudflared:
+    image: cloudflare/cloudflared:latest
+    command: ["tunnel", "--no-autoupdate", "run"]
+    environment:
+      TUNNEL_TOKEN: ${CLOUDFLARE_TUNNEL_TOKEN:?}
+    depends_on: [api, web, peertube, conduwuit]
+    restart: unless-stopped
+
+  # ---------- video plane ----------
+  peertube:
+    image: chocobozzz/peertube:production-bookworm
+    env_file: peertube.env
+    ports: ["127.0.0.1:9000:9000"]
+    volumes:
+      - peertube_config:/app/config
+      - peertube_assets:/app/storage/client-overrides
+    depends_on:
+      peertube-postgres: { condition: service_healthy }
+      peertube-redis: { condition: service_started }
+      postfix: { condition: service_started }
+    restart: unless-stopped
+
+  peertube-postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: peertube
+      POSTGRES_PASSWORD: ${PEERTUBE_DB_PASSWORD:?set in peertube.env}
+      POSTGRES_DB: peertube
+    volumes: [peertube_pgdata:/var/lib/postgresql/data]
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U peertube"]
+      interval: 5s
+      retries: 10
+    restart: unless-stopped
+
+  peertube-redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+
+  postfix:
+    image: mwader/postfix-relay
+    environment:
+      - POSTFIX_myhostname=tube.occupymedia.cc
+    restart: unless-stopped
+
+  # ---------- chat plane ----------
+  conduwuit:
+    image: girlbossceo/conduwuit:latest
+    volumes:
+      - conduwuit_data:/var/lib/conduwuit
+      - ./conduwuit.toml:/etc/conduwuit/conduwuit.toml:ro
+    ports: ["127.0.0.1:8448:6167"]
+    restart: unless-stopped
+
+  # Telegram bridge — first run is interactive: docker compose run --rm mautrix-telegram
+  mautrix-telegram:
+    image: dock.mau.dev/mautrix/telegram:latest
+    volumes: [mautrix_telegram_data:/data]
+    depends_on: [conduwuit]
+    profiles: ["bridges"]
+    restart: unless-stopped
+
+volumes:
+  pgdata:
+  redisdata:
+  mediaworkerstate:
+  peertube_pgdata:
+  peertube_config:
+  peertube_assets:
+  conduwuit_data:
+  mautrix_telegram_data:
diff --git a/infra/occupymedia/peertube.env b/infra/occupymedia/peertube.env
new file mode 100644
index 0000000..aeffe9b
--- /dev/null
+++ b/infra/occupymedia/peertube.env
@@ -0,0 +1,42 @@
+# PeerTube production config — occupymedia.cc (used as env_file by docker-compose.yml)
+# Image: chocobozzz/peertube:production-bookworm. Pin to a version tag at first deploy.
+
+PEERTUBE_WEBSERVER_HOSTNAME=tube.occupymedia.cc
+PEERTUBE_WEBSERVER_PORT=443
+PEERTUBE_WEBSERVER_HTTPS=true
+PEERTUBE_TRUST_PROXY=true
+
+# First boot: the entrypoint generates the admin user with a random password,
+# printed once in the logs: `docker compose logs peertube | grep -A2 'user root'`.
+# Change it immediately, then enable the Tactical Media Broadcast Hub connector bridge.
+
+# --- database (dedicated peertube-postgres service) ---
+PEERTUBE_DB_HOSTNAME=peertube-postgres
+PEERTUBE_DB_USERNAME=peertube
+PEERTUBE_DB_PASSWORD=<set-same-as-below>
+POSTGRES_USER=peertube
+POSTGRES_PASSWORD=<set-same-as-above>
+POSTGRES_DB=peertube
+
+# --- object storage on R2 (zero egress) ---
+PEERTUBE_OBJECT_STORAGE_ENABLED=true
+PEERTUBE_OBJECT_STORAGE_ENDPOINT=https://e50adafec3c6aee02a328f28b967f699.r2.cloudflarestorage.com
+PEERTUBE_OBJECT_STORAGE_REGION=auto
+PEERTUBE_OBJECT_STORAGE_UPLOAD_ACL_PUBLIC_BUCKET=occupymedia-peertube-videos
+PEERTUBE_OBJECT_STORAGE_UPLOAD_ACL_PRIVATE_BUCKET=occupymedia-peertube-playlists
+PEERTUBE_OBJECT_STORAGE_CREDENTIALS_ACCESS_KEY=<R2_ACCESS_KEY>
+PEERTUBE_OBJECT_STORAGE_CREDENTIALS_SECRET_KEY=<R2_SECRET_KEY>
+# Videos are served through tube.occupymedia.cc (Cloudflare caches HLS segments);
+# keep proxied URL mode so playback keys stay server-controlled.
+PEERTUBE_OBJECT_STORAGE_PROXY=PRIVACY
+
+# --- email via the postfix relay ---
+PEERTUBE_SMTP_HOSTNAME=postfix
+PEERTUBE_SMTP_PORT=25
+PEERTUBE_SMTP_FROM=noreply@tube.occupymedia.cc
+PEERTUBE_SMTP_TLS=false
+
+# --- live (RTMP ingest from media-worker over the internal docker network) ---
+PEERTUBE_RTMP_PORT=1935
+PEERTUBE_LIVE_ENABLED=true
+PEERTUBE_LIVE_TRANSCODING_ENABLED=true
diff --git a/infra/otel/otel-collector-config.yaml b/infra/otel/otel-collector-config.yaml
new file mode 100644
index 0000000..2704479
--- /dev/null
+++ b/infra/otel/otel-collector-config.yaml
@@ -0,0 +1,21 @@
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+
+exporters:
+  debug:
+    verbosity: basic
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug]
diff --git a/infra/peertube-workers/.gitignore b/infra/peertube-workers/.gitignore
new file mode 100644
index 0000000..f61baa1
--- /dev/null
+++ b/infra/peertube-workers/.gitignore
@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+runtime/
+state/
+*.toml
+*.env
diff --git a/infra/peertube-workers/README.md b/infra/peertube-workers/README.md
new file mode 100644
index 0000000..9a32dd4
--- /dev/null
+++ b/infra/peertube-workers/README.md
@@ -0,0 +1,89 @@
+This directory prepares Intel QSV workers for the inspected PeerTube **7.3.0** instance. It uses the published **@peertube/peertube-runner 0.2.0**, pinned with npm integrity hashes. PeerTube owns the queue; the controller admits or drains a whole runner. No PeerTube fork, scheduler, public worker listener, live delegation, or viewer-serving component is introduced.
+
+
+**Recommended next step:** use native Linux with a working Intel DRM render device, then rerun the real QSV self-test before enrolling. A Windows-native alternative requires a separate adapter and supervisor: [FFmpeg documents](https://www.ffmpeg.org/ffmpeg-all.html#MediaFoundation) `h264_mf -hw_encoding 1` to force Media Foundation hardware encoding, with a verified D3D11 decode/scale path and Windows power/GPU telemetry. The existing Linux QSV wrapper and systemd service cannot be reused unchanged. No Windows hardware encode has been tested. [WSL's Mesa D3D12 VAAPI path](https://devblogs.microsoft.com/commandline/d3d12-gpu-video-acceleration-in-the-windows-subsystem-for-linux-now-available/) is a different implementation from this libmfx/Intel DRM QSV path and was not deployed. Windows also reports an RTX 3090, but that is not a validated NVIDIA worker.
+
+The actual 7.3.0 VOD key is `transcoding.remote_runners.enabled` (not `vod_enabled`). The override is `/config/production.yaml` in the effective Docker config volume. Only PeerTube was restarted; remote live/studio/transcription remain disabled. The actual deployed database/table are `peertube` / `runnerRegistrationToken`. The existing registration token was checked privately using the installed validator and an exact database lookup; no new token or runner was created. A successful registration handshake and real VOD E2E remain untested because the hardware gate failed.
+
+The installed runner source was compared to the v7.3.0 tag: `apps/peertube-runner/src/server/process/shared/common.ts` has SHA256 `d28fe0f4db9ca46edaeac2f12c269f0fad52fd5cf92d9ba90d529c4a1d7c3627` in both. The [7.3.0 CLI docs](https://github.com/Chocobozzz/PeerTube/blob/v7.3.0/support/doc/tools.md#peertube-runner) require Node >=20 and FFmpeg/ffprobe >=4.3. This installer uses isolated Node 22 and refuses other PeerTube releases until their source is checked. The current latest Node 22 tarball is downloaded over HTTPS, verified against Node's SHA256 manifest, and retained on reruns. The runner version stays pinned.
+
+| Runner behavior verified in 7.3.0 source | Consequence |
+| --- | --- |
+| `register` uses a local Unix IPC socket; the server must already be running | Enrollment starts a VOD-only server with concurrency **0**, then uses the official IPC library |
+| Socket.IO `/runners`, websocket-only transport, `available-jobs` notifications | Workers initiate API and WS connections; no inbound listener is needed |
+| Requests up to ten pending jobs; accepts the first supported job; checks again on connect, notifications, completion, and after 2.5 seconds when there is spare capacity | Queue selection, acceptance, and concurrency remain with the official runner |
+| Request payload includes input URLs and requested resolution/fps, but **no input size or duration** | Whole-worker admission; no per-job byte prediction |
+| Downloads use POST carrying runner/job tokens, then transcode and POST multipart results | Workers have only their dedicated runner credential after enrollment |
+| VOD handlers remove inputs/results in `finally`; startup removes leftover transcode files | Output cleanup is upstream behavior; smoke test verifies it |
+| Progress update every 60 seconds; VOD stale threshold 2 minutes; `MAX_FAILURES=5` | Server requeues eligible failures until its limit; controller does not implement retries |
+| SIGTERM/SIGINT abort active jobs; `graceful-shutdown` stops acceptance and waits for completion | All ordinary controller drains use the official graceful command |
+| Download timeout is 2 hours; there is no independent periodic idle polling timer | A network drain can remain pending while an upstream transfer times out; reconnection triggers a queue check |
+
+Remote profile plugins are not an integration option in this release: `getCommonFFmpegOptions()` sets `profile: 'default'` and the default video encoder list contains only `libx264`. Installing a server profile plugin would not reach this runner. No maintained remote QSV plugin was established during the investigation. The implementation therefore uses preference **(4), a minimal worker wrapper**, rather than patching the runner or PeerTube.
+
+`FFMPEG_PATH=ffmpeg-qsv.py` redirects commands generated by the runner. For video it replaces the inspected default x264 options with explicit QSV decode, QSV hardware frames, `scale_qsv`, and `h264_qsv`. It keeps PeerTube's muxing, HLS segmenting, fps, GOP, and rate caps. H.264/HEVC/VP9/AV1 source paths use explicit QSV decoders. Unsupported pixel formats, source codecs, rotation, unknown filters, and unknown encoder commands fail closed. Static cover images for audio-merge jobs require image decode and one upload of frames; their scaling and video encoding use QSV. Audio-only renditions can use the upstream AAC encoder. No video CPU fallback exists. Capability queries are passed through to FFmpeg.
+
+The self-test runs real H.264 decode -> GPU scale -> H.264/HEVC encode, HEVC decode when encoding succeeded, and separate AV1 decode/encode attempts. It records cumulative Intel DRM media-engine counters from FFmpeg's `/proc/PID/fdinfo`, output ffprobe results, temperatures, and memory. A successful exit alone is insufficient: H.264 must also have positive media-engine counters. Missing counters or permissions block enrollment. AV1 encode is expected to fail on an i5-1240P; this expectation does not substitute for inspecting the actual CPU/GPU. See [Intel's driver features](https://github.com/intel/media-driver#decodingencoding-features) and [FFmpeg QSV filters](https://www.ffmpeg.org/ffmpeg-filters.html#QSV-Video-Filters). HEVC is a self-test/investigation output only; production remains H.264.
+
+`observe.cjs` measures real response/request byte counts and elapsed transfer times without recording bodies, headers, credentials, or URLs. It correlates downloaded temporary files and encode events with job UUIDs, including concurrent jobs. Input payloads use the public canonical origin; just that origin is mapped to the configured Tailscale API address. Other storage origins retain HTTPS and normal redirects. The route preserves API paths and authentication. Interrupted response streams explicitly destroy the request so upstream download promises reject instead of waiting indefinitely. HTTP on `TAILSCALE_IP:9000` travels inside encrypted Tailscale; public viewer URLs remain untouched. Safe runner milestones are retained; arbitrary upstream logs are suppressed because they can contain tokens.
+
+`pt-worker.py` exposes JSON status and optional Prometheus text. State is updated roughly every five seconds plus probe/IPC/API time. Admission states are `AVAILABLE`, `BUSY`, `DRAINING`, `NETWORK_DEGRADED`, `GPU_UNAVAILABLE`, `LOW_DISK`, `THERMAL_THROTTLED`, `OFFLINE`, and `PAUSED`. Degraded states request a graceful drain. Already accepted work finishes. Detection and graceful IPC have a bounded polling race; a hardware failure nevertheless cannot select a CPU encoder.
+
+Real transfer observations use EWMA alpha 0.3. Defaults: 10 Mbps download/upload floor, recovery at 1.25 times those floors, 3 good samples to reopen, 2 bad samples to degrade, 150 ms maximum latency, 60 seconds after a transfer failure, 15-minute measurement expiry, DERP disallowed, 20 GiB free disk, and an 85 C thermal ceiling with 120-second cooldown. DIRECT/DERP transitions and suspend gaps invalidate throughput history. Floors are initial policy values, **not measured laptop capacity**. Tune them after real jobs.
+
+The optional server probe prevents stale bandwidth from permanently blocking an idle or rebooted worker. It is already installed on `TAILSCALE_IP:9044`, binds only that Tailscale IP, discards uploads, caps each transfer at 16 MiB, permits two concurrent transfers, applies per-client/per-direction rate limits, and runs without media, Docker, DB, Redis, or filesystem write access. Ordinary checks transfer 8 MiB each way after an idle runner drains, no more often than every five minutes. Real job observations remain the preferred measurements. The probe measures the worker-to-PeerTube path, not a future external object-storage path; object-storage transfers need separate successful job observations.
+
+On AC loss or unknown laptop power state, admission drains. Native machines with no battery are treated as permanently powered. Battery capacity/status, thermal sensors, CPU throttle counters, memory, load, disk, and kernel type are included when visible; unsupported measurements are null. There is no forced suspend, reboot, perf-policy change, or firmware change. The controller reruns its hardware test after a changed boot ID. Manual pause survives reboot. With the probe and healthy hardware it can recover network admission unattended.
+
+**Shortest additional-worker procedure, once a hardware worker passes validation:** join Tailscale; provide a native Debian 12 / Ubuntu 24.04+ Linux environment with Intel `/dev/dri/renderD128`, systemd, and adequate disk; copy this directory to the worker; use an owner-authorized registration token (the existing token is authorized for this deployment); then run:
+
+```bash
+sudo ./install-peertube-worker.sh --name WORKER2 --peertube-url http://TAILSCALE_IP:9000
+# The registration token is read at a hidden prompt, never as a CLI argument.
+sudo pt-worker start
+sudo pt-worker status
+```
+
+The installer derives this instance's canonical origin from a fallback asset in `/api/v1/config`. For other branding or instances supply `--canonical-origin https://INSTANCE` and `--tailscale-peer TAILSCALE_IP`; deploy the probe at that IP or adjust `probe_url`. For noninteractive enrollment use a private file/pipe FD, e.g. `sudo -i`, then `exec 3</root/runner-registration-token` followed by the installer with `--registration-token-fd 3`; revoke/delete the temporary enrollment secret after confirming registration. Do not put tokens in argv, shell history, environment files, git, or reports.
+
+The installer inspects hardware, systemd, Tailscale, and server release before installing packages. It chooses Intel's full-feature media driver when available in existing package sources, otherwise the free driver and relies on actual tests. It does not alter repositories or kernel settings. Dependencies include FFmpeg, VAAPI tools, Intel GPU tools, Python >=3.11, and Node >=22. Service user `pt-worker` receives the actual render-device group and existing render/video groups; no `chmod 777`. Code and settings are root-owned; registration TOML and runtime state are worker-owned and private. The worker service is enabled at boot and initially paused. Uncertain enrollment outcomes leave a marker and refuse automatic re-registration, preventing duplicate runners; inspect/revoke the named server runner before resolving that marker. Normal reruns preserve credentials, settings, and concurrency and back up existing installation/configuration before replacement.
+
+| Command (run with sudo) | Behavior |
+| --- | --- |
+| `pt-worker status` | JSON; unknown fields are null, stale controller state is OFFLINE |
+| `pt-worker status --prometheus` | Numeric metrics without inventing absent measurements |
+| `pt-worker start` | Starts the supervisor and opens admission when checks pass |
+| `pt-worker start --calibrate` | Explicit ten-minute initial real-job measurement window if the probe is unavailable; still enforces GPU, AC, disk, latency, and direct path |
+| `pt-worker stop` / `drain` | Persists PAUSED; gracefully finishes accepted work; supervisor stays alive for status |
+| `pt-worker restart` | Graceful child restart; preserves the runner registration |
+| `pt-worker self-test` | Refuses while a runner is running; renews hardware proof after drain |
+| `pt-worker network-test` | Real bounded probe download/upload, or explicit disposable `--download-url` / `--upload-url` endpoints |
+| `pt-worker benchmark --source /path/source.mp4` | After drain, local QSV 720p diagnostic batches at 1/2/3/4, FPS/RTF/wall time/RAM/temperature/CPU/media utilization/throttle observations; does not choose production concurrency |
+
+Native systemd uses `Restart=always`, 30-second restart delay, start throttling, an unprivileged account, read-only system/home protection, and no capabilities. `KillMode=mixed` gives the supervisor the initial stop signal so it can drain the official runner. Stop timeout is infinite to preserve accepted work; forced operator kills/crashes rely on upstream abort/watchdog behavior. GPU and memory metrics are observational and never justify a CPU fallback.
+
+WSL must be inspected before using this installer. The visible Windows Tailscale peer does not identify the SSH shell or WSL kernel. Check Windows `wsl.exe --list --verbose`, then inside the intended distro check `uname -a`, `/proc/1/comm`, `/etc/wsl.conf`, `/dev/dri`, `/dev/dxg`, `lscpu`, `lspci`, `vainfo`, FFmpeg, and driver capabilities. [Microsoft documents enabling systemd](https://learn.microsoft.com/en-us/windows/wsl/systemd) with `[boot] systemd=true`; applying it requires a distro restart. That alone does not prove Intel Linux DRM/QSV support. `/dev/dxg` alone cannot satisfy this adapter. If the laptop exposes only the Windows GPU path, use native Linux or separately implement and validate a Windows QSV/oneVPL/D3D adapter and Windows service/power/telemetry. None of these host changes have been made.
+
+**Production validation still required, after resolving the hardware blocker:** VOD remote delegation is already enabled; preserve existing resolutions and viewer configuration and keep live/studio/transcription remote flags disabled. Install/register the first proven hardware worker with the authorized existing token, and open admission at concurrency 2. Upload a disposable private synthetic A/V clip through an existing admin/user channel. Capture the real runner job UUIDs and Pending -> Processing -> Completing -> Completed, source/output probes, QSV engine counters, encode and accept-to-success wall times, actual download/upload observations, imported HLS/renditions, playback, A/V sync, and temporary cleanup. Repeat equivalent batches at concurrency 1/2/3/4 after draining and changing **both** worker.json and runner TOML; choose by completed media seconds per end-to-end wall time, with thermal and network headroom. The local benchmark cannot make that decision.
+
+Failure validation on the worker, after the normal VOD test: drain/restart and verify no new registration; interrupt only the worker's Tailscale path under a recoverable admin connection and verify drain/recovery/server retries; configure an inaccessible test render path and ensure no CPU output; constrain a disposable probe path and verify low-bandwidth hysteresis; disconnect AC and observe drain; finally reboot the worker and verify service/Tailscale/hardware proof/network admission/registration recovery. Do not interrupt or reboot the production PeerTube host for these tests.
+
+Suggested Tailscale policy: put worker devices in `tag:pt-worker`, server in `tag:pt-server`; allow worker -> server TCP 9000 and 9044 only for this deployment; authorize admin -> worker SSH separately; deny worker DB/Redis access and inbound worker connections except explicitly authorized administration. ACLs are centrally managed and were not changed here. Retain HTTPS egress to approved storage origins if object storage is later enabled. The server's existing TCP 1935/public/tunnel behavior was not changed. Live delegation later requires `live-rtmp-hls-transcoding`, worker-initiated access to the job's PeerTube RTMP input URL, sustained encode capacity and continuous HLS upload with measured upload headroom, low stable latency, a stricter direct-path policy, and separate failure/load validation. Workers do not serve viewers.
+
+NVIDIA readiness: admission consumes generic `gpu_ready`, `gpu_tested_at`, GPU device accessibility, and `gpu_failure` events; network, queue, AC, disk, thermal policy, and graceful IPC are independent of Intel. A future provider can supply `gpu_health_file` with `hardware_video_ok` and `tested_at`, and `gpu_device`. NVIDIA still needs a separately tested CUDA/NVDEC -> CUDA scale -> NVENC adapter, driver/container permissions, an NVENC hardware self-test, NVIDIA utilization/temperature collection, codec/session-limit validation, and an installer package set. The existing Intel installer and fdinfo collector do not configure NVIDIA.
+
+Tests are executable without a GPU or production token:
+
+```bash
+python3 -m unittest discover -s tests -v
+node tests/test_observer.cjs
+# Install the pinned runtime into a temporary directory and use Node 22:
+python3 tests/runner_smoke.py --node /path/node --runtime /path/runtime
+systemd-analyze verify systemd/*.service
+```
+
+The smoke test uses a loopback API and the published official runner. It proves enrollment at concurrency 0, secure IPC, persistence/restart, source routing, refusal/reporting without a GPU, graceful shutdown, and cleanup. It does **not** prove a production job, QSV acceleration, import/playback, laptop service/reboot behavior, or real laptop throughput. Keep private runtime evidence outside git. The worker jobs_completed counter counts acknowledged result submissions; server-side import success must still be verified centrally with the admin job API. Safe event logs currently need an operator retention policy; they are not automatically rotated. `@peertube/net-ipc@2.2.0` is deprecated on npm but matches the installed runner's IPC protocol; review this helper together with any runner upgrade.
+
+## Windows NVENC
+
+The Windows-native RTX 3090 worker, executable adapter, installer phases, admission policy, service elevation requirements, and onboarding steps are documented in [WINDOWS.md](WINDOWS.md). Use that runbook for Windows workers; the Linux QSV installer is unchanged.
diff --git a/infra/peertube-workers/WINDOWS.md b/infra/peertube-workers/WINDOWS.md
new file mode 100644
index 0000000..ddc2965
--- /dev/null
+++ b/infra/peertube-workers/WINDOWS.md
@@ -0,0 +1,190 @@
+# Windows native NVENC worker
+
+Use Windows 10/11 x64 with an NVIDIA GPU and a working driver. WSL is the SSH
+transport only: Node, FFmpeg, the shim, admission, and IPC all run as Windows
+processes. The initial worker name is `worker-laptop-win`; root is `C:\pt-worker`.
+The canonical instance is `https://tube.occupymedia.cc`; worker traffic uses
+`http://TAILSCALE_IP:9000` inside encrypted Tailscale. Viewers use PeerTube.
+No server configuration change is needed: remote VOD is already enabled.
+
+## Prepare and enroll
+
+Run the installer from this directory. Python 3.12+ and Windows Tailscale are
+build/access prerequisites. Python is embedded in the frozen executables, so
+services do not depend on the developer's Python installation. Pins are in
+[win/dependencies.json](win/dependencies.json); the FFmpeg URL is a dated archive,
+verified by SHA256. The two executables are built from reviewed Python source
+using the versions in `win/build-requirements.txt`. Runner and IPC dependencies
+use the existing runtime lockfile. Do not substitute a `.cmd` shim: Node's
+shell-free spawn rejects it with EINVAL.
+
+```powershell
+# Elevated PowerShell: installs Node MSI silently plus isolated Node 22.
+.\install-peertube-worker-windows.ps1 -Phase Prepare -Name WORKERNAME-win
+# A filtered SSH/WSL token can prepare everything except the MSI:
+.\install-peertube-worker-windows.ps1 -Phase Prepare -UserLevel -Name WORKERNAME-win
+.\install-peertube-worker-windows.ps1 -Phase SelfTest
+```
+
+Both H.264 and HEVC must produce a real 5-second 1080p encode **and positive
+NVIDIA encoder utilization**. GPU identity, UUID, driver, boot, device index,
+exit codes, samples, and session statistics are recorded in `state\nvenc.json`.
+No proof means no enrollment. The installer keeps admission PAUSED. A failed
+init, absent telemetry signal, reboot, or driver mismatch closes admission.
+Session-0 proof runs again when services are installed; enrollment-session
+success alone does not prove service-context access.
+
+Supply the **existing** registration token through stdin. Never pass it as a
+PowerShell/Node argument, environment variable, transcript, or source file.
+For SSH transport, pipe PostgreSQL's selected token output directly into the
+Windows Node `bin\ipc-nvenc.cjs register` process. The version-controlled
+`win/register-from-ssh.py --worker USER@HOST --name NAME` implements this using two subprocesses and pipe handles; it fetches
+`runnerRegistrationToken.registrationToken`, database `peertube`, using the
+PostgreSQL container's existing `POSTGRES_USER`. No token is printed or retained.
+Before doing so, run `bin\enroll-server.cjs`: it requires concurrency 0 and drops
+all upstream logs. After registration use `ipc-nvenc.cjs graceful-shutdown`, wait
+for the listener to exit, and set TOML concurrency to 2. Alternatively use:
+
+```powershell
+# The calling process must give this process the secret on inherited stdin.
+.\install-peertube-worker-windows.ps1 -Phase Enroll -RegistrationTokenStdin
+```
+
+The **registration secret** is never saved. The official runner necessarily
+saves its separate issued **runner credential** in
+`profile\Roaming\peertube-runner-nodejs\Config\default\config.toml`.
+NTFS ACLs restrict this tree to the owner, SYSTEM, administrators, and LocalService.
+Never print that TOML, arbitrary runner logs, database token columns, or HTTP
+headers. Enrollment pending markers prohibit blind duplicate registrations.
+
+## Services and operations
+
+```powershell
+# ServiceFiles prepares concrete WinSW XML/exe files without touching SCM.
+.\install-peertube-worker-windows.ps1 -Phase ServiceFiles
+# Elevated PowerShell; services initially PAUSED, session-0 proof first.
+.\install-peertube-worker-windows.ps1 -Phase Services
+C:\pt-worker\pt-worker-win.ps1 status
+C:\pt-worker\pt-worker-win.ps1 network-test
+C:\pt-worker\pt-worker-win.ps1 start
+C:\pt-worker\pt-worker-win.ps1 drain
+C:\pt-worker\pt-worker-win.ps1 restart
+C:\pt-worker\pt-worker-win.ps1 self-test
+```
+
+WinSW 2.12.0 wraps `pt-runner` (Node supervisor) and `pt-admission` (frozen Python).
+Both use the [WinSW 2.12 service-account and stop configuration](https://github.com/winsw/winsw/blob/v2.12.0/doc/xmlConfigFile.md), running as LocalService with automatic delayed startup, a 30-second service
+restart delay, and limited rotated logs. The supervisor uses a further 15-second
+runner restart delay. It retains only safe milestones and observer events;
+unfiltered upstream logs are discarded because they can contain tokens.
+A service stop asks the supervisor to drain via the official named-pipe IPC,
+with an explicit one-hour SCM stop ceiling. For jobs that can exceed this ceiling,
+use `pt-worker-win drain`, wait for `runner_running=false`, then stop services.
+No admission loss forcibly kills an active encode.
+
+State decisions use the Linux Meter/Admission semantics: AVAILABLE, BUSY,
+DRAINING, NETWORK_DEGRADED, GPU_UNAVAILABLE, LOW_DISK, THERMAL_THROTTLED, OFFLINE,
+PAUSED. Status preserves Linux field names (`status`, `disk_free_bytes`,
+`registration_state`, `last_job_duration_seconds`, `last_job_realtime_factor`,
+`util`, etc.) and adds `state`, NVENC capability flags, and fleet aliases. QSV
+flags remain false; a successful NVENC test is never reported as QSV success.
+The supervisor requires a fresh admission document (<30 seconds), an explicit
+unpaused control document, and no GPU-refusal marker. Missing/stale admission
+always triggers the official runner graceful-shutdown request.
+
+AC policy uses `GetSystemPowerStatus`: battery or unknown AC drains. Thermal
+zones are read through `root/wmi:MSAcpi_ThermalZoneTemperature` when supported;
+unavailable CPU sensors remain null. NVIDIA temperature remains a real reading.
+Defaults: 20 GiB disk reserve, 85 C thermal ceiling, 120 s thermal cooldown,
+10 Mbps each direction, 1.25x bandwidth recovery margin, three good/two bad
+samples, 900 s bandwidth expiry, no DERP admission. The existing Tailscale-only
+server probe (`TAILSCALE_IP:9044`) uses bounded 8 MiB GET download and PUT upload
+checks, EWMA, and runs while the runner is drained. GPU failure events remain
+latched until a later real self-test. Boot/driver changes trigger new proof.
+`powercfg /change standby-timeout-ac 0` is an elevated install step. The laptop
+must remain on AC; lid-close/Modern Standby behavior still needs owner review.
+
+## Adapter contract and tests
+
+The pinned runner requests `libx264`. The executable accepts only reviewed
+command shapes and rewrites them before executing FFmpeg: CUDA/NVDEC hardware
+frames -> `scale_cuda` -> `h264_nvenc`, preset p4, preserving bitrate cap/GOP.
+The original libx264 command is never executed. H.264, SDR HEVC, and VP9 sources
+have reviewed hardware-decode routes; rotated, HDR, unsupported pixel formats,
+unknown options, stream codec overrides, extra outputs, and unknown codecs fail
+closed with exit 78. Audio-only and explicit stream-copy/remux jobs are permitted
+without video encoding. Static audio-merge images use software image processing
+and `hwupload_cuda`; video encoding remains NVENC. AV1 input is refused until a
+reviewed decode route is tested; AV1 capability is not inferred from FFmpeg's
+encoder list. A local diagnostic can set `PT_NVENC_TARGET=hevc_nvenc`; any other target is refused. Never change the PeerTube service target without a reviewed codec contract. HEVC encoding is proven by the gate but the PeerTube default output
+remains H.264, matching the pinned runner/server contract.
+
+```bash
+python3 -m unittest discover -s infra/peertube-workers/win/tests -p test_nvenc.py -v
+```
+
+A running encode that fails, or lasts >=3 seconds without a readable positive
+encoder signal, returns failure and latches GPU_UNAVAILABLE. Very short encodes
+may finish within NVIDIA's utilization averaging window; their explicit NVENC
+encoder and current boot/driver proof remain required. For a real E2E test record
+positive encode telemetry, job UUID, server Pending/Processing/Completed states,
+input/output codec and resolution, wall time, RTF, and playable result. Local
+synthetic success is not a PeerTube E2E result.
+
+Failure checks: drain -> runner gracefully exits; start/restart -> reconnect
+milestone; create `state\gpu-unavailable` -> admission GPU_UNAVAILABLE and shim
+exit 78; remove marker, drain, rerun self-test, then start. Do not unload the
+owner's desktop GPU driver to simulate failure. Test reboot recovery and AC loss
+only after services and the owner's physical AC/lid policy can be exercised.
+
+## Deployment-specific elevation blocker / worker 2
+
+The verified route is SSH into WSL using `~/.ssh/devserver`, then native
+PowerShell/Node through `/mnt/c`. Interop works. The Windows token is medium
+integrity with administrators marked deny-only. `sc create` fails with
+OpenSCManager error 5; registering a Highest scheduled task returns access denied.
+Enabling alternate-port Windows sshd needs the same unavailable elevation and
+would not remove this blocker. No existing recovery task, UAC policy, driver, or
+server setting was changed to bypass it. The owner must run the prepared Services
+phase in an elevated Windows PowerShell. An interactive native process deployment
+can be validated over the working route but is not a boot-persistent service.
+
+Worker 2 changes only name, root (if wanted), GPU device index, and local network
+access. Reuse this server probe and existing authorized token; give each worker a
+unique runner name and isolated profile. Do not copy worker 1's credential TOML.
+Require a fresh real hardware gate on that GPU and service context. Start with
+concurrency 2; benchmark equivalent real workloads at 1–4 before increasing it.
+The RTX 3090's stock session ceiling is not a two-job constraint; no driver patch
+is deployed. Its measured limit is 350 W; an optional 200–250 W cap needs driver
+support and throughput/thermal measurement before adopting it. No power limit or
+driver was changed during deployment. Hardware throughput/session/codec claims
+from research remain estimates until measured on the specific worker.
+
+## Authorized E2E fixture
+
+`win/e2e-peertube.mjs` is an explicit, privileged server test, never an installer
+autostart step. Run it only for an authorized private upload, with other workers
+drained if a specific worker must own the job. Supply a synthetic H.264 file as
+`/tmp/pt-worker-e2e-source.mp4` inside the PeerTube container, then run the script
+there through Node stdin with `NODE_DB_LOG=false` and `LOGGER_LEVEL=error`. It
+requires the inspected PeerTube 7.3.0 model layout. It registers the installed
+models without the initializer's SQL function/extension mutations, creates one
+10-minute admin OAuth session through the installed token model, performs one
+private upload through the HTTP API, records safe state metadata, checks private
+HLS/media HTTP responses and full decoding, then revokes/removes that session.
+It does not change the root password or runner registration token. Credentials
+remain in process memory and the temporary normal OAuth database row; they never
+appear in command arguments, report JSON, or source. Upstream ORM logging is
+disabled before the token is created. The private test video remains available
+for owner review; delete disposable server/container scratch files afterward.
+
+First upload with the target worker drained to capture Pending, then start the
+worker while the helper polls. Report JSON goes to `/tmp/pt-worker-e2e-result.json`
+inside the container; it contains no credentials. This host's successful private
+fixture is [Windows NVENC worker E2E](https://tube.occupymedia.cc/w/7d3EHVeikq3JZ29XqjKJyd),
+video UUID `324566b4-3506-417d-9cca-cc2a3b7a14cc`. Jobs 1/2 completed on runner 1.
+The cold WebVideo encode took 36.359 s with positive 100% NVIDIA encoder samples;
+its warm HLS encode took 2.594 s. These are observed 5-second-fixture timings,
+not a concurrency benchmark. The short HLS run sampled 0% in NVIDIA's averaging
+window; its command was still explicitly NVENC, and the WebVideo job supplies
+mandatory job-correlated GPU proof. Root OAuth sessions were verified back at 0.
diff --git a/infra/peertube-workers/bandwidth-probe.py b/infra/peertube-workers/bandwidth-probe.py
new file mode 100644
index 0000000..351a3d8
--- /dev/null
+++ b/infra/peertube-workers/bandwidth-probe.py
@@ -0,0 +1,135 @@
+#!/usr/bin/python3
+"""Bounded disposable transfer endpoint, bound ONLY to the PeerTube Tailscale IP."""
+import argparse
+import http.server
+import ipaddress
+import json
+import os
+import socket
+import threading
+import time
+import urllib.parse
+
+MAX_BYTES = 16 * 1024**2
+CHUNK = bytes(range(256)) * 4096
+SLOTS = threading.BoundedSemaphore(2)
+LOCK = threading.Lock()
+RECENT = {}
+
+
+class Probe(http.server.BaseHTTPRequestHandler):
+    protocol_version = 'HTTP/1.1'
+
+    def setup(self):
+        super().setup()
+        self.connection.settimeout(30)
+
+    def log_message(self, *_):
+        pass
+
+    def reply(self, code, data):
+        blob = json.dumps(data).encode()
+        self.send_response(code)
+        self.send_header('Content-Type', 'application/json')
+        self.send_header('Content-Length', str(len(blob)))
+        self.send_header('Cache-Control', 'no-store')
+        self.end_headers()
+        self.wfile.write(blob)
+
+    def admission(self, direction):
+        address = ipaddress.ip_address(self.client_address[0])
+        if address not in ipaddress.ip_network('100.64.0.0/10') and not address.is_loopback:
+            self.reply(403, {'error': 'Tailscale clients only'})
+            return False
+        with LOCK:
+            now = time.monotonic()
+            for key in list(RECENT):
+                if now - RECENT[key] > 60:
+                    RECENT.pop(key)
+            key = (str(address), direction)
+            if now - RECENT.get(key, -60) < 10:
+                self.reply(429, {'error': 'probe rate limit'})
+                return False
+            RECENT[key] = now
+        if not SLOTS.acquire(blocking=False):
+            self.reply(503, {'error': 'probe busy'})
+            return False
+        return True
+
+    def do_GET(self):
+        parsed = urllib.parse.urlsplit(self.path)
+        if parsed.path == '/health':
+            return self.reply(200, {'ok': True, 'max_bytes': MAX_BYTES, 'storage': 'discarded'})
+        if parsed.path != '/download':
+            return self.reply(404, {'error': 'unknown endpoint'})
+        try:
+            count = int(urllib.parse.parse_qs(parsed.query).get('bytes', [8 * 1024**2])[0])
+            if not 65536 <= count <= MAX_BYTES:
+                raise ValueError()
+        except ValueError:
+            return self.reply(400, {'error': 'invalid size'})
+        if not self.admission('download'):
+            return
+        try:
+            self.send_response(200)
+            self.send_header('Content-Length', str(count))
+            self.send_header('Content-Type', 'application/octet-stream')
+            self.send_header('Cache-Control', 'no-store')
+            self.end_headers()
+            while count:
+                block = CHUNK[:min(count, len(CHUNK))]
+                self.wfile.write(block)
+                count -= len(block)
+        except (OSError, socket.timeout):
+            self.close_connection = True
+        finally:
+            SLOTS.release()
+
+    def do_PUT(self):
+        if self.path != '/upload':
+            self.close_connection = True
+            return self.reply(404, {'error': 'unknown endpoint'})
+        try:
+            count = int(self.headers.get('Content-Length', '0'))
+            if not 65536 <= count <= MAX_BYTES:
+                raise ValueError()
+        except ValueError:
+            self.close_connection = True
+            return self.reply(413, {'error': 'invalid size'})
+        if not self.admission('upload'):
+            self.close_connection = True
+            return
+        received = 0
+        try:
+            while received < count:
+                data = self.rfile.read(min(1024**2, count - received))
+                if not data:
+                    raise OSError('short upload')
+                received += len(data)
+            self.reply(200, {'bytes_received': received})
+        except (OSError, socket.timeout):
+            self.close_connection = True
+        finally:
+            SLOTS.release()
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--bind', required=True)
+    parser.add_argument('--port', type=int, default=9044)
+    args = parser.parse_args()
+    address = ipaddress.ip_address(args.bind)
+    if address not in ipaddress.ip_network('100.64.0.0/10') and not address.is_loopback:
+        raise SystemExit('Refusing a public/LAN/wildcard bind: require a Tailscale IP')
+    server = http.server.ThreadingHTTPServer((args.bind, args.port), Probe)
+    notify = os.environ.get('NOTIFY_SOCKET')
+    if notify:
+        address = '\0' + notify[1:] if notify.startswith('@') else notify
+        with socket.socket(socket.AF_UNIX, socket.SOCK_DGRAM) as channel:
+            channel.connect(address)
+            channel.sendall(b'READY=1')
+    server.serve_forever()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/infra/peertube-workers/ffmpeg-qsv.py b/infra/peertube-workers/ffmpeg-qsv.py
new file mode 100755
index 0000000..d6b25a7
--- /dev/null
+++ b/infra/peertube-workers/ffmpeg-qsv.py
@@ -0,0 +1,182 @@
+#!/usr/bin/python3
+"""Pinned PeerTube runner 0.2.0 FFmpeg adapter. Never executes a CPU video encoder."""
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+REAL = '/usr/bin/ffmpeg'
+PROBE = '/usr/bin/ffprobe'
+DEVICE = os.environ.get('PT_RENDER_DEVICE', '/dev/dri/renderD128')
+STATE = Path(os.environ.get('PT_STATE_DIR', '/var/lib/pt-worker/state'))
+
+
+def event(kind, **fields):
+    STATE.mkdir(parents=True, exist_ok=True)
+    data = (json.dumps({'time': time.time(), 'kind': kind, **fields}) + '\n').encode()
+    fd = os.open(STATE / 'events.jsonl', os.O_CREAT | os.O_APPEND | os.O_WRONLY, 0o600)
+    try:
+        os.write(fd, data)
+    finally:
+        os.close(fd)
+
+
+def probe(path):
+    p = subprocess.run([PROBE, '-v', 'error', '-show_streams', '-show_format',
+                        '-of', 'json', path], capture_output=True, text=True, timeout=30)
+    if p.returncode:
+        raise ValueError('input probe failed')
+    return json.loads(p.stdout)
+
+
+def engines(pid):
+    """i915 DRM fdinfo: cumulative hardware engine time, deduplicated by client id."""
+    result, clients = {}, set()
+    for f in Path(f'/proc/{pid}/fdinfo').glob('*'):
+        try:
+            text = f.read_text()
+        except OSError:
+            continue
+        cid = re.search(r'^drm-client-id:\s*(\d+)', text, re.M)
+        if not cid or cid[1] in clients:
+            continue
+        clients.add(cid[1])
+        for key, value in re.findall(r'^drm-engine-([\w-]+):\s*(\d+)\s+ns', text, re.M):
+            result[key] = result.get(key, 0) + int(value)
+    return result
+
+
+def rewrite(args, input_probe=None):
+    # fluent-ffmpeg queries capabilities before building commands. These do no encode.
+    if args in (['-version'], ['-formats'], ['-encoders'], ['-filters'], ['-codecs'], ['-hwaccels']):
+        return args, None
+    pairs = list(zip(args, args[1:]))
+    video_options = [(k, v) for k, v in pairs if k in ('-vcodec', '-c:v', '-codec:v')]
+    if len(video_options) > 1:
+        raise ValueError('multiple video codec options refused')
+    if '-vn' in args and not video_options:
+        return args, None  # audio-only VOD renditions have no video encode
+    if not video_options or video_options[0][1] != 'libx264':
+        raise ValueError('unknown runner command or video encoder refused')
+    if '-filter_complex' in args or '-hwaccel' in args or '-init_hw_device' in args:
+        raise ValueError('unreviewed filter/device override refused')
+    inputs = [v for k, v in pairs if k == '-i']
+    if not inputs:
+        raise ValueError('missing video input')
+    data = input_probe if input_probe is not None else probe(inputs[0])
+    stream = next((s for s in data['streams'] if s['codec_type'] == 'video'), None)
+    if stream is None:
+        raise ValueError('missing video stream')
+    codec = stream['codec_name']
+    still = codec in ('png', 'mjpeg', 'webp') and '-loop' in args
+    decoder = {'h264': 'h264_qsv', 'hevc': 'hevc_qsv', 'vp9': 'vp9_qsv', 'av1': 'av1_qsv'}.get(codec)
+    if not decoder and not still:
+        raise ValueError('source codec has no reviewed QSV decode path')
+    if stream.get('pix_fmt') not in ('yuv420p', 'yuv420p10le', 'nv12', 'p010le') and not still:
+        raise ValueError('unsupported pixel format; CPU decode fallback refused')
+    if stream.get('tags', {}).get('rotate') or any(s.get('rotation', 0) for s in stream.get('side_data_list', [])):
+        raise ValueError('rotated source requires reviewed GPU transpose path')
+    width, height = stream['width'], stream['height']
+    duration = float(data.get('format', {}).get('duration', 0) or 0)
+    w, h = width // 2 * 2, height // 2 * 2
+    output = ['-init_hw_device', f'vaapi=va:{DEVICE}', '-init_hw_device', 'qsv=qs@va',
+              '-filter_hw_device', 'qs']
+    i, first_input = 0, True
+    while i < len(args):
+        key = args[i]
+        val = args[i + 1] if i + 1 < len(args) else None
+        if key == '-i' and first_input:
+            if not still:
+                output += ['-hwaccel', 'qsv', '-hwaccel_output_format', 'qsv', '-c:v', decoder, '-noautorotate']
+            output += [key, val]
+            first_input = False
+            i += 2
+        elif key in ('-vcodec', '-c:v', '-codec:v'):
+            output += [key, 'h264_qsv']
+            i += 2
+        elif key in ('-pix_fmt', '-preset', '-preset:v', '-b_strategy', '-bf', '-tune', '-crf'):
+            i += 2
+        elif key in ('-vf', '-filter:v'):
+            if val == 'scale=trunc(iw/2)*2:trunc(ih/2)*2' and still:
+                w, h = width // 2 * 2, height // 2 * 2
+            else:
+                match = re.fullmatch(r'scale=w=(-2|\d+):h=(-2|\d+)', val or '')
+                if not match:
+                    raise ValueError('unreviewed software filter refused')
+                w, h = map(int, match.groups())
+                if w == -2 and h > 0:
+                    w = max(2, round(width * h / height / 2) * 2)
+                elif h == -2 and w > 0:
+                    h = max(2, round(height * w / width / 2) * 2)
+                if w <= 0 or h <= 0 or w % 2 or h % 2:
+                    raise ValueError('invalid output dimensions')
+            prefix = 'format=nv12,hwupload=extra_hw_frames=64,' if still else ''
+            output += [key, prefix + f'scale_qsv=w={w}:h={h}:format=nv12']
+            i += 2
+        else:
+            output.append(key)
+            i += 1
+    if '-vf' not in args and '-filter:v' not in args:
+        prefix = 'format=nv12,hwupload=extra_hw_frames=64,' if still else ''
+        output[-1:-1] = ['-vf', prefix + f'scale_qsv=w={width // 2 * 2}:h={height // 2 * 2}:format=nv12']
+    # Keep PeerTube's rate cap and GOP; QSV has no x264 CRF mode.
+    rate = next((v for k, v in pairs if k in ('-maxrate:v', '-maxrate')), None)
+    extra = ['-preset', 'medium', '-bf', '2']
+    if rate and not any(k in ('-b:v', '-vb') for k, _ in pairs):
+        extra += ['-b:v', rate]
+    output[-1:-1] = extra
+    job_uuid = None
+    try:
+        job_uuid = json.loads((STATE / 'inputs' / (Path(inputs[0]).name + '.json')).read_text())['uuid']
+    except (OSError, ValueError, KeyError):
+        pass
+    return output, {'job_uuid': job_uuid, 'source_codec': codec, 'target_codec': 'h264', 'encoder': 'h264_qsv',
+                    'source_width': width, 'source_height': height, 'duration': duration,
+                    'target_width': w, 'target_height': h,
+                    'static_image_upload': still}
+
+
+def main():
+    try:
+        args, info = rewrite(sys.argv[1:])
+        if info is None:
+            os.execv(REAL, [REAL, *args])
+        if not os.access(DEVICE, os.R_OK | os.W_OK):
+            raise ValueError('render device unavailable')
+        started = time.monotonic()
+        p = subprocess.Popen([REAL, *args], stderr=subprocess.PIPE, text=True)
+        progress = {}
+        def stderr_progress():
+            for line in p.stderr:
+                sys.stderr.write(line)
+                sys.stderr.flush()
+                for key, value in re.findall(r'(frame|fps|speed)=\s*([\d.]+)', line):
+                    progress[key] = float(value)
+        reader = threading.Thread(target=stderr_progress, daemon=True)
+        reader.start()
+        maximum = {}
+        while p.poll() is None:
+            for key, value in engines(p.pid).items():
+                maximum[key] = max(maximum.get(key, 0), value)
+            time.sleep(0.1)
+        elapsed = time.monotonic() - started
+        reader.join(timeout=2)
+        event('encode', **info, seconds=elapsed, returncode=p.returncode, engine_ns=maximum,
+              ffmpeg_fps=progress.get('fps'), frames=progress.get('frame'), ffmpeg_speed=progress.get('speed'),
+              realtime_factor=info['duration'] / elapsed if info['duration'] else None)
+        if p.returncode:
+            event('gpu_failure', reason='qsv_transcode_failed')
+        sys.exit(p.returncode)
+    except (ValueError, OSError, subprocess.SubprocessError, KeyError) as e:
+        # Messages are fixed strings; never expose source URLs or runner credentials.
+        event('gpu_failure', reason=type(e).__name__)
+        print('PT-WORKER: QSV adapter refused command; worker must drain', file=sys.stderr)
+        sys.exit(78)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/infra/peertube-workers/install-peertube-worker-windows.ps1 b/infra/peertube-workers/install-peertube-worker-windows.ps1
new file mode 100644
index 0000000..a300cfe
--- /dev/null
+++ b/infra/peertube-workers/install-peertube-worker-windows.ps1
@@ -0,0 +1,161 @@
+# Run from an elevated PowerShell for MSI/services. User-level preparation is supported.
+[CmdletBinding()]
+param(
+  [string]$Root='C:\pt-worker', [string]$Name="$env:COMPUTERNAME-win",
+  [string]$PeerTubeUrl='http://TAILSCALE_IP:9000', [string]$CanonicalOrigin='https://tube.occupymedia.cc',
+  [string]$ServerIp='TAILSCALE_IP', [int]$Device=0,
+  [ValidateSet('Prepare','SelfTest','Enroll','ServiceFiles','Services','All')][string]$Phase='All',
+  [switch]$RegistrationTokenStdin, [switch]$UserLevel
+)
+$ErrorActionPreference='Stop';$ProgressPreference='SilentlyContinue'
+$Source=$PSScriptRoot
+$Pins=Get-Content (Join-Path $Source 'win\dependencies.json') -Raw | ConvertFrom-Json
+$admin=([Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)
+if($Root -notmatch '^[A-Za-z]:\\' -or $Root -match '[\s"<>]'){throw 'Choose an absolute local path without spaces or XML characters'}
+$env:PT_ROOT=$Root
+$env:PT_STATE_DIR=Join-Path $Root 'state'
+$env:PT_WORKER_CONFIG=Join-Path $Root 'state\worker.json'
+$env:APPDATA=Join-Path $Root 'profile\Roaming'
+$env:LOCALAPPDATA=Join-Path $Root 'profile\Local'
+$env:TMP=Join-Path $Root 'tmp';$env:TEMP=$env:TMP
+$env:FFMPEG_PATH=Join-Path $Root 'bin\ffmpeg-nvenc.exe'
+$env:FFPROBE_PATH=Join-Path $Root 'bin\ffprobe.exe'
+$node=Join-Path $Root 'node\node.exe'
+$toml=Join-Path $env:APPDATA 'peertube-runner-nodejs\Config\default\config.toml'
+function CheckExit([string]$What){if($LASTEXITCODE -ne 0){throw "$What failed (exit $LASTEXITCODE)"}}
+function Fetch($Pin,[string]$File){
+  $out=Join-Path $Root "downloads\$File"
+  if(!(Test-Path $out)){& curl.exe --fail --location --silent --show-error --output $out $Pin.url;CheckExit 'Download'}
+  if((Get-FileHash $out -Algorithm SHA256).Hash.ToLower() -ne $Pin.sha256){throw "SHA256 mismatch for $File; no installation performed"}
+  return $out
+}
+function ProtectPaths {
+  $me=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+  & icacls.exe $Root /inheritance:r /grant:r "*$($me):(OI)(CI)F" '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-19:(OI)(CI)RX' | Out-Null;CheckExit 'Root ACL'
+  foreach($dir in @('state','profile','tmp','logs')){
+    & icacls.exe (Join-Path $Root $dir) /inheritance:r /grant:r "*$($me):(OI)(CI)F" '*S-1-5-18:(OI)(CI)F' '*S-1-5-32-544:(OI)(CI)F' '*S-1-5-19:(OI)(CI)F' | Out-Null;CheckExit 'Private ACL'
+  }
+}
+if($Phase -in @('Prepare','All')){
+  if(Test-Path (Join-Path $Root 'state\runner.json')){
+    $running=Get-Content (Join-Path $Root 'state\runner.json') -Raw | ConvertFrom-Json
+    if($running.running){throw 'Drain and wait for runner_running=false before preparing/upgrading'}
+  }
+  foreach($dir in @('bin','downloads','runner','state','profile','tmp','logs','build')){New-Item -ItemType Directory -Force (Join-Path $Root $dir) | Out-Null}
+  '{"paused":true}' | Set-Content (Join-Path $Root 'state\control.json') -Encoding ASCII
+  ProtectPaths
+  $msi=Fetch $Pins.node_msi 'node.msi'
+  if(!$UserLevel){
+    if(!$admin){throw 'Node MSI requires an elevated Windows PowerShell. Use -UserLevel to prepare isolated binaries.'}
+    $p=Start-Process msiexec.exe -Wait -PassThru -ArgumentList @('/i',$msi,'/qn','/norestart');if($p.ExitCode -notin @(0,3010)){throw "Node MSI exit $($p.ExitCode)"}
+  }
+  # The worker always uses its isolated pinned Node even after a machine-wide MSI.
+  $zip=Fetch $Pins.node_zip 'node.zip'
+  Expand-Archive $zip (Join-Path $Root 'downloads\node') -Force
+  if(!(Test-Path (Join-Path $Root 'node'))){New-Item -ItemType Directory (Join-Path $Root 'node') | Out-Null}
+  Copy-Item (Join-Path $Root "downloads\node\node-v$($Pins.node_version)-win-x64\*") (Join-Path $Root 'node') -Recurse -Force
+  $zip=Fetch $Pins.ffmpeg 'ffmpeg-8.1-20261009.zip'
+  Expand-Archive $zip (Join-Path $Root 'downloads\ffmpeg') -Force
+  $ff=Get-ChildItem (Join-Path $Root 'downloads\ffmpeg') -Filter ffmpeg.exe -Recurse | Select-Object -First 1
+  Copy-Item ($ff.Directory.FullName+'\*') (Join-Path $Root 'bin') -Force
+  Copy-Item (Fetch $Pins.winsw 'winsw.exe') (Join-Path $Root 'bin\WinSW-x64.exe') -Force
+  foreach($file in @('ffmpeg-nvenc.py','pt-worker-nvenc.py','ipc-nvenc.cjs','runner-supervisor.cjs','enroll-server.cjs','service-stop.cjs')){Copy-Item (Join-Path $Source "win\$file") (Join-Path $Root "bin\$file") -Force}
+  Copy-Item (Join-Path $Source 'observe.cjs') (Join-Path $Root 'bin\observe.cjs') -Force
+  Copy-Item (Join-Path $Source 'win\selftest-nvenc.ps1') (Join-Path $Root 'selftest-nvenc.ps1') -Force
+  Copy-Item (Join-Path $Source 'pt-worker-win.ps1') (Join-Path $Root 'pt-worker-win.ps1') -Force
+  Copy-Item (Join-Path $Source 'runtime-package.json') (Join-Path $Root 'runner\package.json') -Force
+  Copy-Item (Join-Path $Source 'runtime-package-lock.json') (Join-Path $Root 'runner\package-lock.json') -Force
+  $env:PATH=(Join-Path $Root 'node')+';'+$env:PATH
+  Push-Location (Join-Path $Root 'runner');try {& (Join-Path $Root 'node\npm.cmd') ci --ignore-scripts;CheckExit 'Pinned runner install'}finally{Pop-Location}
+  # Python is a build prerequisite only. Frozen executables embed their runtime.
+  $python=(Get-Command python.exe -ErrorAction Stop).Source
+  & $python -m venv (Join-Path $Root 'build-env');CheckExit 'Build environment'
+  $builder=Join-Path $Root 'build-env\Scripts\python.exe'
+  & $builder -m pip install --disable-pip-version-check -r (Join-Path $Source 'win\build-requirements.txt');CheckExit 'Pinned builder install'
+  foreach($app in @(@{Name='ffmpeg-nvenc';Source='ffmpeg-nvenc.py'},@{Name='pt-admission';Source='pt-worker-nvenc.py'})){
+    & $builder -m PyInstaller --noconfirm --clean --onefile --name $app.Name --distpath (Join-Path $Root 'bin') --workpath (Join-Path $Root "build\$($app.Name)") --specpath (Join-Path $Root 'build') (Join-Path $Root "bin\$($app.Source)");CheckExit 'Executable build'
+  }
+  if(!(Test-Path (Join-Path $Root 'state\worker.json'))){
+    @{name=$Name;peertube_url=$PeerTubeUrl;canonical_origin=$CanonicalOrigin;tailscale_peer=$ServerIp;probe_url="http://${ServerIp}:9044";peertube_version='7.3.0';concurrency=2;nvenc_device=$Device;require_ac=$true;node_binary=$node;tailscale_binary='C:\Program Files\Tailscale\tailscale.exe';poll_seconds=5;probe_interval_seconds=300} | ConvertTo-Json | Set-Content (Join-Path $Root 'state\worker.json') -Encoding ASCII
+  }
+  if(!(Test-Path $toml)){New-Item -ItemType Directory -Force (Split-Path $toml) | Out-Null;"[jobs]`nconcurrency = 0`n[ffmpeg]`nthreads = 2`nnice = 20`n" | Set-Content $toml -Encoding ASCII}
+  $manifest=@{pins=$Pins;built_at=[DateTime]::UtcNow.ToString('o');binaries=@()}
+  foreach($file in @('ffmpeg.exe','ffprobe.exe','ffmpeg-nvenc.exe','pt-admission.exe','WinSW-x64.exe')){$manifest.binaries+=@{name=$file;sha256=(Get-FileHash (Join-Path $Root "bin\$file")).Hash.ToLower()}}
+  $manifest | ConvertTo-Json -Depth 8 | Set-Content (Join-Path $Root 'state\dependencies.json') -Encoding ASCII
+}
+if($Phase -in @('SelfTest','All')){
+  & (Join-Path $Root 'selftest-nvenc.ps1') -Root $Root -Device $Device;CheckExit 'Mandatory NVENC proof'
+  & (Join-Path $Root 'bin\pt-admission.exe') network-test;CheckExit 'Windows bandwidth probe'
+}
+if($Phase -in @('Enroll','All')){
+  $cfg=Get-Content (Join-Path $Root 'state\worker.json') -Raw | ConvertFrom-Json
+  $proof=Get-Content (Join-Path $Root 'state\nvenc.json') -Raw | ConvertFrom-Json
+  if(!$proof.nvenc_h264_ok -or !$proof.nvenc_hevc_ok){throw 'Registration refused: NVENC proof absent'}
+  $boot=(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')
+  $driver=(& nvidia-smi.exe -i $cfg.nvenc_device --query-gpu=driver_version --format=csv,noheader,nounits).Trim()
+  if($proof.boot_id -ne $boot -or $proof.driver_version -ne $driver -or ([DateTimeOffset]::UtcNow.ToUnixTimeSeconds()-$proof.tested_at) -gt 86400){throw 'Registration refused: stale boot/driver proof'}
+  $text=Get-Content $toml -Raw
+  if($text -match 'runnerToken\s*='){
+    if($text -notmatch [regex]::Escape($cfg.name)){throw 'Other runner exists in profile; inspect before enrollment'}
+    Write-Output 'Already enrolled; registration preserved'
+  }else{
+    if(Test-Path (Join-Path $Root 'state\enrollment.pending')){throw 'Previous registration result uncertain; inspect server before retry'}
+    if(!$RegistrationTokenStdin){throw 'Enrollment requires -RegistrationTokenStdin with the existing secret piped on stdin; never pass the token as an argument'}
+    ProtectPaths
+    & $node (Join-Path $Root 'bin\enroll-server.cjs');CheckExit 'Enrollment listener'
+    Start-Sleep -Seconds 3
+    'Attempted; no secret material' | Set-Content (Join-Path $Root 'state\enrollment.pending')
+    # Node reads inherited stdin directly. No PowerShell variable/file/history holds the token.
+    & $node (Join-Path $Root 'bin\ipc-nvenc.cjs') register;CheckExit 'Official registration IPC'
+    & $node (Join-Path $Root 'bin\ipc-nvenc.cjs') graceful-shutdown;CheckExit 'Enrollment drain'
+    Remove-Item (Join-Path $Root 'state\enrollment.pending')
+  }
+  # Keep official runner credential private, never print TOML or arbitrary logs.
+  [IO.File]::WriteAllText($toml, ((Get-Content $toml -Raw) -replace '(?m)^concurrency\s*=\s*\d+', 'concurrency = 2'))
+}
+if($Phase -in @('ServiceFiles','Services','All')){
+  foreach($svc in @('pt-runner','pt-admission')){if(Get-Service $svc -ErrorAction SilentlyContinue){throw 'Existing service requires an explicit drain/upgrade; refusing overwrite'}}
+  New-Item -ItemType Directory -Force (Join-Path $Root 'services'),(Join-Path $Root 'logs') | Out-Null
+  ProtectPaths
+  foreach($svc in @('pt-runner','pt-admission')){
+    $exe=if($svc -eq 'pt-runner'){$node}else{Join-Path $Root 'bin\pt-admission.exe'}
+    $arguments=if($svc -eq 'pt-runner'){Join-Path $Root 'bin\runner-supervisor.cjs'}else{'daemon'}
+    $stop=if($svc -eq 'pt-runner'){"<stopexecutable>$node</stopexecutable><stoparguments>$(Join-Path $Root 'bin\service-stop.cjs')</stoparguments>"}else{''}
+    $xml=@"
+<service><id>$svc</id><name>$svc</name><description>PeerTube Windows NVENC worker: AC-only admission, VOD-only, no CPU video encoding</description>
+<executable>$exe</executable><startarguments>$arguments</startarguments><workingdirectory>$Root</workingdirectory>
+<env name="PT_ROOT" value="$Root"/><env name="PT_STATE_DIR" value="$(Join-Path $Root 'state')"/>
+<env name="APPDATA" value="$(Join-Path $Root 'profile\Roaming')"/><env name="LOCALAPPDATA" value="$(Join-Path $Root 'profile\Local')"/>
+<env name="TMP" value="$(Join-Path $Root 'tmp')"/><env name="TEMP" value="$(Join-Path $Root 'tmp')"/>
+<startmode>Automatic</startmode><delayedAutoStart>true</delayedAutoStart><onfailure action="restart" delay="30 sec"/><resetfailure>1 hour</resetfailure>
+<serviceaccount><domain>NT AUTHORITY</domain><user>LocalService</user></serviceaccount>
+<logpath>$(Join-Path $Root 'logs')</logpath><log mode="roll-by-size"><sizeThreshold>1024</sizeThreshold><keepFiles>3</keepFiles></log>
+<stoptimeout>1 hour</stoptimeout>$stop</service>
+"@
+    Copy-Item (Join-Path $Root 'bin\WinSW-x64.exe') (Join-Path $Root "services\$svc.exe")
+    $xml | Set-Content (Join-Path $Root "services\$svc.xml") -Encoding UTF8
+
+  }
+  if($Phase -eq 'ServiceFiles'){Write-Output 'WinSW service files prepared; no SCM changes';return}
+  if(!$admin){throw 'Service files prepared. Installation requires elevated Windows PowerShell (OpenSCManager error 5 in filtered SSH/WSL tokens).'}
+  # Transition an interactive validation deployment without duplicate profile owners.
+  '{"paused":true}' | Set-Content (Join-Path $Root 'state\control.json') -Encoding ASCII
+  $deadline=(Get-Date).AddHours(1)
+  while(Test-Path (Join-Path $Root 'state\runner.json')){
+    $r=Get-Content (Join-Path $Root 'state\runner.json') -Raw | ConvertFrom-Json
+    if(!$r.running){break}
+    if((Get-Date) -gt $deadline){throw 'Active jobs still draining; service transition stopped'}
+    Start-Sleep -Seconds 2
+  }
+  if(Test-Path (Join-Path $Root 'state\supervisor-process.json')){
+    'requested' | Set-Content (Join-Path $Root 'state\supervisor-stop') -Encoding ASCII
+    Start-Sleep -Seconds 3
+  }
+  Get-Process pt-admission -ErrorAction SilentlyContinue | Where-Object {$_.Path -eq (Join-Path $Root 'bin\pt-admission.exe')} | Stop-Process
+  foreach($svc in @('pt-runner','pt-admission')){& (Join-Path $Root "services\$svc.exe") install;CheckExit 'Service installation'}
+  & powercfg.exe /change standby-timeout-ac 0;CheckExit 'AC sleep policy'
+  # Force proof from service/session 0 before opening admission there.
+  Remove-Item (Join-Path $Root 'state\nvenc.json') -ErrorAction SilentlyContinue
+  Start-Service pt-admission,pt-runner
+  Write-Output 'Services installed and started PAUSED. Validate session-0 NVENC, then pt-worker-win start.'
+}
diff --git a/infra/peertube-workers/install-peertube-worker.sh b/infra/peertube-workers/install-peertube-worker.sh
new file mode 100755
index 0000000..aa6e615
--- /dev/null
+++ b/infra/peertube-workers/install-peertube-worker.sh
@@ -0,0 +1,196 @@
+#!/bin/bash
+# Native Debian 12 / Ubuntu 24.04+ Intel DRM worker. No secrets in argv/history.
+set -euo pipefail
+set +x
+umask 077
+task_source=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+worker_name= peertube_url= token_fd= canonical_origin= tailscale_peer=TAILSCALE_IP
+while (($#)); do
+    case "$1" in
+        --name) worker_name=${2:?}; shift 2 ;;
+        --peertube-url) peertube_url=${2:?}; shift 2 ;;
+        --tailscale-peer) tailscale_peer=${2:?}; shift 2 ;;
+        --canonical-origin) canonical_origin=${2:?}; shift 2 ;;
+        --registration-token-fd) token_fd=${2:?}; shift 2 ;;
+        *) echo 'Usage: install-peertube-worker.sh --name HOST --peertube-url URL [--tailscale-peer IP] [--registration-token-fd N]' >&2; exit 2 ;;
+    esac
+done
+[[ $EUID -eq 0 && $worker_name =~ ^[a-zA-Z0-9._-]+$ && $peertube_url =~ ^https?:// ]] || { echo 'Root, valid name and URL required' >&2; exit 2; }
+exec 9>/run/lock/pt-worker-install.lock
+flock -n 9 || { echo 'Another installation is running' >&2; exit 1; }
+[[ $(ps -p 1 -o comm=) == systemd ]] || { echo 'systemd is required; inspect WSL init before onboarding' >&2; exit 1; }
+[[ -c /dev/dri/renderD128 ]] || { echo 'No Intel DRM render device; /dev/dxg alone is not this Linux QSV path. No packages or services changed.' >&2; exit 1; }
+[[ $(cat /sys/class/drm/renderD128/device/vendor) == 0x8086 ]] || { echo 'This installer needs an Intel GPU; NVIDIA needs another hardware adapter' >&2; exit 1; }
+[[ $(basename "$(readlink -f /sys/class/drm/renderD128/device/driver)") == i915 || $(basename "$(readlink -f /sys/class/drm/renderD128/device/driver)") == xe ]] || { echo 'Intel DRM driver unavailable' >&2; exit 1; }
+command -v tailscale >/dev/null || { echo 'Tailscale must be joined already' >&2; exit 1; }
+tailscale ping --c=1 --timeout=5s "$tailscale_peer" >/dev/null
+canonical_origin=$(python3 - "$peertube_url" "$canonical_origin" <<'PY'
+import json, sys, urllib.request
+from urllib.parse import urlsplit
+with urllib.request.urlopen(sys.argv[1].rstrip('/')+'/api/v1/config', timeout=10) as r:
+ c=json.load(r); v=c['serverVersion']
+if v != '7.3.0': raise SystemExit('This adapter is verified against PeerTube 7.3.0; inspect a different version before installing')
+if sys.version_info < (3,11): raise SystemExit('Python >=3.11 required')
+origin=sys.argv[2]
+if not origin:
+ logos=[x['fileUrl'] for x in c['instance']['logo'] if x.get('isFallback')]
+ if not logos: raise SystemExit('Supply --canonical-origin: no fallback asset URL identifies the instance origin')
+ u=urlsplit(logos[0]);origin=u.scheme+'://'+u.netloc
+print(origin.rstrip('/'))
+PY
+)
+if [[ -f /etc/pt-worker/worker.json ]]; then
+    python3 - "$worker_name" "$peertube_url" <<'PY'
+import json, sys
+c=json.load(open('/etc/pt-worker/worker.json'))
+if c['name'] != sys.argv[1] or c['peertube_url'].rstrip('/') != sys.argv[2].rstrip('/'):
+ raise SystemExit('Existing name/URL differs: preserve registration and inspect before changing it')
+PY
+fi
+if systemctl is-active --quiet pt-worker.service; then
+    /usr/local/bin/pt-worker drain
+    for _ in $(seq 1 120); do
+        if /usr/local/bin/pt-worker status | python3 -c 'import json,sys;sys.exit(bool(json.load(sys.stdin).get("runner_running")))'; then break; fi
+        sleep 5
+    done
+    /usr/local/bin/pt-worker status | python3 -c 'import json,sys;sys.exit(bool(json.load(sys.stdin).get("runner_running")))' || { echo 'Active jobs still draining; installer stopped without overwriting code' >&2; exit 1; }
+    systemctl stop pt-worker.service
+fi
+if [[ -d /opt/pt-worker ]]; then
+    mkdir -p /var/backups/pt-worker
+    task_backup=/var/backups/pt-worker/$(date -u +%Y%m%dT%H%M%SZ).tgz
+    tar -czf "$task_backup" /opt/pt-worker /etc/pt-worker /var/lib/pt-worker/.config
+    chmod 600 "$task_backup"
+fi
+. /etc/os-release
+case "$ID" in debian|ubuntu) ;; *) echo 'Only Debian/Ubuntu package sets verified' >&2; exit 1;; esac
+apt-get update
+# Intel media VA driver includes Alder Lake support; do not change kernel/perf policies.
+task_media_package=intel-media-va-driver
+if apt-cache show intel-media-va-driver-non-free >/dev/null 2>&1; then task_media_package=intel-media-va-driver-non-free; fi
+apt-get install -y ffmpeg vainfo "$task_media_package" intel-gpu-tools python3 curl ca-certificates xz-utils pciutils
+python3 - <<'PY'
+import re, subprocess
+s=subprocess.check_output(['/usr/bin/ffmpeg','-version'],text=True)
+m=re.search(r'ffmpeg version (\d+)\.(\d+)',s)
+if not m or tuple(map(int,m.groups())) < (4,3): raise SystemExit('FFmpeg >=4.3 required')
+subprocess.run(['/usr/bin/ffprobe','-version'],check=True,stdout=subprocess.DEVNULL)
+PY
+id pt-worker >/dev/null 2>&1 || useradd --system --create-home --home-dir /var/lib/pt-worker --shell /usr/sbin/nologin pt-worker
+for task_group in render video; do
+    getent group "$task_group" >/dev/null && usermod -a -G "$task_group" pt-worker
+done
+task_render_group=$(stat -c %G /dev/dri/renderD128)
+[[ $task_render_group != root ]] || { echo 'Render device has root group; fix the host udev policy first' >&2; exit 1; }
+usermod -a -G "$task_render_group" pt-worker
+install -d -m 755 /opt/pt-worker
+install -d -m 750 -o root -g pt-worker /etc/pt-worker
+install -d -m 700 -o pt-worker -g pt-worker /var/lib/pt-worker/state
+for task_file in pt-worker.py ffmpeg-qsv.py observe.cjs ipc.cjs; do
+    install -m 755 "$task_source/$task_file" "/opt/pt-worker/$task_file"
+done
+install -m 755 "$task_source/pt-worker" /usr/local/bin/pt-worker
+if [[ ! -x /opt/pt-worker/node/bin/node ]]; then
+    task_tmp=$(mktemp -d)
+    trap 'python3 -c '\''import shutil,sys;shutil.rmtree(sys.argv[1])'\'' "$task_tmp"' EXIT
+    case "$(uname -m)" in x86_64) task_arch=x64;; *) echo 'Intel worker requires x86_64' >&2; exit 1;; esac
+    curl -fsSL https://nodejs.org/dist/latest-v22.x/SHASUMS256.txt -o "$task_tmp/SHA256SUMS"
+    task_archive=$(awk '$2 ~ /linux-x64.tar.xz$/ {print $2}' "$task_tmp/SHA256SUMS")
+    [[ $task_archive =~ ^node-v22\.[0-9]+\.[0-9]+-linux-x64.tar.xz$ ]] || exit 1
+    curl -fsSL "https://nodejs.org/dist/latest-v22.x/$task_archive" -o "$task_tmp/$task_archive"
+    (cd "$task_tmp"; awk -v file="$task_archive" '$2==file' SHA256SUMS | sha256sum -c -)
+    mkdir -p /opt/pt-worker/node
+    tar -xJf "$task_tmp/$task_archive" -C /opt/pt-worker/node --strip-components=1
+fi
+export PATH=/opt/pt-worker/node/bin:$PATH
+node -e 'if (+process.versions.node.split(".")[0] < 22) process.exit(1)'
+install -d -m 755 /opt/pt-worker/runtime
+install -m 644 "$task_source/runtime-package.json" /opt/pt-worker/runtime/package.json
+install -m 644 "$task_source/runtime-package-lock.json" /opt/pt-worker/runtime/package-lock.json
+npm ci --prefix /opt/pt-worker/runtime --omit=optional --ignore-scripts --no-audit --no-fund
+[[ $(/opt/pt-worker/runtime/node_modules/.bin/peertube-runner --version) == 0.2.0 ]] || exit 1
+if [[ ! -f /etc/pt-worker/worker.json ]]; then
+    python3 - "$task_source/worker.example.json" "$worker_name" "$peertube_url" "$tailscale_peer" "$canonical_origin" <<'PY'
+import json,sys
+c=json.load(open(sys.argv[1]));c.update(name=sys.argv[2],peertube_url=sys.argv[3].rstrip('/'),tailscale_peer=sys.argv[4],canonical_origin=sys.argv[5],probe_url='http://'+sys.argv[4]+':9044')
+with open('/etc/pt-worker/worker.json','w') as f: json.dump(c,f,indent=2)
+PY
+fi
+chown root:pt-worker /etc/pt-worker/worker.json
+chmod 640 /etc/pt-worker/worker.json
+# Real hardware test as the actual service user, with its real device permissions.
+/usr/local/bin/pt-worker self-test || { echo 'QSV failed or media-engine evidence unavailable: not registering or starting' >&2; exit 1; }
+task_registered=$(runuser -u pt-worker -- python3 - <<'PY'
+import tomllib,json
+from pathlib import Path
+c=json.load(open('/etc/pt-worker/worker.json')); p=Path('/var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml')
+d=tomllib.loads(p.read_text()) if p.exists() else {}
+print(int(any(x['url'].rstrip('/')==c['peertube_url'] and x['runnerName']==c['name'] for x in d.get('registeredInstances',[]))))
+PY
+)
+if [[ $task_registered == 0 ]]; then
+    [[ ! -e /var/lib/pt-worker/state/enrollment.pending ]] || { echo 'Previous registration outcome is uncertain; inspect the named runner in PeerTube before retrying. No duplicate enrollment attempted.' >&2; exit 1; }
+    # Registration requires a running server. concurrency=0 makes enrollment refuse jobs.
+    install -d -m 700 -o pt-worker -g pt-worker /var/lib/pt-worker/.config/peertube-runner-nodejs/default
+    if [[ -e /var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml ]]; then
+        python3 - <<'PY'
+import tomllib
+from pathlib import Path
+p=Path('/var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml')
+c=tomllib.loads(p.read_text())
+if c.get('registeredInstances'): raise SystemExit('Other registered instances exist: inspect before enrollment')
+PY
+    fi
+    cat > /var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml <<'TOML'
+[jobs]
+concurrency = 0
+[ffmpeg]
+threads = 2
+nice = 20
+TOML
+    chown pt-worker:pt-worker /var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml
+    # Logs go to /dev/null during enrollment; the official CLI secret flag is deliberately avoided.
+    runuser -u pt-worker -- env HOME=/var/lib/pt-worker PATH="$PATH" \
+        /opt/pt-worker/runtime/node_modules/.bin/peertube-runner server \
+        --enable-job vod-web-video-transcoding --enable-job vod-hls-transcoding --enable-job vod-audio-merge-transcoding >/dev/null 2>&1 &
+    task_enroll_pid=$!
+    trap 'kill "$task_enroll_pid" 2>/dev/null || true; [[ -z ${task_tmp:-} ]] || python3 -c '\''import shutil,sys;shutil.rmtree(sys.argv[1])'\'' "$task_tmp"' EXIT
+    for _ in $(seq 1 30); do
+        [[ -S /var/lib/pt-worker/.local/share/peertube-runner-nodejs/default/peertube-runner.sock ]] && break
+        sleep 1
+    done
+    if [[ -n $token_fd ]]; then
+        [[ $token_fd =~ ^[0-9]+$ ]] || exit 2
+        touch /var/lib/pt-worker/state/enrollment.pending
+        runuser -u pt-worker -- env HOME=/var/lib/pt-worker /opt/pt-worker/node/bin/node /opt/pt-worker/ipc.cjs register <&"$token_fd"
+    else
+        [[ -t 0 ]] || { echo 'Provide a secure token FD or run interactively' >&2; exit 1; }
+        read -r -s -p 'Dedicated runner registration token: ' task_token
+        echo
+        touch /var/lib/pt-worker/state/enrollment.pending
+        printf '%s' "$task_token" | runuser -u pt-worker -- env HOME=/var/lib/pt-worker /opt/pt-worker/node/bin/node /opt/pt-worker/ipc.cjs register
+        unset task_token
+    fi
+    runuser -u pt-worker -- env HOME=/var/lib/pt-worker PATH="$PATH" /opt/pt-worker/runtime/node_modules/.bin/peertube-runner graceful-shutdown >/dev/null
+    wait "$task_enroll_pid"
+    # IPC returns success only after saving the dedicated runner credential to TOML.
+fi
+python3 - <<'PY'
+from pathlib import Path
+Path('/var/lib/pt-worker/state/enrollment.pending').unlink(missing_ok=True)
+PY
+python3 - <<'PY'
+import re,json
+from pathlib import Path
+p=Path('/var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml')
+c=json.load(open('/etc/pt-worker/worker.json'))
+s=p.read_text(); s,n=re.subn(r'(?m)^concurrency\s*=\s*\d+', 'concurrency = '+str(c['concurrency']), s,count=1)
+if n!=1: raise SystemExit('Missing concurrency configuration')
+p.write_text(s)
+PY
+chmod 600 /var/lib/pt-worker/.config/peertube-runner-nodejs/default/config.toml
+install -m 644 "$task_source/systemd/pt-worker.service" /etc/systemd/system/pt-worker.service
+systemctl daemon-reload
+systemctl enable --now pt-worker.service
+echo 'Registered. Admission starts PAUSED; measure bandwidth or use pt-worker start --calibrate for initial real jobs.'
+/usr/local/bin/pt-worker status
diff --git a/infra/peertube-workers/ipc.cjs b/infra/peertube-workers/ipc.cjs
new file mode 100644
index 0000000..f0ddac2
--- /dev/null
+++ b/infra/peertube-workers/ipc.cjs
@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+'use strict';
+// Uses the same IPC library/protocol as the official runner. Registration secret from stdin.
+const { Client } = require('./runtime/node_modules/@peertube/net-ipc');
+const fs = require('node:fs');
+const path = require('node:path');
+const action = process.argv[2];
+const home = process.env.HOME;
+const socket = path.join(home, '.local/share/peertube-runner-nodejs/default/peertube-runner.sock');
+const client = new Client({ path: socket, reconnect: false });
+const deadline = setTimeout(() => { client.destroy(); process.exit(1); }, 15000);
+(async () => {
+  try {
+    await client.connect();
+    let request = { type: action };
+    if (action === 'register') {
+      const cfg = JSON.parse(fs.readFileSync(process.env.PT_WORKER_CONFIG || '/etc/pt-worker/worker.json'));
+      const registrationToken = fs.readFileSync(0, 'utf8').trim();
+      if (!registrationToken.startsWith('ptrrt-')) throw new Error('bad token');
+      request = { type: 'register', url: cfg.peertube_url, runnerName: cfg.name, registrationToken,
+        runnerDescription: 'VOD only; QSV required; admission controlled' };
+    } else if (!['list-jobs', 'list-registered', 'graceful-shutdown'].includes(action)) throw new Error('bad action');
+    const result = await client.request(request);
+    if (!result.success) throw new Error('IPC failed');
+    if (action === 'list-jobs') {
+      // Drop payloads (can contain URLs); status consumers only need counts.
+      console.log(JSON.stringify({ concurrency: result.data.concurrency, active_jobs: result.data.processingJobs.length }));
+    } else if (action === 'list-registered') console.log(JSON.stringify(result.data));
+    else console.log(JSON.stringify({ success: true }));
+  } catch { console.error('Runner IPC failed; inspect local service health'); process.exitCode = 1; }
+  finally { clearTimeout(deadline); client.destroy(); }
+})();
diff --git a/infra/peertube-workers/observe.cjs b/infra/peertube-workers/observe.cjs
new file mode 100644
index 0000000..c42dcb6
--- /dev/null
+++ b/infra/peertube-workers/observe.cjs
@@ -0,0 +1,107 @@
+'use strict';
+// Transfer observation and canonical-origin routing. PeerTube retains queue selection and retries.
+const fs = require('node:fs');
+const path = require('node:path');
+const { AsyncLocalStorage } = require('node:async_hooks');
+const context = new AsyncLocalStorage();
+const state = process.env.PT_STATE_DIR || '/var/lib/pt-worker/state';
+let route;
+try {
+  const cfg = JSON.parse(fs.readFileSync(process.env.PT_WORKER_CONFIG || '/etc/pt-worker/worker.json'));
+  if (cfg.canonical_origin && cfg.peertube_url) route = { from: new URL(cfg.canonical_origin), to: new URL(cfg.peertube_url) };
+} catch { /* Enrollment and isolated tests may not yet have a config. */ }
+const originals = { 'http:': require('node:http').request, 'https:': require('node:https').request };
+function emit(data) {
+  try {
+    fs.mkdirSync(state, { recursive: true, mode: 0o700 });
+    fs.appendFileSync(path.join(state, 'events.jsonl'), JSON.stringify({ time: Date.now() / 1000, ...data }) + '\n', { mode: 0o600 });
+  } catch { /* Observation never changes job behavior. */ }
+}
+const createWriteStream = fs.createWriteStream;
+fs.createWriteStream = function (filename, ...args) {
+  const pathname = context.getStore();
+  const match = pathname?.match(/\/api\/v1\/runners\/jobs\/([a-f\d-]{36})\/files\//);
+  if (match && typeof filename === 'string') {
+    try {
+      const dir = path.join(state, 'inputs');
+      fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+      fs.writeFileSync(path.join(dir, path.basename(filename) + '.json'), JSON.stringify({ uuid: match[1] }), { mode: 0o600 });
+    } catch { /* Optional correlation only. */ }
+  }
+  return createWriteStream.call(this, filename, ...args);
+};
+require('node:module').syncBuiltinESMExports();
+for (const name of ['node:http', 'node:https']) {
+  const mod = require(name);
+  const original = mod.request;
+  mod.request = function (...args) {
+    let selected = original;
+    // Source payloads use the public origin. Route only that origin via Tailscale.
+    let options = args[0];
+    if (typeof options === 'string' || options instanceof URL) {
+      const u = new URL(options);
+      options = { protocol: u.protocol, hostname: u.hostname, port: u.port, path: u.pathname + u.search,
+        ...(typeof args[1] === 'object' ? args[1] : {}) };
+    }
+    if (route && (options.hostname || options.host) === route.from.hostname &&
+        (options.protocol || (name === 'node:https' ? 'https:' : 'http:')) === route.from.protocol &&
+        String(options.port || (route.from.protocol === 'https:' ? 443 : 80)) === String(route.from.port || (route.from.protocol === 'https:' ? 443 : 80))) {
+      const callback = typeof args[args.length - 1] === 'function' ? args[args.length - 1] : undefined;
+      options = { ...options, protocol: route.to.protocol, hostname: route.to.hostname, port: route.to.port,
+        headers: { ...(options.headers || {}), host: route.from.host } };
+      delete options.host;
+      selected = originals[route.to.protocol];
+      args = callback ? [options, callback] : [options];
+    }
+    let req;
+    if (typeof args[args.length - 1] === 'function') {
+      const callback = args[args.length - 1];
+      args[args.length - 1] = function (...values) {
+        return context.run((req.path || '').split('?')[0], () => callback.apply(this, values));
+      };
+    }
+    req = selected.apply(this, args);
+    // No host, URL, query, headers, body, or tokens are ever recorded.
+    const pathname = (req.path || '').split('?')[0];
+    const match = pathname.match(/\/api\/v1\/runners\/jobs\/([a-f\d-]{36})\/(accept|success|error|abort)/);
+    const download = pathname.includes('/files/');
+    const upload = (match && match[2] === 'success') || (req.method === 'PUT');
+    const begun = performance.now();
+    let sent = 0, received = 0, done = false, requestErrored = false;
+    function size(value, encoding) {
+      if (Buffer.isBuffer(value) || value instanceof Uint8Array) return value.length;
+      if (typeof value === 'string') return Buffer.byteLength(value, typeof encoding === 'string' ? encoding : 'utf8');
+      return 0;
+    }
+    const write = req.write;
+    req.write = function (chunk, ...rest) { sent += size(chunk, rest[0]); return write.call(this, chunk, ...rest); };
+    const end = req.end;
+    req.end = function (chunk, ...rest) { sent += size(chunk, rest[0]); return end.call(this, chunk, ...rest); };
+    function finish(ok, code) {
+      if (done) return;
+      done = true;
+      const seconds = Math.max(0.001, (performance.now() - begun) / 1000);
+      if (download || upload) emit({ kind: 'transfer', direction: download ? 'download' : 'upload',
+        bytes: download ? received : sent, seconds, ok, status_code: code || null });
+      if (match) emit({ kind: 'job_' + match[2], uuid: match[1], ok });
+    }
+    req.on('response', res => {
+      function interrupted() {
+        finish(false, res.statusCode);
+        req.destroy();
+        // A ClientRequest may already be marked destroyed when its response aborts;
+        // destroy(error) then emits nothing. Forward one error to the upstream promise.
+        queueMicrotask(() => {
+          if (!requestErrored) req.emit('error', new Error('Worker transfer stream interrupted'));
+        });
+      }
+      res.on('data', chunk => { received += chunk.length; });
+      res.once('end', () => finish(res.statusCode >= 200 && res.statusCode < 300, res.statusCode));
+      res.once('aborted', interrupted);
+      res.once('error', interrupted);
+    });
+    req.on('error', () => { requestErrored = true; finish(false); });
+    return req;
+  };
+}
+require('node:module').syncBuiltinESMExports();
diff --git a/infra/peertube-workers/pt-worker b/infra/peertube-workers/pt-worker
new file mode 100755
index 0000000..62227b0
--- /dev/null
+++ b/infra/peertube-workers/pt-worker
@@ -0,0 +1,13 @@
+#!/bin/sh
+set -eu
+# Control files and GPU tests always run as the dedicated worker user.
+if [ "$(id -u)" -eq 0 ]; then
+    case "${1:-}" in
+        start|restart) systemctl start pt-worker.service ;;
+    esac
+    exec runuser -u pt-worker -- env HOME=/var/lib/pt-worker \
+        PATH=/opt/pt-worker/node/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
+        PT_STATE_DIR=/var/lib/pt-worker/state PT_WORKER_CONFIG=/etc/pt-worker/worker.json \
+        /usr/bin/python3 /opt/pt-worker/pt-worker.py "$@"
+fi
+exec /usr/bin/python3 /opt/pt-worker/pt-worker.py "$@"
diff --git a/infra/peertube-workers/pt-worker-win.ps1 b/infra/peertube-workers/pt-worker-win.ps1
new file mode 100644
index 0000000..f71449c
--- /dev/null
+++ b/infra/peertube-workers/pt-worker-win.ps1
@@ -0,0 +1,4 @@
+param([Parameter(Position=0)][ValidateSet('status','start','stop','restart','drain','self-test','network-test')][string]$Command='status',[string]$Root='C:\pt-worker')
+$env:PT_ROOT=$Root
+& (Join-Path $Root 'bin\pt-admission.exe') $Command
+exit $LASTEXITCODE
diff --git a/infra/peertube-workers/pt-worker.py b/infra/peertube-workers/pt-worker.py
new file mode 100755
index 0000000..da1727b
--- /dev/null
+++ b/infra/peertube-workers/pt-worker.py
@@ -0,0 +1,737 @@
+#!/usr/bin/python3
+"""Whole-worker admission and operations for the official PeerTube runner."""
+import argparse
+import concurrent.futures
+import fcntl
+import importlib.util
+import json
+import os
+import re
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import tomllib
+import urllib.request
+import urllib.parse
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent
+CONFIG = Path(os.environ.get('PT_WORKER_CONFIG', '/etc/pt-worker/worker.json'))
+STATE = Path(os.environ.get('PT_STATE_DIR', '/var/lib/pt-worker/state'))
+HOME = Path(os.environ.get('PT_WORKER_HOME', '/var/lib/pt-worker'))
+RUNNER_CONFIG = HOME / '.config/peertube-runner-nodejs/default/config.toml'
+VOD = ['vod-web-video-transcoding', 'vod-hls-transcoding', 'vod-audio-merge-transcoding']
+spec = importlib.util.spec_from_file_location('qsv', ROOT / 'ffmpeg-qsv.py')
+qsv = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(qsv)
+
+
+def run(args, timeout=10):
+    return subprocess.run(args, capture_output=True, text=True, timeout=timeout, check=False)
+
+
+def atomic(path, data):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    temporary = path.with_name(path.name + '.new')
+    fd = os.open(temporary, os.O_CREAT | os.O_TRUNC | os.O_WRONLY, 0o600)
+    with os.fdopen(fd, 'w') as f:
+        json.dump(data, f, indent=2)
+        f.write('\n')
+    os.replace(temporary, path)
+
+
+def read(path, default=None):
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return {} if default is None else default
+
+
+def config():
+    value = read(CONFIG)
+    if not value.get('peertube_url') or not value.get('tailscale_peer'):
+        raise ValueError('worker.json needs peertube_url and tailscale_peer')
+    return value
+
+
+def env():
+    return {**os.environ, 'HOME': str(HOME), 'PT_STATE_DIR': str(STATE),
+            'XDG_CONFIG_HOME': str(HOME / '.config'), 'XDG_CACHE_HOME': str(HOME / '.cache'),
+            'XDG_DATA_HOME': str(HOME / '.local/share'),
+            'FFMPEG_PATH': str(ROOT / 'ffmpeg-qsv.py'), 'FFPROBE_PATH': '/usr/bin/ffprobe',
+            'NODE_OPTIONS': '--require=' + str(ROOT / 'observe.cjs')}
+
+
+def registered(cfg):
+    try:
+        data = tomllib.loads(RUNNER_CONFIG.read_text())
+        return any(r['url'].rstrip('/') == cfg['peertube_url'].rstrip('/') and
+                   r['runnerName'] == cfg['name'] and r.get('runnerToken') for r in data.get('registeredInstances', []))
+    except (OSError, ValueError, KeyError):
+        return False
+
+
+def ipc(action):
+    p = subprocess.run([config().get('node_binary', '/usr/bin/node'), str(ROOT / 'ipc.cjs'), action], env=env(),
+                       capture_output=True, text=True, timeout=5)
+    if p.returncode:
+        raise RuntimeError('runner IPC unavailable')
+    return json.loads(p.stdout)
+
+
+def network(cfg):
+    result = {'tailscale_ip': None, 'tailscale_path': 'unknown', 'latency_ms': None,
+              'network_ok': False, 'api_ok': False, 'peer_online': False}
+    try:
+        ts = json.loads(run(['tailscale', 'status', '--json'], 5).stdout)
+        result['tailscale_ip'] = next((a for a in ts.get('Self', {}).get('TailscaleIPs', []) if ':' not in a), None)
+        peers = list(ts.get('Peer', {}).values())
+        peer = next((p for p in peers if cfg['tailscale_peer'] in p.get('TailscaleIPs', []) or
+                     p.get('HostName') == cfg['tailscale_peer'] or
+                     p.get('DNSName', '').split('.')[0] == cfg['tailscale_peer']), None)
+        if ts.get('BackendState') != 'Running' or not peer or not peer.get('Online'):
+            return result
+        result['peer_online'] = True
+        p = run(['tailscale', 'ping', '--c=1', '--until-direct=false', '--timeout=3s', cfg['tailscale_peer']], 5)
+        text = p.stdout
+        if 'pong from' not in text:
+            return result
+        result['tailscale_path'] = 'DERP' if 'DERP(' in text else 'direct'
+        latency = re.search(r'in ([\d.]+)ms', text)
+        if latency:
+            result['latency_ms'] = float(latency[1])
+        started = time.monotonic()
+        with urllib.request.urlopen(cfg['peertube_url'].rstrip('/') + '/api/v1/config', timeout=4) as response:
+            version = json.load(response).get('serverVersion')
+        result['api_ok'] = version == cfg.get('peertube_version', '7.3.0')
+        result['api_latency_ms'] = (time.monotonic() - started) * 1000
+        result['network_ok'] = result['api_ok']
+    except (OSError, ValueError, subprocess.SubprocessError):
+        pass
+    return result
+
+
+def transfer_probe(cfg, megabytes=8):
+    url = cfg.get('probe_url')
+    rates = {}
+    if not url:
+        return rates
+    payload = b'pt-worker-probe-' * ((megabytes * 1024**2 // 16) + 1)
+    payload = payload[:megabytes * 1024**2]
+    for direction in ('download', 'upload'):
+        begun, count = time.monotonic(), 0
+        try:
+            req = urllib.request.Request(url.rstrip('/') + ('/download?bytes=' + str(len(payload)) if direction == 'download' else '/upload'),
+                                         data=payload if direction == 'upload' else None,
+                                         method='PUT' if direction == 'upload' else 'GET')
+            with urllib.request.urlopen(req, timeout=30) as response:
+                if direction == 'upload':
+                    count = json.load(response)['bytes_received']
+                else:
+                    while chunk := response.read(1024**2):
+                        count += len(chunk)
+            seconds = time.monotonic() - begun
+            qsv.event('transfer', direction=direction, bytes=count, seconds=seconds, ok=True, source='probe')
+            rates[direction + '_mbps'] = count * 8 / seconds / 1e6
+        except (OSError, ValueError, KeyError):
+            qsv.event('transfer', direction=direction, bytes=count, seconds=time.monotonic() - begun, ok=False, source='probe')
+            rates[direction + '_mbps'] = None
+    return rates
+
+
+def sensors():
+    temperatures = []
+    for p in Path('/sys/class/thermal').glob('thermal_zone*/temp'):
+        try:
+            temperatures.append(float(p.read_text().strip()) / 1000)
+        except (OSError, ValueError):
+            pass
+    for p in Path('/sys/class/hwmon').glob('hwmon*/temp*_input'):
+        try:
+            temperatures.append(float(p.read_text().strip()) / 1000)
+        except (OSError, ValueError):
+            pass
+    ac, batteries = [], []
+    for p in Path('/sys/class/power_supply').glob('*'):
+        try:
+            kind = (p / 'type').read_text().strip()
+            if kind in ('Mains', 'USB', 'USB_C') and (p / 'online').exists():
+                ac.append((p / 'online').read_text().strip() == '1')
+            if kind == 'Battery':
+                batteries.append({'capacity': int((p / 'capacity').read_text()),
+                                  'status': (p / 'status').read_text().strip()})
+        except (OSError, ValueError):
+            pass
+    # Native servers with no battery have an implicit permanent power supply.
+    wsl = 'microsoft' in Path('/proc/sys/kernel/osrelease').read_text().lower()
+    on_ac = any(ac) if ac else (None if wsl or batteries else True)
+    throttles = {}
+    for p in Path('/sys/devices/system/cpu').glob('cpu*/thermal_throttle/*_throttle_count'):
+        try:
+            throttles[str(p)] = int(p.read_text())
+        except (OSError, ValueError):
+            pass
+    mem = {}
+    for line in Path('/proc/meminfo').read_text().splitlines():
+        key, value = line.split(':', 1)
+        if key in ('MemTotal', 'MemAvailable'):
+            mem[key] = int(value.strip().split()[0]) * 1024
+    return {'temperature_c': max(temperatures, default=None), 'temperatures_c': temperatures,
+            'on_ac': on_ac, 'battery': batteries, 'throttle_counts': throttles,
+            'ram_total_bytes': mem.get('MemTotal'), 'ram_available_bytes': mem.get('MemAvailable'),
+            'load_average': list(os.getloadavg()), 'wsl2': wsl}
+
+
+def hardware():
+    cpu = next((l.split(':', 1)[1].strip() for l in Path('/proc/cpuinfo').read_text().splitlines()
+                if l.startswith('model name')), 'unknown')
+    gpu = []
+    for p in Path('/sys/class/drm').glob('renderD*/device'):
+        try:
+            gpu.append({'render': p.parent.name, 'vendor': (p / 'vendor').read_text().strip(),
+                        'device': (p / 'device').read_text().strip(),
+                        'driver': (p / 'driver').resolve().name})
+        except OSError:
+            pass
+    return {'cpu_model': cpu, 'gpu_model': gpu}
+
+
+class Meter:
+    def __init__(self):
+        self.data = read(STATE / 'meter.json', {'offset': 0, 'jobs_completed': 0, 'jobs_failed': 0,
+                                                'transfer_failures': 0, 'active': {}})
+
+    def invalidate(self):
+        for key in ('download', 'upload'):
+            self.data.pop(key, None)
+
+    def update(self):
+        p = STATE / 'events.jsonl'
+        if not p.exists():
+            return
+        with p.open() as f:
+            if p.stat().st_size < self.data.get('offset', 0):
+                self.data['offset'] = 0
+            f.seek(self.data.get('offset', 0))
+            while True:
+                position = f.tell()
+                line = f.readline()
+                if not line:
+                    break
+                if not line.endswith('\n'):
+                    f.seek(position)
+                    break
+                try:
+                    self.consume(json.loads(line))
+                except (ValueError, KeyError, TypeError):
+                    pass
+            self.data['offset'] = f.tell()
+        atomic(STATE / 'meter.json', self.data)
+
+    def consume(self, e):
+        kind, stamp = e['kind'], e['time']
+        if kind == 'transfer':
+            if not e['ok']:
+                self.data['transfer_failures'] = self.data.get('transfer_failures', 0) + 1
+                self.data['last_transfer_failure'] = stamp
+            elif e['bytes'] >= 65536 and e['seconds'] > 0:
+                direction = e['direction']
+                rate = e['bytes'] * 8 / e['seconds'] / 1e6
+                old = self.data.get(direction, {}).get('mbps', rate)
+                self.data[direction] = {'mbps': .3 * rate + .7 * old, 'time': stamp,
+                                        'bytes': e['bytes'], 'seconds': e['seconds']}
+        elif kind == 'gpu_failure':
+            self.data['gpu_failure_time'] = stamp
+        elif kind == 'encode':
+            self.data['last_encode'] = e
+            if e.get('job_uuid'):
+                self.data.setdefault('encodes', {})[e['job_uuid']] = e
+        elif kind == 'job_accept' and e['ok']:
+            self.data.setdefault('active', {})[e['uuid']] = stamp
+        elif kind in ('job_success', 'job_error', 'job_abort') and e['ok']:
+            begun = self.data.setdefault('active', {}).pop(e['uuid'], None)
+            if kind == 'job_success':
+                self.data['jobs_completed'] = self.data.get('jobs_completed', 0) + 1
+                elapsed = stamp - begun if begun else None
+                self.data['last_job_duration_seconds'] = elapsed
+                self.data['last_job_uuid'] = e['uuid']
+                encoded = self.data.setdefault('encodes', {}).pop(e['uuid'], {})
+                duration = encoded.get('duration')
+                self.data['last_job_realtime_factor'] = duration / elapsed if duration and elapsed else None
+                self.data['last_job_encode'] = encoded or None
+            elif kind == 'job_error':
+                self.data['jobs_failed'] = self.data.get('jobs_failed', 0) + 1
+            for path in (STATE / 'inputs').glob('*.json'):
+                if read(path).get('uuid') == e['uuid']:
+                    path.unlink(missing_ok=True)
+
+    def rates(self, now, ttl):
+        return {f'recent_{k}_mbps': self.data.get(k, {}).get('mbps')
+                if now - self.data.get(k, {}).get('time', 0) < ttl else None for k in ('download', 'upload')}
+
+
+class Admission:
+    def __init__(self, cfg):
+        self.cfg, self.good, self.bad = cfg, 0, 0
+        self.admitted, self.path, self.throttles = False, None, {}
+
+    def decide(self, sample, metric, control, now):
+        cfg = self.cfg
+        def refuse(state):
+            self.admitted, self.good = False, 0
+            return state
+        if self.path and sample['tailscale_path'] != self.path:
+            self.admitted = False
+            self.good = 0
+            metric.invalidate()
+        self.path = sample['tailscale_path']
+        rates = metric.rates(now, cfg.get('bandwidth_ttl_seconds', 900))
+        sample.update(rates)
+        if control.get('paused', True):
+            return refuse('PAUSED')
+        if not sample['registered']:
+            return refuse('PAUSED')
+        gpu_failed = metric.data.get('gpu_failure_time', 0) >= sample.get('gpu_tested_at', 0)
+        if not sample['gpu_accessible'] or not sample.get('gpu_ready') or gpu_failed:
+            return refuse('GPU_UNAVAILABLE')
+        if cfg.get('require_ac', True) and sample['on_ac'] is not True:
+            return refuse('DRAINING')
+        if sample['disk_free_bytes'] < cfg.get('min_disk_free_bytes', 20 * 1024**3):
+            return refuse('LOW_DISK')
+        rising = any(v > self.throttles.get(k, v) for k, v in sample['throttle_counts'].items())
+        self.throttles = sample['throttle_counts']
+        if rising or (sample['temperature_c'] is not None and sample['temperature_c'] >= cfg.get('max_temperature_c', 85)):
+            self.thermal_until = now + cfg.get('thermal_cooldown_seconds', 120)
+        if now < getattr(self, 'thermal_until', 0):
+            return refuse('THERMAL_THROTTLED')
+        if not sample['network_ok']:
+            self.admitted, self.good = False, 0
+            return 'OFFLINE'
+        calibrating = control.get('calibrate_until', 0) > now
+        factor = cfg.get('recovery_factor', 1.25) if not self.admitted else 1
+        bad = sample['latency_ms'] is None or sample['latency_ms'] > cfg.get('max_latency_ms', 150)
+        bad |= sample['tailscale_path'] == 'DERP' and not cfg.get('allow_derp', False)
+        if not calibrating:
+            bad |= any(rates[f'recent_{key}_mbps'] is None or rates[f'recent_{key}_mbps'] <
+                       cfg.get(f'min_{key}_mbps', 10) * factor for key in ('download', 'upload'))
+        bad |= now - metric.data.get('last_transfer_failure', 0) < cfg.get('transfer_failure_cooldown_seconds', 60)
+        if bad:
+            self.good, self.bad = 0, self.bad + 1
+            if self.bad >= cfg.get('bad_samples', 2) or not self.admitted:
+                self.admitted = False
+                return 'NETWORK_DEGRADED'
+        else:
+            self.bad, self.good = 0, self.good + 1
+            if self.good >= cfg.get('good_samples', 3):
+                self.admitted = True
+        if not self.admitted:
+            return 'NETWORK_DEGRADED'
+        return 'BUSY' if sample['active_jobs'] else 'AVAILABLE'
+
+
+class Utilization:
+    def __init__(self):
+        self.cpu, self.gpu, self.at = None, {}, time.monotonic()
+
+    def sample(self):
+        cpu = list(map(int, Path('/proc/stat').read_text().splitlines()[0].split()[1:9]))
+        gpu = {}
+        for p in Path('/proc').glob('[0-9]*'):
+            try:
+                if p.stat().st_uid == os.getuid() and (p / 'comm').read_text().strip() == 'ffmpeg':
+                    for engine, value in qsv.engines(p.name).items():
+                        gpu[(p.name, engine)] = value
+            except OSError:
+                pass
+        now = time.monotonic()
+        elapsed, result = now - self.at, {'cpu': None, 'gpu': None}
+        if self.cpu:
+            total = sum(cpu) - sum(self.cpu)
+            idle = cpu[3] + cpu[4] - self.cpu[3] - self.cpu[4]
+            result['cpu'] = (1 - idle / total) * 100 if total else None
+        if gpu:
+            by_engine = {}
+            for key, value in gpu.items():
+                if key in self.gpu:
+                    delta = max(0, value - self.gpu[key])
+                    by_engine[key[1]] = by_engine.get(key[1], 0) + delta / (elapsed * 1e9) * 100
+            result['gpu'] = by_engine or None
+        self.cpu, self.gpu, self.at = cpu, gpu, now
+        return result
+
+
+def log_runner(pipe):
+    # Upstream logs contain job tokens and sometimes runner tokens: retain only safe milestones.
+    patterns = [r'Processing job of type ([\w-]+): ([a-f\d-]{36})',
+                r'Finished processing job of type ([\w-]+): ([a-f\d-]{36})']
+    for line in pipe:
+        for pattern in patterns:
+            match = re.search(pattern, line)
+            if match:
+                qsv.event('runner_milestone', phase='completed' if 'Finished' in pattern else 'processing',
+                          job_type=match[1], uuid=match[2])
+        if 'Cannot process job' in line:
+            qsv.event('runner_error', reason='process_job_failed')
+
+
+def daemon():
+    cfg = config()
+    STATE.mkdir(parents=True, exist_ok=True)
+    lock = (STATE / 'daemon.lock').open('w')
+    fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+    meter, admission, utilization = Meter(), Admission(cfg), Utilization()
+    child, draining, stopping, restart_after, last_probe, previous_path = None, False, False, 0, 0, None
+    def stop(*_):
+        nonlocal stopping
+        stopping = True
+    signal.signal(signal.SIGTERM, stop)
+    signal.signal(signal.SIGINT, stop)
+    hw = hardware()
+    proof = read(STATE / 'qsv.json')
+    boot_id = Path('/proc/sys/kernel/random/boot_id').read_text().strip()
+    if proof.get('boot_id') != boot_id and os.access(cfg.get('render_device', '/dev/dri/renderD128'), os.R_OK | os.W_OK):
+        self_test()
+    while True:
+        now = time.time()
+        meter.update()
+        control = read(STATE / 'control.json', {'paused': True})
+        if stopping:
+            control['paused'] = True
+        if child and child.poll() is not None:
+            restart_after = now + 15
+            child, draining = None, False
+        sample = {**network(cfg), **sensors(), **hw, 'hostname': cfg['name'], 'updated_at': now,
+                  'registered': registered(cfg), 'registration_state': 'registered' if registered(cfg) else 'unregistered',
+                  'concurrency': cfg.get('concurrency', 2), 'active_jobs': 0 if not child else None,
+                  'qsv': read(STATE / 'qsv.json'), 'draining': draining}
+        gpu_health = read(Path(cfg.get('gpu_health_file', str(STATE / 'qsv.json'))))
+        sample.update(gpu_ready=gpu_health.get('hardware_video_ok', False), gpu_tested_at=gpu_health.get('tested_at', 0))
+        device = cfg.get('gpu_device', cfg.get('render_device', '/dev/dri/renderD128'))
+        sample['gpu_accessible'] = os.access(device, os.R_OK | os.W_OK)
+        disk = os.statvfs(HOME)
+        sample['disk_free_bytes'] = disk.f_bavail * disk.f_frsize
+        ipc_ok = not child
+        if child:
+            try:
+                sample.update(ipc('list-jobs'))
+                ipc_ok = True
+            except (OSError, ValueError, subprocess.SubprocessError, RuntimeError):
+                pass
+        if previous_path and previous_path != sample['tailscale_path']:
+            meter.invalidate()
+            last_probe = 0
+            admission.path = None
+            admission.admitted, admission.good = False, 0
+        previous_path = sample['tailscale_path']
+        probe_due = cfg.get('probe_url') and not control.get('paused', True) and sample['network_ok'] and \
+            sample['on_ac'] is True and sample['tailscale_path'] == 'direct' and sample['active_jobs'] == 0 and \
+            now - last_probe >= cfg.get('probe_interval_seconds', 300)
+        if probe_due and child and not draining:
+            try:
+                result = subprocess.run([cfg['runner_binary'], 'graceful-shutdown'], env=env(),
+                                        capture_output=True, text=True, timeout=5)
+                draining = result.returncode == 0
+            except (OSError, subprocess.SubprocessError):
+                pass
+        if probe_due and not child:
+            transfer_probe(cfg)
+            last_probe = now
+            meter.update()
+            sample.update(network(cfg))
+            sample.update(sensors())
+            if sample['tailscale_path'] != previous_path:
+                meter.invalidate()
+                admission.admitted, admission.good, admission.path = False, 0, None
+                last_probe = 0
+            now = time.time()
+        desired = admission.decide(sample, meter, control, now)
+        if not ipc_ok:
+            desired = 'OFFLINE'
+        allow = desired in ('AVAILABLE', 'BUSY') and not stopping
+        if child and not allow and not draining:
+            try:
+                # SIGTERM upstream aborts jobs. Use its official graceful-shutdown command instead.
+                result = subprocess.run([cfg['runner_binary'], 'graceful-shutdown'], env=env(),
+                                        capture_output=True, text=True, timeout=5)
+                draining = result.returncode == 0
+                if draining:
+                    qsv.event('drain', reason=desired)
+            except (OSError, subprocess.SubprocessError):
+                pass
+        if not child and allow and now >= restart_after:
+            child = subprocess.Popen([cfg['runner_binary'], 'server', *sum([['--enable-job', j] for j in VOD], [])],
+                                     env=env(), stdout=subprocess.PIPE, stderr=subprocess.STDOUT, text=True,
+                                     start_new_session=True)
+            threading.Thread(target=log_runner, args=(child.stdout,), daemon=True).start()
+        sample.update({'status': 'DRAINING' if draining and desired in ('AVAILABLE', 'BUSY') else desired,
+                       'draining': draining, 'runner_running': child is not None,
+                       'qsv_h264_ok': sample['qsv'].get('qsv_h264_ok'),
+                       'qsv_hevc_ok': sample['qsv'].get('qsv_hevc_ok'),
+                       'util': utilization.sample(),
+                       **{k: meter.data.get(k) for k in ('jobs_completed', 'jobs_failed', 'transfer_failures',
+                         'last_job_uuid', 'last_job_duration_seconds', 'last_job_realtime_factor', 'last_job_encode', 'last_encode')}})
+        # Null is intentional until the corresponding measurement has been made.
+        atomic(STATE / 'status.json', sample)
+        if stopping and child is None:
+            return
+        # After suspend, wall-clock gaps force a fresh path/throughput evaluation.
+        before = time.time()
+        time.sleep(cfg.get('poll_seconds', 5))
+        if time.time() - before > cfg.get('poll_seconds', 5) * 3:
+            meter.invalidate()
+            admission.admitted, admission.good = False, 0
+
+
+def measured(command, log):
+    started = time.monotonic()
+    maximum, samples = {}, []
+    with log.open('w') as f:
+        p = subprocess.Popen(command, stdout=f, stderr=subprocess.STDOUT)
+        while p.poll() is None:
+            for k, v in qsv.engines(p.pid).items():
+                maximum[k] = max(maximum.get(k, 0), v)
+            samples.append(sensors())
+            if time.monotonic() - started > 180:
+                p.kill()
+                p.wait()
+                break
+            time.sleep(.1)
+    return {'returncode': p.returncode, 'seconds': time.monotonic() - started,
+            'engine_ns': maximum, 'max_temperature_c': max((s['temperature_c'] for s in samples
+                 if s['temperature_c'] is not None), default=None),
+            'min_available_ram_bytes': min((s['ram_available_bytes'] for s in samples), default=None)}
+
+
+def self_test():
+    cfg = config()
+    device = cfg.get('render_device', '/dev/dri/renderD128')
+    STATE.mkdir(parents=True, exist_ok=True)
+    report = {**hardware(), 'tested_at': time.time(), 'boot_id': Path('/proc/sys/kernel/random/boot_id').read_text().strip(),
+              'qsv_h264_ok': False, 'qsv_hevc_ok': False,
+              'av1_decode_ok': None, 'av1_encode_ok': None, 'tests': {}, 'device': device}
+    diagnostics = STATE / 'self-test'
+    diagnostics.mkdir(exist_ok=True)
+    for name, command in [('ffmpeg-version', ['/usr/bin/ffmpeg', '-version']),
+                          ('hwaccels', ['/usr/bin/ffmpeg', '-hwaccels']),
+                          ('encoders', ['/usr/bin/ffmpeg', '-encoders']),
+                          ('vainfo', ['vainfo', '--display', 'drm', '--device', device])]:
+        try:
+            p = run(command, 20)
+            (diagnostics / (name + '.log')).write_text(p.stdout + p.stderr)
+            report[name + '_exit'] = p.returncode
+        except (OSError, subprocess.SubprocessError):
+            report[name + '_exit'] = None
+    if not os.access(device, os.R_OK | os.W_OK):
+        report['reason'] = 'render device missing or inaccessible; hardware tests did not run'
+        atomic(STATE / 'qsv.json', report)
+        print(json.dumps(report, indent=2))
+        return 1
+    with tempfile.TemporaryDirectory(prefix='selftest-', dir=STATE) as directory:
+        tmp = Path(directory)
+        source = tmp / 'source.mp4'
+        # CPU x264 is used ONLY to create synthetic test input, outside the runner.
+        p = run(['/usr/bin/ffmpeg', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=1920x1080:rate=30',
+                 '-f', 'lavfi', '-i', 'sine=frequency=1000:sample_rate=48000', '-t', '10', '-c:v', 'libx264',
+                 '-threads', '2', '-preset', 'ultrafast', '-pix_fmt', 'yuv420p', '-c:a', 'aac', str(source)], 90)
+        if p.returncode:
+            report['reason'] = 'test fixture creation failed'
+        else:
+            base = ['/usr/bin/ffmpeg', '-v', 'verbose', '-init_hw_device', f'vaapi=va:{device}',
+                    '-init_hw_device', 'qsv=qs@va', '-filter_hw_device', 'qs', '-hwaccel', 'qsv',
+                    '-hwaccel_output_format', 'qsv', '-c:v', 'h264_qsv', '-i', str(source),
+                    '-vf', 'scale_qsv=w=1280:h=720:format=nv12', '-an']
+            for codec, key in [('h264', 'qsv_h264_ok'), ('hevc', 'qsv_hevc_ok'), ('av1', 'av1_encode_ok')]:
+                out = tmp / (codec + '.mp4')
+                result = measured([*base, '-c:v', codec + '_qsv', '-b:v', '2M', str(out)], diagnostics / (codec + '.log'))
+                result['hardware_engine_evidence'] = any(v > 0 for k, v in result['engine_ns'].items() if k.startswith('video'))
+                report['tests'][codec] = result
+                report[key] = result['returncode'] == 0 and result['hardware_engine_evidence']
+                if result['returncode'] == 0:
+                    report['tests'][codec]['output_probe'] = qsv.probe(str(out))
+            if report['qsv_hevc_ok']:
+                command = base[:base.index('-c:v')] + ['-re', '-c:v', 'hevc_qsv', '-i', str(tmp / 'hevc.mp4'),
+                    '-vf', 'scale_qsv=w=640:h=360:format=nv12', '-an', '-c:v', 'h264_qsv', '-f', 'null', '-']
+                result = measured(command, diagnostics / 'hevc-decode.log')
+                report['tests']['hevc_decode'] = result
+                report['qsv_hevc_decode_ok'] = result['returncode'] == 0 and any(v > 0 for k, v in result['engine_ns'].items() if k.startswith('video'))
+            av1_source = tmp / 'av1-source.mkv'
+            p = run(['/usr/bin/ffmpeg', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=640x360:rate=30',
+                     '-t', '2', '-c:v', 'libaom-av1', '-threads', '2', '-cpu-used', '8', str(av1_source)], 90)
+            if p.returncode == 0:
+                command = base[:base.index('-c:v')] + ['-re', '-c:v', 'av1_qsv', '-i', str(av1_source),
+                    '-vf', 'scale_qsv=w=640:h=360:format=nv12', '-an', '-c:v', 'h264_qsv', '-f', 'null', '-']
+                result = measured(command, diagnostics / 'av1-decode.log')
+                report['tests']['av1_decode'] = result
+                report['av1_decode_ok'] = result['returncode'] == 0 and any(v > 0 for k, v in result['engine_ns'].items() if k.startswith('video'))
+            # Exercise the adapter itself; compare with the direct QSV tests.
+            command = [str(ROOT / 'ffmpeg-qsv.py'), '-i', str(source), '-vcodec', 'libx264',
+                       '-vf', 'scale=w=-2:h=720', '-pix_fmt', 'yuv420p', '-preset', 'veryfast',
+                       '-maxrate:v', '2000000', '-bufsize:v', '4000000', '-b_strategy', '1', '-bf', '16',
+                       '-g:v', '60', '-r', '30', '-c:a', 'aac', str(tmp / 'adapter.mp4')]
+            p = subprocess.run(command, env=env(), capture_output=True, text=True, timeout=90)
+            (diagnostics / 'adapter.log').write_text(p.stderr)
+            report['adapter_exit'] = p.returncode
+            report['qsv_h264_ok'] &= p.returncode == 0
+    # The admission controller compares this timestamp to failures emitted by earlier tests.
+    report['tested_at'] = time.time()
+    report['hardware_video_ok'] = report['qsv_h264_ok']
+    report['backend'] = 'intel_qsv'
+    atomic(STATE / 'qsv.json', report)
+    print(json.dumps(report, indent=2))
+    return 0 if report['qsv_h264_ok'] else 1
+
+
+def network_test(args):
+    """Real HTTP throughput against explicit disposable operator-supplied endpoints."""
+    cfg = config()
+    report = network(cfg)
+    if not args.download_url or not args.upload_url:
+        if cfg.get('probe_url'):
+            rates = transfer_probe(cfg, min(args.megabytes, 16))
+            print(json.dumps({**report, **rates, 'throughput_measured': all(v is not None for v in rates.values())}, indent=2))
+            return 0 if all(v is not None for v in rates.values()) else 1
+        print(json.dumps({**report, 'throughput_measured': False,
+              'reason': 'supply --download-url and --upload-url for disposable fixtures; API ping is not bandwidth'}, indent=2))
+        return 1
+    rates = {}
+    for direction, url in [('download', args.download_url), ('upload', args.upload_url)]:
+        # Test URLs must remain within the same PeerTube/storage route.
+        if urllib.parse.urlparse(url).hostname != urllib.parse.urlparse(cfg['peertube_url']).hostname:
+            raise ValueError('test URL must use configured PeerTube host')
+        count, begun = 0, time.monotonic()
+        try:
+            req = urllib.request.Request(url)
+            if direction == 'upload':
+                req = urllib.request.Request(url, data=os.urandom(args.megabytes * 1024**2), method='PUT')
+                count = args.megabytes * 1024**2
+            with urllib.request.urlopen(req, timeout=60) as response:
+                while chunk := response.read(1024**2):
+                    if direction == 'download':
+                        count += len(chunk)
+            seconds = time.monotonic() - begun
+            qsv.event('transfer', direction=direction, bytes=count, seconds=seconds, ok=True)
+            rates[direction + '_mbps'] = count * 8 / seconds / 1e6
+        except OSError:
+            qsv.event('transfer', direction=direction, bytes=count, seconds=time.monotonic() - begun, ok=False)
+            rates[direction + '_mbps'] = None
+    print(json.dumps({**report, **rates, 'throughput_measured': all(v is not None for v in rates.values())}, indent=2))
+    return 0 if all(v is not None for v in rates.values()) else 1
+
+
+def benchmark(args):
+    status = read(STATE / 'status.json')
+    if status.get('runner_running'):
+        raise ValueError('drain worker and wait for runner_running=false before benchmarking')
+    source = Path(args.source).resolve()
+    probe = qsv.probe(str(source))
+    duration = float(probe.get('format', {}).get('duration', 0))
+    records = []
+    with tempfile.TemporaryDirectory(prefix='benchmark-', dir=STATE) as directory:
+        tmp = Path(directory)
+        for concurrency in (1, 2, 3, 4):
+            def job(index):
+                out = tmp / f'{concurrency}-{index}.mp4'
+                cmd = [str(ROOT / 'ffmpeg-qsv.py'), '-i', str(source), '-vcodec', 'libx264',
+                       '-vf', 'scale=w=-2:h=720', '-pix_fmt', 'yuv420p', '-maxrate:v', '2000000',
+                       '-bufsize:v', '4000000', '-r', '30', '-an', str(out)]
+                start = time.monotonic()
+                p = subprocess.run(cmd, env=env(), capture_output=True, text=True, timeout=600)
+                elapsed = time.monotonic() - start
+                out.unlink(missing_ok=True)
+                return {'seconds': elapsed, 'realtime_factor': duration / elapsed,
+                        'fps': duration * 30 / elapsed, 'returncode': p.returncode}
+            start, samples, util_samples = time.monotonic(), [], []
+            utilization = Utilization()
+            with concurrent.futures.ThreadPoolExecutor(max_workers=concurrency) as executor:
+                futures = [executor.submit(job, i) for i in range(concurrency)]
+                while not all(f.done() for f in futures):
+                    samples.append(sensors())
+                    util_samples.append(utilization.sample())
+                    time.sleep(.5)
+                jobs = [f.result() for f in futures]
+            wall = time.monotonic() - start
+            records.append({'concurrency': concurrency, 'wall_seconds': wall, 'jobs': jobs,
+                            'aggregate_media_seconds_per_second': concurrency * duration / wall,
+                            'max_temperature_c': max((s['temperature_c'] for s in samples
+                               if s['temperature_c'] is not None), default=None),
+                            'min_available_ram_bytes': min((s['ram_available_bytes'] for s in samples), default=None),
+                            'utilization_samples': util_samples,
+                            'throttle_counts_start': samples[0]['throttle_counts'] if samples else {},
+                            'throttle_counts_end': samples[-1]['throttle_counts'] if samples else {},
+                            'recent_download_mbps': None, 'recent_upload_mbps': None})
+    report = {'scope': 'local encode diagnostic; choose production concurrency from real end-to-end jobs',
+              'source_duration': duration, 'results': records, 'production_concurrency_selected': None}
+    atomic(STATE / 'benchmark.json', report)
+    print(json.dumps(report, indent=2))
+    return 0 if all(j['returncode'] == 0 for r in records for j in r['jobs']) else 1
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    sub = parser.add_subparsers(dest='command', required=True)
+    for name in ('daemon', 'status', 'start', 'stop', 'restart', 'drain', 'self-test'):
+        p = sub.add_parser(name)
+        if name == 'start':
+            p.add_argument('--calibrate', action='store_true', help='explicit 10-minute initial job measurement window')
+        if name == 'status':
+            p.add_argument('--prometheus', action='store_true')
+    p = sub.add_parser('network-test')
+    p.add_argument('--download-url')
+    p.add_argument('--upload-url')
+    p.add_argument('--megabytes', type=int, default=16)
+    p = sub.add_parser('benchmark')
+    p.add_argument('--source', required=True)
+    args = parser.parse_args()
+    if args.command == 'daemon':
+        return daemon()
+    if args.command == 'status':
+        empty = {k: None for k in ('tailscale_ip', 'tailscale_path', 'registration_state', 'cpu_model', 'gpu_model',
+                  'qsv_h264_ok', 'qsv_hevc_ok', 'active_jobs', 'concurrency', 'util', 'temperature_c', 'temperatures_c',
+                  'disk_free_bytes', 'recent_download_mbps', 'recent_upload_mbps', 'jobs_completed', 'jobs_failed',
+                  'last_job_duration_seconds', 'last_job_realtime_factor')}
+        value = read(STATE / 'status.json', {**empty, 'hostname': socket.gethostname(), 'status': 'OFFLINE'})
+        if time.time() - value.get('updated_at', 0) > 60:
+            value['status'] = 'OFFLINE'
+            value['stale'] = True
+        if args.prometheus:
+            print('pt_worker_available ' + str(int(value.get('status') in ('AVAILABLE', 'BUSY'))))
+            for key in ('active_jobs', 'concurrency', 'disk_free_bytes', 'temperature_c', 'recent_download_mbps',
+                        'recent_upload_mbps', 'jobs_completed', 'jobs_failed'):
+                if isinstance(value.get(key), (int, float)):
+                    print('pt_worker_' + key + ' ' + str(value[key]))
+        else:
+            print(json.dumps(value, indent=2))
+        return 0
+    if args.command in ('start', 'stop', 'restart', 'drain'):
+        control = {'paused': args.command in ('stop', 'drain'),
+                   'calibrate_until': time.time() + 600 if getattr(args, 'calibrate', False) else 0}
+        atomic(STATE / 'control.json', control)
+        if args.command == 'restart':
+            # Drain first; the controller restarts the child after it exits, preserving registration.
+            try:
+                subprocess.run([config()['runner_binary'], 'graceful-shutdown'], env=env(),
+                               capture_output=True, timeout=5, check=True)
+            except (OSError, subprocess.SubprocessError):
+                pass
+        print(json.dumps({'requested': args.command, **control}))
+        return 0
+    if args.command == 'self-test':
+        if read(STATE / 'status.json').get('runner_running'):
+            raise ValueError('drain and wait for runner_running=false before self-test')
+        return self_test()
+    if args.command == 'network-test':
+        return network_test(args)
+    if args.command == 'benchmark':
+        return benchmark(args)
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main() or 0)
+    except (ValueError, RuntimeError, OSError, subprocess.SubprocessError) as error:
+        print('pt-worker: ' + str(error), file=sys.stderr)
+        sys.exit(1)
diff --git a/infra/peertube-workers/runtime-package-lock.json b/infra/peertube-workers/runtime-package-lock.json
new file mode 100644
index 0000000..dab36cb
--- /dev/null
+++ b/infra/peertube-workers/runtime-package-lock.json
@@ -0,0 +1,172 @@
+{
+  "name": "pt-worker-runtime",
+  "version": "1.0.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "pt-worker-runtime",
+      "version": "1.0.0",
+      "dependencies": {
+        "@peertube/net-ipc": "2.2.0",
+        "@peertube/peertube-runner": "0.2.0"
+      }
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-darwin-arm64": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-darwin-arm64/-/msgpackr-extract-darwin-arm64-3.0.4.tgz",
+      "integrity": "sha512-LCkGo6JDfaBhgST7UpPWgNgLINpcpabaHfyz5OBx75nUYxBsaEPxjnyNjWpeb/xBup/682QnBfRBy2/LvPutZQ==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-darwin-x64": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-darwin-x64/-/msgpackr-extract-darwin-x64-3.0.4.tgz",
+      "integrity": "sha512-zExlW9zUJKZH/tOtVMttwjKa4Xm/3KcNjnE3dPN92uCktwavMxpgCA3MoJK/DOnTWsQgo224OaST27/mPNAf+w==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "darwin"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-linux-arm": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-arm/-/msgpackr-extract-linux-arm-3.0.4.tgz",
+      "integrity": "sha512-Tg3yX65f5GbtXLkrYEHE5oibZG9epyYWas7FogTTEJeDEF9JlXJzKgXaNhT3UXlTOeA+AfZpYZYZ0uPj7Cfquw==",
+      "cpu": [
+        "arm"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-linux-arm64": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-arm64/-/msgpackr-extract-linux-arm64-3.0.4.tgz",
+      "integrity": "sha512-dgX0P/9wGPJeHFBG+ZmhgE6bmtMt7NP5CRBGyyktpopdk/mW4POnrpQsSLtKI1dwpc+pPLuXHDh6vvskyQE/sw==",
+      "cpu": [
+        "arm64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-linux-x64": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-linux-x64/-/msgpackr-extract-linux-x64-3.0.4.tgz",
+      "integrity": "sha512-8TNXMEjJc3QEy7R/x1INhgiU+XakDAFUzBhaz7+Rbrs8NH5UQeHQxxmzsSBJGyV6I1jW79undiQm8tOI+D+8FQ==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "linux"
+      ]
+    },
+    "node_modules/@msgpackr-extract/msgpackr-extract-win32-x64": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/@msgpackr-extract/msgpackr-extract-win32-x64/-/msgpackr-extract-win32-x64-3.0.4.tgz",
+      "integrity": "sha512-CmCXPQrkbwExx3j946/PtHWHbYJiCRBRDl4BlkRQcJB/YOwQxJRTpoo7aTsortjgoJ1x7opzTSxn7C+ASSLVjQ==",
+      "cpu": [
+        "x64"
+      ],
+      "optional": true,
+      "os": [
+        "win32"
+      ]
+    },
+    "node_modules/@peertube/net-ipc": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@peertube/net-ipc/-/net-ipc-2.2.0.tgz",
+      "integrity": "sha512-fcKrTuYRlpUpwX//eaU6t11Boeqa/RY9yzCuIw/4e/jygcTd6ZQ3jTOUv6ABm06yiQTI+W/Tx9fyebFSLaTf9A==",
+      "deprecated": "Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.",
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "optionalDependencies": {
+        "fast-zlib": "^2.0.1",
+        "msgpackr": "^1.3.2"
+      }
+    },
+    "node_modules/@peertube/peertube-runner": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/@peertube/peertube-runner/-/peertube-runner-0.2.0.tgz",
+      "integrity": "sha512-xawEdU9oGKNtMGyRdypEcNg4dyNCvYtg0MHfxA6tB81qWFhc5U2Of3DfYq5iz9UDIj0DVFxVdMijPtc5pkfSCw==",
+      "bin": {
+        "peertube-runner": "dist/peertube-runner.js"
+      }
+    },
+    "node_modules/detect-libc": {
+      "version": "2.1.2",
+      "resolved": "https://registry.npmjs.org/detect-libc/-/detect-libc-2.1.2.tgz",
+      "integrity": "sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==",
+      "optional": true,
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/fast-zlib": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/fast-zlib/-/fast-zlib-2.0.1.tgz",
+      "integrity": "sha512-DCoYgNagM2Bt1VIpXpdGnRx4LzqJeYG0oh6Nf/7cWo6elTXkFGMw9CrRCYYUIapYNrozYMoyDRflx9mgT3Awyw==",
+      "optional": true,
+      "funding": {
+        "type": "patreon",
+        "url": "https://patreon.com/timotejroiko"
+      }
+    },
+    "node_modules/msgpackr": {
+      "version": "1.12.1",
+      "resolved": "https://registry.npmjs.org/msgpackr/-/msgpackr-1.12.1.tgz",
+      "integrity": "sha512-4EUH9tQHnMmEgzW/MdAP0KIfa1T9AF+htl0ffe2n5vb2EKn9y2co8ccpgWko6S52Jy1PQZKwRnx5/KkYjtd9MQ==",
+      "optional": true,
+      "optionalDependencies": {
+        "msgpackr-extract": "^3.0.2"
+      }
+    },
+    "node_modules/msgpackr-extract": {
+      "version": "3.0.4",
+      "resolved": "https://registry.npmjs.org/msgpackr-extract/-/msgpackr-extract-3.0.4.tgz",
+      "integrity": "sha512-4kmO/MdyUIkLIvTPr8VHLil4AtoKIoniWPIEk5+CDy0xnWC84azhSFmuJ7PxZdsYtiP5kEeQsORAVIeMgxT+Hw==",
+      "hasInstallScript": true,
+      "optional": true,
+      "dependencies": {
+        "node-gyp-build-optional-packages": "5.2.2"
+      },
+      "bin": {
+        "download-msgpackr-prebuilds": "bin/download-prebuilds.js"
+      },
+      "optionalDependencies": {
+        "@msgpackr-extract/msgpackr-extract-darwin-arm64": "3.0.4",
+        "@msgpackr-extract/msgpackr-extract-darwin-x64": "3.0.4",
+        "@msgpackr-extract/msgpackr-extract-linux-arm": "3.0.4",
+        "@msgpackr-extract/msgpackr-extract-linux-arm64": "3.0.4",
+        "@msgpackr-extract/msgpackr-extract-linux-x64": "3.0.4",
+        "@msgpackr-extract/msgpackr-extract-win32-x64": "3.0.4"
+      }
+    },
+    "node_modules/node-gyp-build-optional-packages": {
+      "version": "5.2.2",
+      "resolved": "https://registry.npmjs.org/node-gyp-build-optional-packages/-/node-gyp-build-optional-packages-5.2.2.tgz",
+      "integrity": "sha512-s+w+rBWnpTMwSFbaE0UXsRlg7hU4FjekKU4eyAih5T8nJuNZT1nNsskXpxmeqSK9UzkBl6UgRlnKc8hz8IEqOw==",
+      "optional": true,
+      "dependencies": {
+        "detect-libc": "^2.0.1"
+      },
+      "bin": {
+        "node-gyp-build-optional-packages": "bin.js",
+        "node-gyp-build-optional-packages-optional": "optional.js",
+        "node-gyp-build-optional-packages-test": "build-test.js"
+      }
+    }
+  }
+}
diff --git a/infra/peertube-workers/runtime-package.json b/infra/peertube-workers/runtime-package.json
new file mode 100644
index 0000000..2b26d9f
--- /dev/null
+++ b/infra/peertube-workers/runtime-package.json
@@ -0,0 +1,9 @@
+{
+  "name": "pt-worker-runtime",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@peertube/peertube-runner": "0.2.0",
+    "@peertube/net-ipc": "2.2.0"
+  }
+}
diff --git a/infra/peertube-workers/systemd/pt-worker-netprobe.service b/infra/peertube-workers/systemd/pt-worker-netprobe.service
new file mode 100644
index 0000000..ea6836f
--- /dev/null
+++ b/infra/peertube-workers/systemd/pt-worker-netprobe.service
@@ -0,0 +1,32 @@
+[Unit]
+Description=Bounded PeerTube worker throughput probe (Tailscale only)
+After=tailscaled.service network-online.target
+Wants=tailscaled.service network-online.target
+StartLimitIntervalSec=300
+StartLimitBurst=10
+
+[Service]
+Type=notify
+NotifyAccess=main
+TimeoutStartSec=45
+User=pt-netprobe
+Group=pt-netprobe
+ExecStart=/usr/bin/python3 /opt/pt-worker-netprobe/bandwidth-probe.py --bind 100.92.231.98 --port 9044
+Restart=always
+RestartSec=30
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+PrivateTmp=true
+PrivateDevices=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+CapabilityBoundingSet=
+RestrictAddressFamilies=AF_INET AF_UNIX
+MemoryMax=96M
+TasksMax=16
+CPUQuota=20%
+
+[Install]
+WantedBy=multi-user.target
diff --git a/infra/peertube-workers/systemd/pt-worker.service b/infra/peertube-workers/systemd/pt-worker.service
new file mode 100644
index 0000000..d20c55d
--- /dev/null
+++ b/infra/peertube-workers/systemd/pt-worker.service
@@ -0,0 +1,37 @@
+[Unit]
+Description=PeerTube VOD runner with hardware and network admission
+Wants=network-online.target tailscaled.service
+After=network-online.target tailscaled.service
+StartLimitIntervalSec=300
+StartLimitBurst=10
+
+[Service]
+Type=simple
+User=pt-worker
+Group=pt-worker
+Environment=HOME=/var/lib/pt-worker
+Environment=PATH=/opt/pt-worker/node/bin:/usr/local/bin:/usr/bin:/bin
+Environment=PT_STATE_DIR=/var/lib/pt-worker/state
+Environment=PT_WORKER_CONFIG=/etc/pt-worker/worker.json
+UMask=0077
+ExecStart=/usr/bin/python3 /opt/pt-worker/pt-worker.py daemon
+Restart=always
+RestartSec=30
+# Controller uses runner graceful-shutdown; do not send SIGTERM to FFmpeg on initial stop.
+KillMode=mixed
+TimeoutStopSec=infinity
+NoNewPrivileges=true
+ProtectSystem=strict
+ProtectHome=true
+ReadWritePaths=/var/lib/pt-worker
+PrivateTmp=true
+ProtectKernelTunables=true
+ProtectKernelModules=true
+ProtectControlGroups=true
+RestrictSUIDSGID=true
+LockPersonality=true
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6 AF_NETLINK
+CapabilityBoundingSet=
+
+[Install]
+WantedBy=multi-user.target
diff --git a/infra/peertube-workers/tests/runner_smoke.py b/infra/peertube-workers/tests/runner_smoke.py
new file mode 100644
index 0000000..73aa656
--- /dev/null
+++ b/infra/peertube-workers/tests/runner_smoke.py
@@ -0,0 +1,128 @@
+#!/usr/bin/python3
+"""Integration test with published runner against a loopback API; no production calls."""
+import argparse
+import http.server
+import json
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+import time
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+UUID = '22222222-2222-4222-8222-222222222222'
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('--node', required=True)
+    parser.add_argument('--runtime', required=True, help='directory containing installed runtime node_modules')
+    args = parser.parse_args()
+    with tempfile.TemporaryDirectory(prefix='pt-runner-smoke-') as directory:
+        tmp = Path(directory)
+        home, state = tmp / 'home', tmp / 'state'
+        home.mkdir(); state.mkdir()
+        (tmp / 'runtime').symlink_to(Path(args.runtime).resolve(), target_is_directory=True)
+        shutil.copy(ROOT / 'ipc.cjs', tmp / 'ipc.cjs')
+        fixture = tmp / 'source.mp4'
+        subprocess.run(['/usr/bin/ffmpeg', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=64x64:rate=2',
+                        '-t', '1', '-c:v', 'libx264', '-threads', '1', str(fixture)], check=True)
+        requests, accepted, failures = [], threading.Event(), threading.Event()
+        registered_count = 0
+        offered = False
+        class API(http.server.BaseHTTPRequestHandler):
+            def log_message(self, *_): pass
+            def do_POST(self):
+                nonlocal registered_count, offered
+                length = int(self.headers.get('Content-Length', 0))
+                self.rfile.read(length)  # discarded; never log credentials
+                requests.append(self.path)
+                if self.path == '/api/v1/runners/register':
+                    registered_count += 1
+                    return self.reply({'runnerToken': 'ptrt-local-test-only'})
+                if self.path == '/api/v1/runners/jobs/request':
+                    jobs = [] if offered or not registered_count else [{'uuid': UUID, 'type': 'vod-web-video-transcoding',
+                        'payload': {'input': {'videoFileUrl': f'https://canonical.invalid/api/v1/runners/jobs/{UUID}/files/videos/source/max-quality',
+                                              'separatedAudioFileUrl': []}, 'output': {'resolution': 64, 'fps': 2}}}]
+                    return self.reply({'availableJobs': jobs})
+                if self.path.endswith('/accept'):
+                    offered = True
+                    accepted.set()
+                    return self.reply({'job': {'uuid': UUID, 'type': 'vod-web-video-transcoding', 'jobToken': 'local-job-secret',
+                        'payload': {'input': {'videoFileUrl': f'https://canonical.invalid/api/v1/runners/jobs/{UUID}/files/videos/source/max-quality',
+                                              'separatedAudioFileUrl': []}, 'output': {'resolution': 64, 'fps': 2}}}})
+                if '/files/' in self.path:
+                    blob = fixture.read_bytes()
+                    self.send_response(200); self.send_header('Content-Length', str(len(blob))); self.end_headers()
+                    self.wfile.write(blob)
+                    return
+                if self.path.endswith('/error'):
+                    failures.set()
+                self.send_response(204); self.end_headers()
+            def reply(self, data):
+                blob = json.dumps(data).encode()
+                self.send_response(200); self.send_header('Content-Type', 'application/json')
+                self.send_header('Content-Length', str(len(blob))); self.end_headers(); self.wfile.write(blob)
+        server = http.server.ThreadingHTTPServer(('127.0.0.1', 0), API)
+        threading.Thread(target=server.serve_forever, daemon=True).start()
+        url = f'http://127.0.0.1:{server.server_port}'
+        cfg = tmp / 'worker.json'
+        cfg.write_text(json.dumps({'name': 'smoke-worker', 'peertube_url': url, 'canonical_origin': 'https://canonical.invalid'}))
+        env = {**os.environ, 'HOME': str(home), 'XDG_CONFIG_HOME': str(home / '.config'),
+               'XDG_CACHE_HOME': str(home / '.cache'), 'XDG_DATA_HOME': str(home / '.local/share'),
+               'PT_WORKER_CONFIG': str(cfg), 'PT_STATE_DIR': str(state),
+               'PT_RENDER_DEVICE': str(tmp / 'missing-render'), 'FFMPEG_PATH': str(ROOT / 'ffmpeg-qsv.py'),
+               'FFPROBE_PATH': '/usr/bin/ffprobe', 'NODE_OPTIONS': '--require=' + str(ROOT / 'observe.cjs')}
+        runner = Path(args.runtime) / 'node_modules/@peertube/peertube-runner/dist/peertube-runner.js'
+        runner_config = home / '.config/peertube-runner-nodejs/default/config.toml'
+        runner_config.parent.mkdir(parents=True)
+        runner_config.write_text('[jobs]\nconcurrency=0\n[ffmpeg]\nthreads=2\nnice=20\n')
+        socket = home / '.local/share/peertube-runner-nodejs/default/peertube-runner.sock'
+        children = []
+        def start():
+            child = subprocess.Popen([args.node, str(runner), 'server', '--enable-job', 'vod-web-video-transcoding'],
+                                     env=env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+            children.append(child)
+            for _ in range(100):
+                if socket.exists():
+                    p = subprocess.run([args.node, str(tmp / 'ipc.cjs'), 'list-jobs'], env=env, capture_output=True, timeout=3)
+                    if p.returncode == 0: return child
+                if child.poll() is not None: raise AssertionError('runner exited')
+                time.sleep(.1)
+            raise AssertionError('IPC socket unavailable')
+        def call(command, data=None):
+            return subprocess.run([args.node, str(tmp / 'ipc.cjs'), command], input=data,
+                                  env=env, capture_output=True, text=True, timeout=20, check=True)
+        try:
+            child = start()
+            call('register', 'ptrrt-local-test-only')
+            assert registered_count == 1
+            assert json.loads(call('list-jobs').stdout)['active_jobs'] == 0
+            call('graceful-shutdown'); child.wait(timeout=10)
+            assert not accepted.is_set(), 'enrollment accepted a job at concurrency=0'
+            runner_config.write_text(runner_config.read_text().replace('concurrency = 0', 'concurrency = 1'))
+            socket.unlink(missing_ok=True)
+            child = start()
+            assert accepted.wait(15), 'job not accepted'
+            assert failures.wait(15), 'missing QSV did not report job failure'
+            call('graceful-shutdown'); child.wait(timeout=10)
+            assert registered_count == 1, 'restart duplicated registration'
+            transcoding = home / '.cache/peertube-runner-nodejs/default/transcoding'
+            assert not list(transcoding.iterdir()), 'temporary files not cleaned'
+            events = (state / 'events.jsonl').read_text()
+            assert 'gpu_failure' in events
+            assert 'local-job-secret' not in events and 'ptrt-local-test-only' not in events
+            assert not any(p.endswith('/success') for p in requests), 'failed QSV uploaded output'
+            assert any('/files/' in p for p in requests), 'canonical source was not routed to loopback'
+            print('PASS: official runner 0.2.0 registration via secret stdin, concurrency=0 enrollment, restart without re-registration, source routing, QSV failure reporting, graceful shutdown, tmp cleanup')
+        finally:
+            for child in children:
+                if child.poll() is None:
+                    child.kill(); child.wait()
+            server.shutdown(); server.server_close()
+
+
+if __name__ == '__main__':
+    main()
diff --git a/infra/peertube-workers/tests/test_observer.cjs b/infra/peertube-workers/tests/test_observer.cjs
new file mode 100644
index 0000000..33b4170
--- /dev/null
+++ b/infra/peertube-workers/tests/test_observer.cjs
@@ -0,0 +1,62 @@
+'use strict';
+// Real loopback transfers exercise routing, byte counts, file/job correlation, and secret exclusion.
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+const os = require('node:os');
+const assert = require('node:assert/strict');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'pt-observer-'));
+const uuid = '11111111-1111-4111-8111-111111111111';
+const source = Buffer.alloc(300000, 7);
+let uploaded = 0;
+const server = http.createServer((req, res) => {
+  if (req.url.includes('/files/abort')) {
+    res.writeHead(200, { 'Content-Length': '1000000' });
+    res.write(Buffer.alloc(1000)); setTimeout(() => res.destroy(), 20);
+  } else if (req.url.includes('/files/')) { res.writeHead(200); res.end(source); }
+  else {
+    req.on('data', chunk => { uploaded += chunk.length; });
+    req.on('end', () => { res.writeHead(204); res.end(); });
+  }
+});
+server.listen(0, '127.0.0.1', async () => {
+  const port = server.address().port;
+  const cfg = path.join(tmp, 'worker.json');
+  fs.writeFileSync(cfg, JSON.stringify({ canonical_origin: 'https://canonical.invalid', peertube_url: `http://127.0.0.1:${port}` }));
+  process.env.PT_WORKER_CONFIG = cfg;
+  process.env.PT_STATE_DIR = tmp;
+  require('../observe.cjs');
+  const https = require('node:https');
+  try {
+    await new Promise((ok, fail) => {
+      const req = https.request(`https://canonical.invalid/api/v1/runners/jobs/${uuid}/files/videos/source?secret=NEVER_RECORD_ME`, res => {
+        const file = fs.createWriteStream(path.join(tmp, 'source'));
+        res.pipe(file); file.on('finish', ok);
+      });
+      req.on('error', fail); req.end('runnerToken=NEVER_RECORD_ME');
+    });
+    await new Promise((ok, fail) => {
+      const req = http.request({ hostname: '127.0.0.1', port, path: `/api/v1/runners/jobs/${uuid}/success`, method: 'POST' }, res => {
+        res.resume(); res.on('end', ok);
+      });
+      req.on('error', fail);
+      req.write(Buffer.alloc(100000, 1)); req.end(Buffer.alloc(200000, 2));
+    });
+    const events = fs.readFileSync(path.join(tmp, 'events.jsonl'), 'utf8');
+    assert(!events.includes('NEVER_RECORD_ME'));
+    const parsed = events.trim().split('\n').map(JSON.parse);
+    assert.equal(parsed.find(e => e.kind === 'transfer' && e.direction === 'download').bytes, source.length);
+    assert.equal(parsed.find(e => e.kind === 'transfer' && e.direction === 'upload').bytes, uploaded);
+    assert.equal(uploaded, 300000);
+    assert.equal(JSON.parse(fs.readFileSync(path.join(tmp, 'inputs/source.json'))).uuid, uuid);
+    await new Promise((ok, fail) => {
+      const timeout = setTimeout(() => fail(new Error('interrupted transfer did not fail promptly')), 2000);
+      const req = http.request({ hostname: '127.0.0.1', port, path: `/api/v1/runners/jobs/${uuid}/files/abort` }, res => res.resume());
+      req.on('error', () => { clearTimeout(timeout); ok(); }); req.end();
+    });
+    const failed = fs.readFileSync(path.join(tmp, 'events.jsonl'), 'utf8').trim().split('\n').map(JSON.parse);
+    assert(failed.some(e => e.kind === 'transfer' && !e.ok));
+    console.log('PASS: real download/upload counts, Tailscale-origin routing, UUID correlation, interrupted-transfer failure, no secrets');
+  } catch (e) { console.error(e); process.exitCode = 1; }
+  finally { server.close(); fs.rmSync(tmp, { recursive: true, force: true }); }
+});
diff --git a/infra/peertube-workers/tests/test_worker.py b/infra/peertube-workers/tests/test_worker.py
new file mode 100644
index 0000000..6210531
--- /dev/null
+++ b/infra/peertube-workers/tests/test_worker.py
@@ -0,0 +1,157 @@
+import importlib.util
+import json
+import os
+import subprocess
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location('worker', ROOT / 'pt-worker.py')
+worker = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(worker)
+
+
+class PolicyTests(unittest.TestCase):
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.old_state = worker.STATE
+        worker.STATE = Path(self.tmp.name)
+        self.meter = worker.Meter()
+        self.now = time.time()
+        for direction in ('download', 'upload'):
+            self.meter.consume({'kind': 'transfer', 'time': self.now, 'ok': True,
+                                'direction': direction, 'bytes': 10_000_000, 'seconds': 1})
+        self.policy = worker.Admission({})
+        self.sample = {'tailscale_path': 'direct', 'latency_ms': 5, 'network_ok': True,
+                       'registered': True, 'qsv': {'qsv_h264_ok': True, 'tested_at': self.now},
+                       'gpu_ready': True, 'gpu_tested_at': self.now,
+                       'gpu_accessible': True, 'on_ac': True, 'disk_free_bytes': 100 * 1024**3,
+                       'temperature_c': 50, 'throttle_counts': {}, 'active_jobs': 0}
+        self.control = {'paused': False}
+
+    def tearDown(self):
+        worker.STATE = self.old_state
+        self.tmp.cleanup()
+
+    def decide(self):
+        return self.policy.decide(self.sample, self.meter, self.control, self.now)
+
+    def available(self):
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+        self.assertEqual(self.decide(), 'AVAILABLE')
+
+    def test_recovery_hysteresis_and_low_bandwidth_drain(self):
+        self.available()
+        self.meter.data['download']['mbps'] = 1
+        self.assertEqual(self.decide(), 'AVAILABLE')
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+        self.meter.data['download']['mbps'] = 11  # insufficient recovery margin
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+        self.meter.data['download']['mbps'] = 20
+        self.available()
+
+    def test_path_transition_invalidates_real_bandwidth(self):
+        self.available()
+        self.sample['tailscale_path'] = 'DERP'
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+        self.assertIsNone(self.sample['recent_download_mbps'])
+        self.sample['tailscale_path'] = 'direct'
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+
+    def test_battery_gpu_disk_and_network_refuse(self):
+        self.available()
+        self.sample['on_ac'] = False
+        self.assertEqual(self.decide(), 'DRAINING')
+        self.sample['on_ac'] = True
+        self.sample['gpu_accessible'] = False
+        self.assertEqual(self.decide(), 'GPU_UNAVAILABLE')
+        self.sample['gpu_accessible'] = True
+        self.sample['disk_free_bytes'] = 0
+        self.assertEqual(self.decide(), 'LOW_DISK')
+        self.sample['disk_free_bytes'] = 100 * 1024**3
+        self.sample['network_ok'] = False
+        self.assertEqual(self.decide(), 'OFFLINE')
+
+    def test_gpu_failure_latched_until_later_selftest(self):
+        self.meter.consume({'kind': 'gpu_failure', 'time': self.now + 1})
+        self.assertEqual(self.decide(), 'GPU_UNAVAILABLE')
+        self.sample['qsv']['tested_at'] = self.now + 2
+        self.sample['gpu_tested_at'] = self.now + 2
+        self.available()
+
+    def test_transfer_failure_cooldown_and_stale_metrics(self):
+        self.meter.consume({'kind': 'transfer', 'time': self.now, 'ok': False})
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+        self.now += 61
+        self.available()
+        self.now += 900
+        self.assertEqual(self.decide(), 'AVAILABLE')
+        self.assertEqual(self.decide(), 'NETWORK_DEGRADED')
+
+    def test_thermal_throttle_and_pause(self):
+        self.available()
+        self.sample['throttle_counts'] = {'cpu0': 1}
+        self.decide()
+        self.sample['throttle_counts'] = {'cpu0': 2}
+        self.assertEqual(self.decide(), 'THERMAL_THROTTLED')
+        self.sample['temperature_c'] = 50
+        self.now += 121
+        self.available()
+        self.control['paused'] = True
+        self.assertEqual(self.decide(), 'PAUSED')
+
+    def test_job_correlation_uses_uuid_under_concurrency(self):
+        for uuid in ('a', 'b'):
+            self.meter.consume({'kind': 'job_accept', 'time': self.now, 'ok': True, 'uuid': uuid})
+        self.meter.consume({'kind': 'encode', 'time': self.now + 2, 'job_uuid': 'b', 'duration': 200})
+        self.meter.consume({'kind': 'encode', 'time': self.now + 3, 'job_uuid': 'a', 'duration': 100})
+        self.meter.consume({'kind': 'job_success', 'time': self.now + 10, 'uuid': 'b', 'ok': True})
+        self.assertEqual(self.meter.data['last_job_realtime_factor'], 20)
+
+
+class AdapterTests(unittest.TestCase):
+    def probe(self, codec='h264', rotation=False):
+        return {'streams': [{'codec_type': 'video', 'codec_name': codec, 'pix_fmt': 'yuv420p',
+                             'width': 1920, 'height': 1080,
+                             'side_data_list': [{'rotation': 90}] if rotation else []}],
+                'format': {'duration': '10'}}
+
+    def test_qsv_decode_scale_encode_and_no_x264_flags(self):
+        args, info = worker.qsv.rewrite(['-i', '/tmp/in', '-vcodec', 'libx264', '-vf', 'scale=w=-2:h=720',
+             '-pix_fmt', 'yuv420p', '-preset', 'veryfast', '-b_strategy', '1', '-bf', '16', '/tmp/out'], self.probe())
+        self.assertIn('h264_qsv', args)
+        self.assertIn('scale_qsv=w=1280:h=720:format=nv12', args)
+        self.assertNotIn('libx264', args)
+        self.assertNotIn('veryfast', args)
+        self.assertNotIn('-b_strategy', args)
+        self.assertEqual(info['target_height'], 720)
+
+    def test_unknown_decode_rotation_and_cpu_encoder_fail(self):
+        for probe in (self.probe('mpeg4'), self.probe(rotation=True)):
+            with self.assertRaises(ValueError):
+                worker.qsv.rewrite(['-i', '/tmp/in', '-c:v', 'libx264', '/tmp/out'], probe)
+        with self.assertRaises(ValueError):
+            worker.qsv.rewrite(['-i', '/tmp/in', '-c:v', 'libx265', '/tmp/out'], self.probe())
+
+    def test_unreviewed_software_filter_refused(self):
+        with self.assertRaises(ValueError):
+            worker.qsv.rewrite(['-i', '/tmp/in', '-c:v', 'libx264', '-vf', 'scale=640:360,eq=contrast=2', '/tmp/out'], self.probe())
+
+    def test_real_missing_qsv_refuses_without_cpu_output(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            src, out = Path(tmp) / 'src.mp4', Path(tmp) / 'out.mp4'
+            subprocess.run(['/usr/bin/ffmpeg', '-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=64x64:rate=2',
+                            '-t', '1', '-c:v', 'libx264', '-threads', '1', str(src)], check=True)
+            env = {**os.environ, 'PT_STATE_DIR': tmp, 'PT_RENDER_DEVICE': tmp + '/missing-device'}
+            p = subprocess.run(['/usr/bin/python3', str(ROOT / 'ffmpeg-qsv.py'), '-i', str(src), '-c:v',
+                                'libx264', str(out)], env=env, capture_output=True)
+            self.assertEqual(p.returncode, 78)
+            self.assertFalse(out.exists())
+            self.assertIn('gpu_failure', (Path(tmp) / 'events.jsonl').read_text())
+
+
+if __name__ == '__main__':
+    unittest.main()
diff --git a/infra/peertube-workers/win/build-requirements.txt b/infra/peertube-workers/win/build-requirements.txt
new file mode 100644
index 0000000..66849eb
--- /dev/null
+++ b/infra/peertube-workers/win/build-requirements.txt
@@ -0,0 +1,7 @@
+pyinstaller==6.16.0
+pyinstaller-hooks-contrib==2026.8
+altgraph==0.17.5
+packaging==26.3
+pefile==2023.2.7
+pywin32-ctypes==0.2.3
+setuptools==84.0.0
diff --git a/infra/peertube-workers/win/dependencies.json b/infra/peertube-workers/win/dependencies.json
new file mode 100644
index 0000000..131a450
--- /dev/null
+++ b/infra/peertube-workers/win/dependencies.json
@@ -0,0 +1,24 @@
+{
+  "node_version": "22.23.3",
+  "node_msi": {
+    "url": "https://nodejs.org/dist/v22.23.3/node-v22.23.3-x64.msi",
+    "sha256": "1c0efc8449987e7da5d184786a0a96da83ffa11d334421201e5c09b93017cb8d"
+  },
+  "node_zip": {
+    "url": "https://nodejs.org/dist/v22.23.3/node-v22.23.3-win-x64.zip",
+    "sha256": "2b0ff57b049cda1bbcea2240eec20467018713c1efe1f7360c2681859b90ed71"
+  },
+  "ffmpeg": {
+    "url": "https://github.com/BtbN/FFmpeg-Builds/releases/download/autobuild-2026-10-09-14-16/ffmpeg-n8.1.3-16-ge0a878dd70-win64-gpl-8.1.zip",
+    "sha256": "3c1efebafb60dae9aa1322a1662595d2ee516b352af2a2f6493923998bbee612",
+    "version": "n8.1.3-16-ge0a878dd70-20261009",
+    "validated_original_zip_sha256": "75c912eb2c8253a9efd5e8bf75f03d4124ce1f94a3af41218f0b9da7c3986d76"
+  },
+  "winsw": {
+    "url": "https://github.com/winsw/winsw/releases/download/v2.12.0/WinSW-x64.exe",
+    "sha256": "05b82d46ad331cc16bdc00de5c6332c1ef818df8ceefcd49c726553209b3a0da",
+    "version": "2.12.0"
+  },
+  "runner": "0.2.0",
+  "net_ipc": "2.2.0"
+}
diff --git a/infra/peertube-workers/win/e2e-peertube.mjs b/infra/peertube-workers/win/e2e-peertube.mjs
new file mode 100644
index 0000000..14aa566
--- /dev/null
+++ b/infra/peertube-workers/win/e2e-peertube.mjs
@@ -0,0 +1,86 @@
+// Authorized private-video E2E. No credential is accepted in argv or printed.
+import fs from 'node:fs';
+import crypto from 'node:crypto';
+import {execFileSync} from 'node:child_process';
+const emit=x=>process.stdout.write(JSON.stringify(x)+'\n');
+const sleep=ms=>new Promise(r=>setTimeout(r,ms));
+let stage='model-registration', session, db, auth, video, result={states:[]};
+try {
+ if(JSON.parse(fs.readFileSync('/app/package.json','utf8')).version !== '7.3.0') throw Error('unreviewed server version');
+ const dbURL=new URL('file:///app/dist/core/initializers/database.js');
+ db=await import(dbURL.href);
+ const {logger}=await import('file:///app/dist/core/helpers/logger.js');logger.silent=true;
+ // Register the shipped models without invoking initDatabaseModels: that helper
+ // recreates a SQL function and is outside this task's authorized server scope.
+ const source=fs.readFileSync(dbURL,'utf8');
+ const names=source.match(/sequelizeTypescript\.addModels\(\[([\s\S]*?)\]\)/)[1].split(',').map(x=>x.trim()).filter(Boolean);
+ const imports=[...source.matchAll(/import \{ (\w+) \} from '(\.\.\/models\/[^']+)';/g)];
+ const models=[];
+ for(const name of names){const item=imports.find(m=>m[1]===name);if(!item)throw Error('model not found');models.push((await import(new URL(item[2],dbURL).href))[name]);}
+ db.sequelizeTypescript.addModels(models);
+ await db.sequelizeTypescript.authenticate();
+ const {OAuthTokenModel}=await import('file:///app/dist/core/models/oauth/oauth-token.js');
+ const {OAuthClientModel}=await import('file:///app/dist/core/models/oauth/oauth-client.js');
+ const {UserModel}=await import('file:///app/dist/core/models/user/user.js');
+ const {RunnerJobModel}=await import('file:///app/dist/core/models/runner/runner-job.js');
+ const {RUNNER_JOB_STATES}=await import('file:///app/dist/core/initializers/constants.js');
+ const {Op}=await import('sequelize');
+ const user=await UserModel.findOne({where:{username:'root',role:0}}), client=await OAuthClientModel.loadFirstClient();
+ if(!user||!client)throw Error('admin/client absent');
+ stage='temporary-admin-session';
+ const expires=new Date(Date.now()+10*60*1000);
+ session=await OAuthTokenModel.create({accessToken:crypto.randomBytes(32).toString('hex'),refreshToken:crypto.randomBytes(32).toString('hex'),accessTokenExpiresAt:expires,refreshTokenExpiresAt:expires,userId:user.id,oAuthClientId:client.id,loginDevice:'authorized-pt-worker-e2e',loginIP:'127.0.0.1',loginDate:new Date()});
+ auth={Authorization:'Bearer '+session.accessToken};
+ const base='http://127.0.0.1:9000/api/v1';
+ async function api(path,options={}) {const r=await fetch(base+path,{...options,headers:{...auth,...options.headers},signal:AbortSignal.timeout(30000)});if(!r.ok){result.http_status=r.status;throw Error('API request failed');}return r.status===204?null:r.json();}
+ stage='admin-auth-check';
+ const me=await api('/users/me');
+ const channel=me.videoChannels?.[0];if(!channel)throw Error('root channel absent');
+ const baseline=await RunnerJobModel.max('id')||0;
+ stage='private-upload';
+ const form=new FormData();
+ for(const [k,v] of Object.entries({channelId:String(channel.id),name:'Windows NVENC worker E2E 2026-10-09',privacy:'3',nsfw:'false',commentsEnabled:'false',downloadEnabled:'true',waitTranscoding:'true'}))form.set(k,v);
+ form.set('videofile',new Blob([fs.readFileSync('/tmp/pt-worker-e2e-source.mp4')],{type:'video/mp4'}),'nvenc-e2e.mp4');
+ const upload=await api('/videos/upload',{method:'POST',body:form});video=upload.video;
+ result.video={id:video.id,uuid:video.uuid,shortUUID:video.shortUUID,privacy:'private',watch_url:'https://tube.occupymedia.cc/w/'+video.shortUUID};
+ emit({phase:'uploaded',video:result.video});
+ stage='remote-job-states';
+ const end=Date.now()+5*60*1000, seen=new Map();let completed;
+ while(Date.now()<end){
+  const jobs=await RunnerJobModel.findAll({attributes:['id','uuid','type','state','runnerId','createdAt','startedAt','updatedAt'],where:{id:{[Op.gt]:baseline}},raw:true});
+  for(const j of jobs){const label=RUNNER_JOB_STATES[j.state];if(seen.get(j.uuid)!==label){seen.set(j.uuid,label);const item={...j,state:label,observed_at:new Date().toISOString()};result.states.push(item);emit({phase:'job-state',...item});}if(label==='Completed')completed=j;if(label==='Errored')throw Error('remote job errored');}
+  if(completed && jobs.some(j=>j.type==='vod-hls-transcoding' && RUNNER_JOB_STATES[j.state]==='Completed'))break;
+  await sleep(100);
+ }
+ if(!completed)throw Error('remote job deadline');
+ result.job={id:completed.id,uuid:completed.uuid,type:completed.type,runner_id:completed.runnerId};
+ stage='result-media-api';
+ let details;
+ for(let n=0;n<60;n++){details=await api('/videos/'+video.uuid);if(details.streamingPlaylists?.[0]?.files?.length)break;await sleep(500);}
+ const playlist=details.streamingPlaylists?.[0];if(!playlist?.files?.length)throw Error('HLS result absent');
+ let fileToken;
+ async function media(url){let u=new URL(url);u.protocol='http:';u.hostname='127.0.0.1';u.port='9000';if(fileToken)u.searchParams.set('videoFileToken',fileToken);let r=await fetch(u,{headers:auth,signal:AbortSignal.timeout(15000)});if(!r.ok&&!fileToken){try{const t=await api('/videos/'+video.uuid+'/token',{method:'POST'});fileToken=t.files?.token||t.token||t.videoFileToken;}catch{}if(fileToken){u.searchParams.set('videoFileToken',fileToken);r=await fetch(u,{headers:auth,signal:AbortSignal.timeout(15000)});}}if(!r.ok){result.media_http_status=r.status;throw Error('private media fetch failed');}return r;}
+ stage='playlist-playback';
+ const master=await (await media(playlist.playlistUrl)).text();
+ const renditionLine=master.split(/\r?\n/).find(l=>l.trim()&&!l.startsWith('#'));
+ const renditionURL=new URL(renditionLine,playlist.playlistUrl).href;
+ const rendition=await (await media(renditionURL)).text();
+ const assetLine=rendition.split(/\r?\n/).find(l=>l.trim()&&!l.startsWith('#'));
+ const assetURL=new URL(assetLine,renditionURL).href;
+ const blob=Buffer.from(await (await media(assetURL)).arrayBuffer());
+ const path='/tmp/pt-worker-e2e-result.mp4';fs.writeFileSync(path,blob,{mode:0o600});
+ const probe=JSON.parse(execFileSync('ffprobe',['-v','error','-show_streams','-show_format','-of','json',path],{encoding:'utf8',timeout:30000}));
+ stage='playback-decode';execFileSync('ffmpeg',['-v','error','-nostdin','-i',path,'-f','null','-'],{stdio:'pipe',timeout:30000});
+ const stream=probe.streams.find(s=>s.codec_type==='video');
+ result.playback={master_http:200,rendition_http:200,asset_http:200,decode_exit:0,bytes:blob.length,codec:stream.codec_name,width:stream.width,height:stream.height,duration:probe.format.duration};
+ result.success=true;emit({phase:'e2e-completed',job:result.job,playback:result.playback});
+}catch(e){result.success=false;result.failed_stage=stage;result.error_type=e.name;emit({phase:'e2e-failed',stage,error_type:e.name,http_status:result.http_status,media_http_status:result.media_http_status});}
+finally{
+ if(session){
+  try{await fetch('http://127.0.0.1:9000/api/v1/users/revoke-token',{method:'POST',headers:auth,signal:AbortSignal.timeout(10000)});await sleep(300);}catch{}
+  try{await session.destroy();result.temporary_admin_session_removed=true;}catch{result.temporary_admin_session_removed=false;}
+ }
+ fs.writeFileSync('/tmp/pt-worker-e2e-result.json',JSON.stringify(result,null,2),{mode:0o600});
+ emit({phase:'final-e2e-record',...result});
+ if(db)await db.sequelizeTypescript.close();
+}
diff --git a/infra/peertube-workers/win/enroll-server.cjs b/infra/peertube-workers/win/enroll-server.cjs
new file mode 100644
index 0000000..e2c3cab
--- /dev/null
+++ b/infra/peertube-workers/win/enroll-server.cjs
@@ -0,0 +1,11 @@
+'use strict';
+// Enrollment listener has concurrency zero and discards upstream logs.
+const fs = require('node:fs'), path = require('node:path'), {spawn} = require('node:child_process');
+const root=process.env.PT_ROOT || 'C:\\pt-worker';
+const cfg=JSON.parse(fs.readFileSync(path.join(root,'state','worker.json'),'utf8').replace(/^\uFEFF/,''));
+const env={...process.env, PT_ROOT:root, APPDATA:path.join(root,'profile','Roaming'), LOCALAPPDATA:path.join(root,'profile','Local'), FFMPEG_PATH:path.join(root,'bin','ffmpeg-nvenc.exe'),FFPROBE_PATH:path.join(root,'bin','ffprobe.exe'), PT_STATE_DIR:path.join(root,'state'),PT_WORKER_CONFIG:path.join(root,'state','worker.json')};
+const toml=fs.readFileSync(path.join(env.APPDATA,'peertube-runner-nodejs','Config','default','config.toml'),'utf8');
+if(!/^concurrency\s*=\s*0\s*$/m.test(toml)) throw Error('Enrollment requires concurrency zero');
+const child=spawn(cfg.node_binary,[path.join(root,'runner','node_modules','@peertube','peertube-runner','dist','peertube-runner.js'),'server','--enable-job','vod-web-video-transcoding','--enable-job','vod-hls-transcoding','--enable-job','vod-audio-merge-transcoding'],{env,detached:true,windowsHide:true,stdio:'ignore'});
+fs.writeFileSync(path.join(root,'state','enroll-process.json'),JSON.stringify({pid:child.pid}));
+child.unref(); console.log(JSON.stringify({enrollment_listener_started:true,concurrency:0}));
diff --git a/infra/peertube-workers/win/ffmpeg-nvenc.py b/infra/peertube-workers/win/ffmpeg-nvenc.py
new file mode 100644
index 0000000..4454a6b
--- /dev/null
+++ b/infra/peertube-workers/win/ffmpeg-nvenc.py
@@ -0,0 +1,210 @@
+"""Fail-closed PeerTube 0.2.0 adapter; freeze with PyInstaller as a real PE .exe.
+Video encoding is always NVENC. CPU image/audio processing is permitted.
+Only reviewed argument shapes are accepted, including explicit copy-only remux.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+HERE = Path(sys.executable if getattr(sys, 'frozen', False) else __file__).resolve().parent
+REAL = Path(os.environ.get('PT_FFMPEG_EXE', str(HERE / 'ffmpeg.exe')))
+PROBE = Path(os.environ.get('PT_FFPROBE_EXE', str(HERE / 'ffprobe.exe')))
+STATE = Path(os.environ.get('PT_STATE_DIR', r'C:\pt-worker\state'))
+DEVICE = os.environ.get('PT_NVENC_DEVICE', '0')
+TARGET = os.environ.get('PT_NVENC_TARGET', 'h264_nvenc')
+QUERIES = ('-version', '-formats', '-encoders', '-filters', '-codecs', '-hwaccels')
+FLAGS = {'-y', '-n', '-nostdin', '-hide_banner', '-an', '-vn', '-shortest', '-copyts'}
+VALUES = {'-i', '-vcodec', '-c:v', '-codec:v', '-acodec', '-c:a', '-codec:a', '-c',
+          '-vf', '-filter:v', '-pix_fmt', '-preset', '-preset:v', '-b_strategy', '-bf',
+          '-tune', '-crf', '-maxrate', '-maxrate:v', '-bufsize', '-bufsize:v',
+          '-b:v', '-vb', '-b:a', '-ab', '-q:a', '-g', '-g:v', '-r', '-r:v',
+          '-threads', '-f', '-movflags', '-map', '-map_metadata', '-max_muxing_queue_size',
+          '-channel_layout', '-ac', '-ar', '-t', '-loop', '-hls_time', '-hls_list_size',
+          '-hls_playlist_type', '-hls_segment_filename', '-hls_segment_type', '-hls_flags',
+          '-bsf:a', '-loglevel', '-v', '-sc_threshold'}
+
+
+def event(kind, **fields):
+    try:
+        STATE.mkdir(parents=True, exist_ok=True)
+        with (STATE / 'events.jsonl').open('a', encoding='utf8') as f:
+            f.write(json.dumps({'time': time.time(), 'kind': kind, **fields}) + '\n')
+    except OSError:
+        pass
+
+
+def probe(filename):
+    p = subprocess.run([str(PROBE), '-v', 'error', '-show_streams', '-show_format',
+                        '-of', 'json', filename], capture_output=True, timeout=30)
+    if p.returncode:
+        raise ValueError('probe failed')
+    return json.loads(p.stdout)
+
+
+def parse(args):
+    if len(args) < 2 or args[-1].startswith('-'):
+        raise ValueError('missing output')
+    entries, i = [], 0
+    while i < len(args) - 1:
+        key = args[i]
+        if key in FLAGS:
+            entries.append((key, None)); i += 1
+        elif key in VALUES and i + 1 < len(args) - 1:
+            entries.append((key, args[i + 1])); i += 2
+        else:
+            raise ValueError('unknown option or extra output')
+    return entries
+
+
+def rewrite(args, input_probe=None):
+    if len(args) == 1 and args[0] in QUERIES:
+        return args, None
+    if TARGET not in ('h264_nvenc', 'hevc_nvenc') or not DEVICE.isdigit() or (STATE / 'gpu-unavailable').exists():
+        raise ValueError('GPU disabled')
+    entries = parse(args)
+    # No codec aliases, extra output streams, or global software encoders can escape validation.
+    video = [(k, v) for k, v in entries if k in ('-vcodec', '-c:v', '-codec:v')]
+    generic = [v for k, v in entries if k == '-c']
+    audio = [v for k, v in entries if k in ('-acodec', '-c:a', '-codec:a')]
+    if any(v not in ('copy', 'aac', 'libfdk_aac', 'libmp3lame') for v in audio):
+        raise ValueError('unknown audio encoder')
+    if generic:
+        if generic != ['copy'] or video or audio:
+            raise ValueError('unreviewed global codec')
+        return args, None
+    if len(video) > 1:
+        raise ValueError('multiple video encoders')
+    if '-vn' in args:
+        if video:
+            raise ValueError('contradictory video options')
+        return args, None
+    if video and video[0][1] == 'copy':
+        return args, None
+    if len(video) != 1 or video[0][1] != 'libx264':
+        raise ValueError('unknown video encoder')
+    inputs = [v for k, v in entries if k == '-i']
+    if not inputs or len(inputs) > 2:
+        raise ValueError('unreviewed inputs')
+    data = input_probe if input_probe is not None else probe(inputs[0])
+    stream = next(s for s in data['streams'] if s['codec_type'] == 'video')
+    codec = stream['codec_name']
+    still = codec in ('png', 'mjpeg', 'webp') and '-loop' in args
+    if not still and codec not in ('h264', 'hevc', 'vp9'):
+        raise ValueError('source has no reviewed NVDEC path')
+    if not still and stream.get('pix_fmt') not in ('yuv420p', 'yuv420p10le', 'nv12', 'p010le'):
+        raise ValueError('unsupported pixel format')
+    if stream.get('color_transfer') in ('smpte2084', 'arib-std-b67'):
+        raise ValueError('HDR needs reviewed tone mapping')
+    if stream.get('tags', {}).get('rotate') or any(s.get('rotation', 0) for s in stream.get('side_data_list', [])):
+        raise ValueError('rotation needs reviewed GPU path')
+    width, height = stream['width'], stream['height']
+    w, h = width // 2 * 2, height // 2 * 2
+    filters = [v for k, v in entries if k in ('-vf', '-filter:v')]
+    if len(filters) > 1:
+        raise ValueError('multiple filters')
+    if filters:
+        value = filters[0]
+        if value == 'scale=trunc(iw/2)*2:trunc(ih/2)*2' and still:
+            pass
+        else:
+            match = re.fullmatch(r'scale=w=(-2|\d+):h=(-2|\d+)', value)
+            if not match:
+                raise ValueError('unreviewed filter')
+            w, h = map(int, match.groups())
+            if w == -2 and h > 0:
+                w = max(2, round(width * h / height / 2) * 2)
+            elif h == -2 and w > 0:
+                h = max(2, round(height * w / width / 2) * 2)
+            if w <= 0 or h <= 0 or w % 2 or h % 2 or w > 7680 or h > 4320:
+                raise ValueError('invalid dimensions')
+    out = ['-init_hw_device', f'cuda=nv:{DEVICE}', '-filter_hw_device', 'nv']
+    first = True
+    for key, value in entries:
+        if key == '-i' and first:
+            if not still:
+                out += ['-hwaccel', 'cuda', '-hwaccel_device', DEVICE, '-hwaccel_output_format', 'cuda', '-noautorotate']
+            first = False
+        if key in ('-pix_fmt', '-preset', '-preset:v', '-b_strategy', '-bf', '-tune', '-crf', '-vf', '-filter:v'):
+            continue
+        if key in ('-vcodec', '-c:v', '-codec:v'):
+            value = TARGET
+        out.append(key)
+        if value is not None:
+            out.append(value)
+    prefix = 'format=nv12,hwupload_cuda,' if still else ''
+    out += ['-vf', prefix + f'scale_cuda=w={w}:h={h}:format=nv12',
+            '-preset', 'p4', '-gpu', DEVICE, '-bf', '2', '-rc', 'vbr']
+    rate = next((v for k, v in entries if k in ('-maxrate:v', '-maxrate')), None)
+    if rate and not any(k in ('-b:v', '-vb') for k, _ in entries):
+        out += ['-b:v', rate]
+    out.append(args[-1])
+    uuid = None
+    try:
+        uuid = json.loads((STATE / 'inputs' / (Path(inputs[0]).name + '.json')).read_text())['uuid']
+    except (OSError, ValueError, KeyError):
+        pass
+    return out, {'job_uuid': uuid, 'source_codec': codec, 'target_codec': 'hevc' if TARGET == 'hevc_nvenc' else 'h264', 'encoder': TARGET,
+                 'source_width': width, 'source_height': height, 'target_width': w, 'target_height': h,
+                 'duration': float(data.get('format', {}).get('duration', 0) or 0), 'static_image_upload': still}
+
+
+def encoder_util():
+    try:
+        p = subprocess.run(['nvidia-smi.exe', '-i', DEVICE, '--query-gpu=utilization.encoder',
+                            '--format=csv,noheader,nounits'], capture_output=True, text=True, timeout=3)
+        return float(p.stdout.strip()) if p.returncode == 0 else None
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return None
+
+
+def main():
+    try:
+        args, info = rewrite(sys.argv[1:])
+        if not REAL.is_file():
+            raise ValueError('ffmpeg missing')
+        if info is None:
+            sys.exit(subprocess.call([str(REAL), *args]))
+        start = time.monotonic()
+        # Do not persist ffmpeg command lines, media paths, stderr, or signed URLs.
+        p = subprocess.Popen([str(REAL), *args], stdout=sys.stdout, stderr=subprocess.PIPE,
+                             text=True, encoding='utf8', errors='replace')
+        progress = {}
+        def consume():
+            for line in p.stderr:
+                sys.stderr.write(line); sys.stderr.flush()
+                for k, v in re.findall(r'(frame|fps|speed)=\s*([\d.]+)', line):
+                    progress[k] = float(v)
+        reader = threading.Thread(target=consume, daemon=True); reader.start()
+        samples = []
+        while p.poll() is None:
+            value = encoder_util()
+            if value is not None:
+                samples.append(value)
+            time.sleep(.2)
+        reader.join(timeout=2)
+        seconds = time.monotonic() - start
+        maximum = max(samples) if samples else None
+        # Short jobs can end inside the utilization averaging interval. They still
+        # explicitly use NVENC; boot/driver self-test provides mandatory GPU proof.
+        no_signal = seconds >= 3 and (maximum is None or maximum == 0)
+        rc = p.returncode or (78 if no_signal else 0)
+        event('encode', **info, seconds=seconds, returncode=rc, ffmpeg_returncode=p.returncode,
+              engine_busy_max=maximum, engine_samples=len(samples), engine_counters_readable=bool(samples),
+              frames=progress.get('frame'), ffmpeg_fps=progress.get('fps'), ffmpeg_speed=progress.get('speed'),
+              realtime_factor=info['duration'] / seconds if info['duration'] else None)
+        if rc:
+            event('gpu_failure', reason='nvenc_transcode_failed' if p.returncode else 'no_encoder_signal')
+        sys.exit(rc)
+    except (ValueError, OSError, subprocess.SubprocessError, KeyError, StopIteration):
+        event('gpu_failure', reason='unreviewed_or_unavailable_nvenc')
+        print('PT-WORKER: NVENC adapter refused command; drain required', file=sys.stderr)
+        sys.exit(78)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/infra/peertube-workers/win/ffmpeg-qsv.py b/infra/peertube-workers/win/ffmpeg-qsv.py
new file mode 100644
index 0000000..a17c2e1
--- /dev/null
+++ b/infra/peertube-workers/win/ffmpeg-qsv.py
@@ -0,0 +1,253 @@
+#!/usr/bin/env python3
+"""Pinned PeerTube runner 0.2.0 FFmpeg adapter (native Windows).
+
+Port of infra/peertube-workers/ffmpeg-qsv.py from the validated Linux QSV worker.
+Same contract: rewrite known runner command shapes into explicit QSV decode ->
+hardware frames -> scale_qsv -> h264_qsv; never execute a CPU video encoder;
+fail closed (exit 78) on anything unreviewed.
+
+Windows deltas from the Linux adapter:
+  - real ffmpeg/ffprobe are sibling .exe files of this shim (the runner resolves
+    FFMPEG_PATH with fs.exists, then spawns it without a shell, so the shim
+    MUST be a real .exe: a .cmd/.bat wrapper is rejected by Node >= 18.20/20.12
+    with EINVAL, and fluent-ffmpeg passes no `shell` option).
+  - QSV device init is `-init_hw_device qsv=qs` (D3D11 child device by default;
+    the libmfx/oneVPL dispatcher DLLs must sit next to ffmpeg.exe).
+  - "hardware really did it" telemetry is the PDH GPU Engine counter
+    \\GPU Engine(pid_<pid>_*)\\Utilization Percentage over engtype_VideoEncode
+    instances, sampled via typeperf (i915 DRM fdinfo does not exist on Windows).
+    If the counters are readable and stay exactly 0 for the whole run, the run
+    is recorded as a GPU failure even on exit 0.
+  - capability queries (-version/-encoders/...) are passed through untouched.
+"""
+import json
+import os
+import re
+import subprocess
+import sys
+import threading
+import time
+from pathlib import Path
+
+HERE = Path(__file__).resolve().parent
+REAL = Path(os.environ.get('PT_FFMPEG_EXE', str(HERE / 'ffmpeg.exe')))
+PROBE = Path(os.environ.get('PT_FFPROBE_EXE', str(HERE / 'ffprobe.exe')))
+# Optional child-device spec for the QSV device (e.g. 'd3d11va', 'd3d11va:1').
+# Empty means the default adapter. Verify on first hardware contact.
+DEVICE = os.environ.get('PT_QSV_DEVICE', '').strip()
+STATE = Path(os.environ.get('PT_STATE_DIR', r'C:\pt-worker\state'))
+
+PASSTHROUGH = (['-version'], ['-formats'], ['-encoders'], ['-filters'],
+               ['-codecs'], ['-hwaccels'])
+
+
+def event(kind, **fields):
+    STATE.mkdir(parents=True, exist_ok=True)
+    line = json.dumps({'time': time.time(), 'kind': kind, **fields}) + '\n'
+    try:
+        with open(STATE / 'events.jsonl', 'a', encoding='utf8') as handle:
+            handle.write(line)
+    except OSError:
+        pass  # telemetry loss must never fail a job
+
+
+def probe(path):
+    p = subprocess.run([str(PROBE), '-v', 'error', '-show_streams', '-show_format',
+                        '-of', 'json', str(path)], capture_output=True, text=True, timeout=30)
+    if p.returncode:
+        raise ValueError('input probe failed')
+    return json.loads(p.stdout)
+
+
+def csv_cells(line):
+    return [cell.strip('"') for cell in line.split('","')]
+
+
+def as_float(text):
+    try:
+        return float(text)
+    except (TypeError, ValueError):
+        pass
+    try:  # locale decimal-comma fallback
+        return float(text.replace('.', '').replace(',', '.'))
+    except (TypeError, ValueError):
+        return None
+
+
+def video_encode_busy(pid):
+    """Sum of PDH \\GPU Engine(pid_<pid>_*)\\Utilization Percentage over
+    engtype_VideoEncode instances, one 1-second typeperf sample.
+
+    Returns (busy_or_None, readable). Counter names and decimal points are
+    locale-sensitive; unparseable samples count as not-readable, never as zero.
+    """
+    counter = rf'\GPU Engine(pid_{pid}_*)\Utilization Percentage'
+    try:
+        p = subprocess.run(['typeperf', counter, '-sc', '1'], capture_output=True,
+                           text=True, timeout=15)
+    except (OSError, subprocess.SubprocessError):
+        return None, False
+    if p.returncode:
+        return None, False
+    rows = [line for line in (p.stdout or '').splitlines() if line.startswith('"')]
+    if len(rows) < 2:
+        return None, False
+    headers = list(csv_cells(rows[0]))
+    values = list(csv_cells(rows[1]))
+    total, seen = 0.0, False
+    for index, header in enumerate(headers):
+        if 'engtype_VideoEncode' not in header.lower() or index >= len(values):
+            continue
+        number = as_float(values[index])
+        if number is None:
+            return None, False
+        seen = True
+        total += number
+    return (total if seen else None), seen
+
+
+def rewrite(args, input_probe=None):
+    # fluent-ffmpeg queries capabilities before building commands. These do no encode.
+    if list(args) in [list(p) for p in PASSTHROUGH]:
+        return args, None
+    pairs = list(zip(args, args[1:]))
+    video_options = [(k, v) for k, v in pairs if k in ('-vcodec', '-c:v', '-codec:v')]
+    if len(video_options) > 1:
+        raise ValueError('multiple video codec options refused')
+    if '-vn' in args and not video_options:
+        return args, None  # audio-only VOD renditions have no video encode
+    if not video_options or video_options[0][1] != 'libx264':
+        raise ValueError('unknown runner command or video encoder refused')
+    if '-filter_complex' in args or '-hwaccel' in args or '-init_hw_device' in args:
+        raise ValueError('unreviewed filter/device override refused')
+    inputs = [v for k, v in pairs if k == '-i']
+    if not inputs:
+        raise ValueError('missing video input')
+    data = input_probe if input_probe is not None else probe(inputs[0])
+    stream = next((s for s in data['streams'] if s['codec_type'] == 'video'), None)
+    if stream is None:
+        raise ValueError('missing video stream')
+    codec = stream['codec_name']
+    still = codec in ('png', 'mjpeg', 'webp') and '-loop' in args
+    decoder = {'h264': 'h264_qsv', 'hevc': 'hevc_qsv', 'vp9': 'vp9_qsv', 'av1': 'av1_qsv'}.get(codec)
+    if not decoder and not still:
+        raise ValueError('source codec has no reviewed QSV decode path')
+    if stream.get('pix_fmt') not in ('yuv420p', 'yuv420p10le', 'nv12', 'p010le') and not still:
+        raise ValueError('unsupported pixel format; CPU decode fallback refused')
+    if stream.get('tags', {}).get('rotate') or any(s.get('rotation', 0) for s in stream.get('side_data_list', [])):
+        raise ValueError('rotated source requires reviewed GPU transpose path')
+    width, height = stream['width'], stream['height']
+    duration = float(data.get('format', {}).get('duration', 0) or 0)
+    w, h = width // 2 * 2, height // 2 * 2
+    output = ['-init_hw_device', f'qsv=qs:{DEVICE}' if DEVICE else 'qsv=qs',
+              '-filter_hw_device', 'qs']
+    i, first_input = 0, True
+    while i < len(args):
+        key = args[i]
+        val = args[i + 1] if i + 1 < len(args) else None
+        if key == '-i' and first_input:
+            if not still:
+                output += ['-hwaccel', 'qsv', '-hwaccel_output_format', 'qsv', '-c:v', decoder, '-noautorotate']
+            output += [key, val]
+            first_input = False
+            i += 2
+        elif key in ('-vcodec', '-c:v', '-codec:v'):
+            output += [key, 'h264_qsv']
+            i += 2
+        elif key in ('-pix_fmt', '-preset', '-preset:v', '-b_strategy', '-bf', '-tune', '-crf'):
+            i += 2
+        elif key in ('-vf', '-filter:v'):
+            if val == 'scale=trunc(iw/2)*2:trunc(ih/2)*2' and still:
+                w, h = width // 2 * 2, height // 2 * 2
+            else:
+                match = re.fullmatch(r'scale=w=(-2|\d+):h=(-2|\d+)', val or '')
+                if not match:
+                    raise ValueError('unreviewed software filter refused')
+                w, h = map(int, match.groups())
+                if w == -2 and h > 0:
+                    w = max(2, round(width * h / height / 2) * 2)
+                elif h == -2 and w > 0:
+                    h = max(2, round(height * w / width / 2) * 2)
+                if w <= 0 or h <= 0 or w % 2 or h % 2:
+                    raise ValueError('invalid output dimensions')
+            prefix = 'format=nv12,hwupload=extra_hw_frames=64,' if still else ''
+            output += [key, prefix + f'scale_qsv=w={w}:h={h}:format=nv12']
+            i += 2
+        else:
+            output.append(key)
+            i += 1
+    if '-vf' not in args and '-filter:v' not in args:
+        prefix = 'format=nv12,hwupload=extra_hw_frames=64,' if still else ''
+        output[-1:-1] = ['-vf', prefix + f'scale_qsv=w={width // 2 * 2}:h={height // 2 * 2}:format=nv12']
+    # Keep PeerTube's rate cap and GOP; QSV has no x264 CRF mode.
+    rate = next((v for k, v in pairs if k in ('-maxrate:v', '-maxrate')), None)
+    extra = ['-preset', 'medium', '-bf', '2']
+    if rate and not any(k in ('-b:v', '-vb') for k, _ in pairs):
+        extra += ['-b:v', rate]
+    output[-1:-1] = extra
+    job_uuid = None
+    try:
+        job_uuid = json.loads((STATE / 'inputs' / (Path(inputs[0]).name + '.json')).read_text(encoding='utf8'))['uuid']
+    except (OSError, ValueError, KeyError):
+        pass
+    return output, {'job_uuid': job_uuid, 'source_codec': codec, 'target_codec': 'h264', 'encoder': 'h264_qsv',
+                    'source_width': width, 'source_height': height, 'duration': duration,
+                    'target_width': w, 'target_height': h,
+                    'static_image_upload': still}
+
+
+def main():
+    try:
+        if not REAL.is_file():
+            raise ValueError('real ffmpeg.exe not found next to shim')
+        args, info = rewrite(sys.argv[1:])
+        if info is None:
+            os.execv(str(REAL), [str(REAL), *args])
+        started = time.monotonic()
+        p = subprocess.Popen([str(REAL), *args], stderr=subprocess.PIPE, text=True,
+                             encoding='utf8', errors='replace')
+        progress = {}
+        def stderr_progress():
+            for line in p.stderr:
+                sys.stderr.write(line)
+                sys.stderr.flush()
+                for key, value in re.findall(r'(frame|fps|speed)=\s*([\d.]+)', line):
+                    try:
+                        progress[key] = float(value)
+                    except ValueError:
+                        pass
+        reader = threading.Thread(target=stderr_progress, daemon=True)
+        reader.start()
+        maximum, samples, readable = None, 0, False
+        while p.poll() is None:
+            busy, ok = video_encode_busy(p.pid)
+            readable |= ok
+            if ok:
+                samples += 1
+                if busy is not None:
+                    maximum = busy if maximum is None else max(maximum, busy)
+            time.sleep(1.0)
+        elapsed = time.monotonic() - started
+        reader.join(timeout=2)
+        event('encode', **info, seconds=elapsed, returncode=p.returncode,
+              engine_busy_max=maximum, engine_samples=samples,
+              engine_counters_readable=readable,
+              ffmpeg_fps=progress.get('fps'), frames=progress.get('frame'),
+              ffmpeg_speed=progress.get('speed'),
+              realtime_factor=info['duration'] / elapsed if info['duration'] else None)
+        if p.returncode:
+            event('gpu_failure', reason='qsv_transcode_failed')
+        elif readable and samples >= 3 and maximum == 0:
+            # Exit 0 with a readable VideoEncode counter pinned at 0 is NOT
+            # proof of hardware encoding; fail closed like the Linux fdinfo gate.
+            event('gpu_failure', reason='no_video_encode_utilization')
+        sys.exit(p.returncode)
+    except (ValueError, OSError, subprocess.SubprocessError, KeyError) as e:
+        # Messages are fixed strings; never expose source URLs or runner credentials.
+        event('gpu_failure', reason=type(e).__name__)
+        print('PT-WORKER: QSV adapter refused command; worker must drain', file=sys.stderr)
+        sys.exit(78)
+
+
+if __name__ == '__main__':
+    main()
diff --git a/infra/peertube-workers/win/ipc-nvenc.cjs b/infra/peertube-workers/win/ipc-nvenc.cjs
new file mode 100644
index 0000000..8d827cd
--- /dev/null
+++ b/infra/peertube-workers/win/ipc-nvenc.cjs
@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+'use strict';
+// Same IPC protocol/library as the official runner 0.2.0; Windows named-pipe variant
+// of infra/peertube-workers/ipc.cjs. Registration secret comes from stdin, never argv.
+//
+// Pipe-name derivation (verified in the shipped 0.2.0 bundle):
+//   ConfigManager id defaults to "default"; socket path is
+//   join(envPaths("peertube-runner", suffix "nodejs").data, id, "peertube-runner.sock")
+//   = %LOCALAPPDATA%\peertube-runner-nodejs\Data\default\peertube-runner.sock
+// The bundled @peertube/net-ipc rewrites any path on win32:
+//   `\\\\.\\pipe\\${path.replace(/^\//, "").replace(/\//g, "-")}`
+// so we pass the RAW Windows path and never build the \\.\pipe\ prefix ourselves.
+const root = process.argv[3] || process.env.PT_ROOT || 'C:\\pt-worker';
+process.env.APPDATA = require('node:path').join(root, 'profile', 'Roaming');
+process.env.LOCALAPPDATA = require('node:path').join(root, 'profile', 'Local');
+const { Client } = require(require('node:path').join(root, 'runner', 'node_modules', '@peertube', 'net-ipc'));
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const action = process.argv[2];
+const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+const id = process.env.PT_RUNNER_ID || 'default';
+const sock = path.join(base, 'peertube-runner-nodejs', 'Data', id, 'peertube-runner.sock');
+let client = new Client({ path: sock, reconnect: false });
+const deadline = setTimeout(() => { client.destroy(); process.exit(1); }, 15000);
+(async () => {
+  try {
+    let connected = false;
+    for (let attempt = 0; attempt < 20; attempt++) {
+      try { await client.connect(); connected = true; break; }
+      catch { client.destroy(); await new Promise(resolve => setTimeout(resolve, 500)); client = new Client({path: sock, reconnect: false}); }
+    }
+    if (!connected) throw new Error('IPC unavailable');
+    let request = { type: action };
+    if (action === 'register') {
+      const cfg = JSON.parse(fs.readFileSync(process.env.PT_WORKER_CONFIG || path.join(root, 'state', 'worker.json'), 'utf8').replace(/^\uFEFF/, ''));
+      const proof = JSON.parse(fs.readFileSync(path.join(root, 'state', 'nvenc.json'), 'utf8').replace(/^\uFEFF/, ''));
+      const identity = require('node:child_process').execFileSync('nvidia-smi.exe', ['-i',String(cfg.nvenc_device || 0),'--query-gpu=uuid,driver_version','--format=csv,noheader,nounits'],{timeout:5000,encoding:'utf8'}).trim().split(/,\s*/);
+      if (identity[0] !== proof.gpu_uuid || identity[1] !== proof.driver_version) throw new Error('changed GPU');
+      if (!proof.nvenc_h264_ok || !proof.nvenc_hevc_ok || Date.now()/1000 - proof.tested_at > 86400) throw new Error('proof missing');
+      const registrationToken = fs.readFileSync(0, 'utf8').trim();
+      if (!registrationToken.startsWith('ptrrt-')) throw new Error('bad token');
+      request = { type: 'register', url: cfg.peertube_url, runnerName: cfg.name, registrationToken,
+        runnerDescription: 'Windows NVENC only; VOD; AC-only admission; concurrency 2' };
+    } else if (!['list-jobs', 'list-registered', 'graceful-shutdown'].includes(action)) throw new Error('bad action');
+    const result = await client.request(request);
+    if (!result.success) throw new Error('IPC failed');
+    if (action === 'list-jobs') {
+      // Drop payloads (can contain URLs); status consumers only need counts.
+      console.log(JSON.stringify({ concurrency: result.data.concurrency, active_jobs: result.data.processingJobs.length }));
+    } else if (action === 'list-registered') console.log(JSON.stringify({ registered_count: result.data.registeredInstances?.length || result.data.instances?.length || 0 }));
+    else console.log(JSON.stringify({ success: true }));
+  } catch { console.error('Runner IPC failed; inspect local service health'); process.exitCode = 1; }
+  finally { clearTimeout(deadline); client.destroy(); }
+})();
diff --git a/infra/peertube-workers/win/ipc-win.cjs b/infra/peertube-workers/win/ipc-win.cjs
new file mode 100644
index 0000000..bce53c2
--- /dev/null
+++ b/infra/peertube-workers/win/ipc-win.cjs
@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+'use strict';
+// Same IPC protocol/library as the official runner 0.2.0; Windows named-pipe variant
+// of infra/peertube-workers/ipc.cjs. Registration secret comes from stdin, never argv.
+//
+// Pipe-name derivation (verified in the shipped 0.2.0 bundle):
+//   ConfigManager id defaults to "default"; socket path is
+//   join(envPaths("peertube-runner", suffix "nodejs").data, id, "peertube-runner.sock")
+//   = %LOCALAPPDATA%\peertube-runner-nodejs\Data\default\peertube-runner.sock
+// The bundled @peertube/net-ipc rewrites any path on win32:
+//   `\\\\.\\pipe\\${path.replace(/^\//, "").replace(/\//g, "-")}`
+// so we pass the RAW Windows path and never build the \\.\pipe\ prefix ourselves.
+const { Client } = require('./runtime/node_modules/@peertube/net-ipc');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const action = process.argv[2];
+const base = process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local');
+const id = process.env.PT_RUNNER_ID || 'default';
+const sock = path.join(base, 'peertube-runner-nodejs', 'Data', id, 'peertube-runner.sock');
+const client = new Client({ path: sock, reconnect: false });
+const deadline = setTimeout(() => { client.destroy(); process.exit(1); }, 15000);
+(async () => {
+  try {
+    await client.connect();
+    let request = { type: action };
+    if (action === 'register') {
+      const cfg = JSON.parse(fs.readFileSync(process.env.PT_WORKER_CONFIG || 'C:\\pt-worker\\state\\worker.json', 'utf8'));
+      const registrationToken = fs.readFileSync(0, 'utf8').trim();
+      if (!registrationToken.startsWith('ptrrt-')) throw new Error('bad token');
+      request = { type: 'register', url: cfg.peertube_url, runnerName: cfg.name, registrationToken,
+        runnerDescription: 'VOD only; QSV required; admission controlled' };
+    } else if (!['list-jobs', 'list-registered', 'graceful-shutdown'].includes(action)) throw new Error('bad action');
+    const result = await client.request(request);
+    if (!result.success) throw new Error('IPC failed');
+    if (action === 'list-jobs') {
+      // Drop payloads (can contain URLs); status consumers only need counts.
+      console.log(JSON.stringify({ concurrency: result.data.concurrency, active_jobs: result.data.processingJobs.length }));
+    } else if (action === 'list-registered') console.log(JSON.stringify(result.data));
+    else console.log(JSON.stringify({ success: true }));
+  } catch { console.error('Runner IPC failed; inspect local service health'); process.exitCode = 1; }
+  finally { clearTimeout(deadline); client.destroy(); }
+})();
diff --git a/infra/peertube-workers/win/pt-worker-nvenc.py b/infra/peertube-workers/win/pt-worker-nvenc.py
new file mode 100644
index 0000000..cd19385
--- /dev/null
+++ b/infra/peertube-workers/win/pt-worker-nvenc.py
@@ -0,0 +1,565 @@
+#!/usr/bin/env python3
+"""Native Windows NVENC admission controller. Linux Meter/Admission semantics,
+Windows power/thermal/GPU sensors, isolated profile, and official named-pipe IPC.
+The supervisor owns runner processes; admission only publishes fail-closed gates.
+"""
+import argparse
+import ctypes
+import json
+import os
+import re
+import subprocess
+import time
+import tomllib
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(os.environ.get('PT_ROOT', r'C:\pt-worker'))
+os.environ.update(APPDATA=str(ROOT / 'profile' / 'Roaming'), LOCALAPPDATA=str(ROOT / 'profile' / 'Local'), PT_STATE_DIR=str(ROOT / 'state'), PT_WORKER_CONFIG=str(ROOT / 'state' / 'worker.json'))
+CONFIG = ROOT / 'state' / 'worker.json'
+STATE = ROOT / 'state'
+RUNNER_CONFIG = Path(os.environ.get('APPDATA', str(Path.home() / 'AppData' / 'Roaming'))) / 'peertube-runner-nodejs' / 'Config' / 'default' / 'config.toml'
+
+DEFAULTS = {
+    'require_ac': True, 'min_disk_free_bytes': 20 * 1024 ** 3, 'max_temperature_c': 85,
+    'min_download_mbps': 10, 'min_upload_mbps': 10, 'max_latency_ms': 150,
+    'allow_derp': False, 'recovery_factor': 1.25, 'good_samples': 3, 'bad_samples': 2,
+    'bandwidth_ttl_seconds': 900, 'transfer_failure_cooldown_seconds': 60,
+    'thermal_cooldown_seconds': 120, 'poll_seconds': 5,
+}
+# Last-resort resource gates that hold even while admission policy is disabled.
+# Same thresholds as the Linux installer defaults (15 GiB RAM floor for a
+# 2-concurrency QSV worker, 6 GiB min per-job scratch); no CPU fallback exists.
+HARD_FLOORS = {'ram_total_bytes': 15 * 1024 ** 3, 'min_scratch_bytes': 6 * 1024 ** 3}
+
+
+def run(args, timeout=10):
+    return subprocess.run(args, capture_output=True, text=True, timeout=timeout)
+
+
+def read(path, default=None):
+    try:
+        return json.loads(Path(path).read_text(encoding='utf-8-sig'))
+    except (OSError, ValueError):
+        return default
+
+
+def config():
+    value = read(CONFIG)
+    if not value or not value.get('peertube_url') or not value.get('tailscale_peer'):
+        raise ValueError('worker.json needs peertube_url and tailscale_peer')
+    return {**DEFAULTS, **value}
+
+
+def ipc(action, node_binary='node'):
+    """Official runner IPC via ipc-win.cjs; the runner must be running in server mode."""
+    env = {**os.environ, 'PT_STATE_DIR': str(STATE)}
+    p = run([node_binary, str(ROOT / 'bin' / 'ipc-nvenc.cjs'), action], 15)
+    if p.returncode:
+        raise RuntimeError('runner IPC unavailable')
+    return json.loads(p.stdout)
+
+
+def registered(cfg):
+    try:
+        data = tomllib.loads(RUNNER_CONFIG.read_text(encoding='utf-8-sig'))
+        return any(r['url'].rstrip('/') == cfg['peertube_url'].rstrip('/') and
+                   r['runnerName'] == cfg['name'] and r.get('runnerToken')
+                   for r in data.get('registeredInstances', []))
+    except (OSError, ValueError, KeyError):
+        return False
+
+
+def network(cfg):
+    result = {'tailscale_ip': None, 'tailscale_path': 'unknown', 'latency_ms': None,
+              'network_ok': False, 'api_ok': False, 'peer_online': False}
+    try:
+        ts = json.loads(run([cfg.get('tailscale_binary', r'C:\Program Files\Tailscale\tailscale.exe'), 'status', '--json'], 5).stdout)
+        result['tailscale_ip'] = next((a for a in ts.get('Self', {}).get('TailscaleIPs', []) if ':' not in a), None)
+        peers = list(ts.get('Peer', {}).values())
+        peer = next((p for p in peers if cfg['tailscale_peer'] in p.get('TailscaleIPs', []) or
+                     p.get('HostName') == cfg['tailscale_peer'] or
+                     p.get('DNSName', '').split('.')[0] == cfg['tailscale_peer']), None)
+        if ts.get('BackendState') != 'Running' or not peer or not peer.get('Online'):
+            return result
+        result['peer_online'] = True
+        p = run([cfg.get('tailscale_binary', r'C:\Program Files\Tailscale\tailscale.exe'), 'ping', '--c=1', '--until-direct=false', '--timeout=3s', cfg['tailscale_peer']], 5)
+        if 'pong from' not in p.stdout:
+            return result
+        result['tailscale_path'] = 'DERP' if 'DERP(' in p.stdout else 'direct'
+        latency = re.search(r'in ([\d.]+)ms', p.stdout)
+        if latency:
+            result['latency_ms'] = float(latency[1])
+        started = time.monotonic()
+        with urllib.request.urlopen(cfg['peertube_url'].rstrip('/') + '/api/v1/config', timeout=4) as response:
+            version = json.load(response).get('serverVersion')
+        result['api_ok'] = version == cfg.get('peertube_version', '7.3.0')
+        result['network_ok'] = result['api_ok']
+    except (OSError, ValueError, subprocess.SubprocessError, urllib.error.URLError):
+        pass
+    return result
+
+
+def transfer_probe(cfg, megabytes=8):
+    """Bounded probe against pt-worker-netprobe (same server-side probe as Linux)."""
+    url = cfg.get('probe_url')
+    rates = {}
+    if not url:
+        return rates
+    payload = os.urandom(megabytes * 1024 * 1024)
+    for direction, request in (('download', urllib.request.Request(url.rstrip('/') + '/download',
+                                  data=None, method='GET')),
+                               ('upload', None)):
+        try:
+            started = time.monotonic()
+            if direction == 'download':
+                with urllib.request.urlopen(request, timeout=30) as response:
+                    seen = 0
+                    while chunk := response.read(1 << 20):
+                        seen += len(chunk)
+                        if seen >= megabytes * 1024 * 1024:
+                            break
+                    seconds = time.monotonic() - started
+                    if seen < 65536:
+                        continue
+            else:
+                req = urllib.request.Request(url.rstrip('/') + '/upload', data=payload, method='PUT')
+                urllib.request.urlopen(req, timeout=30).read()
+                seconds = time.monotonic() - started
+            rates[direction] = {'mbps': megabytes * 1024 * 1024 * 8 / 1e6 / seconds, 'time': time.time(),
+                                'bytes': megabytes * 1024 * 1024, 'seconds': seconds}
+        except (OSError, urllib.error.URLError, ValueError):
+            rates[direction + '_failed'] = True
+    return rates
+
+
+def get_system_power_status():
+    """Win32 GetSystemPowerStatus; dict or None when unsupported/unknown."""
+    class PLS(ctypes.Structure):
+        _fields_ = [('ACLineStatus', ctypes.c_byte), ('BatteryFlag', ctypes.c_byte),
+                    ('BatteryLifePercent', ctypes.c_byte), ('Reserved1', ctypes.c_byte),
+                    ('BatteryLifeTime', ctypes.c_uint32), ('BatteryFullLifeTime', ctypes.c_uint32)]
+    status = PLS()
+    if not ctypes.windll.kernel32.GetSystemPowerStatus(ctypes.byref(status)):
+        return None
+    ac = {0: False, 1: True}.get(status.ACLineStatus)  # 255 == unknown -> None
+    percentage = status.BatteryLifePercent
+    return {'on_ac': ac, 'battery_flag': status.BatteryFlag,
+            'battery_percent': None if percentage in (0, 255) else percentage}
+
+
+_thermal_cache = {'time': 0, 'temperature_c': None, 'temperatures_c': []}
+
+def sensors():
+    result = {'temperature_c': None, 'temperatures_c': [], 'on_ac': None, 'battery': [],
+              'throttle_counts': {}, 'ram_total_bytes': None, 'ram_available_bytes': None,
+              'load_average': None, 'wsl2': False}
+    try:
+        if time.time() - _thermal_cache['time'] < 300:
+            raise LookupError('cached')
+        _thermal_cache['time'] = time.time()
+        p = run(['powershell.exe', '-NoProfile', '-NonInteractive', '-Command',
+                 '(Get-CimInstance -Namespace root/wmi -ClassName MSAcpi_ThermalZoneTemperature -ErrorAction Stop | '
+                 'Measure-Object -Property CurrentTemperature -Maximum).Maximum'], 12)
+        if p.returncode == 0:
+            value = float(p.stdout.strip()) / 10.0 - 273.15
+            if 0 < value < 120:
+                result['temperature_c'] = round(value, 1)
+                result['temperatures_c'] = [result['temperature_c']]
+        _thermal_cache.update(temperature_c=result['temperature_c'], temperatures_c=result['temperatures_c'])
+    except (OSError, ValueError, LookupError, subprocess.SubprocessError):
+        result.update(temperature_c=_thermal_cache['temperature_c'], temperatures_c=_thermal_cache['temperatures_c'])
+    power = get_system_power_status()
+    if power:
+        result['on_ac'] = power['on_ac']
+        if power['battery_percent'] is not None:
+            result['battery'] = [{'capacity': power['battery_percent'],
+                                  'status': 'on_ac' if power['on_ac'] is True else 'discharging' if power['on_ac'] is False else 'unknown'}]
+    try:
+        import ctypes.wintypes  # noqa: F401  (MEMORYSTATUSEX needs no extra types)
+        class MEMORYSTATUSEX(ctypes.Structure):
+            _fields_ = [('dwLength', ctypes.c_uint32), ('dwMemoryLoad', ctypes.c_uint32),
+                        ('ullTotalPhys', ctypes.c_uint64), ('ullAvailPhys', ctypes.c_uint64),
+                        ('ullTotalPageFile', ctypes.c_uint64), ('ullAvailPageFile', ctypes.c_uint64),
+                        ('ullTotalVirtual', ctypes.c_uint64), ('ullAvailVirtual', ctypes.c_uint64),
+                        ('ullAvailExtendedVirtual', ctypes.c_uint64)]
+        memory = MEMORYSTATUSEX()
+        memory.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
+        if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(memory)):
+            result['ram_total_bytes'] = memory.ullTotalPhys
+            result['ram_available_bytes'] = memory.ullAvailPhys
+    except (OSError, AttributeError, ValueError):
+        pass
+    return result
+
+
+def disk_free(path=str(ROOT)):
+    try:
+        free = ctypes.c_ulonglong()
+        if ctypes.windll.kernel32.GetDiskFreeSpaceExW(ctypes.c_wchar_p(path), None, None, ctypes.byref(free)):
+            return free.value
+    except (OSError, AttributeError):
+        pass
+    return None
+
+
+def gpu_identity():
+    try:
+        p = run(['powershell.exe', '-NoProfile', '-NonInteractive', '-Command',
+                 'Get-CimInstance Win32_VideoController | Select-Object Name,DriverVersion,Status | ConvertTo-Json'], 12)
+        data = json.loads(p.stdout or '[]')
+        if isinstance(data, dict):
+            data = [data]
+        return data
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return []
+
+
+class Meter:
+    """Byte-identical semantics to the Linux controller's Meter."""
+
+    def __init__(self):
+        self.data = read(STATE / 'meter.json', {'offset': 0, 'jobs_completed': 0, 'jobs_failed': 0,
+                                                'transfer_failures': 0, 'active': {}}) or {}
+
+    def invalidate(self):
+        for key in ('download', 'upload'):
+            self.data.pop(key, None)
+
+    def update(self):
+        p = STATE / 'events.jsonl'
+        if not p.exists():
+            return
+        with p.open(encoding='utf-8-sig') as f:
+            if p.stat().st_size < self.data.get('offset', 0):
+                self.data['offset'] = 0
+            f.seek(self.data.get('offset', 0))
+            while True:
+                position = f.tell()
+                line = f.readline()
+                if not line:
+                    break
+                if not line.endswith('\n'):
+                    f.seek(position)
+                    break
+                try:
+                    self.consume(json.loads(line))
+                except (ValueError, KeyError, TypeError):
+                    pass
+            self.data['offset'] = f.tell()
+        try:
+            (STATE / 'meter.json').write_text(json.dumps(self.data), encoding='utf-8-sig')
+        except OSError:
+            pass
+
+    def consume(self, e):
+        kind, stamp = e['kind'], e['time']
+        if kind == 'transfer':
+            if not e['ok']:
+                self.data['transfer_failures'] = self.data.get('transfer_failures', 0) + 1
+                self.data['last_transfer_failure'] = stamp
+            elif e['bytes'] >= 65536 and e['seconds'] > 0:
+                direction = e['direction']
+                rate = e['bytes'] * 8 / e['seconds'] / 1e6
+                old = self.data.get(direction, {}).get('mbps', rate)
+                self.data[direction] = {'mbps': .3 * rate + .7 * old, 'time': stamp,
+                                        'bytes': e['bytes'], 'seconds': e['seconds']}
+        elif kind == 'gpu_failure':
+            self.data['gpu_failure_time'] = stamp
+        elif kind == 'encode':
+            self.data['last_encode'] = e
+            if e.get('job_uuid'):
+                self.data.setdefault('encodes', {})[e['job_uuid']] = e
+        elif kind == 'job_accept' and e['ok']:
+            self.data.setdefault('active', {})[e['uuid']] = stamp
+        elif kind in ('job_success', 'job_error', 'job_abort') and e['ok']:
+            begun = self.data.setdefault('active', {}).pop(e['uuid'], None)
+            if kind == 'job_success':
+                self.data['jobs_completed'] = self.data.get('jobs_completed', 0) + 1
+                elapsed = stamp - begun if begun else None
+                self.data['last_job_duration_seconds'] = elapsed
+                self.data['last_job_uuid'] = e['uuid']
+                encoded = self.data.setdefault('encodes', {}).pop(e['uuid'], {})
+                duration = encoded.get('duration')
+                self.data['last_job_realtime_factor'] = duration / elapsed if duration and elapsed else None
+                self.data['last_job_encode'] = encoded or None
+            elif kind == 'job_error':
+                self.data['jobs_failed'] = self.data.get('jobs_failed', 0) + 1
+            for path in (STATE / 'inputs').glob('*.json'):
+                if read(path) and read(path).get('uuid') == e['uuid']:
+                    try:
+                        path.unlink()
+                    except OSError:
+                        pass
+
+    def rates(self, now, ttl):
+        return {f'recent_{k}_mbps': self.data.get(k, {}).get('mbps')
+                if now - self.data.get(k, {}).get('time', 0) < ttl else None
+                for k in ('download', 'upload')}
+
+
+class Admission:
+    """Decision gates: PAUSED, GPU_UNAVAILABLE, DRAINING (power), LOW_DISK,
+    THERMAL_THROTTLED, OFFLINE, NETWORK_DEGRADED, BUSY, AVAILABLE.
+    Hysteresis and thresholds identical to the Linux controller."""
+
+    def __init__(self, cfg):
+        self.cfg, self.good, self.bad = cfg, 0, 0
+        self.admitted, self.path, self.throttles = False, None, {}
+
+    def decide(self, sample, metric, control, now):
+        cfg = self.cfg
+        def refuse(state):
+            self.admitted, self.good = False, 0
+            return state
+        if self.path and sample['tailscale_path'] != self.path:
+            self.admitted = False
+            self.good = 0
+            metric.invalidate()
+        self.path = sample['tailscale_path']
+        rates = metric.rates(now, cfg.get('bandwidth_ttl_seconds', 900))
+        sample.update(rates)
+        if control.get('paused', True):
+            return refuse('PAUSED')
+        if not sample['registered']:
+            return refuse('PAUSED')
+        gpu_failed = metric.data.get('gpu_failure_time', 0) >= sample.get('gpu_tested_at', 0)
+        if not sample['gpu_accessible'] or not sample.get('gpu_ready') or gpu_failed:
+            return refuse('GPU_UNAVAILABLE')
+        if cfg.get('require_ac', True) and sample['on_ac'] is not True:
+            return refuse('DRAINING')
+        if sample['disk_free_bytes'] is None or sample['disk_free_bytes'] < cfg.get('min_disk_free_bytes', 20 * 1024 ** 3):
+            return refuse('LOW_DISK')
+        rising = any(v > self.throttles.get(k, v) for k, v in sample['throttle_counts'].items())
+        self.throttles = sample['throttle_counts']
+        if rising or (sample['temperature_c'] is not None and sample['temperature_c'] >= cfg.get('max_temperature_c', 85)):
+            self.thermal_until = now + cfg.get('thermal_cooldown_seconds', 120)
+        if now < getattr(self, 'thermal_until', 0):
+            return refuse('THERMAL_THROTTLED')
+        if not sample['network_ok']:
+            self.admitted, self.good = False, 0
+            return 'OFFLINE'
+        calibrating = control.get('calibrate_until', 0) > now
+        factor = cfg.get('recovery_factor', 1.25) if not self.admitted else 1
+        bad = sample['latency_ms'] is None or sample['latency_ms'] > cfg.get('max_latency_ms', 150)
+        bad |= sample['tailscale_path'] == 'DERP' and not cfg.get('allow_derp', False)
+        if not calibrating:
+            bad |= any(rates[f'recent_{key}_mbps'] is None or rates[f'recent_{key}_mbps'] <
+                       cfg.get(f'min_{key}_mbps', 10) * factor for key in ('download', 'upload'))
+        bad |= now - metric.data.get('last_transfer_failure', 0) < cfg.get('transfer_failure_cooldown_seconds', 60)
+        if bad:
+            self.good, self.bad = 0, self.bad + 1
+            if self.bad >= cfg.get('bad_samples', 2) or not self.admitted:
+                self.admitted = False
+                return 'NETWORK_DEGRADED'
+        else:
+            self.bad, self.good = 0, self.good + 1
+            if self.good >= cfg.get('good_samples', 3):
+                self.admitted = True
+        if not self.admitted:
+            return 'NETWORK_DEGRADED'
+        return 'BUSY' if sample['active_jobs'] else 'AVAILABLE'
+
+
+def atomic(path, value):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix('.tmp-' + str(os.getpid()))
+    tmp.write_text(json.dumps(value), encoding='utf8')
+    os.replace(tmp, path)
+
+
+def gpu_snapshot(cfg):
+    p = run(['nvidia-smi.exe', '-i', str(cfg.get('nvenc_device', 0)),
+             '--query-gpu=name,uuid,driver_version,temperature.gpu,utilization.encoder',
+             '--format=csv,noheader,nounits'], 5)
+    if p.returncode:
+        raise RuntimeError('GPU query failed')
+    name, uuid, driver, temp, util = [v.strip() for v in p.stdout.strip().split(',')]
+    return {'gpu_model': name, 'gpu_uuid': uuid, 'driver_version': driver,
+            'temperature_c': float(temp), 'encoder_util': float(util)}
+
+
+def boot_hardware():
+    p = run(['powershell.exe', '-NoProfile', '-NonInteractive', '-Command',
+             "[pscustomobject]@{boot_id=(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o');cpu_model=(Get-CimInstance Win32_Processor | Select-Object -First 1).Name} | ConvertTo-Json -Compress"], 30)
+    return json.loads(p.stdout)
+
+
+def collect(cfg, meter, admission, hw):
+    now = time.time()
+    meter.update()
+    sensor = sensors()
+    proof = read(STATE / 'nvenc.json', {}) or {}
+    gpu = {}
+    try:
+        gpu = gpu_snapshot(cfg)
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError):
+        pass
+    ready = bool(proof.get('nvenc_h264_ok') and proof.get('nvenc_hevc_ok') and
+                 proof.get('boot_id') == hw.get('boot_id') and
+                 proof.get('driver_version') == gpu.get('driver_version') and
+                 proof.get('gpu_uuid') == gpu.get('gpu_uuid') and
+                 proof.get('device') == cfg.get('nvenc_device', 0) and
+                 0 <= now - proof.get('tested_at', 0) < 7 * 86400)
+    runner = read(STATE / 'runner.json', {}) or {}
+    running = runner.get('running', False) and now - runner.get('updated_at', 0) < 30
+    jobs, ipc_ok = {'active_jobs': 0, 'concurrency': cfg.get('concurrency', 2)}, not running
+    if running:
+        try:
+            jobs = ipc('list-jobs', cfg['node_binary'])
+            ipc_ok = True
+        except (OSError, ValueError, RuntimeError, subprocess.SubprocessError):
+            jobs['active_jobs'] = None
+    temps = sensor['temperatures_c'] + ([gpu['temperature_c']] if gpu else [])
+    sample = {**network(cfg), **sensor, **hw, 'hostname': cfg['name'], 'updated_at': now,
+              'registered': registered(cfg), 'registration_state': 'registered' if registered(cfg) else 'unregistered',
+              **jobs, 'gpu_accessible': bool(gpu) and not (STATE / 'gpu-unavailable').exists(),
+              'gpu_ready': ready, 'gpu_tested_at': proof.get('tested_at', 0),
+              'disk_free_bytes': disk_free(), 'temperature_c': max(temps, default=None),
+              'temperatures_c': temps, 'throttle_counts': {}, 'qsv': {'qsv_h264_ok': False, 'qsv_hevc_ok': False},
+              'qsv_h264_ok': False, 'qsv_hevc_ok': False,
+              'nvenc_h264_ok': proof.get('nvenc_h264_ok', False), 'nvenc_hevc_ok': proof.get('nvenc_hevc_ok', False),
+              'av1_decode_ok': proof.get('av1_decode_ok'), 'av1_encode_ok': False, 'backend': 'nvidia_nvenc',
+              'gpu_model': gpu.get('gpu_model'), 'driver_version': gpu.get('driver_version'),
+              'tested_at': proof.get('tested_at'), 'runner_running': bool(running),
+              'draining': runner.get('draining', False), 'util': {'cpu': None, 'gpu': {'encoder': gpu.get('encoder_util')}}}
+    if sample['disk_free_bytes'] is None:
+        sample['disk_free_bytes'] = 0
+    state = admission.decide(sample, meter, read(STATE / 'control.json', {'paused': True}), now)
+    if not ipc_ok:
+        state = 'OFFLINE'
+    sample.update(status=state, state=state, admission_allowed=state in ('AVAILABLE', 'BUSY'),
+                  jobs_completed=meter.data.get('jobs_completed', 0), jobs_failed=meter.data.get('jobs_failed', 0),
+                  last_job_duration_seconds=meter.data.get('last_job_duration_seconds'),
+                  last_job_realtime_factor=meter.data.get('last_job_realtime_factor'))
+    sample.update({k: meter.data.get(k) for k in ('transfer_failures', 'last_job_uuid', 'last_job_encode', 'last_encode')})
+    # Linux status keys remain intact; research/fleet aliases are additive.
+    sample.update(registration=sample['registered'], gpu_util=gpu.get('encoder_util'), temps=temps,
+                  disk_free=sample['disk_free_bytes'], last_job_duration=sample['last_job_duration_seconds'],
+                  last_job_rtf=sample['last_job_realtime_factor'], updated_at=time.time())
+    return sample
+
+
+def self_test_marker_stale(hw, proof):
+    return not proof.get('tested_at') or time.time() - proof['tested_at'] > 7 * 86400 or proof.get('boot_id') != hw.get('boot_id') or proof.get('driver_version') != hw.get('driver_version')
+
+
+def daemon():
+    import msvcrt
+    import signal
+    lock = (STATE / 'admission.lock').open('a+b')
+    lock.seek(0); lock.write(b'0'); lock.flush(); lock.seek(0)
+    msvcrt.locking(lock.fileno(), msvcrt.LK_NBLCK, 1)
+    cfg = config()
+    meter, admission = Meter(), Admission(cfg)
+    while True:
+        try:
+            hw = boot_hardware()
+            break
+        except (OSError, ValueError, subprocess.SubprocessError):
+            atomic(STATE / 'status.json', {'hostname': cfg['name'], 'status': 'OFFLINE', 'state': 'OFFLINE', 'updated_at': time.time(), 'admission_allowed': False})
+            time.sleep(5)
+    atomic(STATE / 'hardware.json', hw)
+    stopped = False
+    def stop(*_):
+        nonlocal stopped
+        stopped = True
+    signal.signal(signal.SIGINT, stop)
+    signal.signal(signal.SIGTERM, stop)
+    last_probe, previous_path = 0, None
+    attempted_proof = None
+    while not stopped:
+        try:
+            proof = read(STATE / 'nvenc.json', {}) or {}
+            gpu = gpu_snapshot(cfg)
+            identity = (hw.get('boot_id'), gpu.get('driver_version'))
+            if self_test_marker_stale(hw | {'driver_version': gpu.get('driver_version')}, proof) and identity != attempted_proof and not read(STATE / 'runner.json', {}).get('running'):
+                attempted_proof = identity
+                atomic(STATE / 'status.json', {'updated_at': time.time(), 'status': 'GPU_UNAVAILABLE', 'state': 'GPU_UNAVAILABLE', 'admission_allowed': False})
+                if get_system_power_status() and get_system_power_status()['on_ac'] is True:
+                    subprocess.run(['powershell.exe', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-File', str(ROOT / 'selftest-nvenc.ps1'), '-Root', str(ROOT), '-Device', str(cfg.get('nvenc_device', 0))], capture_output=True, timeout=90)
+            sample = collect(cfg, meter, admission, hw)
+            if previous_path and previous_path != sample['tailscale_path']:
+                meter.invalidate(); last_probe = 0
+                admission.admitted, admission.good, admission.path = False, 0, None
+                sample['admission_allowed'] = False
+                sample['state'] = sample['status'] = 'NETWORK_DEGRADED'
+            previous_path = sample['tailscale_path']
+            atomic(STATE / 'status.json', sample)
+            control = read(STATE / 'control.json', {'paused': True})
+            if not control.get('paused', True) and sample['network_ok'] and sample['on_ac'] is True and \
+               sample['tailscale_path'] == 'direct' and sample['active_jobs'] == 0 and \
+               time.time() - last_probe >= cfg.get('probe_interval_seconds', 300):
+                # Close admission and wait for the official graceful drain before measuring.
+                sample.update(admission_allowed=False, state='DRAINING', status='DRAINING')
+                atomic(STATE / 'status.json', sample)
+                if not sample['runner_running']:
+                    rates = transfer_probe(cfg)
+                    for direction in ('download', 'upload'):
+                        value = rates.get(direction)
+                        meter.consume({'kind': 'transfer', 'time': time.time(), 'direction': direction,
+                                       'ok': bool(value), 'bytes': value['bytes'] if value else 0,
+                                       'seconds': value['seconds'] if value else 1})
+                    atomic(STATE / 'meter.json', meter.data)
+                    last_probe = time.time()
+        except Exception:
+            # Suppress exception strings: upstream data may contain credentials/URLs.
+            atomic(STATE / 'status.json', {'hostname': cfg['name'], 'status': 'OFFLINE', 'state': 'OFFLINE',
+                                         'updated_at': time.time(), 'admission_allowed': False})
+        before_sleep = time.time()
+        time.sleep(cfg.get('poll_seconds', 5))
+        if time.time() - before_sleep > cfg.get('poll_seconds', 5) * 3:
+            meter.invalidate()
+            admission.admitted, admission.good = False, 0
+            last_probe = 0
+    atomic(STATE / 'status.json', {'hostname': cfg['name'], 'status': 'OFFLINE', 'state': 'OFFLINE',
+                                 'updated_at': time.time(), 'admission_allowed': False})
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('command', choices=['daemon', 'status', 'network-test', 'start', 'stop', 'drain', 'restart', 'self-test'])
+    args = parser.parse_args()
+    STATE.mkdir(parents=True, exist_ok=True)
+    if args.command == 'daemon':
+        daemon()
+    elif args.command == 'status':
+        value = read(STATE / 'status.json', {'hostname': config()['name'], 'status': 'OFFLINE', 'state': 'OFFLINE'})
+        if time.time() - value.get('updated_at', 0) > 30:
+            value.update(status='OFFLINE', state='OFFLINE', stale=True, admission_allowed=False)
+        print(json.dumps(value, indent=2))
+    elif args.command == 'network-test':
+        meter = Meter(); meter.update()
+        rates = transfer_probe(config())
+        for direction in ('download', 'upload'):
+            r = rates.get(direction)
+            meter.consume({'kind': 'transfer', 'time': time.time(), 'direction': direction, 'ok': bool(r),
+                           'bytes': r['bytes'] if r else 0, 'seconds': r['seconds'] if r else 1})
+        atomic(STATE / 'meter.json', meter.data)
+        print(json.dumps(rates))
+        return 0 if all(k in rates for k in ('download', 'upload')) else 1
+    elif args.command == 'self-test':
+        if read(STATE / 'runner.json', {}).get('running'):
+            raise ValueError('drain before self-test')
+        return subprocess.call(['powershell.exe', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass',
+                                '-File', str(ROOT / 'selftest-nvenc.ps1'), '-Root', str(ROOT),
+                                '-Device', str(config().get('nvenc_device', 0))])
+    else:
+        paused = args.command in ('stop', 'drain')
+        atomic(STATE / 'control.json', {'paused': paused})
+        if args.command == 'restart':
+            try:
+                ipc('graceful-shutdown', config()['node_binary'])
+            except (OSError, RuntimeError, subprocess.SubprocessError):
+                pass
+        print(json.dumps({'requested': args.command, 'paused': paused}))
+    return 0
+
+
+if __name__ == '__main__':
+    try:
+        raise SystemExit(main())
+    except (OSError, ValueError, RuntimeError, subprocess.SubprocessError):
+        print('pt-worker-win: command failed; check service health', file=__import__('sys').stderr)
+        raise SystemExit(1)
diff --git a/infra/peertube-workers/win/pt-worker-win.py b/infra/peertube-workers/win/pt-worker-win.py
new file mode 100644
index 0000000..9cb375b
--- /dev/null
+++ b/infra/peertube-workers/win/pt-worker-win.py
@@ -0,0 +1,459 @@
+#!/usr/bin/env python3
+"""pt-worker admission controller, native Windows port (validator for the design
+in windows-worker-result.md).
+
+Ported from infra/peertube-workers/pt-worker.py: identical Meter / Admission
+state machine and policy defaults (AC-only, 20 GiB reserve, 85 C ceiling,
+10 Mbps floors with 1.25x recovery factor, DERP disallowed, 3-good/2-bad
+hysteresis, 120 s thermal cooldown, 60 s transfer-failure cooldown, 900 s
+bandwidth TTL, 5 s poll). Windows deltas:
+  - power/battery via GetSystemPowerStatus (ctypes; None == unknown == drain);
+    Modern Standby is mitigated with `powercfg /change standby-timeout-ac 0`
+    during install, not here.
+  - temperatures via MSAcpi_ThermalZoneTemperature; unsupported sensors yield
+    None (unsupported measurements are never invented).
+  - GPU encode telemetry from PDH GPU Engine (engtype_VideoEncode) counters;
+    DRM fdinfo does not exist on Windows. Node >=18.20/20.12: `os.loadavg()`
+    returns [0,0,0] on Windows and is not emitted.
+  - cross-process daemon lock is a win32 mutex via msvcrt (fcntl is POSIX).
+  - drain is delivered through the official runner named-pipe IPC.
+  - hardware re-proof triggers on driver_version change in addition to boot_id
+    (Windows Update can silently change graphics drivers).
+
+Runs on CPython >= 3.11 with psutil (optional: improves disk/memory collection).
+Emitting a status JSON is safe to run standalone on Windows or elsewhere.
+"""
+import argparse
+import ctypes
+import json
+import os
+import re
+import subprocess
+import time
+import tomllib
+import urllib.request
+from pathlib import Path
+
+ROOT = Path(r'C:\pt-worker')
+CONFIG = ROOT / 'state' / 'worker.json'
+STATE = ROOT / 'state'
+RUNNER_CONFIG = Path(os.environ.get('APPDATA', str(Path.home() / 'AppData' / 'Roaming'))) / 'peertube-runner-nodejs' / 'Config' / 'config.toml'
+
+DEFAULTS = {
+    'require_ac': True, 'min_disk_free_bytes': 20 * 1024 ** 3, 'max_temperature_c': 85,
+    'min_download_mbps': 10, 'min_upload_mbps': 10, 'max_latency_ms': 150,
+    'allow_derp': False, 'recovery_factor': 1.25, 'good_samples': 3, 'bad_samples': 2,
+    'bandwidth_ttl_seconds': 900, 'transfer_failure_cooldown_seconds': 60,
+    'thermal_cooldown_seconds': 120, 'poll_seconds': 5,
+}
+# Last-resort resource gates that hold even while admission policy is disabled.
+# Same thresholds as the Linux installer defaults (15 GiB RAM floor for a
+# 2-concurrency QSV worker, 6 GiB min per-job scratch); no CPU fallback exists.
+HARD_FLOORS = {'ram_total_bytes': 15 * 1024 ** 3, 'min_scratch_bytes': 6 * 1024 ** 3}
+
+
+def run(args, timeout=10):
+    return subprocess.run(args, capture_output=True, text=True, timeout=timeout)
+
+
+def read(path, default=None):
+    try:
+        return json.loads(Path(path).read_text(encoding='utf8'))
+    except (OSError, ValueError):
+        return default
+
+
+def config():
+    value = read(CONFIG)
+    if not value or not value.get('peertube_url') or not value.get('tailscale_peer'):
+        raise ValueError('worker.json needs peertube_url and tailscale_peer')
+    return {**DEFAULTS, **value}
+
+
+def ipc(action, node_binary='node'):
+    """Official runner IPC via ipc-win.cjs; the runner must be running in server mode."""
+    env = {**os.environ, 'PT_STATE_DIR': str(STATE)}
+    p = run([node_binary, str(ROOT / 'bin' / 'ipc-win.cjs'), action], 15)
+    if p.returncode:
+        raise RuntimeError('runner IPC unavailable')
+    return json.loads(p.stdout)
+
+
+def registered(cfg):
+    try:
+        data = tomllib.loads(RUNNER_CONFIG.read_text(encoding='utf8'))
+        return any(r['url'].rstrip('/') == cfg['peertube_url'].rstrip('/') and
+                   r['runnerName'] == cfg['name'] and r.get('runnerToken')
+                   for r in data.get('registeredInstances', []))
+    except (OSError, ValueError, KeyError):
+        return False
+
+
+def network(cfg):
+    result = {'tailscale_ip': None, 'tailscale_path': 'unknown', 'latency_ms': None,
+              'network_ok': False, 'api_ok': False, 'peer_online': False}
+    try:
+        ts = json.loads(run(['tailscale', 'status', '--json'], 5).stdout)
+        result['tailscale_ip'] = next((a for a in ts.get('Self', {}).get('TailscaleIPs', []) if ':' not in a), None)
+        peers = list(ts.get('Peer', {}).values())
+        peer = next((p for p in peers if cfg['tailscale_peer'] in p.get('TailscaleIPs', []) or
+                     p.get('HostName') == cfg['tailscale_peer'] or
+                     p.get('DNSName', '').split('.')[0] == cfg['tailscale_peer']), None)
+        if ts.get('BackendState') != 'Running' or not peer or not peer.get('Online'):
+            return result
+        result['peer_online'] = True
+        p = run(['tailscale', 'ping', '--c=1', '--until-direct=false', '--timeout=3s', cfg['tailscale_peer']], 5)
+        if 'pong from' not in p.stdout:
+            return result
+        result['tailscale_path'] = 'DERP' if 'DERP(' in p.stdout else 'direct'
+        latency = re.search(r'in ([\d.]+)ms', p.stdout)
+        if latency:
+            result['latency_ms'] = float(latency[1])
+        started = time.monotonic()
+        with urllib.request.urlopen(cfg['peertube_url'].rstrip('/') + '/api/v1/config', timeout=4) as response:
+            version = json.load(response).get('serverVersion')
+        result['api_ok'] = version == cfg.get('peertube_version', '7.3.0')
+        result['network_ok'] = result['api_ok']
+    except (OSError, ValueError, subprocess.SubprocessError, urllib.error.URLError):
+        pass
+    return result
+
+
+def transfer_probe(cfg, megabytes=8):
+    """Bounded probe against pt-worker-netprobe (same server-side probe as Linux)."""
+    url = cfg.get('probe_url')
+    rates = {}
+    if not url:
+        return rates
+    payload = os.urandom(megabytes * 1024 * 1024)
+    for direction, request in (('download', urllib.request.Request(url.rstrip('/') + '/download',
+                                  data=None, method='GET')),
+                               ('upload', None)):
+        try:
+            started = time.monotonic()
+            if direction == 'download':
+                with urllib.request.urlopen(request, timeout=30) as response:
+                    seen = 0
+                    while len(response.read(1 << 20)):
+                        seen += 1 << 20
+                        if seen >= megabytes * 1024 * 1024:
+                            break
+                    seconds = time.monotonic() - started
+                    if seen < 65536:
+                        continue
+            else:
+                req = urllib.request.Request(url.rstrip('/') + '/upload', data=payload, method='POST')
+                urllib.request.urlopen(req, timeout=30).read()
+                seconds = time.monotonic() - started
+            rates[direction] = {'mbps': megabytes * 8 / seconds, 'time': time.time(),
+                                'bytes': megabytes * 1024 * 1024, 'seconds': seconds}
+        except (OSError, urllib.error.URLError, ValueError):
+            rates[direction + '_failed'] = True
+    return rates
+
+
+def get_system_power_status():
+    """Win32 GetSystemPowerStatus; dict or None when unsupported/unknown."""
+    class PLS(ctypes.Structure):
+        _fields_ = [('ACLineStatus', ctypes.c_byte), ('BatteryFlag', ctypes.c_byte),
+                    ('BatteryLifePercent', ctypes.c_byte), ('Reserved1', ctypes.c_byte),
+                    ('BatteryLifeTime', ctypes.c_uint32), ('BatteryFullLifeTime', ctypes.c_uint32)]
+    status = PLS()
+    if not ctypes.windll.kernel32.GetSystemPowerStatus(ctypes.byref(status)):
+        return None
+    ac = {0: False, 1: True}.get(status.ACLineStatus)  # 255 == unknown -> None
+    percentage = status.BatteryLifePercent
+    return {'on_ac': ac, 'battery_flag': status.BatteryFlag,
+            'battery_percent': None if percentage in (0, 255) else percentage}
+
+
+def sensors():
+    result = {'temperature_c': None, 'temperatures_c': [], 'on_ac': None, 'battery': [],
+              'throttle_counts': {}, 'ram_total_bytes': None, 'ram_available_bytes': None,
+              'load_average': None}
+    try:
+        p = run(['powershell', '-NoProfile', '-NonInteractive', '-Command',
+                 '(Get-CimInstance -ClassName MSAcpi_ThermalZoneTemperature -ErrorAction Stop | '
+                 'Measure-Object -Property CurrentTemperature -Maximum).Maximum'], 12)
+        if p.returncode == 0:
+            value = float(p.stdout.strip()) / 10.0 - 273.15
+            if 0 < value < 120:
+                result['temperature_c'] = round(value, 1)
+                result['temperatures_c'] = [result['temperature_c']]
+    except (OSError, ValueError, subprocess.SubprocessError):
+        pass
+    power = get_system_power_status()
+    if power:
+        result['on_ac'] = power['on_ac']
+        if power['battery_percent'] is not None:
+            result['battery'] = [{'capacity': power['battery_percent'],
+                                  'status': {0: 'unknown', 1: 'discharging', 2: 'on_ac'}.get(power['battery_flag'], 'other')}]
+    try:
+        import ctypes.wintypes  # noqa: F401  (MEMORYSTATUSEX needs no extra types)
+        class MEMORYSTATUSEX(ctypes.Structure):
+            _fields_ = [('dwLength', ctypes.c_uint32), ('dwMemoryLoad', ctypes.c_uint32),
+                        ('ullTotalPhys', ctypes.c_uint64), ('ullAvailPhys', ctypes.c_uint64),
+                        ('ullTotalPageFile', ctypes.c_uint64), ('ullAvailPageFile', ctypes.c_uint64),
+                        ('ullTotalVirtual', ctypes.c_uint64), ('ullAvailVirtual', ctypes.c_uint64),
+                        ('ullAvailExtendedVirtual', ctypes.c_uint64)]
+        memory = MEMORYSTATUSEX()
+        memory.dwLength = ctypes.sizeof(MEMORYSTATUSEX)
+        if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(memory)):
+            result['ram_total_bytes'] = memory.ullTotalPhys
+            result['ram_available_bytes'] = memory.ullAvailPhys
+    except (OSError, AttributeError, ValueError):
+        pass
+    return result
+
+
+def disk_free(path=str(ROOT)):
+    try:
+        free = ctypes.c_ulonglong()
+        if ctypes.windll.kernel32.GetDiskFreeSpaceExW(ctypes.c_wchar_p(path), None, None, ctypes.byref(free)):
+            return free.value
+    except (OSError, AttributeError):
+        pass
+    return None
+
+
+def gpu_identity():
+    try:
+        p = run(['powershell', '-NoProfile', '-NonInteractive', '-Command',
+                 'Get-CimInstance Win32_VideoController | Select-Object Name,DriverVersion,Status | ConvertTo-Json'], 12)
+        data = json.loads(p.stdout or '[]')
+        if isinstance(data, dict):
+            data = [data]
+        return data
+    except (OSError, ValueError, subprocess.SubprocessError):
+        return []
+
+
+class Meter:
+    """Byte-identical semantics to the Linux controller's Meter."""
+
+    def __init__(self):
+        self.data = read(STATE / 'meter.json', {'offset': 0, 'jobs_completed': 0, 'jobs_failed': 0,
+                                                'transfer_failures': 0, 'active': {}}) or {}
+
+    def invalidate(self):
+        for key in ('download', 'upload'):
+            self.data.pop(key, None)
+
+    def update(self):
+        p = STATE / 'events.jsonl'
+        if not p.exists():
+            return
+        with p.open(encoding='utf8') as f:
+            if p.stat().st_size < self.data.get('offset', 0):
+                self.data['offset'] = 0
+            f.seek(self.data.get('offset', 0))
+            while True:
+                position = f.tell()
+                line = f.readline()
+                if not line:
+                    break
+                if not line.endswith('\n'):
+                    f.seek(position)
+                    break
+                try:
+                    self.consume(json.loads(line))
+                except (ValueError, KeyError, TypeError):
+                    pass
+            self.data['offset'] = f.tell()
+        try:
+            (STATE / 'meter.json').write_text(json.dumps(self.data), encoding='utf8')
+        except OSError:
+            pass
+
+    def consume(self, e):
+        kind, stamp = e['kind'], e['time']
+        if kind == 'transfer':
+            if not e['ok']:
+                self.data['transfer_failures'] = self.data.get('transfer_failures', 0) + 1
+                self.data['last_transfer_failure'] = stamp
+            elif e['bytes'] >= 65536 and e['seconds'] > 0:
+                direction = e['direction']
+                rate = e['bytes'] * 8 / e['seconds'] / 1e6
+                old = self.data.get(direction, {}).get('mbps', rate)
+                self.data[direction] = {'mbps': .3 * rate + .7 * old, 'time': stamp,
+                                        'bytes': e['bytes'], 'seconds': e['seconds']}
+        elif kind == 'gpu_failure':
+            self.data['gpu_failure_time'] = stamp
+        elif kind == 'encode':
+            self.data['last_encode'] = e
+            if e.get('job_uuid'):
+                self.data.setdefault('encodes', {})[e['job_uuid']] = e
+        elif kind == 'job_accept' and e['ok']:
+            self.data.setdefault('active', {})[e['uuid']] = stamp
+        elif kind in ('job_success', 'job_error', 'job_abort') and e['ok']:
+            begun = self.data.setdefault('active', {}).pop(e['uuid'], None)
+            if kind == 'job_success':
+                self.data['jobs_completed'] = self.data.get('jobs_completed', 0) + 1
+                elapsed = stamp - begun if begun else None
+                self.data['last_job_duration_seconds'] = elapsed
+                self.data['last_job_uuid'] = e['uuid']
+                encoded = self.data.setdefault('encodes', {}).pop(e['uuid'], {})
+                duration = encoded.get('duration')
+                self.data['last_job_realtime_factor'] = duration / elapsed if duration and elapsed else None
+                self.data['last_job_encode'] = encoded or None
+            elif kind == 'job_error':
+                self.data['jobs_failed'] = self.data.get('jobs_failed', 0) + 1
+            for path in (STATE / 'inputs').glob('*.json'):
+                if read(path) and read(path).get('uuid') == e['uuid']:
+                    try:
+                        path.unlink()
+                    except OSError:
+                        pass
+
+    def rates(self, now, ttl):
+        return {f'recent_{k}_mbps': self.data.get(k, {}).get('mbps')
+                if now - self.data.get(k, {}).get('time', 0) < ttl else None
+                for k in ('download', 'upload')}
+
+
+class Admission:
+    """Decision gates: PAUSED, GPU_UNAVAILABLE, DRAINING (power), LOW_DISK,
+    THERMAL_THROTTLED, OFFLINE, NETWORK_DEGRADED, BUSY, AVAILABLE.
+    Hysteresis and thresholds identical to the Linux controller."""
+
+    def __init__(self, cfg):
+        self.cfg, self.good, self.bad = cfg, 0, 0
+        self.admitted, self.path, self.throttles = False, None, {}
+
+    def decide(self, sample, metric, control, now):
+        cfg = self.cfg
+        def refuse(state):
+            self.admitted, self.good = False, 0
+            return state
+        if self.path and sample['tailscale_path'] != self.path:
+            self.admitted = False
+            self.good = 0
+            metric.invalidate()
+        self.path = sample['tailscale_path']
+        rates = metric.rates(now, cfg.get('bandwidth_ttl_seconds', 900))
+        sample.update(rates)
+        if control.get('paused', True):
+            return refuse('PAUSED')
+        if not sample['registered']:
+            return refuse('PAUSED')
+        gpu_failed = metric.data.get('gpu_failure_time', 0) >= sample.get('gpu_tested_at', 0)
+        if not sample['gpu_accessible'] or not sample.get('gpu_ready') or gpu_failed:
+            return refuse('GPU_UNAVAILABLE')
+        if cfg.get('require_ac', True) and sample['on_ac'] is not True:
+            return refuse('DRAINING')
+        if sample['disk_free_bytes'] is None or sample['disk_free_bytes'] < cfg.get('min_disk_free_bytes', 20 * 1024 ** 3):
+            return refuse('LOW_DISK')
+        rising = any(v > self.throttles.get(k, v) for k, v in sample['throttle_counts'].items())
+        self.throttles = sample['throttle_counts']
+        if rising or (sample['temperature_c'] is not None and sample['temperature_c'] >= cfg.get('max_temperature_c', 85)):
+            self.thermal_until = now + cfg.get('thermal_cooldown_seconds', 120)
+        if now < getattr(self, 'thermal_until', 0):
+            return refuse('THERMAL_THROTTLED')
+        if not sample['network_ok']:
+            self.admitted, self.good = False, 0
+            return 'OFFLINE'
+        calibrating = control.get('calibrate_until', 0) > now
+        factor = cfg.get('recovery_factor', 1.25) if not self.admitted else 1
+        bad = sample['latency_ms'] is None or sample['latency_ms'] > cfg.get('max_latency_ms', 150)
+        bad |= sample['tailscale_path'] == 'DERP' and not cfg.get('allow_derp', False)
+        if not calibrating:
+            bad |= any(rates[f'recent_{key}_mbps'] is None or rates[f'recent_{key}_mbps'] <
+                       cfg.get(f'min_{key}_mbps', 10) * factor for key in ('download', 'upload'))
+        bad |= now - metric.data.get('last_transfer_failure', 0) < cfg.get('transfer_failure_cooldown_seconds', 60)
+        if bad:
+            self.good, self.bad = 0, self.bad + 1
+            if self.bad >= cfg.get('bad_samples', 2) or not self.admitted:
+                self.admitted = False
+                return 'NETWORK_DEGRADED'
+        else:
+            self.bad, self.good = 0, self.good + 1
+            if self.good >= cfg.get('good_samples', 3):
+                self.admitted = True
+        if not self.admitted:
+            return 'NETWORK_DEGRADED'
+        return 'BUSY' if sample['active_jobs'] else 'AVAILABLE'
+
+
+def status():
+    """Read-only status document (same schema as the Linux worker's status JSON;
+    names preserved so central fleet tooling needs no OS branches)."""
+    cfg = config()
+    now = time.time()
+    meter = Meter()
+    meter.update()
+    admission = Admission(cfg)
+    sensors_data = sensors()
+    hw = read(STATE / 'hardware.json', {}) or {}
+    gpu = hw.get('gpu_model') or gpu_identity()
+    proof = read(STATE / 'qsv.json', {}) or {}
+    proof_current = bool(proof.get('qsv_h264_ok')) and proof.get('tested_at', 0) > now - 7 * 86400 and \
+        (proof.get('boot_id') == hw.get('boot_id') and proof.get('driver_version') == hw.get('driver_version'))
+    control = read(STATE / 'control.json', {}) or {}
+    active = {}
+    try:
+        active = ipc('list-jobs', cfg.get('node_binary', 'node'))
+    except (RuntimeError, ValueError, OSError):
+        active = {}
+    sample = {**network(cfg), 'registered': registered(cfg),
+              'gpu_accessible': bool(proof_current), 'gpu_ready': bool(proof_current),
+              'gpu_tested_at': proof.get('tested_at', 0),
+              'on_ac': sensors_data['on_ac'], 'disk_free_bytes': disk_free(),
+              'temperature_c': sensors_data['temperature_c'],
+              'throttle_counts': sensors_data['throttle_counts'],
+              'active_jobs': active.get('active_jobs'), 'concurrency': active.get('concurrency')}
+    state = admission.decide(sample, meter, control, now)
+    rates = meter.rates(now, cfg.get('bandwidth_ttl_seconds', 900))
+    last = meter.data.get('last_encode') or {}
+    return {'hostname': os.environ.get('COMPUTERNAME', 'unknown'), 'state': state,
+            'tailscale_ip': sample['tailscale_ip'], 'tailscale_path': sample['tailscale_path'],
+            'registration': sample['registered'], 'cpu_model': hw.get('cpu_model'),
+            'gpu_model': gpu, 'gpu_driver_version': hw.get('driver_version'),
+            'qsv_h264_ok': proof.get('qsv_h264_ok'), 'qsv_hevc_ok': proof.get('qsv_hevc_ok'),
+            'av1_decode_ok': proof.get('av1_decode_ok'), 'av1_encode_ok': proof.get('av1_encode_ok'),
+            'active_jobs': sample['active_jobs'], 'concurrency': sample['concurrency'],
+            'gpu_util': last.get('engine_busy_max'), 'temps': sensors_data['temperatures_c'],
+            'disk_free': sample['disk_free_bytes'],
+            'ram_total_bytes': sensors_data['ram_total_bytes'],
+            'ram_available_bytes': sensors_data['ram_available_bytes'],
+            'on_ac': sample['on_ac'], 'battery': sensors_data['battery'],
+            'recent_download_mbps': rates['recent_download_mbps'],
+            'recent_upload_mbps': rates['recent_upload_mbps'],
+            'jobs_completed': meter.data.get('jobs_completed', 0),
+            'jobs_failed': meter.data.get('jobs_failed', 0),
+            'last_job_duration': meter.data.get('last_job_duration_seconds'),
+            'last_job_rtf': meter.data.get('last_job_realtime_factor'),
+            'tested_at': proof.get('tested_at'), 'boot_id': hw.get('boot_id'),
+            'driver_version': hw.get('driver_version')}
+
+
+def self_test_marker_stale(hw, proof):
+    """Re-proof triggers: boot change, GPU driver change, or 7-day proof age.
+    (Extension of the Linux boot-id rule: Windows Update changes graphics
+    drivers without a boot.)"""
+    if not proof.get('tested_at') or time.time() - proof['tested_at'] > 7 * 86400:
+        return True
+    return proof.get('boot_id') != hw.get('boot_id') or proof.get('driver_version') != hw.get('driver_version')
+
+
+def daemon():
+    raise SystemExit('daemon loop is a validation item; run status/network-test here, '
+                     'see windows-worker-result.md section 6 before production enablement')
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument('command', choices=['status', 'network-test', 'drain'])
+    args = parser.parse_args()
+    if args.command == 'status':
+        print(json.dumps(status(), indent=1))
+    elif args.command == 'network-test':
+        cfg = config()
+        rates = transfer_probe(cfg)
+        print(json.dumps(rates, indent=1))
+    elif args.command == 'drain':
+        cfg = config()
+        print(json.dumps(ipc('graceful-shutdown', cfg.get('node_binary', 'node'))))
+
+
+if __name__ == '__main__':
+    main()
diff --git a/infra/peertube-workers/win/register-from-ssh.py b/infra/peertube-workers/win/register-from-ssh.py
new file mode 100644
index 0000000..13a8314
--- /dev/null
+++ b/infra/peertube-workers/win/register-from-ssh.py
@@ -0,0 +1,35 @@
+"""Pipe the existing registration secret directly between SSH sessions. No file/argv/log."""
+import argparse,json,re,shlex,subprocess,tempfile
+from pathlib import Path
+parser=argparse.ArgumentParser(description=__doc__)
+parser.add_argument('--worker',required=True,help='SSH target user@WSL-host')
+parser.add_argument('--name',required=True)
+parser.add_argument('--root',default=r'C:\pt-worker')
+parser.add_argument('--server',default='root@100.92.231.98')
+parser.add_argument('--server-key',default=str(Path.home()/'.ssh/id_rsa'))
+parser.add_argument('--worker-key',default=str(Path.home()/'.ssh/devserver'))
+args=parser.parse_args()
+assert re.fullmatch(r'[A-Za-z0-9_-]+',args.name),'Use a simple unique runner name'
+assert re.fullmatch(r'[A-Za-z]:\\[^\r\n]+',args.root),'Require local Windows drive root'
+SSH=['ssh','-o','BatchMode=yes','-o','StrictHostKeyChecking=yes']
+server=SSH+['-i',args.server_key,args.server]
+worker=SSH+['-i',args.worker_key,args.worker]
+query='SELECT "registrationToken" FROM "runnerRegistrationToken" WHERE id=1;'
+command="docker exec -i occ-tube-peertube-postgres-1 sh -c 'exec psql -X -v ON_ERROR_STOP=1 -U \"$POSTGRES_USER\" -d peertube -At'"
+# metadata check is independent of, and never prints, token material.
+p=subprocess.run(server+[command],input=f"SELECT (SELECT count(*) FROM \"runnerRegistrationToken\"),(SELECT count(*) FROM \"runner\" WHERE name='{args.name}');",text=True,capture_output=True,check=True)
+assert p.stdout.strip()=='1|0','Expected existing token and no duplicate runner'
+marker=Path(tempfile.gettempdir())/('pt-worker-'+args.name+'-enrollment.pending')
+assert not marker.exists(),'Previous result uncertain; inspect server before retrying'
+marker.write_text('Registration attempted; contains no secrets.\n')
+source=subprocess.Popen(server+[command],stdin=subprocess.PIPE,stdout=subprocess.PIPE,stderr=subprocess.PIPE)
+source.stdin.write(query.encode());source.stdin.close()
+node='/mnt/'+args.root[0].lower()+args.root[2:].replace('\\','/')+'/node/node.exe'
+remote=shlex.join([node,args.root+r'\bin\ipc-nvenc.cjs','register',args.root])
+receiver=subprocess.run(worker+[remote],stdin=source.stdout,capture_output=True)
+source.stdout.close();source.wait(timeout=20)
+if source.returncode or receiver.returncode:
+ raise SystemExit('Registration failed; secret-bearing outputs suppressed, inspect safe metadata before retry')
+assert json.loads(receiver.stdout)['success'] is True
+marker.unlink()
+print(json.dumps({'runner_name':args.name,'registration_success':True,'secret_transport':'SSH stdout->SSH stdin->official named-pipe IPC','secret_saved':False}))
diff --git a/infra/peertube-workers/win/runner-supervisor.cjs b/infra/peertube-workers/win/runner-supervisor.cjs
new file mode 100644
index 0000000..e9db497
--- /dev/null
+++ b/infra/peertube-workers/win/runner-supervisor.cjs
@@ -0,0 +1,65 @@
+'use strict';
+// Both WinSW and interactive validation use this supervisor. Only official IPC
+// drains the runner; loss of admission never kills an in-flight video job.
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawn, execFile } = require('node:child_process');
+const root = process.env.PT_ROOT || 'C:\\pt-worker';
+const state = path.join(root, 'state');
+const cfg = JSON.parse(fs.readFileSync(path.join(state, 'worker.json'), 'utf8').replace(/^\uFEFF/, ''));
+const env = { ...process.env, PT_ROOT: root, PT_STATE_DIR: state,
+  PT_WORKER_CONFIG: path.join(state, 'worker.json'),
+  APPDATA: path.join(root, 'profile', 'Roaming'), LOCALAPPDATA: path.join(root, 'profile', 'Local'),
+  TMP: path.join(root, 'tmp'), TEMP: path.join(root, 'tmp'),
+  FFMPEG_PATH: path.join(root, 'bin', 'ffmpeg-nvenc.exe'),
+  FFPROBE_PATH: path.join(root, 'bin', 'ffprobe.exe'), PT_NVENC_DEVICE: String(cfg.nvenc_device || 0) };
+let child = null, draining = false, asking = false, stopping = false, restartAfter = 0;
+function read(name) { try { return JSON.parse(fs.readFileSync(path.join(state, name), 'utf8').replace(/^\uFEFF/, '')); } catch { return {}; } }
+function emit(data) { fs.appendFileSync(path.join(state, 'events.jsonl'), JSON.stringify({ time: Date.now()/1000, ...data }) + '\n'); }
+function atomic(name, data) { const file = path.join(state, name), tmp = file+'.'+process.pid+'.tmp'; fs.writeFileSync(tmp, JSON.stringify(data)); fs.renameSync(tmp, file); }
+function drain() {
+  if (!child || asking || draining) return;
+  const target = child;
+  asking = true;
+  execFile(cfg.node_binary, [path.join(root, 'bin', 'ipc-nvenc.cjs'), 'graceful-shutdown'],
+    { env, timeout: 17000, windowsHide: true }, err => { asking = false; if (!err && child === target) draining = true; });
+}
+function tick() {
+  if (fs.existsSync(path.join(state, 'supervisor-stop'))) stopping = true;
+  const now = Date.now()/1000, admission = read('status.json'), control = read('control.json');
+  const allow = !stopping && control.paused === false && admission.admission_allowed === true &&
+    now - admission.updated_at < 30 && ['AVAILABLE', 'BUSY'].includes(admission.status) &&
+    !fs.existsSync(path.join(state, 'gpu-unavailable'));
+  if (child && !allow) drain();
+  if (!child && allow && now >= restartAfter) {
+    draining = false;
+    child = spawn(cfg.node_binary, ['--require', path.join(root, 'bin', 'observe.cjs'),
+      path.join(root, 'runner', 'node_modules', '@peertube', 'peertube-runner', 'dist', 'peertube-runner.js'),
+      'server', '--enable-job', 'vod-web-video-transcoding', '--enable-job', 'vod-hls-transcoding',
+      '--enable-job', 'vod-audio-merge-transcoding'], { env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    // Upstream logs can contain tokens. Retain only known safe milestones.
+    let buffer = '';
+    for (const stream of [child.stdout, child.stderr]) stream.on('data', chunk => {
+      buffer += chunk.toString();
+      const lines = buffer.split(/\r?\n/); buffer = lines.pop().slice(-8192);
+      for (const line of lines) {
+        const match = line.match(/(Finished processing|Processing) job of type ([\w-]+): ([a-f\d-]{36})/);
+        if (match) emit({ kind: 'runner_milestone', phase: match[1].startsWith('Finished') ? 'completed' : 'processing', job_type: match[2], uuid: match[3] });
+        if (line.includes('Connected to ') && line.includes('/runners')) emit({kind: 'runner_connected'});
+        if (line.includes('Cannot process job')) emit({kind: 'runner_error', reason: 'process_job_failed'});
+      }
+    });
+    child.once('error', () => { emit({kind: 'runner_error', reason: 'spawn_failed'}); });
+    child.once('exit', code => {
+      emit({kind: 'runner_exit', code, graceful_requested: draining || asking});
+      child = null; draining = false; asking = false; restartAfter = Date.now()/1000 + 15;
+    });
+    emit({kind: 'runner_start', concurrency: cfg.concurrency});
+  }
+  atomic('runner.json', {running: !!child, draining, updated_at: now, pid: child?.pid || null});
+  if (stopping && !child) process.exit(0);
+}
+fs.rmSync(path.join(state, 'supervisor-stop'), {force: true});
+process.on('SIGINT', () => { stopping = true; drain(); });
+process.on('SIGTERM', () => { stopping = true; drain(); });
+setInterval(tick, 1000); tick();
diff --git a/infra/peertube-workers/win/selftest-nvenc.ps1 b/infra/peertube-workers/win/selftest-nvenc.ps1
new file mode 100644
index 0000000..4b1ec7d
--- /dev/null
+++ b/infra/peertube-workers/win/selftest-nvenc.ps1
@@ -0,0 +1,42 @@
+param([string]$Root='C:\pt-worker', [int]$Device=0)
+$ErrorActionPreference='Stop'
+$ProgressPreference='SilentlyContinue'
+$ffmpeg=Join-Path $Root 'bin\ffmpeg.exe'
+$state=Join-Path $Root 'state'
+New-Item -ItemType Directory -Force $state,(Join-Path $Root 'tmp') | Out-Null
+$gpu=& nvidia-smi.exe -i $Device --query-gpu=name,uuid,driver_version --format=csv,noheader,nounits
+if($LASTEXITCODE){throw 'nvidia-smi identity failed'}
+$identity=$gpu -split ',\s*'
+$boot=(Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToUniversalTime().ToString('o')
+$proof=[ordered]@{tested_at=[DateTimeOffset]::UtcNow.ToUnixTimeSeconds();boot_id=$boot;driver_version=$identity[2];gpu_model=$identity[0];gpu_uuid=$identity[1];device=$Device;nvenc_h264_ok=$false;nvenc_hevc_ok=$false;av1_encode_ok=$false;av1_decode_ok=$null;tests=@()}
+foreach($codec in @('h264','hevc')){
+  $out=Join-Path $Root "tmp\selftest-$codec.mp4"
+  $err=Join-Path $state "selftest-$codec.stderr"
+  $stdout=Join-Path $state "selftest-$codec.stdout"
+  $argv=@('-hide_banner','-nostdin','-y','-re','-f','lavfi','-i','testsrc2=size=1920x1080:rate=30','-t','5','-an','-c:v',"${codec}_nvenc",'-gpu',"$Device",'-preset','p4','-pix_fmt','yuv420p',$out)
+  $start=Get-Date
+  $p=Start-Process $ffmpeg -ArgumentList $argv -PassThru -NoNewWindow -RedirectStandardError $err -RedirectStandardOutput $stdout
+  $null=$p.Handle
+  $samples=@(); $sessions=@()
+  while(!( $p.HasExited ) -and ((Get-Date)-$start).TotalSeconds -lt 30){
+    $value=& nvidia-smi.exe -i $Device --query-gpu=utilization.encoder,encoder.stats.sessionCount,encoder.stats.averageFps --format=csv,noheader,nounits
+    if($LASTEXITCODE -eq 0){
+      $cells=$value -split ',\s*'
+      $n=0.0
+      if([double]::TryParse($cells[0],[ref]$n)){$samples+=$n}
+      if($cells.Count -ge 3){$sessions+=@{count=$cells[1];fps=$cells[2]}}
+    }
+    Start-Sleep -Milliseconds 200
+    $p.Refresh()
+  }
+  if(!$p.HasExited){$p.Kill();throw 'NVENC self-test exceeded 30 second deadline'}
+  $p.WaitForExit()
+  $max=if($samples.Count){($samples | Measure-Object -Maximum).Maximum}else{$null}
+  $ok=$p.ExitCode -eq 0 -and $null -ne $max -and $max -gt 0
+  $proof["nvenc_${codec}_ok"]=$ok
+  $proof.tests+=@{codec=$codec;encoder="${codec}_nvenc";width=1920;height=1080;duration=5;exit_code=$p.ExitCode;seconds=((Get-Date)-$start).TotalSeconds;encoder_util_max=$max;encoder_util_samples=$samples;encoder_stats=$sessions;stderr_file=$err}
+  if(!$ok){$proof.failure=if($p.ExitCode -ne 0){Get-Content $err -Raw}else{'No positive NVIDIA encoder utilization: hardware proof refused'};break}
+}
+$proof | ConvertTo-Json -Depth 8 | Set-Content (Join-Path $state 'nvenc.json') -Encoding UTF8
+$proof | ConvertTo-Json -Depth 8
+if(!$proof.nvenc_h264_ok -or !$proof.nvenc_hevc_ok){exit 78}
diff --git a/infra/peertube-workers/win/selftest-qsv.ps1 b/infra/peertube-workers/win/selftest-qsv.ps1
new file mode 100644
index 0000000..9a332ae
--- /dev/null
+++ b/infra/peertube-workers/win/selftest-qsv.ps1
@@ -0,0 +1,159 @@
+# Windows QSV self-test for the PeerTube transcode worker (validator).
+#
+# Gates registration. A real encode MUST produce a positive PDH
+# \GPU Engine\Utilization Percentage (engtype_VideoEncode) signal; exit 0 alone
+# is insufficient. No CPU fallback exists anywhere in this worker.
+#
+# Usage (PowerShell 5.1+, from C:\pt-worker\bin after the ffmpeg zip is unpacked):
+#   powershell -ExecutionPolicy Bypass -File selftest-qsv.ps1
+# Writes C:\pt-worker\state\qsv.json on completion.
+
+$ErrorActionPreference = 'Continue'
+$State   = 'C:\pt-worker\state'
+$Bin     = 'C:\pt-worker\bin'
+$FFmpeg  = Join-Path $Bin 'ffmpeg.exe'
+$FFprobe = Join-Path $Bin 'ffprobe.exe'
+New-Item -ItemType Directory -Force -Path $State | Out-Null
+
+function HexToBytes([string]$hex) {
+    $bytes = New-Object byte[] ($hex.Length / 2)
+    for ($i = 0; $i -lt $bytes.Length; $i++) { $bytes[$i] = [Convert]::ToByte($hex.Substring($i * 2, 2), 16) }
+    return ,$bytes
+}
+
+# 5-second synthetic 1080p30 clip (testsrc2 -> x264 -> mp4). No network, no libx264 use at encode time.
+$TestClip = Join-Path $State 'self-test-source.mp4'
+& $FFmpeg -hide_banner -loglevel error -y -f lavfi -i 'testsrc2=size=1920x1080:rate=30' -t 5 -c:v libx264 -pix_fmt yuv420p $TestClip
+if ($LASTEXITCODE -ne 0) { Write-Error 'failed to build self-test source clip'; exit 2 }
+
+function Get-VideoEncodeBusy([int]$ProcId, [double]$Seconds = 3.0) {
+    # Sum of engtype_VideoEncode instances of \GPU Engine(pid_<id>_*)\Utilization Percentage.
+    # Locale-sensitive counter names/decimal separators: unparseable => -1 (unknown, never 0).
+    $out = & typeperf "\GPU Engine(pid_$ProcId`_*)\Utilization Percentage" -sc 1 2>$null
+    $rows = @($out | Where-Object { $_ -like '"*' })
+    if ($rows.Count -lt 2) { return -1 }
+    $headers = ($rows[0] -replace '^"|"$','').split('","')
+    $values  = ($rows[1] -replace '^"|"$','').split('","')
+    $total = 0.0; $seen = $false
+    for ($i = 0; $i -lt $headers.Count; $i++) {
+        if ($headers[$i] -notmatch 'engtype_VideoEncode') { continue }
+        if ($i -ge $values.Count) { return -1 }
+        $raw = $values[$i]
+        $num = 0.0
+        if (-not [double]::TryParse($raw, [Globalization.NumberStyles]::Float,
+                [Globalization.CultureInfo]::InvariantCulture, [ref]$num)) {
+            $raw = $raw -replace '\.', '' -replace ',', '.'
+            if (-not [double]::TryParse($raw, [Globalization.NumberStyles]::Float,
+                    [Globalization.CultureInfo]::InvariantCulture, [ref]$num)) { return -1 }
+        }
+        $total += $num; $seen = $true
+    }
+    if (-not $seen) { return -1 }
+    return $total
+}
+
+function Test-RealEncode([string]$Name, [string[]]$ExtraArgs, [int]$ProcId) {
+    $log = Join-Path $State "selftest-$Name.log"
+    $proc = Start-Process -FilePath $FFmpeg -ArgumentList $ExtraArgs -NoNewWindow -PassThru `
+        -RedirectStandardError $log -RedirectStandardOutput (Join-Path $State "selftest-$Name.out")
+    $maxBusy = 0.0; $samples = 0; $readable = $false
+    while (-not $proc.HasExited) {
+        $busy = Get-VideoEncodeBusy -ProcId ($proc.Id)
+        if ($busy -ge 0) { $readable = $true; $samples++; if ($busy -gt $maxBusy) { $maxBusy = $busy } }
+        Start-Sleep -Milliseconds 800
+    }
+    $proc.WaitForExit() | Out-Null
+    return @{ name = $Name; exit = $proc.ExitCode; max_busy = $maxBusy;
+              samples = $samples; counters_readable = $readable; log = $log }
+}
+
+$report = [ordered]@{
+    schema = 'pt-worker-qsv-selftest/1'
+    tested_at = [DateTimeOffset]::UtcNow.ToUnixTimeSeconds()
+    gpu = @(); driver_version = $null
+    dispatcher_dlls = @{ libmfx = (Test-Path (Join-Path $Bin 'libmfx64-gen.dll'));
+                         libvpl = (Test-Path (Join-Path $Bin 'libvpl64-1.dll')) }
+    ffmpeg_version = $null; qsv_h264_ok = $false; qsv_hevc_ok = $false
+    h264_mf_ok = $false; av1_decode_ok = $null; av1_encode_ok = $false
+    tests = @{}; failures = @(); boot_id = (Get-CimInstance Win32_OperatingSystem).LastBootUpTime.ToString('o')
+}
+
+$gpus = @(); try {
+    $gpus = @(Get-CimInstance Win32_VideoController | Select-Object Name, DriverVersion, Status)
+} catch { }
+$report.gpu = $gpus
+$intel = $gpus | Where-Object { $_.Name -match 'Intel.*(?:Iris|UHD|Graphics)' } | Select-Object -First 1
+if (-not $intel) { $report.failures += 'no Intel graphics adapter found via WMI' }
+else { $report.driver_version = $intel.DriverVersion }
+$report.ffmpeg_version = (& $FFmpeg -version | Select-Object -First 1)
+
+# --- capability listing (necessary, not sufficient) ---
+$encoders = (& $FFmpeg -hide_banner -encoders) -join "`n"
+foreach ($codec in @('h264_qsv', 'hevc_qsv', 'h264_mf', 'av1_qsv')) {
+    $report.tests["encoder_$codec"] = ($encoders -match [regex]::Escape($codec))
+}
+if ($report.tests.encoder_h264_qsv -ne $true) { $report.failures += 'h264_qsv encoder missing from ffmpeg build' }
+
+# --- session init proof (device open) ---
+$initLog = Join-Path $State 'selftest-qsv-init.log'
+& $FFmpeg -hide_banner -v verbose -y -init_hw_device qsv=hw -f lavfi -i 'testsrc2=size=1280x720:rate=30' `
+    -frames:v 10 -c:v h264_qsv -f null - 2> $initLog
+$initExit = $LASTEXITCODE
+$initText = Get-Content $initLog -Raw
+$report.tests.qsv_device_init_exit = $initExit
+if ($initExit -ne 0) { $report.failures += "h264_qsv session init failed (exit $initExit); see selftest-qsv-init.log" }
+
+# --- REAL H.264 1080p encode with mandatory VideoEncode counter proof ---
+$h264 = Test-RealEncode -Name 'qsv-h264' -ProcId 0 -ExtraArgs @(
+    '-hide_banner', '-nostdin', '-v', 'info',
+    '-init_hw_device', 'qsv=qs', '-filter_hw_device', 'qs',
+    '-hwaccel', 'qsv', '-hwaccel_output_format', 'qsv', '-c:v', 'h264_qsv',
+    '-i', $TestClip,
+    '-vf', 'scale_qsv=w=1280:h=720:format=nv12',
+    '-c:v', 'h264_qsv', '-preset', 'medium', '-b:v', '2M', '-maxrate', '2M', '-bufsize', '4M', '-bf', '2',
+    '-an', '-f', 'null', '-'
+)
+$report.tests.h264 = $h264
+if ($h264.exit -eq 0 -and $h264.counters_readable -and $h264.samples -ge 3 -and $h264.max_busy -gt 0) {
+    $report.qsv_h264_ok = $true
+} elseif ($h264.exit -eq 0) {
+    $report.failures += 'h264_qsv exited 0 without a positive VideoEncode counter; not accepted as hardware proof'
+}
+
+# --- HEVC encode attempt (capability discovery; not enabled in production) ---
+$hevc = Test-RealEncode -Name 'qsv-hevc' -ProcId 0 -ExtraArgs @(
+    '-hide_banner', '-nostdin', '-v', 'info',
+    '-init_hw_device', 'qsv=qs', '-filter_hw_device', 'qs',
+    '-hwaccel', 'qsv', '-hwaccel_output_format', 'qsv', '-c:v', 'hevc_qsv',
+    '-i', $TestClip,
+    '-vf', 'scale_qsv=w=1280:h=720:format=nv12',
+    '-c:v', 'hevc_qsv', '-preset', 'medium', '-b:v', '2M',
+    '-an', '-f', 'null', '-'
+)
+$report.tests.hevc = $hevc
+$report.qsv_hevc_ok = ($hevc.exit -eq 0 -and $hevc.counters_readable -and $hevc.samples -ge 3 -and $hevc.max_busy -gt 0)
+
+# --- AV1: decode-only expectation on Alder Lake; verify, never assume ---
+# Build an AV1 source only if an AV1 encoder (software) exists in this build;
+# decoding AV1 hardware-wise is the capability under test.
+$av1DecodeOk = $false
+$av1Source = Join-Path $State 'self-test-source-av1.mp4'
+& $FFmpeg -hide_banner -loglevel error -y -f lavfi -i 'testsrc2=size=320x180:rate=30' -t 1 -c:v libaom-av1 $av1Source 2>$null
+if ($LASTEXITCODE -eq 0) {
+    $av1Log = Join-Path $State 'selftest-av1-decode.log'
+    & $FFmpeg -hide_banner -v error -y -c:v av1_qsv -i $av1Source -frames:v 5 -f null - 2> $av1Log
+    $av1DecodeOk = ($LASTEXITCODE -eq 0)
+}
+$report.av1_decode_ok = $av1DecodeOk
+$encAv1 = ($encoders -match 'av1_qsv')
+$report.av1_encode_ok = $false
+$report.tests.av1_encoder_present = $encAv1
+
+# --- Record + verdict. NO CPU fallback exists; registration is blocked on failure. ---
+$report | ConvertTo-Json -Depth 5 | Set-Content -Encoding UTF8 (Join-Path $State 'qsv.json')
+if ($report.failures.Count -gt 0 -or -not $report.qsv_h264_ok) {
+    Write-Host 'SELF-TEST FAILED:' ($report.failures -join '; ')
+    exit 1
+}
+Write-Host 'SELF-TEST PASSED: h264_qsv with positive VideoEncode counter proof'
+exit 0
diff --git a/infra/peertube-workers/win/service-stop.cjs b/infra/peertube-workers/win/service-stop.cjs
new file mode 100644
index 0000000..abecb12
--- /dev/null
+++ b/infra/peertube-workers/win/service-stop.cjs
@@ -0,0 +1,8 @@
+'use strict';
+const fs=require('node:fs'),path=require('node:path');
+const root=process.env.PT_ROOT || 'C:\\pt-worker', state=path.join(root,'state');
+// The supervisor owns graceful shutdown; only stop after all processing jobs exit.
+fs.writeFileSync(path.join(state,'supervisor-stop'), 'requested');
+const timer=setInterval(()=>{
+  try {const r=JSON.parse(fs.readFileSync(path.join(state,'runner.json'),'utf8'));if(!r.running){clearInterval(timer);process.exit(0);}}catch{}
+},1000);
diff --git a/infra/peertube-workers/win/tests/test_nvenc.py b/infra/peertube-workers/win/tests/test_nvenc.py
new file mode 100644
index 0000000..db6af3b
--- /dev/null
+++ b/infra/peertube-workers/win/tests/test_nvenc.py
@@ -0,0 +1,87 @@
+import importlib.util
+import os
+from pathlib import Path
+import tempfile
+import time
+import unittest
+
+WIN = Path(__file__).resolve().parents[1]
+ROOT = WIN.parent
+
+def load(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    m = importlib.util.module_from_spec(spec); spec.loader.exec_module(m)
+    return m
+
+shim = load('nvenc', WIN / 'ffmpeg-nvenc.py')
+worker = load('nvenc_worker', WIN / 'pt-worker-nvenc.py')
+linux = load('linux_worker', ROOT / 'pt-worker.py')
+PROBE = {'streams': [{'codec_type': 'video', 'codec_name': 'h264', 'pix_fmt': 'yuv420p', 'width': 1920, 'height': 1080}], 'format': {'duration': '10'}}
+
+class AdapterTests(unittest.TestCase):
+    def setUp(self):
+        self.temp = tempfile.TemporaryDirectory(); self.old = shim.STATE
+        shim.STATE = Path(self.temp.name)
+    def tearDown(self):
+        shim.STATE = self.old; self.temp.cleanup()
+    def test_runner_default_becomes_nvdec_cuda_scale_nvenc(self):
+        args, info = shim.rewrite(['-i','source.mp4','-vcodec','libx264','-vf','scale=w=-2:h=720','-pix_fmt','yuv420p','-preset','veryfast','-maxrate:v','2000000','-bufsize:v','4000000','-b_strategy','1','-bf','16','-g:v','60','-r','30','-c:a','aac','-movflags','faststart','-f','mp4','out.mp4'], PROBE)
+        self.assertIn('h264_nvenc', args); self.assertIn('cuda', args)
+        self.assertIn('scale_cuda=w=1280:h=720:format=nv12', args)
+        self.assertIn('p4', args); self.assertNotIn('libx264', args)
+        self.assertNotIn('-b_strategy', args); self.assertEqual(info['target_height'],720)
+    def test_unknown_args_aliases_codecs_filters_and_extra_outputs_refused(self):
+        base=['-i','a','-c:v','libx264']
+        for extra in (['-unknown','1'],['-c:v:0','libx264'],['-c','libx264'],['-filter_complex','null'],['-vf','scale=640:360,eq=contrast=2'],['-hwaccel','none'],['-x264-params','no-scenecut=1'],['other.mp4'],['-c:v','libx265']):
+            with self.subTest(extra=extra),self.assertRaises(ValueError):
+                shim.rewrite(base+extra+['out'],PROBE)
+    def test_source_rotation_hdr_unknown_codec_refused(self):
+        for change in ({'codec_name':'mpeg4'},{'side_data_list':[{'rotation':90}]},{'color_transfer':'smpte2084'}):
+            p={**PROBE,'streams':[{**PROBE['streams'][0],**change}]}
+            with self.assertRaises(ValueError):shim.rewrite(['-i','a','-c:v','libx264','out'],p)
+    def test_hevc_sdr_source_cuda_decode(self):
+        p={**PROBE,'streams':[{**PROBE['streams'][0],'codec_name':'hevc','pix_fmt':'yuv420p10le'}]}
+        args,_=shim.rewrite(['-i','a','-c:v','libx264','out'],p)
+        self.assertIn('h264_nvenc',args);self.assertIn('cuda',args)
+    def test_hevc_target_is_hardware_only_and_unknown_target_refused(self):
+        old=shim.TARGET
+        try:
+            shim.TARGET='hevc_nvenc'
+            args,info=shim.rewrite(['-i','a','-c:v','libx264','out'],PROBE)
+            self.assertIn('hevc_nvenc',args);self.assertEqual(info['target_codec'],'hevc')
+            shim.TARGET='libx265'
+            with self.assertRaises(ValueError):shim.rewrite(['-i','a','-c:v','libx264','out'],PROBE)
+        finally:shim.TARGET=old
+    def test_gpu_unavailable_marker_refuses_video_and_remux(self):
+        (shim.STATE/'gpu-unavailable').touch()
+        for args in (['-i','a','-c:v','libx264','out'],['-i','a','-c','copy','out']):
+            with self.assertRaises(ValueError):shim.rewrite(args,PROBE)
+    def test_queries_audio_and_copy_are_explicit(self):
+        for args in (['-version'],['-encoders'],['-i','a','-vn','-c:a','aac','out'],['-i','a','-c','copy','out']):
+            out,info=shim.rewrite(args,PROBE);self.assertEqual(out,args);self.assertIsNone(info)
+        with self.assertRaises(ValueError):shim.rewrite(['-i','a','-vn','-c:v','libx264','out'],PROBE)
+
+class AdmissionTests(unittest.TestCase):
+    def setUp(self):
+        self.temp=tempfile.TemporaryDirectory();self.old=(linux.STATE,worker.STATE)
+        linux.STATE=worker.STATE=Path(self.temp.name);self.now=time.time()
+    def tearDown(self):linux.STATE,worker.STATE=self.old;self.temp.cleanup()
+    def test_linux_windows_decisions_match_for_entire_sequence(self):
+        overrides=[{}, {}, {}, {'active_jobs':2}, {'on_ac':False}, {'on_ac':None}, {}, {}, {}, {'temperature_c':90}, {'temperature_c':50}, {'gpu_ready':False}, {'disk_free_bytes':0}, {'network_ok':False}, {'tailscale_path':'DERP'}]
+        traces=[]
+        for mod in (linux,worker):
+            meter=mod.Meter();policy=mod.Admission({})
+            for d in ('download','upload'):meter.consume({'kind':'transfer','time':self.now,'ok':True,'direction':d,'bytes':10_000_000,'seconds':1})
+            trace=[]
+            for i,o in enumerate(overrides):
+                sample={'tailscale_path':'direct','latency_ms':5,'network_ok':True,'registered':True,'gpu_ready':True,'gpu_accessible':True,'gpu_tested_at':self.now,'on_ac':True,'disk_free_bytes':100*1024**3,'temperature_c':50,'throttle_counts':{},'active_jobs':0,**o}
+                trace.append(policy.decide(sample,meter,{'paused':False},self.now+i*130))
+            traces.append(trace)
+        self.assertEqual(traces[0],traces[1]);self.assertEqual(traces[0][:6],['NETWORK_DEGRADED','NETWORK_DEGRADED','AVAILABLE','BUSY','DRAINING','DRAINING'])
+    def test_gpu_failure_latched_until_later_proof(self):
+        policy=worker.Admission({});meter=worker.Meter()
+        meter.consume({'kind':'gpu_failure','time':self.now+1})
+        sample={'tailscale_path':'direct','latency_ms':1,'network_ok':True,'registered':True,'gpu_ready':True,'gpu_accessible':True,'gpu_tested_at':self.now,'on_ac':True,'disk_free_bytes':100*1024**3,'temperature_c':None,'throttle_counts':{},'active_jobs':0}
+        self.assertEqual(policy.decide(sample,meter,{'paused':False},self.now+2),'GPU_UNAVAILABLE')
+
+if __name__=='__main__':unittest.main()
diff --git a/infra/peertube-workers/win/tests/test_win_worker.py b/infra/peertube-workers/win/tests/test_win_worker.py
new file mode 100644
index 0000000..c842109
--- /dev/null
+++ b/infra/peertube-workers/win/tests/test_win_worker.py
@@ -0,0 +1,247 @@
+"""Tests for the Windows worker port (win/). Runs on Linux; no GPU, no Windows host.
+
+Covers the three pieces the wave doc says must hold before first hardware contact:
+  1. ffmpeg-qsv.py argument rewriting matches the validated Linux adapter's
+     contract and fails closed on unreviewed commands (exit 78).
+  2. the capability-query passthrough list matches what the shipped runner
+     actually generates (verified in the 0.2.0 bundle).
+  3. pt-worker-win.py Meter/Admission semantics are byte-identical to the
+     Linux controller's for every decision input (states, hysteresis, floors).
+"""
+import importlib.util
+import json
+import subprocess
+import sys
+import tempfile
+import time
+import unittest
+from pathlib import Path
+
+WIN = Path(__file__).resolve().parents[2] / 'win'
+ROOT = Path(__file__).resolve().parents[2]
+
+
+def load(name, path):
+    spec = importlib.util.spec_from_file_location(name, path)
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+qsv = load('qsv_win', WIN / 'ffmpeg-qsv.py')
+win = load('worker_win', WIN / 'pt-worker-win.py')
+linux = load('worker_linux', ROOT / 'pt-worker.py')
+
+PROBE = {'streams': [{'codec_type': 'video', 'codec_name': 'h264', 'pix_fmt': 'yuv420p',
+                      'width': 1920, 'height': 1080}],
+         'format': {'duration': '10.0'}}
+
+
+class RewriteTests(unittest.TestCase):
+    def setUp(self):
+        self.old_state, self.old_probe = qsv.STATE, qsv.probe
+        self.tmp = tempfile.TemporaryDirectory()
+        qsv.STATE = Path(self.tmp.name)
+        def stub_probe(path):  # no real ffprobe.exe on this Linux host
+            name = str(path).lower()
+            if name.endswith(('.png', '.mjpeg', '.webp')):
+                return {'streams': [{**PROBE['streams'][0], 'codec_name': 'png',
+                                     'pix_fmt': 'rgba'}], 'format': {'duration': '0'}}
+            return PROBE
+        qsv.probe = stub_probe
+
+    def tearDown(self):
+        qsv.STATE, qsv.probe = self.old_state, self.old_probe
+        self.tmp.cleanup()
+
+    def rewritten(self, args, data=PROBE):
+        out, _ = qsv.rewrite(args, input_probe=data)
+        return out
+
+    def test_h264_web_video_becomes_qsv_pipeline(self):
+        out = self.rewritten(['-i', 'in.mp4', '-vf', 'scale=w=-2:h=720', '-c:v', 'libx264',
+                              '-preset', 'veryfast', '-crf', '18', '-maxrate', '1500K',
+                              '-bufsize', '3000K', '-g', '96', '-x264-params', 'nofast-pskip=1',
+                              '-movflags', '+faststart', 'out.mp4'])
+        text = ' '.join(out)
+        self.assertIn('-hwaccel qsv', text)
+        self.assertIn('-hwaccel_output_format qsv', text)
+        self.assertIn('-c:v h264_qsv', text)
+        self.assertIn('scale_qsv=w=1280:h=720', text)
+        self.assertIn('-preset medium', text)
+        self.assertIn('-b:v 1500K', text)   # runner's rate cap kept, CRF dropped
+        self.assertIn('-g 96', text)        # runner's GOP kept
+        self.assertNotIn('libx264', text)
+        self.assertNotIn('-crf', text)
+
+    def test_hevc_source_uses_hevc_qsv_decode(self):
+        data = {**PROBE, 'streams': [{**PROBE['streams'][0], 'codec_name': 'hevc', 'pix_fmt': 'yuv420p10le'}]}
+        out = self.rewritten(['-i', 'in.mkv', '-c:v', 'libx264', 'out.mp4'], data)
+        self.assertIn('-c:v hevc_qsv', ' '.join(out))
+
+    def test_no_vf_gets_default_scale_qsv(self):
+        out = self.rewritten(['-i', 'in.mp4', '-c:v', 'libx264', 'out.mp4'])
+        self.assertIn('scale_qsv=w=1920:h=1080', ' '.join(out))
+
+    def test_audio_only_passthrough(self):
+        out, info = qsv.rewrite(['-i', 'in.mp4', '-vn', '-c:a', 'aac', 'out.m4a'])
+        self.assertEqual(info, None)
+
+    def test_capability_queries_passthrough(self):
+        for args in (['-version'], ['-encoders'], ['-hwaccels']):
+            out, info = qsv.rewrite(args)
+            self.assertEqual((out, info), (args, None))
+
+    def test_fail_closed_cpu_or_unknown(self):
+        # Note: -vf contents are validated after the (stubbed) probe, matching
+        # the Linux adapter, which needs the probe to resolve -2 dimensions.
+        for args in (['-i', 'in.mp4', '-c:v', 'mpeg4', 'out.mp4'],
+                     ['-i', 'in.mp4', '-c:v', 'libx264', '-filter_complex', 'x', 'out.mp4'],
+                     ['-i', 'in.mp4', '-c:v', 'libx264', '-vf', 'scale=w=-2:h=720,hue=s=0', 'out.mp4'],
+                     ['-i', 'in.png', '-c:v', 'libx264', '-vf', 'scale=w=-2:h=720', 'out.mp4'],
+                     ['-i', 'in.mp4', '-c:v', 'libx264', '-vf', 'scale=w=0:h=720', 'out.mp4']):
+            with self.assertRaises(ValueError):
+                qsv.rewrite(args)
+
+    def test_refusal_process_exit_78(self):
+        import os
+        env = {**os.environ, 'PT_STATE_DIR': str(self.tmp.name), 'PT_FFPROBE_EXE': 'ffprobe.exe'}
+        p = subprocess.run([sys.executable, str(WIN / 'ffmpeg-qsv.py'),
+                            '-i', 'x.mp4', '-c:v', 'libx264', 'o.mp4'],
+                           capture_output=True, text=True, env=env)
+        self.assertEqual(p.returncode, 78)
+
+    def test_events_have_fixed_reasons_only(self):
+        import os
+        env = {**os.environ, 'PT_STATE_DIR': str(self.tmp.name), 'PT_FFPROBE_EXE': 'ffprobe.exe'}
+        p = subprocess.run([sys.executable, str(WIN / 'ffmpeg-qsv.py'),
+                            '-i', 'x.mp4', '-c:v', 'libx264', 'o.mp4'],
+                           capture_output=True, text=True, env=env)
+        events = [json.loads(line) for line in
+                  (Path(self.tmp.name) / 'events.jsonl').read_text().splitlines()]
+        self.assertEqual(events[0]['kind'], 'gpu_failure')
+        self.assertEqual(events[0]['reason'], 'ValueError')
+        self.assertNotIn('x.mp4', p.stderr)
+
+
+class RunnerContractTests(unittest.TestCase):
+    """Verified directly in the shipped runner 0.2.0 bundle this session."""
+
+    def test_queries_actually_issued_by_runner(self):
+        bundle = Path('/tmp/peertube-worker-inspect/runtime/node_modules/@peertube/peertube-runner'
+                      '/dist/peertube-runner.js')
+        if not bundle.exists():
+            self.skipTest('pinned runner bundle not present')
+        text = bundle.read_text(errors='replace')
+        # Exactly the queries fluent-ffmpeg's capability probe issues in 0.2.0
+        # (-hwaccels is NOT issued; the shim passes it through anyway, harmlessly).
+        for query in ('-version', '-formats', '-encoders', '-filters', '-codecs'):
+            self.assertIn(query, text)
+        self.assertNotIn('-hwaccels', text)
+        self.assertIn('encodersToTry = this.availableEncoders.encodersToTry', text)
+        self.assertIn('"libx264"', text)
+
+    def test_spawn_without_shell_and_ffprobe_sibling(self):
+        bundle = Path('/tmp/peertube-worker-inspect/runtime/node_modules/@peertube/peertube-runner'
+                      '/dist/peertube-runner.js')
+        if not bundle.exists():
+            self.skipTest('pinned runner bundle not present')
+        text = bundle.read_text(errors='replace')
+        self.assertNotIn('shell: true', text)          # EINVAL on .cmd/.bat shims
+        self.assertIn('utils.isWindows ? "ffprobe.exe" : "ffprobe"', text)
+        self.assertIn('!utils.isWindows', text)        # `nice` skipped on win32
+
+
+class AdmissionParityTests(unittest.TestCase):
+    """The Windows controller must decide identically to the Linux controller."""
+
+    def setUp(self):
+        self.tmp = tempfile.TemporaryDirectory()
+        self.old_win, self.old_lin = win.STATE, linux.STATE
+        win.STATE = linux.STATE = Path(self.tmp.name)
+        self.now = time.time()
+
+    def tearDown(self):
+        win.STATE, linux.STATE = self.old_win, self.old_lin
+        self.tmp.cleanup()
+
+    def meter_with_transfers(self, module, mbps):
+        meter = module.Meter()
+        for direction in ('download', 'upload'):
+            meter.consume({'kind': 'transfer', 'time': self.now, 'ok': True, 'direction': direction,
+                           'bytes': int(mbps * 1e6 / 8), 'seconds': 1})
+        return meter
+
+    def sample(self, **overrides):
+        base = {'tailscale_path': 'direct', 'latency_ms': 5, 'network_ok': True,
+                'registered': True, 'gpu_ready': True, 'gpu_tested_at': self.now,
+                'gpu_accessible': True, 'on_ac': True, 'disk_free_bytes': 100 * 1024 ** 3,
+                'temperature_c': 50, 'throttle_counts': {}, 'active_jobs': 0}
+        base.update(overrides)
+        return base
+
+    def parity(self, overrides, control=None, decisions=1):
+        control = control or {'paused': False}
+        outputs = []
+        for module in (linux, win):
+            policy = module.Admission({})
+            meter = self.meter_with_transfers(module, 50)
+            for _ in range(decisions):
+                outputs.append(policy.decide(self.sample(**overrides), meter, control, self.now))
+        self.assertEqual(outputs[0], outputs[1],
+                         f'Linux and Windows controllers diverge on {overrides}: {outputs}')
+        return outputs[0]
+
+    def test_happy_path(self):
+        self.parity({}, decisions=4)
+
+    def test_power_loss_drains_identically(self):
+        self.assertEqual(self.parity({'on_ac': False}), 'DRAINING')
+
+    def test_unknown_power_drains_identically(self):
+        self.assertEqual(self.parity({'on_ac': None}), 'DRAINING')
+
+    def test_missing_gpu_proof_blocks_identically(self):
+        self.assertEqual(self.parity({'gpu_ready': False, 'gpu_accessible': False}), 'GPU_UNAVAILABLE')
+
+    def test_gpu_failure_event_after_proof_blocks_identically(self):
+        outputs = []
+        for module in (linux, win):
+            policy = module.Admission({})
+            meter = self.meter_with_transfers(module, 50)
+            meter.consume({'kind': 'gpu_failure', 'time': self.now + 1})
+            outputs.append(policy.decide(self.sample(gpu_tested_at=self.now), meter,
+                                         {'paused': False}, self.now + 2))
+        self.assertEqual(outputs[0], 'GPU_UNAVAILABLE')
+        self.assertEqual(outputs[0], outputs[1])
+
+    def test_low_disk_and_thermal(self):
+        self.assertEqual(self.parity({'disk_free_bytes': 10 * 1024 ** 3}), 'LOW_DISK')
+        self.assertEqual(self.parity({'temperature_c': 90}), 'THERMAL_THROTTLED')
+
+    def test_derp_disallowed_and_latency_ceiling(self):
+        self.assertEqual(self.parity({'tailscale_path': 'DERP'}), 'NETWORK_DEGRADED')
+        self.assertEqual(self.parity({'latency_ms': 500}), 'NETWORK_DEGRADED')
+
+    def test_bandwidth_floor_hysteresis(self):
+        # 5 Mbps < 10 Mbps floor: every sample is bad, both controllers degrade.
+        for module in (linux, win):
+            policy = module.Admission({})
+            meter = self.meter_with_transfers(module, 5)
+            outputs = [policy.decide(self.sample(), meter, {'paused': False}, self.now)
+                       for _ in range(3)]
+            self.assertEqual(outputs, ['NETWORK_DEGRADED'] * 3, module.__name__)
+
+    def test_recovery_factor(self):
+        outputs = []
+        for module in (linux, win):
+            policy = module.Admission({})
+            meter = self.meter_with_transfers(module, 11)
+            outputs.append(policy.decide(self.sample(), meter, {'paused': False}, self.now))
+            outputs.append(policy.decide(self.sample(), meter, {'paused': False}, self.now))
+        self.assertEqual(outputs[0], 'NETWORK_DEGRADED')
+        self.assertEqual(outputs[0], outputs[1])
+
+
+if __name__ == '__main__':
+    unittest.main(verbosity=1)
diff --git a/infra/peertube-workers/worker.example.json b/infra/peertube-workers/worker.example.json
new file mode 100644
index 0000000..4f5ad45
--- /dev/null
+++ b/infra/peertube-workers/worker.example.json
@@ -0,0 +1,27 @@
+{
+  "name": "worker-name",
+  "peertube_url": "http://TAILSCALE_IP:9000",
+  "canonical_origin": "https://tube.occupymedia.cc",
+  "probe_url": "http://TAILSCALE_IP:9044",
+  "probe_interval_seconds": 300,
+  "peertube_version": "7.3.0",
+  "tailscale_peer": "TAILSCALE_IP",
+  "runner_binary": "/opt/pt-worker/runtime/node_modules/.bin/peertube-runner",
+  "node_binary": "/opt/pt-worker/node/bin/node",
+  "render_device": "/dev/dri/renderD128",
+  "concurrency": 2,
+  "require_ac": true,
+  "poll_seconds": 5,
+  "min_disk_free_bytes": 21474836480,
+  "max_temperature_c": 85,
+  "thermal_cooldown_seconds": 120,
+  "min_download_mbps": 10,
+  "min_upload_mbps": 10,
+  "max_latency_ms": 150,
+  "allow_derp": false,
+  "recovery_factor": 1.25,
+  "good_samples": 3,
+  "bad_samples": 2,
+  "bandwidth_ttl_seconds": 900,
+  "transfer_failure_cooldown_seconds": 60
+}
diff --git a/infra/peertube/.env.example b/infra/peertube/.env.example
new file mode 100644
index 0000000..1a2cc3e
--- /dev/null
+++ b/infra/peertube/.env.example
@@ -0,0 +1,42 @@
+# === Copy to .env on the PeerTube server and fill in ===
+PEERTUBE_WEBSERVER_HOSTNAME=peertube.example.com
+PEERTUBE_WEBSERVER_PORT=443
+PEERTUBE_WEBSERVER_HTTPS=true
+
+# Initial admin (set on first boot only)
+PEERTUBE_ADMIN_EMAIL=admin@example.com
+
+# --- S3 object storage (REQUIRED per project decision) ---
+# Works with any S3-compatible endpoint: MinIO on the same server, another server, or a cloud provider.
+# Tactical Media Broadcast Hub's own media plane already speaks S3 (StorageService) — use the same bucket infra
+# but a DEDICATED bucket for PeerTube (e.g. tactical-media-broadcast-hub-peertube) with its own credentials.
+PEERTUBE_OBJECT_STORAGE_ENABLED=true
+PEERTUBE_OBJECT_STORAGE_WEB_ENDPOINT=https://s3.example.com
+PEERTUBE_OBJECT_STORAGE_WEB_REGION=us-east-1
+PEERTUBE_OBJECT_STORAGE_ACCESS_KEY_ID=CHANGEME
+PEERTUBE_OBJECT_STORAGE_SECRET_ACCESS_KEY=CHANGEME
+PEERTUBE_OBJECT_STORAGE_VIDEOS_BUCKET=tactical-media-broadcast-hub-peertube-videos
+PEERTUBE_OBJECT_STORAGE_STREAMING_PLAYLISTS_BUCKET=tactical-media-broadcast-hub-peertube-playlists
+PEERTUBE_OBJECT_STORAGE_REDUNDANCY_BUCKET=tactical-media-broadcast-hub-peertube-redundancy
+# Same credentials/endpoint config repeated for the internal (non-web) endpoints if different:
+# PEERTUBE_OBJECT_STORAGE_ENDPOINT=...
+
+# --- Livestreaming (fed by the Tactical Media Broadcast Hub compositor via RTMP) ---
+PEERTUBE_TRANSCODING_ENABLED=true
+PEERTUBE_LIVE_ENABLED=true
+PEERTUBE_LIVE_ALLOW_REPLAY=true
+PEERTUBE_LIVE_MAX_DURATION=-1
+PEERTUBE_LIVE_TRANSCODING_ENABLED=true
+PEERTUBE_LIVE_RTMP_PORT=1935
+
+# --- Database (use the container's postgres or point at your own) ---
+PEERTUBE_DB_USERNAME=peertube
+PEERTUBE_DB_PASSWORD=CHANGEME
+PEERTUBE_DB_HOSTNAME=postgres
+# For an external DB, add a postgres service or set PEERTUBE_DB_HOSTNAME to the server.
+
+# --- Federation ---
+PEERTUBE_FEDERATION_ENABLED=true
+
+# --- Trust the Tactical Media Broadcast Hub API server for connector/bridge calls ---
+PEERTUBE_TRUST_PROXY=127.0.0.1,::1
diff --git a/infra/peertube/brand-sync/sync-brand.sh b/infra/peertube/brand-sync/sync-brand.sh
new file mode 100755
index 0000000..81f2b23
--- /dev/null
+++ b/infra/peertube/brand-sync/sync-brand.sh
@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# sync-brand.sh — propagate the Tactical Media Broadcast Hub brand to a PeerTube instance.
+# SOURCE OF TRUTH: this repo (brand assets + design tokens). Re-run after ANY brand change.
+# Requires: PEERTUBE_URL (e.g. https://peertube.example.com), PEERTUBE_TOKEN (a user token with
+# manage settings scope), both exported or in a .env next to this script.
+set -euo pipefail
+cd "$(dirname "$0")/../.."
+REPO_ROOT="$(pwd)/.."   # infra/peertube -> repo root one level up from infra
+BRAND="$REPO_ROOT/apps/web/public/brand"
+[ -f "$(dirname "$0")/.env" ] && source "$(dirname "$0")/.env"
+: "${PEERTUBE_URL:?export PEERTUBE_URL=https://peertube.example.com}"
+: "${PEERTUBE_TOKEN:?export PEERTUBE_TOKEN=<user token with settings scope>}"
+
+echo "→ syncing Tactical Media Broadcast Hub brand to $PEERTUBE_URL"
+
+# 1. Instance name + short description
+curl -sf -X PUT "$PEERTUBE_URL/api/v1/config/custom" \
+  -H "Authorization: Bearer $PEERTUBE_TOKEN" -H "Content-Type: application/json" \
+  -d '{"instance":{"name":"Tactical Media Broadcast Hub Live","shortDescription":"Our platform. Their feeds. No algorithm in between."}}'
+
+# 2. Custom CSS derived from the brand tokens (warm red on black, tilted identity)
+#    The CSS below is the PROPAGATED COPY — when tokens change in apps/web globals.css,
+#    update docs/peertube-setup.md says: re-run scripts/update-brand-css.sh (or edit here + rerun sync).
+css=$(cat <<'CSS'
+:root { --ap-accent: #FF1610; --ap-bg: #000000; }
+.custom-navbar, body { background: var(--ap-bg) !important; }
+.custom-navbar .navbar-brand, .title-page { color: #fff !important; }
+a, .btn-orange, .peertube-button-link { --mainColor: var(--ap-accent) !important; color: var(--ap-accent) !important; }
+.btn-primary { background-color: var(--ap-accent) !important; border-color: var(--ap-accent) !important; }
+CSS
+)
+python3 - "$css" <<'PY' | curl -sf -X PUT "$PEERTUBE_URL/api/v1/config/custom" -H "Authorization: Bearer $PEERTUBE_TOKEN" -H "Content-Type: application/json" -d @-
+import json, sys, os
+css = sys.argv[1]
+body = {"customization": {"css": css}}
+print(json.dumps(body))
+PY
+
+# 3. Logo — PeerTube takes instance banners/avatar via the config API image endpoints
+#    (uploads the tilted circle-A mark; fallback to avatar upload if banner endpoint differs by version)
+if [ -f "$BRAND/logo.svg" ]; then
+  PNG=$(mktemp --suffix=.png)
+  convert -background none "$BRAND/logo.svg" -resize 512x512 "$PNG" 2>/dev/null || \
+    npx --yes sharp-cli -i "$BRAND/logo.svg" -o "$PNG" 2>/dev/null || true
+  [ -s "$PNG" ] && curl -sf -X POST "$PEERTUBE_URL/api/v1/config/custom/logo" \
+    -H "Authorization: Bearer $PEERTUBE_TOKEN" -F "image=@$PNG" || echo "  (logo upload skipped — check endpoint for your PeerTube version)"
+  rm -f "$PNG"
+fi
+
+echo "✓ brand synced. Re-run this script after any brand change (assets or tokens) — it is idempotent."
diff --git a/infra/peertube/docker-compose.yml b/infra/peertube/docker-compose.yml
new file mode 100644
index 0000000..db9ac37
--- /dev/null
+++ b/infra/peertube/docker-compose.yml
@@ -0,0 +1,33 @@
+# PeerTube instance for Tactical Media Broadcast Hub — DESIGNED TO RUN ON A DIFFERENT SERVER.
+# Deploy: copy this directory to the media server, create .env from .env.example, then `docker compose up -d`.
+# Docs: docs/peertube-setup.md (S3, branding sync, connector bridge, livechat)
+
+services:
+  peertube:
+    image: chocobozzz/peertube:production-bookworm
+    # Pin to a specific tag in production, e.g. chocobozzz/peertube:v7.x
+    env_file: .env
+    ports:
+      - "80:9000"        # put behind your reverse proxy (nginx/caddy) with HTTPS
+      - "1935:1935"      # RTMP ingest — the Tactical Media Broadcast Hub media worker pushes live here
+    volumes:
+      - peertube_assets:/app/storage/client-overrides   # custom logo/emoji live here too, but BRAND SYNC via API is canonical
+      - peertube_config:/app/config
+    depends_on:
+      - redis
+      - postfix
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    restart: unless-stopped
+
+  postfix:
+    image: mwader/postfix-relay
+    environment:
+      - POSTFIX_myhostname=${PEERTUBE_WEBSERVER_HOSTNAME}
+    restart: unless-stopped
+
+volumes:
+  peertube_assets:
+  peertube_config:
diff --git a/infra/prometheus/prometheus.yml b/infra/prometheus/prometheus.yml
new file mode 100644
index 0000000..ea1ff8c
--- /dev/null
+++ b/infra/prometheus/prometheus.yml
@@ -0,0 +1,11 @@
+global:
+  scrape_interval: 15s
+
+scrape_configs:
+  - job_name: superposter-api
+    static_configs:
+      - targets: ["host.docker.internal:3000"]
+
+  - job_name: superposter-media-worker
+    static_configs:
+      - targets: ["media-worker:3100"]
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..48477ee
--- /dev/null
+++ b/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "tactical-media-broadcast-hub",
+  "private": true,
+  "packageManager": "pnpm@9.12.0",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "turbo run build",
+    "dev": "turbo run dev",
+    "lint": "turbo run lint",
+    "typecheck": "turbo run typecheck",
+    "test": "turbo run test"
+  },
+  "devDependencies": {
+    "turbo": "^2.1.3",
+    "typescript": "^5.5.4",
+    "eslint": "^9.9.0",
+    "typescript-eslint": "^8.5.0"
+  }
+}
diff --git a/packages/connector-bluesky/package.json b/packages/connector-bluesky/package.json
new file mode 100644
index 0000000..bb1160a
--- /dev/null
+++ b/packages/connector-bluesky/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-bluesky",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-bluesky/src/contract.test.ts b/packages/connector-bluesky/src/contract.test.ts
new file mode 100644
index 0000000..c29a338
--- /dev/null
+++ b/packages/connector-bluesky/src/contract.test.ts
@@ -0,0 +1,354 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, MediaAsset, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import type { CredentialAccessor } from "@tactical-media-broadcast-hub/connector-sdk";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createBlueskyConnector } from "./index.js";
+
+const DID = "did:plc:alice123";
+const HANDLE = "alice.bsky.social";
+const ACCESS_JWT = "access-jwt-for-tests";
+const REFRESH_JWT = "refresh-jwt-for-tests";
+const SERVICE = "https://bsky.social";
+
+const connection: ConnectorConnection = {
+  id: "conn-bluesky",
+  workspaceId: "ws-1",
+  provider: "bluesky",
+  channelId: DID,
+  credentialId: { kind: "credential-ref", id: "cred-bluesky" },
+  fields: { identifier: HANDLE, service: SERVICE },
+  createdAt: new Date(),
+};
+
+interface StubCall {
+  url: URL;
+  init: RequestInit | undefined;
+}
+
+interface StubRecord {
+  uri: string;
+  cid: string;
+  collection: string;
+  record: Record<string, unknown>;
+}
+
+interface StubState {
+  calls: StubCall[];
+  records: StubRecord[];
+  nextRecord: number;
+}
+
+class TestCredentials implements CredentialAccessor {
+  readonly values = new Map<string, string>([
+    [`${connection.id}:access_token`, ACCESS_JWT],
+    [`${connection.id}:did`, DID],
+  ]);
+
+  private key(subject: ConnectorConnection, name: string): string {
+    return `${subject.id}:${name}`;
+  }
+
+  async getAccessToken(subject: ConnectorConnection): Promise<string> {
+    const value = this.values.get(this.key(subject, "access_token"));
+    if (value === undefined) throw new Error("missing access token");
+    return value;
+  }
+
+  async getSecret(subject: ConnectorConnection, key: string): Promise<string> {
+    const value = this.values.get(this.key(subject, key));
+    if (value === undefined) throw new Error(`missing ${key}`);
+    return value;
+  }
+
+  async put(subject: ConnectorConnection, key: string, value: string): Promise<void> {
+    this.values.set(this.key(subject, key), value);
+  }
+}
+
+function json(value: unknown, status = 200): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function requestUrl(input: Parameters<typeof fetch>[0]): URL {
+  if (typeof input === "string") return new URL(input);
+  if (input instanceof URL) return input;
+  return new URL(input.url);
+}
+
+function jsonBody(init: RequestInit | undefined): Record<string, unknown> {
+  return JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+}
+
+function stubXrpc(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const url = requestUrl(input);
+    state.calls.push({ url, init });
+    const method = url.pathname.replace("/xrpc/", "");
+
+    if (method === "com.atproto.server.createSession") {
+      const body = jsonBody(init);
+      if (body.identifier !== HANDLE || body.password !== "app-pass-1234") {
+        return json({ error: "AuthenticationRequired", message: "bad credentials" }, 401);
+      }
+      return json({ accessJwt: ACCESS_JWT, refreshJwt: REFRESH_JWT, did: DID });
+    }
+
+    expect(init?.headers).toMatchObject({ authorization: `Bearer ${ACCESS_JWT}` });
+
+    if (method === "app.bsky.actor.getProfile") {
+      return json({
+        did: DID,
+        handle: HANDLE,
+        displayName: "Alice Example",
+        avatar: "https://cdn.example.test/alice.jpg",
+      });
+    }
+    if (method === "com.atproto.repo.createRecord") {
+      const body = jsonBody(init);
+      const collection = String(body.collection);
+      const record = body.record as Record<string, unknown>;
+      const rkey = `record-${state.nextRecord}`;
+      state.nextRecord += 1;
+      const created: StubRecord = {
+        uri: `at://${DID}/${collection}/${rkey}`,
+        cid: `bafy-${rkey}`,
+        collection,
+        record,
+      };
+      state.records.unshift(created);
+      return json({ uri: created.uri, cid: created.cid });
+    }
+    if (method === "com.atproto.repo.deleteRecord") {
+      const body = jsonBody(init);
+      const collection = String(body.collection);
+      const rkey = String(body.rkey);
+      state.records = state.records.filter(
+        (record) => record.collection !== collection || !record.uri.endsWith(`/${rkey}`),
+      );
+      return json({});
+    }
+    if (method === "com.atproto.repo.uploadBlob") {
+      expect(init?.body).toBeInstanceOf(Blob);
+      expect(init?.headers).toMatchObject({ "content-type": "image/png" });
+      return json({
+        blob: {
+          $type: "blob",
+          ref: { $link: "bafy-image-1" },
+          mimeType: "image/png",
+          size: 4,
+        },
+      });
+    }
+    if (method === "app.bsky.feed.getTimeline") {
+      const feed = state.records
+        .filter((record) => record.collection === "app.bsky.feed.post")
+        .map((stored) => ({
+          post: {
+            uri: stored.uri,
+            cid: stored.cid,
+            author: { did: DID, handle: HANDLE, displayName: "Alice Example" },
+            record: stored.record,
+            likeCount: 3,
+            repostCount: 2,
+            replyCount: 1,
+          },
+        }));
+      return json({ feed, cursor: feed.length > 0 ? "timeline-next" : undefined });
+    }
+    if (method === "app.bsky.feed.getPostThread") {
+      return json({ thread: { post: {}, replies: [] } });
+    }
+    return json({ error: "UnknownMethod", message: method }, 400);
+  };
+}
+
+interface Harness {
+  state: StubState;
+  credentials: TestCredentials;
+  connector: ReturnType<typeof createBlueskyConnector>;
+}
+
+function createHarness(): Harness {
+  const state: StubState = { calls: [], records: [], nextRecord: 1 };
+  const credentials = new TestCredentials();
+  const connector = createBlueskyConnector({
+    fetchImpl: stubXrpc(state),
+    credentials,
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    loadAsset: async (assetId) => mediaAsset(assetId),
+    openAsset: async () => ({ bytes: new Uint8Array([137, 80, 78, 71]), filename: "photo.png" }),
+  });
+  return { state, credentials, connector };
+}
+
+function post(text: string, mediaAssetIds: string[] = []): NormalizedPost {
+  return {
+    text,
+    mediaAssetIds,
+    visibility: "public",
+    providerMetadata: {},
+  };
+}
+
+function mediaAsset(id: string): MediaAsset {
+  return {
+    id,
+    workspaceId: "ws-1",
+    storageKey: `assets/${id}`,
+    mimeType: "image/png",
+    sizeBytes: 4,
+    width: 100,
+    height: 50,
+    createdAt: new Date(),
+  };
+}
+
+connectorContractTests(createHarness().connector, { connection });
+
+describe("bluesky connector", () => {
+  it("declares the AT Protocol connection fields and capabilities", () => {
+    const manifest = createHarness().connector.manifest();
+    expect(manifest).toMatchObject({
+      id: "bluesky",
+      displayName: "Bluesky",
+      capabilities: {
+        publishText: true,
+        publishImages: true,
+        feed: true,
+        mentions: true,
+        replies: true,
+        comments: true,
+        amplifyRepost: true,
+        amplifyQuote: true,
+        deletePublication: true,
+        directMessages: false,
+        webhooks: false,
+      },
+    });
+    expect(manifest.connectionFields).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "identifier", secret: false, required: true }),
+        expect.objectContaining({ name: "appKey", secret: true, required: true }),
+        expect.objectContaining({ name: "service", secret: false, required: false }),
+      ]),
+    );
+  });
+
+  it("creates a session, stores JWTs, and resolves the profile during authorize", async () => {
+    const { connector, credentials, state } = createHarness();
+    const result = await connector.authorize({
+      redirectUri: "https://app.example.test/connect/callback",
+      workspaceId: "ws-auth",
+      state: "csrf-state",
+      fields: { identifier: HANDLE, appPassword: "app-pass-1234" },
+      providerMetadata: { connectionId: "conn-authorized" },
+    });
+
+    expect(result.connection).toMatchObject({
+      id: "conn-authorized",
+      provider: "bluesky",
+      channelId: DID,
+      fields: { identifier: HANDLE, service: SERVICE },
+    });
+    expect(result.connection.fields).not.toHaveProperty("appPassword");
+    expect(result.identity).toMatchObject({
+      provider: "bluesky",
+      remoteId: DID,
+      handle: HANDLE,
+      displayName: "Alice Example",
+    });
+    expect(credentials.values.get("conn-authorized:access_token")).toBe(ACCESS_JWT);
+    expect(credentials.values.get("conn-authorized:refresh_token")).toBe(REFRESH_JWT);
+    expect(credentials.values.get("conn-authorized:did")).toBe(DID);
+    expect(state.calls.map((call) => call.url.pathname)).toEqual([
+      "/xrpc/com.atproto.server.createSession",
+      "/xrpc/app.bsky.actor.getProfile",
+    ]);
+  });
+
+  it("publishes a post and reads it back through timeline cursor paging", async () => {
+    const { connector, state } = createHarness();
+    const publication = await connector.publish(connection, post("Hello from the newsroom"));
+    const page = await connector.getFeed(connection, { kind: "home", limit: 25 });
+
+    expect(publication.remoteId).toMatch(/^at:\/\/did:plc:alice123\/app\.bsky\.feed\.post\/.+\|bafy-/);
+    expect(publication.providerMetadata).toMatchObject({
+      uri: expect.stringContaining("/app.bsky.feed.post/"),
+      cid: expect.stringMatching(/^bafy-/),
+    });
+    expect(page).toMatchObject({
+      nextCursor: "timeline-next",
+      items: [
+        {
+          remoteId: publication.remoteId,
+          authorHandle: HANDLE,
+          text: "Hello from the newsroom",
+          metrics: { likes: 3, reposts: 2, replies: 1 },
+        },
+      ],
+    });
+    expect(state.calls.some((call) => call.url.pathname.endsWith("getTimeline"))).toBe(true);
+  });
+
+  it("roundtrips repost and quote records and removes an amplification", async () => {
+    const { connector, state } = createHarness();
+    const original = await connector.publish(connection, post("Original"));
+    const repost = await connector.amplify(connection, {
+      kind: "repost",
+      targetRemoteId: original.remoteId,
+    });
+    const quote = await connector.amplify(connection, {
+      kind: "quote",
+      targetRemoteId: original.remoteId,
+      commentary: "Worth reading",
+    });
+
+    const repostRecord = state.records.find((record) => record.collection === "app.bsky.feed.repost");
+    expect(repostRecord?.record.subject).toEqual({
+      uri: original.providerMetadata.uri,
+      cid: original.providerMetadata.cid,
+    });
+    const quoteRecord = state.records.find(
+      (record) => record.uri === String(quote.providerMetadata.uri),
+    );
+    expect(quoteRecord?.record).toMatchObject({
+      text: "Worth reading",
+      embed: {
+        $type: "app.bsky.embed.record",
+        record: {
+          uri: original.providerMetadata.uri,
+          cid: original.providerMetadata.cid,
+        },
+      },
+    });
+
+    await connector.unamplify(connection, repost.remoteId);
+    expect(state.records.some((record) => record.uri === repostRecord?.uri)).toBe(false);
+  });
+
+  it("uploads raw image bytes and embeds the returned blob in an image post", async () => {
+    const { connector, state } = createHarness();
+    const publication = await connector.publish(connection, post("A chart", ["chart.png"]));
+    const stored = state.records.find(
+      (record) => record.uri === String(publication.providerMetadata.uri),
+    );
+    expect(stored?.record.embed).toEqual({
+      $type: "app.bsky.embed.images",
+      images: [
+        {
+          alt: "",
+          image: {
+            $type: "blob",
+            ref: { $link: "bafy-image-1" },
+            mimeType: "image/png",
+            size: 4,
+          },
+        },
+      ],
+    });
+  });
+});
diff --git a/packages/connector-bluesky/src/index.ts b/packages/connector-bluesky/src/index.ts
new file mode 100644
index 0000000..392197d
--- /dev/null
+++ b/packages/connector-bluesky/src/index.ts
@@ -0,0 +1,766 @@
+/**
+ * Bluesky connector using the AT Protocol XRPC API.
+ *
+ * AT record operations need both a URI and CID. the connector
+ * methods expose one remoteId, so this connector encodes record references as
+ * `<at-uri>|<cid>`. The individual values are also retained in publication
+ * metadata. Delete operations only need the URI and accept either form.
+ */
+import { randomUUID } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  CredentialRef,
+  FeedItem,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  Page,
+  Publication,
+  RemoteMedia,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  InMemoryCredentials,
+  pageOf,
+  RateLimitedHttpClient,
+  type AuthorizationRequest,
+  type AuthorizationResult,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "bluesky";
+const DEFAULT_SERVICE = "https://bsky.social";
+const POST_COLLECTION = "app.bsky.feed.post";
+const REPOST_COLLECTION = "app.bsky.feed.repost";
+const MAX_IMAGES = 4;
+
+const SECRET = {
+  accessToken: "access_token",
+  refreshToken: "refresh_token",
+  did: "did",
+} as const;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  feed: true,
+  mentions: true,
+  replies: true,
+  comments: true,
+  amplifyRepost: true,
+  amplifyQuote: true,
+  deletePublication: true,
+  directMessages: false,
+  webhooks: false,
+};
+
+export interface BlueskyConnectorOptions {
+  /** fetch override for tests and host applications. */
+  fetchImpl?: typeof fetch;
+  /** The documented default is one request per second. */
+  requestsPerSecond?: number;
+  /** Sleep override for deterministic tests. */
+  sleep?: (ms: number) => Promise<void>;
+  /** Secret store. Default: in-memory for development and contract tests. */
+  credentials?: CredentialAccessor;
+  /** Resolve local media ids used by NormalizedPost. */
+  loadAsset?: (assetId: string) => Promise<MediaAsset>;
+  /** Read media bytes for com.atproto.repo.uploadBlob. */
+  openAsset?: (media: MediaAsset) => Promise<{ bytes: Uint8Array; filename: string }>;
+}
+
+export interface BlueskyAuthorizationRequest extends AuthorizationRequest {
+  fields?: Record<string, string>;
+  providerMetadata?: Record<string, unknown>;
+}
+
+export interface BlueskyConnector
+  extends Omit<
+    PlatformConnector,
+    | "authorize"
+    | "publish"
+    | "deletePublication"
+    | "uploadMedia"
+    | "getFeed"
+    | "getComments"
+    | "reply"
+    | "amplify"
+    | "unamplify"
+  > {
+  authorize(input: BlueskyAuthorizationRequest): Promise<AuthorizationResult>;
+  publish: NonNullable<PlatformConnector["publish"]>;
+  deletePublication: NonNullable<PlatformConnector["deletePublication"]>;
+  uploadMedia: NonNullable<PlatformConnector["uploadMedia"]>;
+  getFeed: NonNullable<PlatformConnector["getFeed"]>;
+  getComments: NonNullable<PlatformConnector["getComments"]>;
+  reply: NonNullable<PlatformConnector["reply"]>;
+  amplify: NonNullable<PlatformConnector["amplify"]>;
+  unamplify: NonNullable<PlatformConnector["unamplify"]>;
+}
+
+interface SessionResponse {
+  accessJwt: string;
+  refreshJwt: string;
+  did: string;
+}
+
+interface ProfileResponse {
+  did: string;
+  handle: string;
+  displayName?: string;
+  avatar?: string;
+}
+
+interface RecordReference {
+  uri: string;
+  cid: string;
+}
+
+interface StrongRef {
+  uri: string;
+  cid: string;
+}
+
+interface BlobReference {
+  $type?: string;
+  ref: { $link: string } | string;
+  mimeType: string;
+  size: number;
+}
+
+interface UploadBlobResponse {
+  blob: BlobReference;
+}
+
+interface CreateRecordResponse extends RecordReference {
+  validationStatus?: string;
+}
+
+interface PostRecord {
+  text: string;
+  createdAt: string;
+  reply?: { root: StrongRef; parent: StrongRef };
+}
+
+interface PostView {
+  uri: string;
+  cid: string;
+  author: {
+    did: string;
+    handle: string;
+    displayName?: string;
+    avatar?: string;
+  };
+  record: PostRecord;
+  embed?: unknown;
+  likeCount?: number;
+  repostCount?: number;
+  replyCount?: number;
+}
+
+interface FeedViewPost {
+  post: PostView;
+}
+
+interface TimelineResponse {
+  feed: FeedViewPost[];
+  cursor?: string;
+}
+
+interface SearchResponse {
+  posts: PostView[];
+  cursor?: string;
+}
+
+interface NotificationView {
+  uri: string;
+  cid: string;
+  author: PostView["author"];
+  record: PostRecord;
+  reason: string;
+  indexedAt: string;
+}
+
+interface NotificationsResponse {
+  notifications: NotificationView[];
+  cursor?: string;
+}
+
+interface ThreadViewPost {
+  post: PostView;
+  replies?: ThreadViewPost[];
+}
+
+interface PostThreadResponse {
+  thread: ThreadViewPost;
+}
+
+interface ParsedAtUri {
+  repo: string;
+  collection: string;
+  rkey: string;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function normalizeService(value: string | undefined): string {
+  const raw = value === undefined || value.trim() === "" ? DEFAULT_SERVICE : value.trim();
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch (cause) {
+    throw new ConnectorError(`${PROVIDER}: invalid service URL`, PROVIDER, cause);
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") {
+    throw new ConnectorError(`${PROVIDER}: service must use http or https`, PROVIDER);
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function jsonPost(body: Record<string, unknown>): RequestInit {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  };
+}
+
+function encodeReference(reference: RecordReference): string {
+  return `${reference.uri}|${reference.cid}`;
+}
+
+function parseAtUri(uri: string): ParsedAtUri {
+  const match = /^at:\/\/([^/]+)\/([^/]+)\/([^/?#]+)$/.exec(uri);
+  if (match === null) {
+    throw new ConnectorError(`${PROVIDER}: malformed AT record URI "${uri}"`, PROVIDER);
+  }
+  const repo = match[1];
+  const collection = match[2];
+  const rkey = match[3];
+  if (repo === undefined || collection === undefined || rkey === undefined) {
+    throw new ConnectorError(`${PROVIDER}: incomplete AT record URI "${uri}"`, PROVIDER);
+  }
+  return { repo, collection, rkey };
+}
+
+function imageUrls(embed: unknown): string[] {
+  if (!isObject(embed) || !Array.isArray(embed.images)) return [];
+  return embed.images.flatMap((image) => {
+    if (!isObject(image)) return [];
+    const fullsize = stringValue(image.fullsize);
+    const thumb = stringValue(image.thumb);
+    return fullsize !== undefined ? [fullsize] : thumb !== undefined ? [thumb] : [];
+  });
+}
+
+function blobCid(blob: BlobReference): string {
+  if (typeof blob.ref === "string") return blob.ref;
+  return blob.ref.$link;
+}
+
+export function createBlueskyConnector(options: BlueskyConnectorOptions = {}): BlueskyConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: options.requestsPerSecond ?? 1,
+    fetchImpl: options.fetchImpl,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  const references = new Map<string, RecordReference>();
+  const replyRoots = new Map<string, StrongRef>();
+  const blobReferences = new Map<string, BlobReference>();
+  const handles = new Map<string, string>();
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Bluesky",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "identifier",
+        label: "Handle or email",
+        required: true,
+        secret: false,
+        placeholder: "you.bsky.social",
+      },
+      {
+        // The SDK contract forbids "password" in field names so generic UIs
+        // and logs do not mistake this for an account password.
+        name: "appKey",
+        label: "App password (never your account password)",
+        required: true,
+        secret: true,
+        placeholder: "xxxx-xxxx-xxxx-xxxx",
+      },
+      {
+        name: "service",
+        label: "Personal data server",
+        required: false,
+        secret: false,
+        placeholder: DEFAULT_SERVICE,
+      },
+    ],
+    oauth: { kind: "token" },
+    docsUrl: "https://docs.bsky.app/docs/category/http-reference",
+  };
+
+  function serviceOf(connection: ConnectorConnection): string {
+    return normalizeService(connection.fields.service);
+  }
+
+  async function send(url: string, init: RequestInit): Promise<Response> {
+    const response = await client.request(PROVIDER, url, {
+      ...init,
+      headers: { accept: "application/json", ...init.headers },
+    });
+    if (response.ok) return response;
+    let detail = "";
+    try {
+      const body = (await response.json()) as { error?: string; message?: string };
+      detail = body.message ?? body.error ?? "";
+    } catch {
+      detail = "";
+    }
+    const message = `${PROVIDER}: HTTP ${response.status} ${new URL(url).pathname}${detail ? `: ${detail}` : ""}`;
+    if (response.status === 401 || response.status === 403) {
+      throw new AuthError(message, PROVIDER, false);
+    }
+    throw new ConnectorError(message, PROVIDER, { status: response.status });
+  }
+
+  async function publicJson<T>(service: string, path: string, init: RequestInit): Promise<T> {
+    const response = await send(`${service}/xrpc/${path}`, init);
+    return (await response.json()) as T;
+  }
+
+  async function api<T>(
+    connection: ConnectorConnection,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<T> {
+    let token: string;
+    try {
+      token = await credentials.getAccessToken(connection);
+    } catch {
+      throw new AuthError(`${PROVIDER}: no access token stored for ${connection.id}`, PROVIDER, false);
+    }
+    const response = await send(`${serviceOf(connection)}/xrpc/${path}`, {
+      ...init,
+      headers: { authorization: `Bearer ${token}`, ...init.headers },
+    });
+    const text = await response.text();
+    return (text.length === 0 ? {} : JSON.parse(text)) as T;
+  }
+
+  async function didOf(connection: ConnectorConnection): Promise<string> {
+    if (connection.channelId.startsWith("did:")) return connection.channelId;
+    try {
+      return await credentials.getSecret(connection, SECRET.did);
+    } catch {
+      throw new AuthError(`${PROVIDER}: no DID stored for ${connection.id}`, PROVIDER, false);
+    }
+  }
+
+  function rememberReference(reference: RecordReference, root?: StrongRef): string {
+    const encoded = encodeReference(reference);
+    references.set(encoded, reference);
+    references.set(reference.uri, reference);
+    if (root !== undefined) {
+      replyRoots.set(encoded, root);
+      replyRoots.set(reference.uri, root);
+    }
+    return encoded;
+  }
+
+  function requireReference(remoteId: string): RecordReference {
+    const remembered = references.get(remoteId);
+    if (remembered !== undefined) return remembered;
+    const divider = remoteId.lastIndexOf("|");
+    if (divider > 0 && divider < remoteId.length - 1) {
+      const reference = { uri: remoteId.slice(0, divider), cid: remoteId.slice(divider + 1) };
+      parseAtUri(reference.uri);
+      references.set(remoteId, reference);
+      references.set(reference.uri, reference);
+      return reference;
+    }
+    throw new ConnectorError(
+      `${PROVIDER}: record reference must include both URI and CID (expected "at://…|cid")`,
+      PROVIDER,
+    );
+  }
+
+  function uriFromRemoteId(remoteId: string): string {
+    const remembered = references.get(remoteId);
+    if (remembered !== undefined) return remembered.uri;
+    const divider = remoteId.lastIndexOf("|");
+    const uri = divider > 0 ? remoteId.slice(0, divider) : remoteId;
+    parseAtUri(uri);
+    return uri;
+  }
+
+  async function createRecord(
+    connection: ConnectorConnection,
+    collection: string,
+    record: Record<string, unknown>,
+  ): Promise<CreateRecordResponse> {
+    return api<CreateRecordResponse>(
+      connection,
+      "com.atproto.repo.createRecord",
+      jsonPost({ repo: await didOf(connection), collection, record }),
+    );
+  }
+
+  function remoteUrl(connection: ConnectorConnection, uri: string): string | undefined {
+    if (!uri.includes(`/${POST_COLLECTION}/`)) return undefined;
+    const handle = handles.get(connection.id) ?? connection.fields.identifier;
+    if (handle === undefined || handle.length === 0) return undefined;
+    return `https://bsky.app/profile/${encodeURIComponent(handle)}/post/${encodeURIComponent(parseAtUri(uri).rkey)}`;
+  }
+
+  function toPublication(
+    connection: ConnectorConnection,
+    reference: CreateRecordResponse,
+    draftId: string,
+    publishedAt: Date,
+    providerMetadata: Record<string, unknown> = {},
+  ): Publication {
+    const remoteId = rememberReference(reference);
+    const publication: Publication = {
+      id: randomUUID(),
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId,
+      publishedAt,
+      providerMetadata: {
+        uri: reference.uri,
+        cid: reference.cid,
+        collection: parseAtUri(reference.uri).collection,
+        ...providerMetadata,
+      },
+    };
+    const url = remoteUrl(connection, reference.uri);
+    if (url !== undefined) publication.remoteUrl = url;
+    return publication;
+  }
+
+  function toFeedItem(post: PostView): FeedItem {
+    const root = post.record.reply?.root;
+    const remoteId = rememberReference(post, root);
+    return {
+      id: post.uri,
+      provider: PROVIDER,
+      remoteId,
+      authorHandle: post.author.handle,
+      text: post.record.text,
+      mediaUrls: imageUrls(post.embed),
+      createdAt: new Date(post.record.createdAt),
+      metrics: {
+        likes: post.likeCount ?? 0,
+        reposts: post.repostCount ?? 0,
+        replies: post.replyCount ?? 0,
+      },
+    };
+  }
+
+  async function uploadAsset(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia> {
+    if (!media.mimeType.startsWith("image/")) {
+      throw new ConnectorError(`${PROVIDER}: uploadMedia accepts images only`, PROVIDER);
+    }
+    if (options.openAsset === undefined) {
+      throw new ConnectorError(`${PROVIDER}: media upload requires the openAsset option`, PROVIDER);
+    }
+    const { bytes } = await options.openAsset(media);
+    const response = await api<UploadBlobResponse>(
+      connection,
+      "com.atproto.repo.uploadBlob",
+      {
+        method: "POST",
+        headers: { "content-type": media.mimeType },
+        body: new Blob([new Uint8Array(bytes)], { type: media.mimeType }),
+      },
+    );
+    const cid = blobCid(response.blob);
+    blobReferences.set(cid, response.blob);
+    const remote: RemoteMedia = { remoteId: cid, mimeType: response.blob.mimeType };
+    if (media.width !== undefined) remote.width = media.width;
+    if (media.height !== undefined) remote.height = media.height;
+    return remote;
+  }
+
+  async function imagesFor(
+    connection: ConnectorConnection,
+    post: NormalizedPost,
+  ): Promise<{ alt: string; image: BlobReference }[]> {
+    if (post.mediaAssetIds.length > MAX_IMAGES) {
+      throw new ConnectorError(`${PROVIDER}: posts support at most ${MAX_IMAGES} images`, PROVIDER);
+    }
+    const altText = isObject(post.providerMetadata.altText) ? post.providerMetadata.altText : {};
+    const images: { alt: string; image: BlobReference }[] = [];
+    for (const assetId of post.mediaAssetIds) {
+      let blob = blobReferences.get(assetId);
+      if (blob === undefined) {
+        if (options.loadAsset === undefined) {
+          throw new ConnectorError(
+            `${PROVIDER}: publishing local media requires the loadAsset option`,
+            PROVIDER,
+          );
+        }
+        const remote = await uploadAsset(connection, await options.loadAsset(assetId));
+        blob = blobReferences.get(remote.remoteId);
+      }
+      if (blob === undefined) {
+        throw new ConnectorError(`${PROVIDER}: upload returned no blob reference`, PROVIDER);
+      }
+      images.push({ alt: stringValue(altText[assetId]) ?? "", image: blob });
+    }
+    return images;
+  }
+
+  async function deleteRecord(connection: ConnectorConnection, remoteId: string): Promise<void> {
+    const parsed = parseAtUri(uriFromRemoteId(remoteId));
+    await api<Record<string, never>>(
+      connection,
+      "com.atproto.repo.deleteRecord",
+      jsonPost({ repo: await didOf(connection), collection: parsed.collection, rkey: parsed.rkey }),
+    );
+  }
+
+  async function identityFor(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+    const did = await didOf(connection);
+    const profile = await api<ProfileResponse>(
+      connection,
+      `app.bsky.actor.getProfile?actor=${encodeURIComponent(did)}`,
+    );
+    handles.set(connection.id, profile.handle);
+    const identity: NormalizedIdentity = {
+      provider: PROVIDER,
+      remoteId: profile.did,
+      handle: profile.handle,
+    };
+    if (profile.displayName !== undefined && profile.displayName !== "") {
+      identity.displayName = profile.displayName;
+    }
+    if (profile.avatar !== undefined && profile.avatar !== "") identity.avatarUrl = profile.avatar;
+    return identity;
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize(input: BlueskyAuthorizationRequest): Promise<AuthorizationResult> {
+      const fields = input.fields ?? {};
+      const identifier = fields.identifier?.trim();
+      // appPassword remains accepted for callers already using AT's common
+      // terminology; appKey is the SDK-safe manifest field name.
+      const appPassword = (fields.appKey ?? fields.appPassword)?.trim();
+      if (identifier === undefined || identifier === "") {
+        throw new AuthError(`${PROVIDER}: authorize needs fields.identifier`, PROVIDER, false);
+      }
+      if (appPassword === undefined || appPassword === "") {
+        throw new AuthError(
+          `${PROVIDER}: authorize needs fields.appKey (an app password from Bluesky Settings, never the account password)`,
+          PROVIDER,
+          false,
+        );
+      }
+      const service = normalizeService(fields.service);
+      const session = await publicJson<SessionResponse>(
+        service,
+        "com.atproto.server.createSession",
+        jsonPost({ identifier, password: appPassword }),
+      );
+      const metadata = input.providerMetadata ?? {};
+      const connectionId = stringValue(metadata.connectionId) ?? `${PROVIDER}:${input.workspaceId}:${session.did}`;
+      const credentialId: CredentialRef = { kind: "credential-ref", id: connectionId };
+      const connection: ConnectorConnection = {
+        id: connectionId,
+        workspaceId: input.workspaceId,
+        provider: PROVIDER,
+        channelId: session.did,
+        credentialId,
+        fields: { identifier, service },
+        createdAt: new Date(),
+      };
+      await credentials.put(connection, SECRET.accessToken, session.accessJwt);
+      await credentials.put(connection, SECRET.refreshToken, session.refreshJwt);
+      await credentials.put(connection, SECRET.did, session.did);
+      const identity = await identityFor(connection);
+      return { connection, identity };
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return identityFor(connection);
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const createdAt = new Date();
+      const record: Record<string, unknown> = { text: post.text, createdAt: createdAt.toISOString() };
+      const images = await imagesFor(connection, post);
+      if (images.length > 0) {
+        record.embed = { $type: "app.bsky.embed.images", images };
+      }
+      const response = await createRecord(connection, POST_COLLECTION, record);
+      const draftId = stringValue(post.providerMetadata.draftId) ?? "direct";
+      return toPublication(connection, response, draftId, createdAt);
+    },
+
+    async uploadMedia(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia> {
+      return uploadAsset(connection, media);
+    },
+
+    async getFeed(
+      connection: ConnectorConnection,
+      request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+    ): Promise<Page<FeedItem>> {
+      const limit = Math.max(1, Math.min(100, request.limit));
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (request.cursor !== undefined) params.set("cursor", request.cursor);
+
+      if (request.kind === "home") {
+        const data = await api<TimelineResponse>(
+          connection,
+          `app.bsky.feed.getTimeline?${params.toString()}`,
+        );
+        return pageOf(data.feed.map((entry) => toFeedItem(entry.post)), data.cursor);
+      }
+      if (request.kind === "search") {
+        const query = request.query?.trim();
+        if (query === undefined || query === "") {
+          throw new ConnectorError(`${PROVIDER}: search requires a query`, PROVIDER);
+        }
+        params.set("q", query);
+        const data = await api<SearchResponse>(
+          connection,
+          `app.bsky.feed.searchPosts?${params.toString()}`,
+        );
+        return pageOf(data.posts.map(toFeedItem), data.cursor);
+      }
+
+      const data = await api<NotificationsResponse>(
+        connection,
+        `app.bsky.notification.listNotifications?${params.toString()}`,
+      );
+      const items = data.notifications
+        .filter((notification) => notification.reason === "mention" || notification.reason === "reply")
+        .map((notification) =>
+          toFeedItem({
+            ...notification,
+            embed: undefined,
+            likeCount: 0,
+            repostCount: 0,
+            replyCount: 0,
+          }),
+        );
+      return pageOf(items, data.cursor);
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const target = requireReference(request.onRemoteId);
+      const params = new URLSearchParams({ uri: target.uri, depth: "1", parentHeight: "0" });
+      const data = await api<PostThreadResponse>(
+        connection,
+        `app.bsky.feed.getPostThread?${params.toString()}`,
+      );
+      const replies = data.thread.replies ?? [];
+      const offset = request.cursor === undefined ? 0 : Number(request.cursor);
+      if (!Number.isInteger(offset) || offset < 0) {
+        throw new ConnectorError(`${PROVIDER}: invalid comments cursor`, PROVIDER);
+      }
+      const slice = replies.slice(offset, offset + request.limit);
+      const items = slice.map((reply): Comment => ({
+        id: reply.post.uri,
+        provider: PROVIDER,
+        remoteId: rememberReference(reply.post, reply.post.record.reply?.root),
+        onRemoteId: request.onRemoteId,
+        authorHandle: reply.post.author.handle,
+        text: reply.post.record.text,
+        createdAt: new Date(reply.post.record.createdAt),
+      }));
+      const next = offset + slice.length;
+      return pageOf(items, next < replies.length ? String(next) : undefined);
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const parent = requireReference(request.onRemoteId);
+      const root = replyRoots.get(request.onRemoteId) ?? parent;
+      const createdAt = new Date();
+      const response = await createRecord(connection, POST_COLLECTION, {
+        text: request.text,
+        createdAt: createdAt.toISOString(),
+        reply: { root, parent },
+      });
+      rememberReference(response, root);
+      return toPublication(connection, response, "reply", createdAt, {
+        reply: { root, parent },
+      });
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: {
+        kind: "repost" | "quote" | "share";
+        targetRemoteId: string;
+        commentary?: string;
+        quoteAssetIds?: string[];
+      },
+    ): Promise<Publication> {
+      const target = requireReference(request.targetRemoteId);
+      const createdAt = new Date();
+      if (request.kind === "repost") {
+        const response = await createRecord(connection, REPOST_COLLECTION, {
+          subject: target,
+          createdAt: createdAt.toISOString(),
+        });
+        return toPublication(connection, response, "amplify:repost", createdAt, {
+          amplifies: target,
+          kind: "repost",
+        });
+      }
+      if (request.kind === "quote") {
+        if ((request.quoteAssetIds?.length ?? 0) > 0) {
+          throw new CapabilityNotSupportedError(PROVIDER, "quote posts with images");
+        }
+        const response = await createRecord(connection, POST_COLLECTION, {
+          text: request.commentary ?? "",
+          createdAt: createdAt.toISOString(),
+          embed: { $type: "app.bsky.embed.record", record: target },
+        });
+        return toPublication(connection, response, "amplify:quote", createdAt, {
+          amplifies: target,
+          kind: "quote",
+        });
+      }
+      throw new CapabilityNotSupportedError(PROVIDER, "amplifyShare");
+    },
+
+    async unamplify(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      await deleteRecord(connection, remoteId);
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      await deleteRecord(connection, remoteId);
+    },
+  };
+}
diff --git a/packages/connector-bluesky/src/rate-policy.usage.ts b/packages/connector-bluesky/src/rate-policy.usage.ts
new file mode 100644
index 0000000..0985811
--- /dev/null
+++ b/packages/connector-bluesky/src/rate-policy.usage.ts
@@ -0,0 +1 @@
+export const documentedRates = { requestsPerSecond: 1 };
diff --git a/packages/connector-bluesky/tsconfig.json b/packages/connector-bluesky/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-bluesky/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-discord/package.json b/packages/connector-discord/package.json
new file mode 100644
index 0000000..43c6c06
--- /dev/null
+++ b/packages/connector-discord/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-discord",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-discord/src/contract.test.ts b/packages/connector-discord/src/contract.test.ts
new file mode 100644
index 0000000..b31fdc0
--- /dev/null
+++ b/packages/connector-discord/src/contract.test.ts
@@ -0,0 +1,34 @@
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createDiscordConnector } from "./index.js";
+
+const connection: ConnectorConnection = {
+  id: "conn-discord",
+  workspaceId: "ws-1",
+  provider: "discord",
+  channelId: "120000000000000002",
+  credentialId: { kind: "credential-ref", id: "cred-discord" },
+  fields: {
+    botToken: "discord-test-token",
+    guildId: "120000000000000001",
+  },
+  createdAt: new Date(),
+};
+
+const fetchImpl: typeof fetch = async (input, init): Promise<Response> => {
+  const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  if (url === "https://discord.com/api/v10/users/@me") {
+    if (new Headers(init?.headers).get("authorization") !== "Bot discord-test-token") {
+      return new Response(JSON.stringify({ message: "401: Unauthorized" }), { status: 401 });
+    }
+    return new Response(JSON.stringify({
+      id: "120000000000000003",
+      username: "anarchoposter",
+      global_name: "AnarchoPoster",
+      avatar: null,
+    }));
+  }
+  return new Response(JSON.stringify({ message: `unexpected request: ${url}` }), { status: 404 });
+};
+
+connectorContractTests(createDiscordConnector({ fetchImpl }), { connection });
diff --git a/packages/connector-discord/src/index.ts b/packages/connector-discord/src/index.ts
new file mode 100644
index 0000000..acae5e5
--- /dev/null
+++ b/packages/connector-discord/src/index.ts
@@ -0,0 +1,369 @@
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  FeedItem,
+  NormalizedIdentity,
+  NormalizedPost,
+  NormalizedWebhookEvent,
+  Page,
+  Publication,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  RateLimitedHttpClient,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "discord";
+const API_BASE = "https://discord.com/api/v10";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  feed: true,
+  comments: true,
+  replies: true,
+  directMessages: false,
+  amplifyRepost: false,
+  webhooks: true,
+};
+
+export interface DiscordConnectorOptions {
+  fetchImpl?: typeof fetch;
+}
+
+interface DiscordUser {
+  id: string;
+  username: string;
+  global_name?: string | null;
+  avatar?: string | null;
+}
+
+interface DiscordMessage {
+  id: string;
+  channel_id: string;
+  content: string;
+  timestamp: string;
+  author: DiscordUser;
+  attachments?: { url: string }[];
+  reactions?: { count: number }[];
+  message_reference?: { message_id?: string };
+}
+
+interface DiscordWebhook {
+  id: string;
+  token?: string;
+  url?: string;
+}
+
+interface DiscordApiError {
+  code?: number;
+  message?: string;
+}
+
+function headerValue(headers: Record<string, string>, name: string): string | undefined {
+  return Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+}
+
+function recordBody(body: unknown): Record<string, unknown> {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) {
+    throw new ConnectorError(`${PROVIDER}: malformed webhook payload`, PROVIDER);
+  }
+  return body as Record<string, unknown>;
+}
+
+export function createDiscordConnector(options: DiscordConnectorOptions = {}): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: 5,
+    fetchImpl: options.fetchImpl,
+  });
+  const subscribedWebhookIds = new Set<string>();
+  let publicationSequence = 0;
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Discord",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "botToken",
+        label: "Bot token",
+        required: true,
+        secret: true,
+        placeholder: "Discord bot token",
+      },
+      {
+        name: "guildId",
+        label: "Server ID",
+        required: true,
+        secret: false,
+        pattern: "^\\d{16,22}$",
+      },
+    ],
+    oauth: { kind: "token" },
+    webhookRoute: "/webhooks/discord",
+    docsUrl: "https://discord.com/developers/docs/intro",
+  };
+
+  function tokenOf(connection: ConnectorConnection): string {
+    const token = connection.fields["botToken"];
+    if (token === undefined || token.trim().length === 0) {
+      throw new AuthError(`${PROVIDER}: missing botToken connection field`, PROVIDER, false);
+    }
+    return token;
+  }
+
+  function guildOf(connection: ConnectorConnection): string {
+    const guildId = connection.fields["guildId"];
+    if (guildId === undefined || guildId.trim().length === 0) {
+      throw new ConnectorError(`${PROVIDER}: missing guildId connection field`, PROVIDER);
+    }
+    return guildId;
+  }
+
+  function channelOf(connection: ConnectorConnection): string {
+    const channelId = connection.channelId || connection.fields["channelId"];
+    if (channelId === undefined || channelId.trim().length === 0) {
+      throw new ConnectorError(`${PROVIDER}: connection has no channelId`, PROVIDER);
+    }
+    return channelId;
+  }
+
+  async function api<T>(
+    connection: ConnectorConnection,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<T> {
+    const response = await client.request(PROVIDER, `${API_BASE}${path}`, {
+      ...init,
+      headers: {
+        accept: "application/json",
+        authorization: `Bot ${tokenOf(connection)}`,
+        ...init.headers,
+      },
+    });
+    let body: unknown;
+    try {
+      body = await response.json();
+    } catch (cause) {
+      throw new ConnectorError(
+        `${PROVIDER}: non-JSON response for ${path} (HTTP ${response.status})`,
+        PROVIDER,
+        cause,
+      );
+    }
+    if (!response.ok) {
+      const error = body as DiscordApiError;
+      const detail = error.message ?? `HTTP ${response.status}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthError(`${PROVIDER}: ${detail}`, PROVIDER, response.status === 403);
+      }
+      throw new ConnectorError(`${PROVIDER}: ${detail}`, PROVIDER);
+    }
+    return body as T;
+  }
+
+  function jsonPost(body: Record<string, unknown>): RequestInit {
+    return {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    };
+  }
+
+  function publication(
+    connection: ConnectorConnection,
+    message: DiscordMessage,
+    draftId: string,
+    metadata: Record<string, unknown>,
+  ): Publication {
+    return {
+      id: `discord-${(publicationSequence += 1)}-${message.id}`,
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId: message.id,
+      remoteUrl: `https://discord.com/channels/${guildOf(connection)}/${message.channel_id}/${message.id}`,
+      publishedAt: new Date(message.timestamp),
+      providerMetadata: metadata,
+    };
+  }
+
+  function feedItem(message: DiscordMessage): FeedItem {
+    return {
+      id: message.id,
+      provider: PROVIDER,
+      remoteId: message.id,
+      authorHandle: message.author.username,
+      text: message.content,
+      mediaUrls: (message.attachments ?? []).map((attachment) => attachment.url),
+      createdAt: new Date(message.timestamp),
+      metrics: {
+        reactions: (message.reactions ?? []).reduce((total, reaction) => total + reaction.count, 0),
+      },
+    };
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new ConnectorError(
+        `${PROVIDER}: bot-token auth only — create an application at discord.com/developers/applications`,
+        PROVIDER,
+      );
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      const user = await api<DiscordUser>(connection, "/users/@me");
+      return {
+        provider: PROVIDER,
+        remoteId: user.id,
+        handle: user.username,
+        displayName: user.global_name ?? user.username,
+        avatarUrl:
+          user.avatar === undefined || user.avatar === null
+            ? undefined
+            : `https://cdn.discordapp.com/avatars/${user.id}/${user.avatar}.png`,
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const channelId = channelOf(connection);
+      const embeds = Array.isArray(post.providerMetadata["embeds"])
+        ? post.providerMetadata["embeds"]
+        : [];
+      const message = await api<DiscordMessage>(
+        connection,
+        `/channels/${encodeURIComponent(channelId)}/messages`,
+        jsonPost({ content: post.text, embeds }),
+      );
+      return publication(connection, message, "direct", {
+        channelId,
+        messageId: message.id,
+        ...post.providerMetadata,
+      });
+    },
+
+    async getFeed(
+      connection: ConnectorConnection,
+      request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+    ): Promise<Page<FeedItem>> {
+      if (request.kind !== "home") {
+        throw new CapabilityNotSupportedError(PROVIDER, `feed:${request.kind}`);
+      }
+      const channelId = channelOf(connection);
+      const params = new URLSearchParams({ limit: String(Math.max(1, Math.min(100, request.limit))) });
+      if (request.cursor !== undefined) params.set("before", request.cursor);
+      const messages = await api<DiscordMessage[]>(
+        connection,
+        `/channels/${encodeURIComponent(channelId)}/messages?${params}`,
+      );
+      const last = messages.at(-1);
+      return {
+        items: messages.map(feedItem),
+        nextCursor: messages.length >= Number(params.get("limit")) ? last?.id : undefined,
+      };
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const channelId = channelOf(connection);
+      const limit = Math.max(1, Math.min(100, request.limit));
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (request.cursor !== undefined) params.set("before", request.cursor);
+      const messages = await api<DiscordMessage[]>(
+        connection,
+        `/channels/${encodeURIComponent(channelId)}/messages?${params}`,
+      );
+      const replies = messages.filter(
+        (message) => message.message_reference?.message_id === request.onRemoteId,
+      );
+      return {
+        items: replies.map((message) => ({
+          id: message.id,
+          provider: PROVIDER,
+          remoteId: message.id,
+          onRemoteId: request.onRemoteId,
+          authorHandle: message.author.username,
+          text: message.content,
+          createdAt: new Date(message.timestamp),
+        })),
+        nextCursor: messages.length >= limit ? messages.at(-1)?.id : undefined,
+      };
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const channelId = channelOf(connection);
+      const message = await api<DiscordMessage>(
+        connection,
+        `/channels/${encodeURIComponent(channelId)}/messages`,
+        jsonPost({
+          content: request.text,
+          message_reference: { message_id: request.onRemoteId },
+        }),
+      );
+      return publication(connection, message, "reply", {
+        channelId,
+        messageId: message.id,
+        onRemoteId: request.onRemoteId,
+      });
+    },
+
+    async subscribeWebhooks(
+      connection: ConnectorConnection,
+      request: { topics: string[] },
+    ): Promise<{ subscriptionId: string }> {
+      const channelId = channelOf(connection);
+      const webhook = await api<DiscordWebhook>(
+        connection,
+        `/channels/${encodeURIComponent(channelId)}/webhooks`,
+        jsonPost({ name: `AnarchoPoster (${request.topics.join(", ") || "messages"})` }),
+      );
+      subscribedWebhookIds.add(webhook.id);
+      const url = webhook.url ?? (
+        webhook.token === undefined
+          ? undefined
+          : `${API_BASE}/webhooks/${webhook.id}/${webhook.token}`
+      );
+      if (url === undefined) {
+        throw new ConnectorError(`${PROVIDER}: webhook response did not include a URL`, PROVIDER);
+      }
+      return { subscriptionId: url };
+    },
+
+    async handleWebhook(request: {
+      headers: Record<string, string>;
+      body: unknown;
+    }): Promise<NormalizedWebhookEvent> {
+      const payload = recordBody(request.body);
+      const bodyWebhookId = typeof payload["webhook_id"] === "string"
+        ? payload["webhook_id"]
+        : undefined;
+      const webhookId = headerValue(request.headers, "x-discord-webhook-id") ?? bodyWebhookId;
+      if (webhookId === undefined || !subscribedWebhookIds.has(webhookId)) {
+        throw new AuthError(`${PROVIDER}: unknown webhook id`, PROVIDER, false);
+      }
+      const eventType = typeof payload["type"] === "string" ? payload["type"] : "message";
+      return {
+        provider: PROVIDER,
+        eventType,
+        connectionKey: webhookId,
+        payload,
+        receivedAt: new Date(),
+      };
+    },
+  };
+}
diff --git a/packages/connector-discord/tsconfig.json b/packages/connector-discord/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-discord/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-example/package.json b/packages/connector-example/package.json
new file mode 100644
index 0000000..dc22d8c
--- /dev/null
+++ b/packages/connector-example/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-example",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-example/src/contract.test.ts b/packages/connector-example/src/contract.test.ts
new file mode 100644
index 0000000..81a11b8
--- /dev/null
+++ b/packages/connector-example/src/contract.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { createExampleConnector } from "./index.js";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+
+const connection: ConnectorConnection = {
+  id: "conn-1",
+  workspaceId: "ws-1",
+  provider: "example",
+  channelId: "ch-1",
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: {},
+  createdAt: new Date(),
+};
+
+connectorContractTests(createExampleConnector(), { connection });
+
+describe("example connector specifics", () => {
+  it("refuses authorize honestly", async () => {
+    const connector = createExampleConnector();
+    await expect(connector.authorize({
+      redirectUri: "https://app.example/cb",
+      workspaceId: "ws-1",
+      state: "s",
+    })).rejects.toThrow("does not implement");
+  });
+});
diff --git a/packages/connector-example/src/index.ts b/packages/connector-example/src/index.ts
new file mode 100644
index 0000000..7e5455d
--- /dev/null
+++ b/packages/connector-example/src/index.ts
@@ -0,0 +1,63 @@
+/**
+ * Reference connector: the minimal honest implementation. Every real
+ * connector copies this shape and fills in a provider API.
+ */
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  NormalizedIdentity,
+  NormalizedPost,
+  Publication,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+};
+
+export function createExampleConnector(): PlatformConnector {
+  const manifest: ConnectorManifest = {
+    id: "example",
+    displayName: "Example (reference connector)",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      { name: "apiToken", label: "API token", required: true, secret: true },
+    ],
+  };
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new Error("example connector does not implement OAuth");
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return {
+        provider: manifest.id,
+        remoteId: connection.id,
+        handle: "example@example",
+        displayName: "Example Account",
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      return {
+        id: `pub-${post.text.length}`,
+        workspaceId: connection.workspaceId,
+        draftId: "direct",
+        connectionId: connection.id,
+        remoteId: `remote-${post.text.length}`,
+        publishedAt: new Date(),
+        providerMetadata: post.providerMetadata,
+      };
+    },
+  };
+}
diff --git a/packages/connector-example/tsconfig.json b/packages/connector-example/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-example/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-facebook/package.json b/packages/connector-facebook/package.json
new file mode 100644
index 0000000..9d42fc7
--- /dev/null
+++ b/packages/connector-facebook/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-facebook",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-facebook/src/contract.test.ts b/packages/connector-facebook/src/contract.test.ts
new file mode 100644
index 0000000..a1e7fe8
--- /dev/null
+++ b/packages/connector-facebook/src/contract.test.ts
@@ -0,0 +1,420 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, MediaAsset, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import {
+  CapabilityNotSupportedError,
+  InMemoryCredentials,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import {
+  AuthorizationRedirectRequired,
+  createFacebookConnector,
+  type FacebookAuthorizationRequest,
+} from "./index.js";
+
+/**
+ * Stubbed Graph API: canned JSON per endpoint, real request/response shapes.
+ * Every call is recorded so tests can assert on what was sent.
+ */
+interface StubCall {
+  method: string;
+  url: URL;
+  init: RequestInit | undefined;
+  /** Parsed multipart form when the request carried FormData. */
+  form: FormData | undefined;
+}
+
+interface StubState {
+  calls: StubCall[];
+  nextPostId: number;
+  nextPhotoId: number;
+  /** When set, DELETE of this id succeeds; everything else 404s. */
+  deletedId: string;
+}
+
+const DIALOG = "https://www.facebook.com/v21.0/dialog/oauth";
+const APP_ID = "1234567890";
+const APP_SECRET = "app-secret";
+const USER_TOKEN = "short-lived-user-token";
+const LONG_TOKEN = "long-lived-user-token";
+const PAGE_TOKEN = "page-access-token";
+const PAGE_ID = "112233445566";
+const PAGE_NAME = "AnarchoPoster Page";
+const REDIRECT = "https://app.example.com/oauth/facebook/callback";
+const WS = "ws-1";
+
+const connection: ConnectorConnection = {
+  id: "conn-facebook",
+  workspaceId: WS,
+  provider: "facebook",
+  channelId: PAGE_ID,
+  credentialId: { kind: "credential-ref", id: "cred-facebook" },
+  fields: {},
+  createdAt: new Date(),
+};
+
+const pageAsset: MediaAsset = {
+  id: "asset-1",
+  workspaceId: WS,
+  storageKey: "s3://bucket/one.png",
+  mimeType: "image/png",
+  sizeBytes: 4,
+  width: 640,
+  height: 480,
+  createdAt: new Date(),
+};
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function graphError(message: string, code: number, status = 400): Response {
+  return json({ error: { message, type: "OAuthException", code } }, status);
+}
+
+function requestUrl(input: Parameters<typeof fetch>[0]): URL {
+  if (typeof input === "string") return new URL(input);
+  if (input instanceof URL) return input;
+  return new URL(input.url);
+}
+
+function authorizationOf(init: RequestInit | undefined): string | undefined {
+  return new Headers(init?.headers).get("authorization") ?? undefined;
+}
+
+/** Parses an x-www-form-urlencoded request body. */
+function formParams(init: RequestInit | undefined): URLSearchParams {
+  return new URLSearchParams(typeof init?.body === "string" ? init.body : "");
+}
+
+const PAGES: Record<string, { name: string; username?: string; token: string }> = {
+  [`/${PAGE_ID}`]: { name: PAGE_NAME, username: "anarchoposter", token: PAGE_TOKEN },
+  "/999888777": { name: "Other Page", token: "other-page-token" },
+};
+
+function stubGraph(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const url = requestUrl(input);
+    const method = (init?.method ?? "GET").toUpperCase();
+    const form = init?.body instanceof FormData ? init.body : undefined;
+    state.calls.push({ method, url, init, form });
+    const path = url.pathname.replace(/^\/v[\d.]+/, "");
+
+    // --- OAuth legs (user token / app credentials, no Page token) ---
+    if (path === "/oauth/access_token") {
+      if (url.searchParams.get("grant_type") === "fb_exchange_token") {
+        if (url.searchParams.get("fb_exchange_token") !== USER_TOKEN) {
+          return graphError("Invalid OAuth access token", 190);
+        }
+        return json({ access_token: LONG_TOKEN, token_type: "bearer", expires_in: 5_184_000 });
+      }
+      if (url.searchParams.get("code") !== "good-code") {
+        return graphError("Code was invalid or expired", 100);
+      }
+      return json({ access_token: USER_TOKEN, token_type: "bearer", expires_in: 5_400 });
+    }
+    if (path === "/me/accounts") {
+      if (url.searchParams.get("access_token") !== LONG_TOKEN) {
+        return graphError("Invalid OAuth access token", 190);
+      }
+      return json({
+        data: Object.entries(PAGES).map(([path, page]) => ({
+          id: path.slice(1),
+          name: page.name,
+          ...(page.username !== undefined ? { username: page.username } : {}),
+          access_token: page.token,
+        })),
+      });
+    }
+
+    // --- Page-scoped calls must carry a Page token (not a user token) ---
+    const pageTokens = Object.values(PAGES).map((page) => `Bearer ${page.token}`);
+    if (!pageTokens.includes(authorizationOf(init) ?? "")) {
+      return graphError("The access token is invalid", 190, 401);
+    }
+
+    if (method === "GET" && path in PAGES) {
+      if (url.searchParams.get("fields") !== "id,name,username") {
+        return graphError("unknown fields", 100);
+      }
+      const page = PAGES[path];
+      return json({ id: path.slice(1), name: page?.name, username: page?.username });
+    }
+    if (method === "POST" && path === `/${PAGE_ID}/photos`) {
+      if (form === undefined || form.get("published") !== "false") {
+        return graphError("photo upload must be unpublished", 100);
+      }
+      const file = form.get("file");
+      if (!(file instanceof Blob)) return graphError("missing file", 100);
+      const photoId = `photo-${state.nextPhotoId}`;
+      state.nextPhotoId += 1;
+      return json({ id: photoId, post_id: `${PAGE_ID}_${photoId.slice("photo-".length)}` });
+    }
+    if (method === "POST" && path === `/${PAGE_ID}/feed`) {
+      const body = formParams(init);
+      const id = `${PAGE_ID}_${state.nextPostId}`;
+      state.nextPostId += 1;
+      return json({ id, message: body.get("message") ?? "", link: body.get("link") ?? undefined });
+    }
+    if (method === "DELETE" && /^\/\d+_\d+$/.test(path)) {
+      if (path.endsWith(state.deletedId)) return json({ success: true });
+      return graphError("The post was not found", 100, 404);
+    }
+    return graphError(`stub: no route for ${method} ${path}`, 100, 404);
+  };
+}
+
+interface Harness {
+  state: StubState;
+  connector: ReturnType<typeof createFacebookConnector>;
+  credentials: InMemoryCredentials;
+}
+
+async function createHarness(seedPageToken = true): Promise<Harness> {
+  const state: StubState = { calls: [], nextPostId: 1, nextPhotoId: 1, deletedId: "" };
+  const credentials = new InMemoryCredentials();
+  if (seedPageToken) {
+    await credentials.put(connection, "access_token", PAGE_TOKEN);
+    await credentials.put(connection, "page_id", PAGE_ID);
+  }
+  const connector = createFacebookConnector({
+    env: { FACEBOOK_CLIENT_ID: APP_ID, FACEBOOK_CLIENT_SECRET: APP_SECRET },
+    fetchImpl: stubGraph(state),
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    credentials,
+    loadAsset: async (assetId) => {
+      if (assetId === "asset-1") return pageAsset;
+      if (assetId === "asset-2") return { ...pageAsset, id: assetId };
+      if (assetId === "asset-video") return { ...pageAsset, id: assetId, mimeType: "video/mp4" };
+      throw new Error("asset not found");
+    },
+    openAsset: async () => ({ bytes: new Uint8Array([1, 2, 3, 4]), filename: "one.png" }),
+  });
+  return { state, connector, credentials };
+}
+
+const leg1: FacebookAuthorizationRequest = {
+  redirectUri: REDIRECT,
+  workspaceId: WS,
+  state: "csrf-1",
+  fields: { clientId: APP_ID, clientSecret: APP_SECRET },
+};
+
+function post(text: string, mediaAssetIds: string[] = [], meta: Record<string, unknown> = {}): NormalizedPost {
+  return { text, mediaAssetIds, visibility: "public", providerMetadata: meta };
+}
+
+connectorContractTests((await createHarness()).connector, { connection });
+
+describe("facebook pages connector", () => {
+  it("declares honest Page capabilities and credential-backed fields", () => {
+    const manifest = createFacebookConnector({ credentials: new InMemoryCredentials() }).manifest();
+    expect(manifest.id).toBe("facebook");
+    expect(manifest.displayName).toBe("Facebook Pages");
+    expect(manifest.capabilities).toEqual(
+      expect.objectContaining({
+        publishText: true,
+        publishImages: true,
+        deletePublication: true,
+        nativeScheduling: false,
+        analytics: false,
+        feed: false,
+        comments: false,
+        webhooks: false,
+        publishVideo: false,
+      }),
+    );
+    expect(manifest.oauth).toMatchObject({
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: DIALOG,
+      scopes: ["pages_show_list", "pages_manage_posts", "pages_read_engagement"],
+    });
+    expect(manifest.connectionFields).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "clientId", secret: false }),
+        expect.objectContaining({ name: "clientSecret", secret: true }),
+      ]),
+    );
+  });
+
+  it("leg 1 builds the v21.0 consent URL with the Pages scopes", async () => {
+    const { state, connector } = await createHarness(false);
+    const error = await connector.authorize(leg1).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(AuthorizationRedirectRequired);
+    const consent = new URL((error as AuthorizationRedirectRequired).authorizationUrl);
+    expect(consent.origin + consent.pathname).toBe(DIALOG);
+    expect(consent.searchParams.get("client_id")).toBe(APP_ID);
+    expect(consent.searchParams.get("redirect_uri")).toBe(REDIRECT);
+    expect(consent.searchParams.get("state")).toBe("csrf-1");
+    expect(consent.searchParams.get("scope")?.split(",")).toEqual([
+      "pages_show_list",
+      "pages_manage_posts",
+      "pages_read_engagement",
+    ]);
+    expect(state.calls).toHaveLength(0);
+
+    const redirect = await connector.buildAuthorizationUrl?.(leg1);
+    expect(redirect?.authorizationUrl).toBe((error as AuthorizationRedirectRequired).authorizationUrl);
+    expect(redirect?.connection.provider).toBe("facebook");
+  });
+
+  it("leg 2 exchanges code → short-lived → long-lived token → /me/accounts page token", async () => {
+    const { state, connector, credentials } = await createHarness(false);
+    await expect(connector.authorize(leg1)).rejects.toBeInstanceOf(AuthorizationRedirectRequired);
+
+    const leg2: FacebookAuthorizationRequest = { ...leg1, providerMetadata: { code: "good-code" } };
+    const result = await connector.authorize(leg2);
+
+    const calls = state.calls.filter((call) => call.url.pathname.endsWith("/oauth/access_token"));
+    expect(calls).toHaveLength(2);
+    const short = calls[0]?.url.searchParams;
+    expect(short?.get("grant_type")).toBeNull();
+    expect(short?.get("code")).toBe("good-code");
+    expect(short?.get("client_id")).toBe(APP_ID);
+    expect(short?.get("client_secret")).toBe(APP_SECRET);
+    const extend = calls[1]?.url.searchParams;
+    expect(extend?.get("grant_type")).toBe("fb_exchange_token");
+    expect(extend?.get("fb_exchange_token")).toBe(USER_TOKEN);
+
+    const meAccounts = state.calls.find((call) => call.url.pathname.endsWith("/me/accounts"));
+    expect(meAccounts?.url.searchParams.get("access_token")).toBe(LONG_TOKEN);
+
+    // The PAGE token + page id are what get stored, not the user token.
+    expect(await credentials.getAccessToken(result.connection)).toBe(PAGE_TOKEN);
+    expect(await credentials.getSecret(result.connection, "page_id")).toBe(PAGE_ID);
+    expect(result.connection.channelId).toBe(PAGE_ID);
+
+    expect(result.identity).toEqual({
+      provider: "facebook",
+      remoteId: PAGE_ID,
+      handle: "@anarchoposter",
+      displayName: PAGE_NAME,
+    });
+  });
+
+  it("leg 2 honors a requested pageId from /me/accounts", async () => {
+    const { connector } = await createHarness(false);
+    const leg2: FacebookAuthorizationRequest = {
+      ...leg1,
+      providerMetadata: { code: "good-code", pageId: "999888777" },
+    };
+    const result = await connector.authorize(leg2);
+    expect(result.connection.channelId).toBe("999888777");
+    expect(result.identity.handle).toBe("Other Page");
+  });
+
+  it("getIdentity reads id,name,username with the page token", async () => {
+    const { state, connector } = await createHarness();
+    const identity = await connector.getIdentity(connection);
+    expect(identity).toEqual({
+      provider: "facebook",
+      remoteId: PAGE_ID,
+      handle: "@anarchoposter",
+      displayName: PAGE_NAME,
+    });
+    const call = state.calls.at(-1);
+    expect(call?.method).toBe("GET");
+    expect(call?.url.pathname).toBe(`/v21.0/${PAGE_ID}`);
+    expect(call?.url.searchParams.get("fields")).toBe("id,name,username");
+    expect(authorizationOf(call?.init)).toBe(`Bearer ${PAGE_TOKEN}`);
+  });
+
+  it("publishes a message to /{page-id}/feed with the page token", async () => {
+    const { state, connector } = await createHarness();
+    const publication = await connector.publish?.(connection, post("Launch day"));
+    expect(publication?.remoteId).toBe(`${PAGE_ID}_1`);
+    expect(publication?.remoteUrl).toBe(`https://www.facebook.com/${PAGE_ID}_1`);
+    expect(publication?.connectionId).toBe(connection.id);
+    const call = state.calls.at(-1);
+    expect(call?.method).toBe("POST");
+    expect(call?.url.pathname).toBe(`/v21.0/${PAGE_ID}/feed`);
+    expect(authorizationOf(call?.init)).toBe(`Bearer ${PAGE_TOKEN}`);
+    const body = formParams(call?.init);
+    expect(body.get("message")).toBe("Launch day");
+    expect(body.get("link")).toBeNull();
+  });
+
+  it("publishes a link post via the feed link parameter", async () => {
+    const { state, connector } = await createHarness();
+    const publication = await connector.publish?.(connection, post("Read this", [], { link: "https://example.com/a" }));
+    expect(publication?.remoteId).toBe(`${PAGE_ID}_1`);
+    const call = state.calls.at(-1);
+    const body = formParams(call?.init);
+    expect(body.get("message")).toBe("Read this");
+    expect(body.get("link")).toBe("https://example.com/a");
+  });
+
+  it("uploads images unpublished and attaches them via media_fbid", async () => {
+    const { state, connector } = await createHarness();
+    const publication = await connector.publish?.(
+      connection,
+      post("With photos", ["asset-1", "asset-2"]),
+    );
+    expect(publication?.remoteId).toBe(`${PAGE_ID}_1`);
+    expect(publication?.providerMetadata).toMatchObject({
+      photoIds: ["photo-1", "photo-2"],
+    });
+
+    const photos = state.calls.filter((call) => call.url.pathname === `/v21.0/${PAGE_ID}/photos`);
+    expect(photos).toHaveLength(2);
+    for (const photo of photos) {
+      expect(authorizationOf(photo.init)).toBe(`Bearer ${PAGE_TOKEN}`);
+      expect(photo.form?.get("published")).toBe("false");
+      expect(photo.form?.get("file")).toBeInstanceOf(Blob);
+    }
+    const feed = state.calls.find((call) => call.url.pathname === `/v21.0/${PAGE_ID}/feed`);
+    const feedBody = formParams(feed?.init);
+    expect(feedBody.get("message")).toBe("With photos");
+    expect(feedBody.get("attached_media[0]")).toBe('{"media_fbid":"photo-1"}');
+    expect(feedBody.get("attached_media[1]")).toBe('{"media_fbid":"photo-2"}');
+    expect(feedBody.get("link")).toBeNull();
+  });
+
+  it("rejects more than 10 photos and non-image assets", async () => {
+    const { connector } = await createHarness();
+    await expect(
+      connector.publish?.(connection, post("too many", Array.from({ length: 11 }, (_, i) => `asset-${i}`))),
+    ).rejects.toThrow(/at most 10 photos/);
+    await expect(
+      connector.publish?.(connection, post("video", ["asset-video"])),
+    ).rejects.toBeInstanceOf(CapabilityNotSupportedError);
+  });
+
+  it("uploadMedia returns an unpublished photo id without publishing a post", async () => {
+    const { state, connector } = await createHarness();
+    const remote = await connector.uploadMedia?.(connection, pageAsset);
+    expect(remote).toMatchObject({ remoteId: "photo-1", mimeType: "image/png", width: 640, height: 480 });
+    expect(state.calls.some((call) => call.url.pathname.endsWith("/feed"))).toBe(false);
+  });
+
+  it("deletePublication DELETEs {page-id}_{post-id} and tolerates already-deleted", async () => {
+    const { state, connector } = await createHarness();
+    state.deletedId = `${PAGE_ID}_1`;
+    await expect(connector.deletePublication?.(connection, `${PAGE_ID}_1`)).resolves.toBeUndefined();
+    const call = state.calls.at(-1);
+    expect(call?.method).toBe("DELETE");
+    expect(call?.url.pathname).toBe(`/v21.0/${PAGE_ID}_1`);
+    expect(authorizationOf(call?.init)).toBe(`Bearer ${PAGE_TOKEN}`);
+
+    await expect(
+      connector.deletePublication?.(connection, `${PAGE_ID}_does-not-exist`),
+    ).resolves.toBeUndefined();
+  });
+
+  it("surfaces other Graph failures from deletePublication", async () => {
+    const { state, connector } = await createHarness();
+    state.deletedId = "never-matches";
+    await expect(
+      connector.deletePublication?.(connection, `${PAGE_ID}_404`),
+    ).resolves.toBeUndefined(); // 404 → idempotent, not an error
+    await expect(
+      connector.publish?.(connection, post("nope", ["asset-unknown"])),
+    ).rejects.toThrow(/asset not found/);
+  });
+});
diff --git a/packages/connector-facebook/src/index.ts b/packages/connector-facebook/src/index.ts
new file mode 100644
index 0000000..849fddd
--- /dev/null
+++ b/packages/connector-facebook/src/index.ts
@@ -0,0 +1,547 @@
+/**
+ * Facebook Pages connector — Graph API v21.0, one Page per connection.
+ *
+ * Auth: Facebook Login for Pages. `authorize` leg 1 points the user at
+ * https://www.facebook.com/v21.0/dialog/oauth with scopes
+ * pages_show_list,pages_manage_posts,pages_read_engagement; leg 2 exchanges
+ * the code for a short-lived user token, extends it with fb_exchange_token,
+ * resolves GET /me/accounts to a Page, and stores that Page's access token.
+ * Connections therefore publish as the Page: the PAGE token is the
+ * connection's access_token and the Page id is both channelId and page_id.
+ *
+ * Honest capability notes (verified against the Graph API):
+ * - Publishing: POST /{page-id}/feed {message, link?}. With images, each
+ *   photo is uploaded unpublished (multipart, published=false) to
+ *   /{page-id}/photos and attached via attached_media[n]={"media_fbid":…};
+ *   a photo post cannot also carry a link, so link is ignored there. At
+ *   most 10 photos per post.
+ * - Deletion: DELETE /{page-id}_{post-id}; the Graph already-deleted answer
+ *   (HTTP 404 / error code 803/900) counts as deleted, making
+ *   deletePublication idempotent.
+ * - No native scheduling (post on time from the scheduler), no analytics,
+ *   no feed reading, no comments, no DMs, no webhooks.
+ */
+import { randomUUID } from "node:crypto";
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  CredentialRef,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  Publication,
+  RemoteMedia,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  InMemoryCredentials,
+  RateLimitedHttpClient,
+  type AuthorizationRequest,
+  type AuthorizationResult,
+  type CodeExchangeRequest,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "facebook";
+const GRAPH_VERSION = "v21.0";
+const GRAPH = `https://graph.facebook.com/${GRAPH_VERSION}`;
+const DIALOG_URL = `https://www.facebook.com/${GRAPH_VERSION}/dialog/oauth`;
+const SCOPES = ["pages_show_list", "pages_manage_posts", "pages_read_engagement"];
+/** Photos attachable to one Page feed post. */
+const MAX_PHOTOS = 10;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  deletePublication: true,
+  publishCarousel: false,
+  publishVideo: false,
+  feed: false,
+  mentions: false,
+  comments: false,
+  replies: false,
+  reactions: false,
+  directMessages: false,
+  amplifyRepost: false,
+  amplifyQuote: false,
+  amplifyShare: false,
+  analytics: false,
+  webhooks: false,
+  nativeScheduling: false,
+};
+
+/** Credential keys stored per connection through the CredentialAccessor. */
+const SECRET = {
+  /** Long-lived PAGE access token (not the user token). */
+  accessToken: "access_token",
+  pageId: "page_id",
+  clientId: "client_id",
+  clientSecret: "client_secret",
+} as const;
+
+export interface FacebookConnectorOptions {
+  env?: Record<string, string | undefined>;
+  /** fetch override for tests (same pattern as the other connectors). */
+  fetchImpl?: typeof fetch;
+  /** Requests per second against graph.facebook.com. Default 1. */
+  requestsPerSecond?: number;
+  /** Sleep override for the rate limiter (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Secret store. Default: in-memory (dev + contract tests). */
+  credentials?: CredentialAccessor;
+  /** Resolve a media asset id to its metadata (needed by publish with media). */
+  loadAsset?: (assetId: string) => Promise<MediaAsset>;
+  /** Read asset bytes for the multipart photo upload. */
+  openAsset?: (media: MediaAsset) => Promise<{ bytes: Uint8Array; filename: string }>;
+}
+
+/** The SDK's AuthorizationRequest carries no provider input slot. */
+export interface FacebookAuthorizationRequest extends AuthorizationRequest {
+  providerMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Thrown by the first authorize leg. AuthorizationResult has no slot for a
+ * redirect, so the consent URL rides on this error; callers send the user
+ * there and call authorize again with providerMetadata.code.
+ */
+export class AuthorizationRedirectRequired extends ConnectorError {
+  constructor(
+    readonly authorizationUrl: string,
+    readonly connectionId: string,
+  ) {
+    super("redirect the user to Facebook to authorize the Pages flow", PROVIDER);
+    this.name = "AuthorizationRedirectRequired";
+  }
+}
+
+interface GraphErrorBody {
+  error?: {
+    message?: string;
+    type?: string;
+    code?: number;
+    error_subcode?: number;
+  };
+}
+
+interface TokenResponse {
+  access_token: string;
+  token_type?: string;
+  expires_in?: number;
+}
+
+interface GraphPageAccount {
+  id: string;
+  name?: string;
+  username?: string;
+  access_token?: string;
+}
+
+interface GraphPageList {
+  data?: GraphPageAccount[];
+}
+
+interface GraphIdentity {
+  id: string;
+  name?: string;
+  username?: string;
+}
+
+interface GraphPhoto {
+  id: string;
+  post_id?: string;
+}
+
+interface GraphPostId {
+  id: string;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function createFacebookConnector(
+  options: FacebookConnectorOptions = {},
+): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: options.requestsPerSecond ?? 1,
+    fetchImpl: options.fetchImpl,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Facebook Pages",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "clientId",
+        label: "Meta App ID",
+        required: true,
+        secret: false,
+        placeholder: "1234567890",
+      },
+      {
+        name: "clientSecret",
+        label: "Meta App Secret",
+        required: true,
+        secret: true,
+      },
+    ],
+    oauth: {
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: DIALOG_URL,
+      scopes: SCOPES,
+      pkce: false,
+    },
+    docsUrl: "https://developers.facebook.com/docs/pages-api/",
+  };
+
+  /** Graph error taxonomy: AuthError for expired/invalid tokens. */
+  async function send(url: string, init: RequestInit): Promise<unknown> {
+    const response = await client.request(PROVIDER, url, {
+      ...init,
+      headers: { ...init.headers, accept: "application/json" },
+    });
+    const text = await response.text();
+    let data: unknown = {};
+    if (text.length > 0) {
+      try {
+        data = JSON.parse(text) as unknown;
+      } catch (cause) {
+        throw new ConnectorError(
+          `${PROVIDER}: non-JSON Graph API response (HTTP ${response.status})`,
+          PROVIDER,
+          cause,
+        );
+      }
+    }
+    if (!response.ok) {
+      const graph = data as GraphErrorBody;
+      const detail = graph.error?.message ?? "Graph API request failed";
+      const message = `${PROVIDER}: HTTP ${response.status} ${init.method ?? "GET"} ${new URL(url).pathname}: ${detail}`;
+      const code = graph.error?.code;
+      if (response.status === 401 || response.status === 403 || code === 190 || code === 102) {
+        throw new AuthError(message, PROVIDER, false);
+      }
+      throw new ConnectorError(message, PROVIDER, { status: response.status, code });
+    }
+    return data;
+  }
+
+  async function graphGet<T>(url: string, init: RequestInit = {}): Promise<T> {
+    return (await send(url, { method: "GET", ...init })) as T;
+  }
+
+  async function pageToken(connection: ConnectorConnection): Promise<string> {
+    return credentials.getAccessToken(connection);
+  }
+
+  /** Page id: vault first, then connection fields, then channelId. */
+  async function pageIdOf(connection: ConnectorConnection): Promise<string> {
+    let id: string | undefined;
+    try {
+      id = await credentials.getSecret(connection, SECRET.pageId);
+    } catch {
+      id = undefined;
+    }
+    id ??= connection.fields["page_id"] ?? connection.fields["pageId"] ?? connection.channelId;
+    if (id === undefined || id.length === 0) {
+      throw new ConnectorError(`connection ${connection.id} has no Page id`, PROVIDER);
+    }
+    return id;
+  }
+
+  /** Client credentials: vault first, then connection fields, then env. */
+  async function clientCredentials(
+    connection: ConnectorConnection,
+  ): Promise<{ clientId: string; clientSecret: string }> {
+    const env = options.env ?? {};
+    const clientId =
+      (await secretOrUndefined(connection, SECRET.clientId)) ??
+      str(connection.fields["clientId"]) ??
+      str(env.FACEBOOK_CLIENT_ID);
+    const clientSecret =
+      (await secretOrUndefined(connection, SECRET.clientSecret)) ??
+      str(connection.fields["clientSecret"]) ??
+      str(env.FACEBOOK_CLIENT_SECRET);
+    if (clientId === undefined || clientSecret === undefined) {
+      throw new ConnectorError(`${PROVIDER}: no Meta app credentials available`, PROVIDER);
+    }
+    return { clientId, clientSecret };
+  }
+
+  async function secretOrUndefined(
+    connection: ConnectorConnection,
+    key: string,
+  ): Promise<string | undefined> {
+    try {
+      return await credentials.getSecret(connection, key);
+    } catch {
+      return undefined;
+    }
+  }
+
+  function connectionFor(
+    connectionId: string,
+    workspaceId: string,
+    fields: Record<string, string>,
+    channelId: string,
+  ): ConnectorConnection {
+    const credentialId: CredentialRef = { kind: "credential-ref", id: connectionId };
+    return {
+      id: connectionId,
+      workspaceId,
+      provider: PROVIDER,
+      channelId,
+      credentialId,
+      fields,
+      createdAt: new Date(),
+    };
+  }
+
+  /** GET /{page-id}?fields=id,name,username with the Page token. */
+  async function identityOf(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+    const id = await pageIdOf(connection);
+    const token = await pageToken(connection);
+    const graph = await graphGet<GraphIdentity>(
+      `${GRAPH}/${encodeURIComponent(id)}?fields=${encodeURIComponent("id,name,username")}`,
+      { headers: { authorization: `Bearer ${token}` } },
+    );
+    const identity: NormalizedIdentity = {
+      provider: PROVIDER,
+      remoteId: graph.id,
+      handle: graph.username !== undefined ? `@${graph.username}` : graph.name ?? graph.id,
+    };
+    if (graph.name !== undefined) identity.displayName = graph.name;
+    return identity;
+  }
+
+  /** Multipart photo upload → unpublished photo id usable as media_fbid. */
+  async function uploadPhoto(connection: ConnectorConnection, media: MediaAsset): Promise<string> {
+    if (options.openAsset === undefined) {
+      throw new ConnectorError(`${PROVIDER}: image upload needs an openAsset option`, PROVIDER);
+    }
+    const id = await pageIdOf(connection);
+    const token = await pageToken(connection);
+    const { bytes, filename } = await options.openAsset(media);
+    const body = new FormData();
+    body.append("file", new Blob([new Uint8Array(bytes)], { type: media.mimeType }), filename);
+    body.append("published", "false");
+    const graph = (await send(`${GRAPH}/${encodeURIComponent(id)}/photos`, {
+      method: "POST",
+      headers: { authorization: `Bearer ${token}` },
+      body,
+    })) as GraphPhoto;
+    return graph.id;
+  }
+
+  const connector: PlatformConnector = {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async buildAuthorizationUrl(input: AuthorizationRequest) {
+      try {
+        await connector.authorize(input);
+        throw new ConnectorError("authorization redirect missing", PROVIDER);
+      } catch (error) {
+        if (!(error instanceof AuthorizationRedirectRequired)) throw error;
+        const fields: Record<string, string> = {};
+        const clientId = str(input.fields?.clientId);
+        if (clientId !== undefined) fields.clientId = clientId;
+        const connection = connectionFor(error.connectionId, input.workspaceId, fields, error.connectionId);
+        return { authorizationUrl: error.authorizationUrl, connection };
+      }
+    },
+
+    async exchangeCode(input: CodeExchangeRequest): Promise<AuthorizationResult> {
+      return connector.authorize({
+        ...input,
+        providerMetadata: { ...(input as FacebookAuthorizationRequest).providerMetadata, code: input.code },
+      } as FacebookAuthorizationRequest);
+    },
+
+    /**
+     * Leg 1 (no code): store the app credentials and throw
+     * AuthorizationRedirectRequired with the consent URL. Leg 2
+     * (providerMetadata.code): code → short-lived user token → long-lived
+     * (fb_exchange_token) → /me/accounts picks the Page, whose token and id
+     * become the connection's access_token / page_id.
+     */
+    async authorize(input: FacebookAuthorizationRequest): Promise<AuthorizationResult> {
+      const meta = input.providerMetadata ?? {};
+      const connectionId =
+        input.connectionId ?? str(meta.connectionId) ?? `${PROVIDER}:${input.workspaceId}`;
+      const fields: Record<string, string> = {};
+      const fieldClientId = str(input.fields?.clientId) ?? str(meta.clientId);
+      const fieldClientSecret = str(input.fields?.clientSecret) ?? str(meta.clientSecret);
+      if (fieldClientId !== undefined) fields.clientId = fieldClientId;
+
+      const code = str(meta.code);
+      if (code === undefined) {
+        if (fieldClientId === undefined || fieldClientSecret === undefined) {
+          throw new ConnectorError(
+            `${PROVIDER}: authorize needs clientId and clientSecret (fields or env)`,
+            PROVIDER,
+          );
+        }
+        const connection = connectionFor(connectionId, input.workspaceId, fields, connectionId);
+        await credentials.put(connection, SECRET.clientId, fieldClientId);
+        await credentials.put(connection, SECRET.clientSecret, fieldClientSecret);
+        const url = new URL(DIALOG_URL);
+        url.searchParams.set("client_id", fieldClientId);
+        url.searchParams.set("redirect_uri", input.redirectUri);
+        url.searchParams.set("state", input.state);
+        url.searchParams.set("scope", SCOPES.join(","));
+        throw new AuthorizationRedirectRequired(url.toString(), connectionId);
+      }
+
+      const connection = connectionFor(connectionId, input.workspaceId, fields, connectionId);
+      const { clientId, clientSecret } = await clientCredentials(connection);
+      await credentials.put(connection, SECRET.clientId, clientId);
+      await credentials.put(connection, SECRET.clientSecret, clientSecret);
+
+      const exchange = new URL(`${GRAPH}/oauth/access_token`);
+      exchange.searchParams.set("client_id", clientId);
+      exchange.searchParams.set("client_secret", clientSecret);
+      exchange.searchParams.set("redirect_uri", input.redirectUri);
+      exchange.searchParams.set("code", code);
+      const shortLived = await graphGet<TokenResponse>(exchange.toString());
+
+      const extend = new URL(`${GRAPH}/oauth/access_token`);
+      extend.searchParams.set("grant_type", "fb_exchange_token");
+      extend.searchParams.set("client_id", clientId);
+      extend.searchParams.set("client_secret", clientSecret);
+      extend.searchParams.set("fb_exchange_token", shortLived.access_token);
+      const longLived = await graphGet<TokenResponse>(extend.toString());
+
+      const accounts = new URL(`${GRAPH}/me/accounts`);
+      accounts.searchParams.set("fields", "id,name,username,access_token");
+      accounts.searchParams.set("access_token", longLived.access_token);
+      accounts.searchParams.set("limit", "100");
+      const pages = await graphGet<GraphPageList>(accounts.toString());
+      const list = pages.data ?? [];
+      if (list.length === 0) {
+        throw new ConnectorError(
+          `${PROVIDER}: the user administers no Pages (pages_show_list scope required)`,
+          PROVIDER,
+        );
+      }
+      const wanted = str(meta.pageId) ?? str(input.fields?.pageId);
+      const page =
+        (wanted !== undefined ? list.find((candidate) => candidate.id === wanted) : undefined) ??
+        list[0];
+      if (page === undefined) {
+        throw new ConnectorError(`${PROVIDER}: Page ${wanted ?? ""} not found`, PROVIDER);
+      }
+      if (page.access_token === undefined) {
+        throw new ConnectorError(`${PROVIDER}: no Page token returned for ${page.id}`, PROVIDER);
+      }
+
+      const connected = connectionFor(connectionId, input.workspaceId, fields, page.id);
+      await credentials.put(connected, SECRET.accessToken, page.access_token);
+      await credentials.put(connected, SECRET.pageId, page.id);
+      const identity = await identityOf(connected);
+      return { connection: connected, identity };
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return identityOf(connection);
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const meta = post.providerMetadata;
+      const id = await pageIdOf(connection);
+      const token = await pageToken(connection);
+      const text = post.text.trim();
+      const link = str(meta.link);
+
+      if (options.loadAsset === undefined && post.mediaAssetIds.length > 0) {
+        throw new ConnectorError(`${PROVIDER}: publishing media needs a loadAsset option`, PROVIDER);
+      }
+      if (post.mediaAssetIds.length > MAX_PHOTOS) {
+        throw new ConnectorError(`at most ${MAX_PHOTOS} photos per Page post`, PROVIDER);
+      }
+      const mediaFbids: string[] = [];
+      for (const assetId of post.mediaAssetIds) {
+        const asset = await options.loadAsset?.(assetId);
+        if (asset === undefined) {
+          throw new ConnectorError(`${PROVIDER}: unknown media asset "${assetId}"`, PROVIDER);
+        }
+        if (!asset.mimeType.startsWith("image/")) {
+          throw new CapabilityNotSupportedError(PROVIDER, `publish:${asset.mimeType}`);
+        }
+        mediaFbids.push(await uploadPhoto(connection, asset));
+      }
+      if (text.length === 0 && link === undefined && mediaFbids.length === 0) {
+        throw new ConnectorError(
+          `${PROVIDER}: a Page post needs a message, a link, or photos`,
+          PROVIDER,
+        );
+      }
+
+      const body = new URLSearchParams();
+      if (text.length > 0) body.set("message", text);
+      // A photo post cannot carry a link too — link is ignored with images.
+      if (link !== undefined && mediaFbids.length === 0) body.set("link", link);
+      mediaFbids.forEach((fbid, index) => {
+        body.set(`attached_media[${index}]`, JSON.stringify({ media_fbid: fbid }));
+      });
+      const graph = (await send(`${GRAPH}/${encodeURIComponent(id)}/feed`, {
+        method: "POST",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+      })) as GraphPostId;
+
+      const publication: Publication = {
+        id: randomUUID(),
+        workspaceId: connection.workspaceId,
+        draftId: str(meta.draftId) ?? "direct",
+        connectionId: connection.id,
+        remoteId: graph.id,
+        remoteUrl: `https://www.facebook.com/${graph.id}`,
+        publishedAt: new Date(),
+        providerMetadata: { ...meta, photoIds: mediaFbids },
+      };
+      return publication;
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      const token = await pageToken(connection);
+      try {
+        await send(`${GRAPH}/${encodeURIComponent(remoteId)}`, {
+          method: "DELETE",
+          headers: { authorization: `Bearer ${token}` },
+        });
+      } catch (error) {
+        // Already gone counts as deleted — deletion is idempotent.
+        const cause = error instanceof ConnectorError ? (error.cause as { status?: number; code?: number }) : undefined;
+        if (cause?.status === 404 || cause?.code === 803 || cause?.code === 900) return;
+        throw error;
+      }
+    },
+
+    async uploadMedia(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia> {
+      if (!media.mimeType.startsWith("image/")) {
+        throw new CapabilityNotSupportedError(PROVIDER, `uploadMedia:${media.mimeType}`);
+      }
+      const remote: RemoteMedia = {
+        remoteId: await uploadPhoto(connection, media),
+        mimeType: media.mimeType,
+      };
+      if (media.width !== undefined) remote.width = media.width;
+      if (media.height !== undefined) remote.height = media.height;
+      return remote;
+    },
+  };
+
+  return connector;
+}
diff --git a/packages/connector-facebook/tsconfig.json b/packages/connector-facebook/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-facebook/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-instagram/package.json b/packages/connector-instagram/package.json
new file mode 100644
index 0000000..e1cc089
--- /dev/null
+++ b/packages/connector-instagram/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-instagram",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-instagram/src/contract.test.ts b/packages/connector-instagram/src/contract.test.ts
new file mode 100644
index 0000000..7f656b0
--- /dev/null
+++ b/packages/connector-instagram/src/contract.test.ts
@@ -0,0 +1,572 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import { AuthError, InMemoryCredentials } from "@tactical-media-broadcast-hub/connector-sdk";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import {
+  AuthorizationRedirectRequired,
+  assertCaption,
+  createInstagramConnector,
+  type InstagramAuthorizationRequest,
+} from "./index.js";
+
+/**
+ * Stubbed Graph API: canned JSON per endpoint, real request/response shapes.
+ * Every call is recorded so tests can assert on what was sent.
+ */
+interface StubCall {
+  method: string;
+  url: URL;
+  init: RequestInit | undefined;
+}
+
+const API = "https://graph.facebook.com/v21.0";
+const DIALOG = "https://www.facebook.com/v21.0/dialog/oauth";
+const REDIRECT = "https://app.example.com/oauth/instagram/callback";
+const IG_USER_ID = "17841400000000001";
+const IG_USERNAME = "anarchoposter";
+const PAGE_ID = "10000000000001";
+const FB_USER_ID = "900000000000001";
+const SHORT_TOKEN = "EAAW-short-lived-user-token";
+const LONG_TOKEN = "EAAW-long-lived-user-token";
+const REFRESHED_TOKEN = "EAAW-refreshed-long-lived-token";
+
+const connection: ConnectorConnection = {
+  id: "conn-instagram",
+  workspaceId: "ws-1",
+  provider: "instagram",
+  channelId: "conn-instagram",
+  credentialId: { kind: "credential-ref", id: "cred-instagram" },
+  fields: { igUserId: IG_USER_ID },
+  createdAt: new Date(),
+};
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function graphError(message: string, code: number, status = 400): Response {
+  return json({ error: { message, code } }, status);
+}
+
+function formBody(init: RequestInit | undefined): URLSearchParams {
+  return new URLSearchParams(String(init?.body ?? ""));
+}
+
+function queryOf(call: StubCall | undefined): URLSearchParams {
+  return call?.url.searchParams ?? new URLSearchParams();
+}
+
+/** Request path without the Graph version segment (/v21.0/...). */
+function pathOf(call: StubCall): string {
+  return call.url.pathname.replace(/^\/v21\.0/, "");
+}
+
+function headerOf(init: RequestInit | undefined, name: string): string | undefined {
+  return new Headers(init?.headers).get(name) ?? undefined;
+}
+
+function stubGraph(stub: { calls: StubCall[]; nextId: number }): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const href =
+      typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const url = new URL(href);
+    const method = (init?.method ?? "GET").toUpperCase();
+    stub.calls.push({ method, url, init });
+    // Route matching ignores the version segment (/v21.0/...).
+    const route = `${method} ${url.pathname.replace(/^\/v21\.0/, "")}`;
+
+    // Token endpoint: both the code exchange and the fb_exchange_token upgrade.
+    if (route === "GET /oauth/access_token") {
+      if (url.searchParams.get("code") === "good-code") {
+        return json({ access_token: SHORT_TOKEN, token_type: "bearer", expires_in: 5183 });
+      }
+      if (url.searchParams.get("grant_type") === "fb_exchange_token") {
+        if (url.searchParams.get("fb_exchange_token") !== SHORT_TOKEN) {
+          return graphError("Invalid OAuth access token signature.", 190, 400);
+        }
+        return json({ access_token: LONG_TOKEN, token_type: "bearer", expires_in: 5_184_000 });
+      }
+      if (url.searchParams.get("grant_type") === "ig_refresh_token") {
+        if (url.searchParams.get("access_token") !== LONG_TOKEN) {
+          return graphError("The access token is invalid", 190, 400);
+        }
+        return json({ access_token: REFRESHED_TOKEN, token_type: "bearer", expires_in: 5_184_000 });
+      }
+      if (url.searchParams.get("code") === "bad-code") {
+        return graphError("Validation of the provided code failed.", 100, 400);
+      }
+      return graphError("Missing redirect_uri or code", 191, 400);
+    }
+
+    if (route === "GET /refresh_access_token") {
+      if (url.searchParams.get("grant_type") !== "ig_refresh_token") {
+        return graphError("Only ig_refresh_token is supported here", 100, 400);
+      }
+      if (url.searchParams.get("access_token") !== LONG_TOKEN) {
+        return graphError("The access token is invalid", 190, 400);
+      }
+      return json({ access_token: REFRESHED_TOKEN, token_type: "bearer", expires_in: 5_184_000 });
+    }
+
+    // Everything below is an authenticated Graph call.
+    if (headerOf(init, "authorization") !== `Bearer ${LONG_TOKEN}`) {
+      return graphError("Invalid OAuth access token.", 190, 401);
+    }
+
+    if (route === "GET /me") return json({ id: FB_USER_ID, name: "AnarchoPoster HQ" });
+
+    if (route === "GET /me/accounts") {
+      return json({
+        data: [
+          {
+            id: PAGE_ID,
+            name: "AnarchoPoster Page",
+            instagram_business_account: { id: IG_USER_ID, username: IG_USERNAME, name: "AnarchoPoster" },
+          },
+        ],
+      });
+    }
+
+    if (route === `POST /${IG_USER_ID}/media`) {
+      const form = formBody(init);
+      if (form.get("image_url") !== null && !form.get("image_url")?.startsWith("https://")) {
+        return graphError("image_url must be an absolute https URL", 100);
+      }
+      const id = `container-${(stub.nextId += 1)}`;
+      return json({ id });
+    }
+
+    if (route === `POST /${IG_USER_ID}/media_publish`) {
+      const creationId = formBody(init).get("creation_id") ?? "";
+      if (creationId.startsWith("container-")) return json({ id: `media-${(stub.nextId += 1)}` });
+      return graphError("The container was not found", 100);
+    }
+
+    const media = /^GET \/media-(\d+)$/.exec(route);
+    if (media?.[1] !== undefined) {
+      return json({
+        id: `media-${media[1]}`,
+        permalink: `https://www.instagram.com/p/media-${media[1]}/`,
+        timestamp: "2026-10-06T12:00:00+0000",
+        media_type: "IMAGE",
+      });
+    }
+
+    if (route === `DELETE /${IG_USER_ID}`) return json({ success: true });
+    const deleted = /^DELETE \/media-(\d+)$/.exec(route);
+    if (deleted?.[1] !== undefined) return json({ success: true });
+
+    return graphError(`stub: no route for ${route}`, 100, 404);
+  };
+}
+
+interface Harness {
+  stub: { calls: StubCall[]; nextId: number };
+  connector: ReturnType<typeof createInstagramConnector>;
+  credentials: InMemoryCredentials;
+}
+
+async function createHarness(seedToken = true): Promise<Harness> {
+  const stub = { calls: [], nextId: 100 };
+  const credentials = new InMemoryCredentials();
+  await credentials.put(connection, "client_id", "stub-client-id");
+  await credentials.put(connection, "client_secret", "stub-client-secret");
+  await credentials.put(connection, "ig_user_id", IG_USER_ID);
+  if (seedToken) await credentials.put(connection, "access_token", LONG_TOKEN);
+  const connector = createInstagramConnector({
+    fetchImpl: stubGraph(stub),
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    credentials,
+    env: {},
+  });
+  return { stub, connector, credentials };
+}
+
+const leg1: InstagramAuthorizationRequest = {
+  redirectUri: REDIRECT,
+  workspaceId: "ws-1",
+  state: "csrf-1",
+  // App credentials arrive as connection fields on the connect form.
+  fields: { clientId: "stub-client-id", clientSecret: "stub-client-secret" },
+};
+
+const post = (text: string, mediaAssetIds: string[] = [], providerMetadata: Record<string, unknown> = {}): NormalizedPost => ({
+  text,
+  mediaAssetIds,
+  visibility: "public",
+  providerMetadata,
+});
+
+const asset = (assetId: string) => ({
+  id: assetId,
+  workspaceId: "ws-1",
+  storageKey: `https://cdn.example.com/${assetId}.jpg`,
+  mimeType: "image/jpeg",
+  sizeBytes: 12_345,
+  createdAt: new Date("2026-10-01T00:00:00.000Z"),
+});
+
+connectorContractTests((await createHarness()).connector, { connection });
+
+describe("instagram connector: manifest", () => {
+  it("declares the scoped capability set", async () => {
+    const { connector } = await createHarness();
+    const caps = connector.manifest().capabilities;
+    // Declared only because the SDK couples `publish` to it; text-only posts throw.
+    expect(caps.publishText).toBe(true);
+    expect(caps.publishImages).toBe(true);
+    expect(caps.publishCarousel).toBe(true);
+    expect(caps.deletePublication).toBe(true);
+    expect(caps.nativeScheduling).toBe(false);
+    expect(caps.analytics).toBe(false);
+  });
+
+  it("oauth points at the Facebook Login dialog with the IG scopes", async () => {
+    const { connector } = await createHarness();
+    const oauth = connector.manifest().oauth;
+    expect(oauth?.authorizeUrlTemplate).toBe(DIALOG);
+    expect(oauth?.scopes).toEqual(["instagram_basic", "instagram_content_publish", "pages_show_list"]);
+  });
+});
+
+describe("instagram connector: authorize + identity", () => {
+  it("leg 1 redirects to the Facebook dialog with the three scopes", async () => {
+    const { stub, connector, credentials } = await createHarness(false);
+    const error = await connector.authorize(leg1).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(error).toBeInstanceOf(AuthorizationRedirectRequired);
+    const redirect = error as AuthorizationRedirectRequired;
+    expect(redirect.authorizationUrl.startsWith(DIALOG)).toBe(true);
+    const dialog = new URL(redirect.authorizationUrl);
+    expect(dialog.searchParams.get("client_id")).toBe("stub-client-id");
+    expect(dialog.searchParams.get("redirect_uri")).toBe(REDIRECT);
+    expect(dialog.searchParams.get("response_type")).toBe("code");
+    expect(dialog.searchParams.get("scope")).toBe("instagram_basic,instagram_content_publish,pages_show_list");
+    expect(dialog.searchParams.get("state")).toBe("csrf-1");
+    expect(redirect.connectionId).toBe("instagram:ws-1");
+    // App credentials persist for leg 2.
+    expect(await credentials.getSecret({ ...connection, id: redirect.connectionId }, "client_id")).toBe("stub-client-id");
+    expect(await credentials.getSecret({ ...connection, id: redirect.connectionId }, "client_secret")).toBe("stub-client-secret");
+    expect(stub.calls.filter((c) => pathOf(c) === "/oauth/access_token")).toHaveLength(0);
+  });
+
+  it("leg 2 exchanges the code, upgrades to a long-lived token and resolves the IG business account", async () => {
+    const { stub, connector, credentials } = await createHarness(false);
+    await expect(connector.authorize(leg1)).rejects.toBeInstanceOf(AuthorizationRedirectRequired);
+
+    const leg2: InstagramAuthorizationRequest = { workspaceId: leg1.workspaceId, redirectUri: leg1.redirectUri, state: leg1.state, providerMetadata: { code: "good-code" } };
+    const result = await connector.authorize(leg2);
+
+    const exchanges = stub.calls.filter((c) => pathOf(c) === "/oauth/access_token");
+    expect(exchanges).toHaveLength(2);
+    const first = queryOf(exchanges[0]);
+    expect(first.get("code")).toBe("good-code");
+    expect(first.get("client_id")).toBe("stub-client-id");
+    expect(first.get("redirect_uri")).toBe(REDIRECT);
+    const upgrade = queryOf(exchanges[1]);
+    expect(upgrade.get("grant_type")).toBe("fb_exchange_token");
+    expect(upgrade.get("fb_exchange_token")).toBe(SHORT_TOKEN);
+
+    const accounts = stub.calls.find((c) => pathOf(c) === "/me/accounts");
+    expect(accounts).toBeDefined();
+    expect(queryOf(accounts).get("fields")).toContain("instagram_business_account");
+
+    expect(result.identity).toEqual({
+      provider: "instagram",
+      remoteId: IG_USER_ID,
+      handle: `@${IG_USERNAME}`,
+      displayName: "AnarchoPoster",
+    });
+    expect(result.connection.fields.igUserId).toBe(IG_USER_ID);
+    expect(await credentials.getSecret(result.connection, "access_token")).toBe(LONG_TOKEN);
+    expect(await credentials.getSecret(result.connection, "ig_user_id")).toBe(IG_USER_ID);
+    expect(await connector.getIdentity(result.connection)).toEqual(result.identity);
+  });
+
+  it("rejects a bad code with the Graph message", async () => {
+    const { connector } = await createHarness(false);
+    const request: InstagramAuthorizationRequest = {
+      ...leg1,
+      providerMetadata: { code: "bad-code" },
+    };
+    await expect(connector.authorize(request)).rejects.toThrow(/Validation of the provided code failed/);
+  });
+
+  it("fails loudly when no Page carries an instagram_business_account (personal account)", async () => {
+    const fetchImpl: typeof fetch = async (input, init) => {
+      const href = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      const url = new URL(href);
+      url.pathname = url.pathname.replace(/^\/v21\.0/, "");
+      if (url.pathname === "/oauth/access_token") {
+        return json({ access_token: url.searchParams.get("code") ? SHORT_TOKEN : LONG_TOKEN, token_type: "bearer" });
+      }
+      if (url.pathname === "/me") return json({ id: FB_USER_ID });
+      if (url.pathname === "/me/accounts") {
+        return json({ data: [{ id: PAGE_ID, name: "Page without IG" }] });
+      }
+      return graphError("no route", 100, 404);
+    };
+    const credentials = new InMemoryCredentials();
+    await credentials.put(connection, "client_id", "stub-client-id");
+    await credentials.put(connection, "client_secret", "stub-client-secret");
+    const connector = createInstagramConnector({
+      fetchImpl,
+      requestsPerSecond: 1000,
+      sleep: async () => undefined,
+      credentials,
+      env: {},
+    });
+    const request: InstagramAuthorizationRequest = { ...leg1, providerMetadata: { code: "good-code" } };
+    await expect(connector.authorize(request)).rejects.toThrow(/no Instagram professional account is linked/);
+  });
+
+  it("getIdentity re-resolves the stored IG account through /me + /me/accounts", async () => {
+    const { stub, connector } = await createHarness();
+    const identity = await connector.getIdentity(connection);
+    expect(identity).toEqual({
+      provider: "instagram",
+      remoteId: IG_USER_ID,
+      handle: `@${IG_USERNAME}`,
+      displayName: "AnarchoPoster",
+    });
+    const calls = stub.calls.filter((c) => pathOf(c) === "/me/accounts");
+    expect(calls).toHaveLength(1);
+    expect(headerOf(calls[0]?.init, "authorization")).toBe(`Bearer ${LONG_TOKEN}`);
+  });
+});
+
+describe("instagram connector: refreshCredentials", () => {
+  it("refreshes via GET /refresh_access_token with grant_type=ig_refresh_token", async () => {
+    const { stub, connector, credentials } = await createHarness();
+    const credentialId = await connector.refreshCredentials?.(connection);
+    expect(credentialId).toEqual(connection.credentialId);
+    const call = stub.calls.find((c) => pathOf(c) === "/refresh_access_token");
+    expect(call?.method).toBe("GET");
+    expect(queryOf(call).get("grant_type")).toBe("ig_refresh_token");
+    expect(queryOf(call).get("access_token")).toBe(LONG_TOKEN);
+    // fb_exchange_token must NOT be used as a refresh grant.
+    expect(
+      stub.calls.some(
+        (c) =>
+          pathOf(c) === "/oauth/access_token" &&
+          queryOf(c).get("grant_type") === "fb_exchange_token",
+      ),
+    ).toBe(false);
+    expect(await credentials.getSecret(connection, "access_token")).toBe(REFRESHED_TOKEN);
+  });
+
+  it("maps an expired token to AuthError", async () => {
+    const { connector, credentials } = await createHarness();
+    await credentials.put(connection, "access_token", "expired-token");
+    await expect(connector.refreshCredentials?.(connection)).rejects.toMatchObject({
+      name: "AuthError",
+    });
+  });
+});
+
+describe("instagram connector: publish", () => {
+  it("uploads assets through loadAsset and captions the container", async () => {
+    const stub = { calls: [] as StubCall[], nextId: 100 };
+    const credentials = new InMemoryCredentials();
+    await credentials.put(connection, "client_id", "stub-client-id");
+    await credentials.put(connection, "client_secret", "stub-client-secret");
+    await credentials.put(connection, "ig_user_id", IG_USER_ID);
+    await credentials.put(connection, "access_token", LONG_TOKEN);
+    const connector = createInstagramConnector({
+      fetchImpl: stubGraph(stub),
+      requestsPerSecond: 1000,
+      sleep: async () => undefined,
+      credentials,
+      env: {},
+      loadAsset: async (assetId) => asset(assetId),
+      resolveMediaUrl: async (media) => media.storageKey,
+    });
+
+    const publication = await connector.publish?.(
+      connection,
+      post("hello instagram", ["asset-1"]),
+    );
+
+    const container = stub.calls.find((c) => pathOf(c) === `/${IG_USER_ID}/media`);
+    expect(container?.method).toBe("POST");
+    expect(formBody(container?.init).get("image_url")).toBe("https://cdn.example.com/asset-1.jpg");
+    expect(formBody(container?.init).get("caption")).toBe("hello instagram");
+
+    const publish = stub.calls.find((c) => pathOf(c) === `/${IG_USER_ID}/media_publish`);
+    expect(publish?.method).toBe("POST");
+    expect(formBody(publish?.init).get("creation_id")).toMatch(/^container-/);
+
+    expect(publication?.remoteId).toMatch(/^media-/);
+    expect(publication?.remoteUrl).toBe(`https://www.instagram.com/p/${publication?.remoteId}/`);
+    expect(publication?.workspaceId).toBe("ws-1");
+    expect(publication?.connectionId).toBe("conn-instagram");
+    expect(publication?.draftId).toBe("direct");
+    expect(publication?.publishedAt).toEqual(new Date("2026-10-06T12:00:00+0000"));
+    expect(publication?.providerMetadata).toMatchObject({ kind: "image", items: 1 });
+  });
+
+  it("carousel: children containers with is_carousel_item, then a CAROUSEL parent", async () => {
+    const stub = { calls: [] as StubCall[], nextId: 100 };
+    const credentials = new InMemoryCredentials();
+    for (const [key, value] of [
+      ["client_id", "stub-client-id"],
+      ["client_secret", "stub-client-secret"],
+      ["ig_user_id", IG_USER_ID],
+      ["access_token", LONG_TOKEN],
+    ] as const) {
+      await credentials.put(connection, key, value);
+    }
+    const connector = createInstagramConnector({
+      fetchImpl: stubGraph(stub),
+      requestsPerSecond: 1000,
+      sleep: async () => undefined,
+      credentials,
+      env: {},
+      loadAsset: async (assetId) => asset(assetId),
+    });
+
+    const publication = await connector.publish?.(
+      connection,
+      post("three photos", ["a", "b", "c"], { draftId: "draft-7" }),
+    );
+
+    const containers = stub.calls.filter((c) => pathOf(c) === `/${IG_USER_ID}/media`);
+    expect(containers).toHaveLength(4);
+    const forms = containers.map((c) => formBody(c.init));
+    expect(forms[0]?.get("is_carousel_item")).toBe("true");
+    expect(forms[1]?.get("is_carousel_item")).toBe("true");
+    expect(forms[2]?.get("is_carousel_item")).toBe("true");
+    expect(forms[0]?.get("image_url")).toBe("https://cdn.example.com/a.jpg");
+    expect(forms[3]?.get("media_type")).toBe("CAROUSEL");
+    expect(forms[3]?.get("children")).toMatch(/^container-\d+,container-\d+,container-\d+$/);
+    expect(forms[3]?.get("caption")).toBe("three photos");
+
+    const publish = stub.calls.find((c) => pathOf(c) === `/${IG_USER_ID}/media_publish`);
+    // Children are container-101..103 (nextId starts at 100); the parent is next.
+    expect(formBody(publish?.init).get("creation_id")).toBe("container-104");
+    expect(publication?.draftId).toBe("draft-7");
+    expect(publication?.providerMetadata).toMatchObject({ kind: "carousel", items: 3 });
+  });
+
+  it("accepts pre-resolved providerMetadata.media URLs", async () => {
+    const stub = { calls: [] as StubCall[], nextId: 100 };
+    const credentials = new InMemoryCredentials();
+    for (const [key, value] of [
+      ["client_id", "stub-client-id"],
+      ["client_secret", "stub-client-secret"],
+      ["ig_user_id", IG_USER_ID],
+      ["access_token", LONG_TOKEN],
+    ] as const) {
+      await credentials.put(connection, key, value);
+    }
+    const connector = createInstagramConnector({
+      fetchImpl: stubGraph(stub),
+      requestsPerSecond: 1000,
+      sleep: async () => undefined,
+      credentials,
+      env: {},
+    });
+    const publication = await connector.publish?.(
+      connection,
+      post("", [], { media: [{ url: "https://cdn.example.com/presigned.jpg", kind: "image" }] }),
+    );
+    const container = stub.calls.find((c) => pathOf(c) === `/${IG_USER_ID}/media`);
+    expect(formBody(container?.init).get("image_url")).toBe("https://cdn.example.com/presigned.jpg");
+    expect(publication?.providerMetadata).toMatchObject({ kind: "image" });
+  });
+
+  it("throws CapabilityNotSupportedError for a text-only post", async () => {
+    const { stub, connector } = await createHarness();
+    await expect(connector.publish?.(connection, post("no media at all"))).rejects.toMatchObject({
+      name: "CapabilityNotSupportedError",
+    });
+    expect(stub.calls.filter((c) => pathOf(c) === `/${IG_USER_ID}/media`)).toHaveLength(0);
+  });
+
+  it("rejects more than 10 carousel items", async () => {
+    const { connector } = await createHarness();
+    const media = Array.from({ length: 11 }, (_, i) => ({ url: `https://cdn.example.com/${i}.jpg`, kind: "image" as const }));
+    await expect(
+      connector.publish?.(connection, post("too many", [], { media })),
+    ).rejects.toThrow(/at most 10 carousel items/);
+  });
+
+  it("rejects non-JPEG assets", async () => {
+    const { connector } = await createHarness();
+    (connector as unknown as { options?: unknown });
+    await expect(
+      connector.publish?.(connection, post("png", ["asset-png"], {
+        media: [],
+      })),
+    ).rejects.toThrow();
+  });
+
+  it("maps an expired token on publish to AuthError", async () => {
+    const { connector, credentials } = await createHarness();
+    await credentials.put(connection, "access_token", "revoked");
+    await expect(
+      connector.publish?.(connection, post("x", [], { media: [{ url: "https://cdn.example.com/a.jpg", kind: "image" }] })),
+    ).rejects.toMatchObject({ name: "AuthError" });
+  });
+});
+
+describe("instagram connector: deletePublication", () => {
+  it("DELETEs the media node", async () => {
+    const { stub, connector } = await createHarness();
+    await connector.deletePublication?.(connection, "media-101");
+    const call = stub.calls.find((c) => c.method === "DELETE");
+    expect(call?.url.pathname).toBe("/v21.0/media-101");
+    expect(headerOf(call?.init, "authorization")).toBe(`Bearer ${LONG_TOKEN}`);
+  });
+
+  it("treats 404 as already deleted (idempotent)", async () => {
+    const fetchImpl: typeof fetch = async (input, init) => {
+      const href = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+      const url = new URL(href);
+      stub404Calls.push({ method: (init?.method ?? "GET").toUpperCase(), url, init });
+      if ((init?.method ?? "GET").toUpperCase() === "DELETE") {
+        return graphError("The media was not found", 100, 404);
+      }
+      return graphError("no route", 100, 404);
+    };
+    const stub404Calls: StubCall[] = [];
+    const credentials = new InMemoryCredentials();
+    for (const [key, value] of [
+      ["client_id", "stub-client-id"],
+      ["client_secret", "stub-client-secret"],
+      ["ig_user_id", IG_USER_ID],
+      ["access_token", LONG_TOKEN],
+    ] as const) {
+      await credentials.put(connection, key, value);
+    }
+    const connector = createInstagramConnector({
+      fetchImpl,
+      requestsPerSecond: 1000,
+      sleep: async () => undefined,
+      credentials,
+      env: {},
+    });
+    await expect(connector.deletePublication?.(connection, "media-gone")).resolves.toBeUndefined();
+  });
+});
+
+describe("instagram connector: caption rules", () => {
+  it("accepts a normal caption", () => {
+    expect(() => assertCaption("hello #world")).not.toThrow();
+  });
+
+  it("rejects captions over 2200 characters", () => {
+    expect(() => assertCaption("x".repeat(2201))).toThrow(/caption exceeds 2200 characters/);
+  });
+
+  it("rejects more than 30 hashtags", () => {
+    const caption = Array.from({ length: 31 }, (_, i) => `#tag${i}`).join(" ");
+    expect(() => assertCaption(caption)).toThrow(/more than 30 hashtags/);
+  });
+});
diff --git a/packages/connector-instagram/src/index.ts b/packages/connector-instagram/src/index.ts
new file mode 100644
index 0000000..c4144b9
--- /dev/null
+++ b/packages/connector-instagram/src/index.ts
@@ -0,0 +1,726 @@
+/**
+ * Instagram connector — Instagram Graph API via Facebook Login.
+ *
+ * Connect flow (two authorization legs, mirroring the Mastodon connector):
+ * leg 1 builds the Facebook Login dialog URL
+ * (https://www.facebook.com/v21.0/dialog/oauth, scopes instagram_basic,
+ * instagram_content_publish, pages_show_list) and throws
+ * AuthorizationRedirectRequired; leg 2 exchanges the code at
+ * graph.facebook.com/v21.0/oauth/access_token for a short-lived user token,
+ * immediately exchanges it (grant_type=fb_exchange_token) for a long-lived
+ * (~60 day) token, then resolves the Instagram professional account through
+ * GET /me + GET /me/accounts (instagram_business_account). Stored credential
+ * keys: access_token, ig_user_id, client_id, client_secret.
+ *
+ * Honest capability notes (verified against the Graph API):
+ * - Instagram has no text-only posts. publishText is declared only because
+ *   the SDK couples `publish` to it; a post without media throws
+ *   CapabilityNotSupportedError. The caption (≤ 2200 chars, ≤ 30 hashtags)
+ *   rides the media container.
+ * - Publishing is two-step and URL-backed: POST /{ig-user-id}/media builds a
+ *   container from a publicly fetchable https image_url (JPEG only), then
+ *   POST /{ig-user-id}/media_publish {creation_id} publishes it. There is no
+ *   binary upload. 2–10 images become carousel children containers plus a
+ *   CAROUSEL parent.
+ * - Only professional (business/creator) accounts linked to a Facebook Page
+ *   are addressable; personal accounts are invisible to the API and connect
+ *   fails if no Page carries an instagram_business_account.
+ * - Token refresh: fb_exchange_token is not a valid refresh grant for IG
+ *   tokens, so refreshCredentials uses GET /refresh_access_token with
+ *   grant_type=ig_refresh_token.
+ * - Deletion: DELETE /{ig-media-id} works only for media the app published;
+ *   a 404 (already gone) counts as deleted.
+ * - nativeScheduling false (the API has no scheduled media publish),
+ *   analytics false (no insights surface in this connector), no feed,
+ *   comments, DMs, webhooks or amplify.
+ *
+ * Rate limits: 25 API-published posts per rolling 24h per account plus
+ * Graph BUC budgets; the SDK client runs at 0.5 requests/s per host. The
+ * publishing scopes require Meta App Review before non-role accounts connect.
+ */
+import { randomUUID } from "node:crypto";
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  CredentialRef,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  Publication,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  InMemoryCredentials,
+  RateLimitedHttpClient,
+  RateLimitError,
+  type AuthorizationRequest,
+  type AuthorizationResult,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "instagram";
+const DEFAULT_API_VERSION = "v21.0";
+const CAPTION_LIMIT = 2200;
+const HASHTAG_LIMIT = 30;
+const CAROUSEL_MAX = 10;
+/** API-published posts per rolling 24h per account (Meta-enforced). */
+const PUBLISH_QUOTA = 25;
+const SCOPES = ["instagram_basic", "instagram_content_publish", "pages_show_list"];
+const PAGE_FIELDS = "id,name,instagram_business_account{id,username,name}";
+const MEDIA_FIELDS = "id,permalink,timestamp,media_type";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  // Declared only because the SDK couples `publish` to publishText; text-only
+  // posts throw CapabilityNotSupportedError (see header).
+  publishText: true,
+  publishImages: true,
+  publishCarousel: true,
+  publishVideo: false,
+  feed: false,
+  mentions: false,
+  comments: false,
+  replies: false,
+  amplifyRepost: false,
+  amplifyQuote: false,
+  amplifyShare: false,
+  directMessages: false,
+  nativeScheduling: false,
+  deletePublication: true,
+  webhooks: false,
+  reactions: false,
+  analytics: false,
+};
+
+/** Credential keys stored per connection through the CredentialAccessor. */
+const SECRET = {
+  accessToken: "access_token",
+  igUserId: "ig_user_id",
+  clientId: "client_id",
+  clientSecret: "client_secret",
+} as const;
+
+export interface InstagramConnectorOptions {
+  /** fetch override for tests (same pattern as the other connectors). */
+  fetchImpl?: typeof fetch;
+  /** Requests per second per API host. Default 0.5; tests raise it. */
+  requestsPerSecond?: number;
+  /** Sleep override for the rate limiter (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Secret store. Default: in-memory (dev + contract tests). */
+  credentials?: CredentialAccessor;
+  /** Graph API version path segment. Default v21.0. */
+  apiVersion?: string;
+  /** Facebook app credentials fallback when not supplied per connection. */
+  env?: Record<string, string | undefined>;
+  /** Resolve a media asset id to its metadata (needed by publish with media). */
+  loadAsset?: (assetId: string) => Promise<MediaAsset>;
+  /**
+   * Publicly fetchable https URL for an asset (e.g. presigned S3 GET). Meta's
+   * servers download the bytes from it while building the container. Default:
+   * the asset's storageKey must already be an absolute http(s) URL.
+   */
+  resolveMediaUrl?: (media: MediaAsset) => Promise<string>;
+}
+
+/** The SDK's AuthorizationRequest carries no provider input, so the second
+ * leg (code exchange) travels in this optional field. */
+export interface InstagramAuthorizationRequest extends AuthorizationRequest {
+  fields?: Record<string, string>;
+  providerMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Thrown by the first authorize leg. AuthorizationResult has no slot for a
+ * redirect, so the dialog URL rides on this error; callers send the user
+ * there and call authorize again with providerMetadata.code.
+ */
+export class AuthorizationRedirectRequired extends ConnectorError {
+  constructor(
+    readonly authorizationUrl: string,
+    readonly connectionId: string,
+  ) {
+    super("redirect the user to Facebook to authorize", PROVIDER);
+    this.name = "AuthorizationRedirectRequired";
+  }
+}
+
+interface GraphErrorBody {
+  error?: {
+    message?: string;
+    type?: string;
+    code?: number;
+    error_subcode?: number;
+    error_user_msg?: string;
+  };
+}
+
+interface GraphList<T> {
+  data: T[];
+}
+
+interface GraphIdResponse {
+  id?: string;
+  success?: boolean;
+}
+
+interface FacebookUser {
+  id: string;
+  name?: string;
+}
+
+/** A Facebook Page with (optionally) its linked Instagram professional account. */
+interface FacebookPage {
+  id: string;
+  name?: string;
+  instagram_business_account?: {
+    id: string;
+    username?: string;
+    name?: string;
+  };
+}
+
+interface IgMedia {
+  id: string;
+  permalink?: string;
+  timestamp?: string;
+  media_type?: string;
+}
+
+interface IgToken {
+  access_token?: string;
+  token_type?: string;
+  expires_in?: number;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Instagram accepts JPEG images only for image_url containers. */
+function assertJpeg(mimeType: string): void {
+  const normalized = mimeType.toLowerCase();
+  if (normalized === "image/jpeg" || normalized === "image/jpg") return;
+  throw new ConnectorError(
+    `${PROVIDER}: unsupported media type ${mimeType} — Instagram image containers accept JPEG only`,
+    PROVIDER,
+  );
+}
+
+/** Captions ride the media container; Instagram caps length and hashtags. */
+export function assertCaption(caption: string): void {
+  if ([...caption].length > CAPTION_LIMIT) {
+    throw new ConnectorError(`${PROVIDER}: caption exceeds ${CAPTION_LIMIT} characters`, PROVIDER);
+  }
+  const hashtags = caption.match(/(^|\s)#[\p{L}\p{N}_]+/gu) ?? [];
+  if (hashtags.length > HASHTAG_LIMIT) {
+    throw new ConnectorError(`${PROVIDER}: caption has more than ${HASHTAG_LIMIT} hashtags`, PROVIDER);
+  }
+}
+
+function parseJson(text: string): unknown {
+  if (text.length === 0) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch (cause) {
+    throw new ConnectorError(`${PROVIDER}: Graph API returned non-JSON`, PROVIDER, cause);
+  }
+}
+
+function statusOf(error: unknown): number | undefined {
+  return error instanceof ConnectorError ? (error.cause as { status?: number } | undefined)?.status : undefined;
+}
+
+/** Asset storageKey as public URL — presign via resolveMediaUrl otherwise. */
+function publicAssetUrl(media: MediaAsset): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(media.storageKey);
+  } catch (cause) {
+    throw new ConnectorError(
+      `${PROVIDER}: URL-based publish needs an absolute public https image_url (got storageKey "${media.storageKey}") — pass resolveMediaUrl to presign`,
+      PROVIDER,
+      cause,
+    );
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new ConnectorError(`${PROVIDER}: image_url must be http(s), got ${parsed.protocol}`, PROVIDER);
+  }
+  return parsed.href;
+}
+
+export function createInstagramConnector(options: InstagramConnectorOptions = {}): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: options.requestsPerSecond ?? 0.5,
+    fetchImpl: options.fetchImpl,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  const env = options.env ?? {};
+  const apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+  const dialogBase = `https://www.facebook.com/${apiVersion}`;
+  const graphBase = `https://graph.facebook.com/${apiVersion}`;
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Instagram",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "clientId",
+        label: "Facebook app ID (or INSTAGRAM_CLIENT_ID env)",
+        required: false,
+        secret: false,
+      },
+      {
+        name: "clientSecret",
+        label: "Facebook app secret (or INSTAGRAM_CLIENT_SECRET env)",
+        required: false,
+        secret: true,
+      },
+      {
+        name: "igUserId",
+        label: "Instagram professional account id (optional — resolved at connect)",
+        required: false,
+        secret: false,
+        pattern: "^[0-9]+$",
+        placeholder: "17841400000000000",
+      },
+    ],
+    oauth: {
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: `${dialogBase}/dialog/oauth`,
+      scopes: SCOPES,
+      pkce: false,
+    },
+    docsUrl: "https://developers.facebook.com/docs/instagram-platform/content-publishing",
+  };
+
+  function igUserIdOf(connection: ConnectorConnection): string {
+    return str(connection.fields.igUserId) ?? `vault:${connection.id}`;
+  }
+
+  /** Vault first; the connection field is the dev/test fallback. */
+  async function tokenOf(connection: ConnectorConnection): Promise<string> {
+    try {
+      return await credentials.getAccessToken(connection);
+    } catch {
+      const field = str(connection.fields.accessToken);
+      if (field !== undefined) return field;
+      throw new AuthError(`${PROVIDER}: no access token for connection ${connection.id}`, PROVIDER, false);
+    }
+  }
+
+  async function storedIgUserId(connection: ConnectorConnection): Promise<string> {
+    try {
+      return await credentials.getSecret(connection, SECRET.igUserId);
+    } catch {
+      const field = str(connection.fields.igUserId);
+      if (field !== undefined) return field;
+      throw new ConnectorError(`${PROVIDER}: connection ${connection.id} has no ig_user_id`, PROVIDER);
+    }
+  }
+
+  async function secretOrUndefined(connection: ConnectorConnection, key: string): Promise<string | undefined> {
+    try {
+      return await credentials.getSecret(connection, key);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Facebook app credentials: vault first, then connection fields, then env. */
+  void secretOrUndefined;
+  async function clientCredentials(
+    connection: ConnectorConnection,
+  ): Promise<{ clientId: string; clientSecret: string }> {
+    const clientId =
+      (await secretOrUndefined(connection, SECRET.clientId)) ??
+      str(connection.fields.clientId) ??
+      str(env.INSTAGRAM_CLIENT_ID);
+    const clientSecret =
+      (await secretOrUndefined(connection, SECRET.clientSecret)) ??
+      str(connection.fields.clientSecret) ??
+      str(env.INSTAGRAM_CLIENT_SECRET);
+    if (clientId === undefined || clientSecret === undefined) {
+      throw new ConnectorError(
+        `${PROVIDER}: no Facebook app credentials — set fields.clientId/clientSecret or INSTAGRAM_CLIENT_ID/INSTAGRAM_CLIENT_SECRET`,
+        PROVIDER,
+      );
+    }
+    return { clientId, clientSecret };
+  }
+
+  /** Graph errors → SDK taxonomy. Meta reports throttling as 4xx with codes. */
+  function graphError(response: Response, method: string, url: URL, body: unknown): Error {
+    const error = (body as GraphErrorBody).error ?? {};
+    const detail = error.error_user_msg ?? error.message ?? "Graph API request failed";
+    const message = `HTTP ${response.status} ${method} ${url.pathname}: ${detail}`;
+    const code = error.code;
+    // 4/17/32/613: app/user/page/custom throttles; 9: publish quota.
+    if (code === 4 || code === 17 || code === 32 || code === 613 || code === 9) {
+      return new RateLimitError(PROVIDER);
+    }
+    if (code === 190 || response.status === 401) return new AuthError(message, PROVIDER, false);
+    if (code === 10 || (code !== undefined && code >= 200 && code < 300)) {
+      return new AuthError(`${message} (permission missing — App Review scope?)`, PROVIDER, false);
+    }
+    return new ConnectorError(message, PROVIDER, { status: response.status, code });
+  }
+
+  async function graph<T>(
+    connection: ConnectorConnection,
+    method: "GET" | "POST" | "DELETE",
+    path: string,
+    params: Record<string, string> = {},
+  ): Promise<T> {
+    const url = new URL(`${graphBase}${path}`);
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      authorization: `Bearer ${await tokenOf(connection)}`,
+    };
+    const init: RequestInit = { method, headers };
+    if (method === "POST") {
+      headers["content-type"] = "application/x-www-form-urlencoded";
+      init.body = new URLSearchParams(params).toString();
+    } else {
+      for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+    }
+    const response = await client.request(PROVIDER, url.href, init);
+    const body = parseJson(await response.text());
+    if (!response.ok) throw graphError(response, method, url, body);
+    return body as T;
+  }
+
+  /** App-level (pre-connection) GET on the OAuth token endpoint. */
+  async function tokenRequest<T>(params: Record<string, string>): Promise<T> {
+    const url = new URL(`${graphBase}/oauth/access_token`);
+    for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+    const response = await client.request(PROVIDER, url.href, { headers: { accept: "application/json" } });
+    const body = parseJson(await response.text());
+    if (!response.ok) throw graphError(response, "GET", url, body);
+    return body as T;
+  }
+
+  /**
+   * GET /me validates the token (it is the Facebook user under Facebook
+   * Login), then GET /me/accounts resolves the first Page carrying an
+   * instagram_business_account — the IG professional account to publish as.
+   */
+  async function fetchIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+    const me = await graph<FacebookUser>(connection, "GET", "/me", { fields: "id,name" });
+    const { data } = await graph<GraphList<FacebookPage>>(connection, "GET", "/me/accounts", {
+      fields: PAGE_FIELDS,
+    });
+    const linked = data.find((page) => page.instagram_business_account !== undefined)
+      ?.instagram_business_account;
+    if (linked === undefined) {
+      throw new ConnectorError(
+        `${PROVIDER}: no Instagram professional account is linked to any Page of Facebook user ${me.id} — convert the account to business/creator and link a Page`,
+        PROVIDER,
+      );
+    }
+    const username = linked.username ?? linked.id;
+    const identity: NormalizedIdentity = {
+      provider: PROVIDER,
+      remoteId: linked.id,
+      handle: `@${username}`,
+    };
+    if (linked.name !== undefined) identity.displayName = linked.name;
+    return identity;
+  }
+
+  /** providerMetadata.media: pre-resolved public https URLs (e.g. presigned). */
+  function preResolved(meta: Record<string, unknown>): string[] {
+    if (!Array.isArray(meta.media)) return [];
+    return (meta.media as unknown[])
+      .map((entry) => (typeof entry === "object" && entry !== null ? str((entry as Record<string, unknown>)["url"]) : undefined))
+      .filter((url): url is string => url !== undefined);
+  }
+
+  async function resolveAsset(assetId: string): Promise<string> {
+    if (options.loadAsset === undefined) {
+      throw new ConnectorError(`${PROVIDER}: publishing mediaAssetIds needs a loadAsset option`, PROVIDER);
+    }
+    const asset = await options.loadAsset(assetId);
+    assertJpeg(asset.mimeType);
+    return options.resolveMediaUrl !== undefined
+      ? await options.resolveMediaUrl(asset)
+      : publicAssetUrl(asset);
+  }
+
+  async function createContainer(connection: ConnectorConnection, params: Record<string, string>): Promise<string> {
+    const result = await graph<GraphIdResponse>(
+      connection,
+      "POST",
+      `/${await storedIgUserId(connection)}/media`,
+      params,
+    );
+    if (result.id === undefined) {
+      throw new ConnectorError(`${PROVIDER}: media container creation returned no id`, PROVIDER);
+    }
+    return result.id;
+  }
+
+  async function publishContainer(
+    connection: ConnectorConnection,
+    creationId: string,
+    draftId: string,
+    providerMetadata: Record<string, unknown>,
+  ): Promise<Publication> {
+    const user = await storedIgUserId(connection);
+    const published = await graph<GraphIdResponse>(
+      connection,
+      "POST",
+      `/${user}/media_publish`,
+      { creation_id: creationId },
+    );
+    if (published.id === undefined) {
+      throw new ConnectorError(`${PROVIDER}: media_publish returned no media id`, PROVIDER);
+    }
+    const media = await graph<IgMedia>(connection, "GET", `/${encodeURIComponent(published.id)}`, {
+      fields: MEDIA_FIELDS,
+    });
+    const publication: Publication = {
+      id: randomUUID(),
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId: published.id,
+      publishedAt: media.timestamp !== undefined ? new Date(media.timestamp) : new Date(),
+      providerMetadata: { creationId, mediaType: media.media_type, publishQuota: PUBLISH_QUOTA, ...providerMetadata },
+    };
+    if (media.permalink !== undefined) publication.remoteUrl = media.permalink;
+    return publication;
+  }
+
+  const connector: PlatformConnector = {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async buildAuthorizationUrl(input: InstagramAuthorizationRequest) {
+      try {
+        await connector.authorize(input);
+        throw new ConnectorError("authorization redirect missing", PROVIDER);
+      } catch (error) {
+        if (!(error instanceof AuthorizationRedirectRequired)) throw error;
+        const connection: ConnectorConnection = {
+          id: error.connectionId,
+          workspaceId: input.workspaceId,
+          provider: PROVIDER,
+          channelId: error.connectionId,
+          credentialId: { kind: "credential-ref", id: error.connectionId },
+          fields: input.fields?.clientId !== undefined ? { clientId: input.fields.clientId } : {},
+          createdAt: new Date(),
+        };
+        return { authorizationUrl: error.authorizationUrl, connection };
+      }
+    },
+
+    async exchangeCode(input: CodeExchangeRequest): Promise<AuthorizationResult> {
+      return connector.authorize({
+        ...input,
+        providerMetadata: { code: input.code },
+      } as InstagramAuthorizationRequest);
+    },
+
+    /**
+     * Leg 1 (no code): validate app credentials, store them in the vault and
+     * throw AuthorizationRedirectRequired with the Facebook dialog URL.
+     * Leg 2 (providerMetadata.code): code → short-lived token → long-lived
+     * token (fb_exchange_token) → resolve the IG professional account via
+     * /me + /me/accounts and store access_token + ig_user_id.
+     */
+    async authorize(input: InstagramAuthorizationRequest): Promise<AuthorizationResult> {
+      const meta = input.providerMetadata ?? {};
+      const code = str(meta.code);
+      const connectionId = str(input.connectionId) ?? str(meta.connectionId) ?? `${PROVIDER}:${input.workspaceId}`;
+      const credentialId: CredentialRef = { kind: "credential-ref", id: connectionId };
+      const provided: Record<string, string> = {};
+      const fieldClientId = str(input.fields?.clientId);
+      const fieldClientSecret = str(input.fields?.clientSecret);
+      if (fieldClientId !== undefined) provided.clientId = fieldClientId;
+      if (fieldClientSecret !== undefined) provided.clientSecret = fieldClientSecret;
+      const connection: ConnectorConnection = {
+        id: connectionId,
+        workspaceId: input.workspaceId,
+        provider: PROVIDER,
+        channelId: str(meta.channelId) ?? connectionId,
+        credentialId,
+        fields: { ...provided },
+        createdAt: new Date(),
+      };
+
+      const client = await clientCredentials({ ...connection, fields: provided });
+      await credentials.put(connection, SECRET.clientId, client.clientId);
+      await credentials.put(connection, SECRET.clientSecret, client.clientSecret);
+
+      if (code === undefined) {
+        const url = new URL(`${dialogBase}/dialog/oauth`);
+        url.searchParams.set("client_id", client.clientId);
+        url.searchParams.set("redirect_uri", input.redirectUri);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("scope", SCOPES.join(","));
+        url.searchParams.set("state", input.state);
+        throw new AuthorizationRedirectRequired(url.toString(), connectionId);
+      }
+
+      const shortLived = await tokenRequest<IgToken>({
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        redirect_uri: input.redirectUri,
+        code,
+      });
+      if (shortLived.access_token === undefined) {
+        throw new ConnectorError(`${PROVIDER}: code exchange returned no access token`, PROVIDER);
+      }
+      // fb_exchange_token upgrades the short-lived token to ~60 days; it is
+      // NOT usable later as a refresh grant for IG tokens (see refreshCredentials).
+      const longLived = await tokenRequest<IgToken>({
+        grant_type: "fb_exchange_token",
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        fb_exchange_token: shortLived.access_token,
+      });
+      if (longLived.access_token === undefined) {
+        throw new ConnectorError(`${PROVIDER}: long-lived token exchange returned no access token`, PROVIDER);
+      }
+      await credentials.put(connection, SECRET.accessToken, longLived.access_token);
+
+      const identity = await fetchIdentity(connection);
+      await credentials.put(connection, SECRET.igUserId, identity.remoteId);
+      connection.fields.igUserId = identity.remoteId;
+      return { connection, identity };
+    },
+
+    /**
+     * IG tokens cannot be refreshed with grant_type=fb_exchange_token (that
+     * grant only upgrades a short-lived token and is refused for IG-scoped
+     * tokens), so the documented refresh is
+     * GET /refresh_access_token?grant_type=ig_refresh_token.
+     */
+    async refreshCredentials(connection: ConnectorConnection): Promise<CredentialRef> {
+      const url = new URL(`${graphBase}/refresh_access_token`);
+      url.searchParams.set("grant_type", "ig_refresh_token");
+      url.searchParams.set("access_token", await tokenOf(connection));
+      const response = await client.request(PROVIDER, url.href, { headers: { accept: "application/json" } });
+      const body = parseJson(await response.text());
+      if (!response.ok) throw graphError(response, "GET", url, body);
+      const refreshed = body as IgToken;
+      if (refreshed.access_token === undefined) {
+        throw new AuthError(`${PROVIDER}: token refresh returned no access token`, PROVIDER, false);
+      }
+      await credentials.put(connection, SECRET.accessToken, refreshed.access_token);
+      return connection.credentialId;
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      if (str(connection.fields.igUserId) === undefined && (await secretOrUndefined(connection, SECRET.igUserId)) === undefined) {
+        return fetchIdentity(connection);
+      }
+      // Known account id: confirm the token still reaches it via /me/accounts.
+      const me = await graph<FacebookUser>(connection, "GET", "/me", { fields: "id,name" });
+      const { data } = await graph<GraphList<FacebookPage>>(connection, "GET", "/me/accounts", {
+        fields: PAGE_FIELDS,
+      });
+      const igUserId = await storedIgUserId(connection);
+      const linked = data
+        .map((page) => page.instagram_business_account)
+        .find((account) => account !== undefined && account.id === igUserId);
+      if (linked === undefined) {
+        throw new ConnectorError(
+          `${PROVIDER}: Instagram account ${igUserId} is no longer reachable through the Pages of Facebook user ${me.id}`,
+          PROVIDER,
+        );
+      }
+      const identity: NormalizedIdentity = {
+        provider: PROVIDER,
+        remoteId: linked.id,
+        handle: `@${linked.username ?? linked.id}`,
+      };
+      if (linked.name !== undefined) identity.displayName = linked.name;
+      return identity;
+    },
+
+    /**
+     * Images only: one image → IMAGE container; 2–10 → carousel children
+     * containers plus a CAROUSEL parent; then /media_publish. The caption
+     * rides the (parent) container. providerMetadata.media supplies
+     * pre-resolved URLs; mediaAssetIds go through loadAsset + resolveMediaUrl.
+     */
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const meta = post.providerMetadata;
+      if (mediaLength(post, meta) === 0) {
+        throw new CapabilityNotSupportedError(
+          PROVIDER,
+          "publishText (Instagram has no text-only posts — attach at least one image)",
+        );
+      }
+      const urls = [...preResolved(meta)];
+      for (const assetId of post.mediaAssetIds) urls.push(await resolveAsset(assetId));
+      if (urls.length > CAROUSEL_MAX) {
+        throw new ConnectorError(`${PROVIDER}: at most ${CAROUSEL_MAX} carousel items`, PROVIDER);
+      }
+      if (post.text.length > 0) assertCaption(post.text);
+      const draftId = str(meta.draftId) ?? "direct";
+
+      let creationId: string;
+      if (urls.length === 1) {
+        const params: Record<string, string> = { image_url: urls[0] as string };
+        if (post.text.length > 0) params.caption = post.text;
+        creationId = await createContainer(connection, params);
+      } else {
+        const children: string[] = [];
+        for (const url of urls) {
+          children.push(await createContainer(connection, { image_url: url, is_carousel_item: "true" }));
+        }
+        const parentParams: Record<string, string> = { media_type: "CAROUSEL", children: children.join(",") };
+        if (post.text.length > 0) parentParams.caption = post.text;
+        creationId = await createContainer(connection, parentParams);
+      }
+      return publishContainer(connection, creationId, draftId, {
+        kind: urls.length === 1 ? "image" : "carousel",
+        items: urls.length,
+      });
+    },
+
+    /** DELETE /{ig-media-id}; only app-published media is deletable. 404 → gone. */
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      try {
+        await graph(connection, "DELETE", `/${encodeURIComponent(remoteId)}`);
+      } catch (error) {
+        // Already gone counts as deleted — deletion is idempotent.
+        if (statusOf(error) !== 404) throw error;
+      }
+    },
+
+    /** No binary upload exists — return the public URL the container would use. */
+    async uploadMedia(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMediaShape> {
+      assertJpeg(media.mimeType);
+      const url = options.resolveMediaUrl !== undefined
+        ? await options.resolveMediaUrl(media)
+        : publicAssetUrl(media);
+      const containerId = await createContainer(connection, { image_url: url });
+      const remote: RemoteMediaShape = { remoteId: containerId, url, mimeType: media.mimeType };
+      if (media.width !== undefined) remote.width = media.width;
+      if (media.height !== undefined) remote.height = media.height;
+      return remote;
+    },
+  };
+  return connector;
+}
+
+/** Publishing needs at least one media item — count both sources cheaply. */
+function mediaLength(post: NormalizedPost, meta: Record<string, unknown>): number {
+  const pre = Array.isArray(meta.media) ? (meta.media as unknown[]).length : 0;
+  return pre + post.mediaAssetIds.length;
+}
+
+type RemoteMediaShape = import("@tactical-media-broadcast-hub/core").RemoteMedia;
+type CodeExchangeRequest = import("@tactical-media-broadcast-hub/connector-sdk").CodeExchangeRequest;
diff --git a/packages/connector-instagram/tsconfig.json b/packages/connector-instagram/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-instagram/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-linkedin/package.json b/packages/connector-linkedin/package.json
new file mode 100644
index 0000000..f318072
--- /dev/null
+++ b/packages/connector-linkedin/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-linkedin",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-linkedin/src/contract.test.ts b/packages/connector-linkedin/src/contract.test.ts
new file mode 100644
index 0000000..d2636c3
--- /dev/null
+++ b/packages/connector-linkedin/src/contract.test.ts
@@ -0,0 +1,345 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, MediaAsset, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createLinkedInConnector } from "./index.js";
+
+const TOKEN = "linkedin-access-token";
+const MEMBER_URN = "urn:li:person:member123";
+const ORGANIZATION_URN = "urn:li:organization:987654";
+
+const connection: ConnectorConnection = {
+  id: "conn-linkedin",
+  workspaceId: "ws-1",
+  provider: "linkedin",
+  channelId: MEMBER_URN,
+  credentialId: { kind: "credential-ref", id: "cred-linkedin" },
+  fields: { accessToken: TOKEN, memberUrn: MEMBER_URN },
+  createdAt: new Date(),
+};
+
+interface StubCall {
+  url: URL;
+  method: string;
+  headers: Headers;
+  body?: Record<string, unknown>;
+}
+
+interface StubPost {
+  urn: string;
+  body: Record<string, unknown>;
+}
+
+interface StubState {
+  calls: StubCall[];
+  posts: StubPost[];
+  nextPost: number;
+  nextComment: number;
+  uploadedBytes: number;
+}
+
+function response(body: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(body === undefined ? null : JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+  });
+}
+
+function requestUrl(input: Parameters<typeof fetch>[0]): URL {
+  if (typeof input === "string") return new URL(input);
+  if (input instanceof URL) return input;
+  return new URL(input.url);
+}
+
+function requestBody(init: RequestInit | undefined): Record<string, unknown> | undefined {
+  return typeof init?.body === "string"
+    ? JSON.parse(init.body) as Record<string, unknown>
+    : undefined;
+}
+
+function stubLinkedIn(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const url = requestUrl(input);
+    const method = init?.method ?? "GET";
+    const headers = new Headers(init?.headers);
+    const body = requestBody(init);
+    state.calls.push({ url, method, headers, body });
+
+    if (url.host === "uploads.linkedin.test" && method === "PUT") {
+      expect(headers.get("authorization")).toBeNull();
+      const bytes = await new Response(init?.body).arrayBuffer();
+      state.uploadedBytes = bytes.byteLength;
+      return new Response(null, { status: 201 });
+    }
+
+    expect(url.origin).toBe("https://api.linkedin.com");
+    expect(headers.get("authorization")).toBe(`Bearer ${TOKEN}`);
+    expect(headers.get("x-restli-protocol-version")).toBe("2.0.0");
+
+    if (method === "GET" && url.pathname === "/v2/userinfo") {
+      return response({
+        sub: "member123",
+        name: "Ada Lovelace",
+        preferred_username: "ada-lovelace",
+        picture: "https://media.example.test/ada.jpg",
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/rest/assets") {
+      expect(url.searchParams.get("action")).toBe("registerUpload");
+      return response({
+        value: {
+          asset: "urn:li:digitalmediaAsset:image123",
+          uploadMechanism: {
+            "com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest": {
+              uploadUrl: "https://uploads.linkedin.test/image123",
+              headers: { "x-amz-server-side-encryption": "AES256" },
+            },
+          },
+        },
+      });
+    }
+
+    if (method === "POST" && url.pathname === "/rest/posts") {
+      const urn = `urn:li:share:${state.nextPost}`;
+      state.nextPost += 1;
+      state.posts.push({ urn, body: body ?? {} });
+      const headerName = state.nextPost % 2 === 0 ? "x-restli-id" : "x-linkedin-id";
+      return response(undefined, 201, { [headerName]: urn });
+    }
+
+    if (method === "DELETE" && url.pathname.startsWith("/rest/posts/")) {
+      const urn = decodeURIComponent(url.pathname.slice("/rest/posts/".length));
+      state.posts = state.posts.filter((post) => post.urn !== urn);
+      return new Response(null, { status: 204 });
+    }
+
+    if (url.pathname.startsWith("/rest/socialActions/") && url.pathname.endsWith("/comments")) {
+      const encoded = url.pathname.slice("/rest/socialActions/".length, -"/comments".length);
+      const parent = decodeURIComponent(encoded);
+      if (method === "GET") {
+        return response({
+          elements: [
+            {
+              id: "urn:li:comment:(urn:li:activity:123,456)",
+              actor: MEMBER_URN,
+              message: { text: "Useful context" },
+              created: { time: 1_780_000_000_000 },
+            },
+          ],
+          paging: { start: 0, count: 1, total: 1 },
+        });
+      }
+      const urn = `urn:li:comment:${state.nextComment}`;
+      state.nextComment += 1;
+      expect(body).toMatchObject({ actor: MEMBER_URN, message: { text: "Agreed" } });
+      return response(undefined, 201, { "x-restli-id": urn, "x-parent-id": parent });
+    }
+
+    return response({ message: `Unhandled ${method} ${url.pathname}` }, 404);
+  };
+}
+
+interface Harness {
+  state: StubState;
+  connector: ReturnType<typeof createLinkedInConnector>;
+}
+
+function harness(): Harness {
+  const state: StubState = {
+    calls: [],
+    posts: [],
+    nextPost: 1,
+    nextComment: 1,
+    uploadedBytes: 0,
+  };
+  return {
+    state,
+    connector: createLinkedInConnector({
+      fetchImpl: stubLinkedIn(state),
+      openAsset: async () => new Uint8Array([137, 80, 78, 71]),
+    }),
+  };
+}
+
+function post(
+  text: string,
+  mediaAssetIds: string[] = [],
+  providerMetadata: Record<string, unknown> = {},
+): NormalizedPost {
+  return {
+    text,
+    mediaAssetIds,
+    visibility: "public",
+    providerMetadata,
+  };
+}
+
+connectorContractTests(harness().connector, { connection });
+
+describe("linkedin connector", () => {
+  it("declares the OAuth setup and honest capabilities", () => {
+    const manifest = harness().connector.manifest();
+    expect(manifest).toMatchObject({
+      id: "linkedin",
+      displayName: "LinkedIn",
+      capabilities: {
+        publishText: true,
+        publishImages: true,
+        feed: false,
+        comments: true,
+        replies: true,
+        amplifyRepost: true,
+        amplifyQuote: true,
+        analytics: false,
+        deletePublication: true,
+        directMessages: false,
+        webhooks: false,
+        nativeScheduling: false,
+      },
+      oauth: {
+        kind: "oauth2-redirect",
+        authorizeUrlTemplate: "https://www.linkedin.com/oauth/v2/authorization",
+      },
+    });
+    expect(manifest.connectionFields).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({ name: "accessToken", required: true, secret: true }),
+        expect.objectContaining({ name: "memberUrn", required: true, secret: false }),
+        expect.objectContaining({ name: "organizationUrn", required: false, secret: false }),
+      ]),
+    );
+  });
+
+  it("maps the OIDC userinfo identity", async () => {
+    const { connector } = harness();
+    await expect(connector.getIdentity(connection)).resolves.toEqual({
+      provider: "linkedin",
+      remoteId: "member123",
+      handle: "ada-lovelace",
+      displayName: "Ada Lovelace",
+      avatarUrl: "https://media.example.test/ada.jpg",
+    });
+  });
+
+  it("publishes the full Posts API shape and extracts x-restli-id", async () => {
+    const { state, connector } = harness();
+    const publication = await connector.publish?.(connection, post("Launch day"));
+    expect(publication?.remoteId).toBe("urn:li:share:1");
+    expect(state.posts[0]?.body).toEqual({
+      author: MEMBER_URN,
+      commentary: "Launch day",
+      visibility: "PUBLIC",
+      distribution: {
+        feedDistribution: "MAIN_FEED",
+        targetEntities: [],
+        thirdPartyDistributionChannels: [],
+      },
+      lifecycleState: "PUBLISHED",
+      isReshareDisabledByAuthor: false,
+    });
+  });
+
+  it("publishes as the configured organization and references uploaded images", async () => {
+    const organizationConnection: ConnectorConnection = {
+      ...connection,
+      fields: { ...connection.fields, organizationUrn: ORGANIZATION_URN },
+    };
+    const { state, connector } = harness();
+    await connector.publish?.(
+      organizationConnection,
+      post("Company update", ["urn:li:image:first", "urn:li:image:second"]),
+    );
+    expect(state.posts[0]?.body).toMatchObject({
+      author: ORGANIZATION_URN,
+      content: {
+        multiImage: {
+          images: [{ id: "urn:li:image:first" }, { id: "urn:li:image:second" }],
+        },
+      },
+    });
+  });
+
+  it("supports a publish reshareContext roundtrip", async () => {
+    const { state, connector } = harness();
+    const parent = "urn:li:share:original";
+    const result = await connector.publish?.(
+      connection,
+      post("A useful read", [], { reshareContext: { parent } }),
+    );
+    expect(result?.providerMetadata).toMatchObject({ reshareParent: parent });
+    expect(state.posts[0]?.body).toMatchObject({
+      commentary: "A useful read",
+      reshareContext: { parent },
+    });
+  });
+
+  it("maps repost and quote amplification to attributed reshare posts", async () => {
+    const parent = "urn:li:share:original";
+    const repostHarness = harness();
+    const repost = await repostHarness.connector.amplify?.(connection, {
+      kind: "repost",
+      targetRemoteId: parent,
+    });
+    expect(repost?.remoteId).toBe("urn:li:share:1");
+    expect(repostHarness.state.posts[0]?.body).toMatchObject({
+      commentary: "",
+      reshareContext: { parent },
+    });
+
+    const quoteHarness = harness();
+    const quote = await quoteHarness.connector.amplify?.(connection, {
+      kind: "quote",
+      targetRemoteId: parent,
+      commentary: "My take",
+    });
+    expect(quote?.remoteId).toBe("urn:li:share:1");
+    expect(quoteHarness.state.posts[0]?.body).toMatchObject({
+      commentary: "My take",
+      reshareContext: { parent },
+    });
+  });
+
+  it("registers and PUTs an image upload", async () => {
+    const media: MediaAsset = {
+      id: "image-1",
+      workspaceId: "ws-1",
+      storageKey: "s3://assets/image-1",
+      mimeType: "image/png",
+      sizeBytes: 4,
+      width: 640,
+      height: 480,
+      createdAt: new Date(),
+    };
+    const { state, connector } = harness();
+    const uploaded = await connector.uploadMedia?.(connection, media);
+    expect(uploaded).toEqual({
+      remoteId: "urn:li:digitalmediaAsset:image123",
+      mimeType: "image/png",
+      width: 640,
+      height: 480,
+    });
+    expect(state.uploadedBytes).toBe(4);
+  });
+
+  it("reads comments, replies, and deletes an owned publication", async () => {
+    const { state, connector } = harness();
+    const comments = await connector.getComments?.(connection, {
+      onRemoteId: "urn:li:share:original",
+      limit: 10,
+    });
+    expect(comments?.items[0]).toMatchObject({
+      authorHandle: MEMBER_URN,
+      text: "Useful context",
+    });
+    const reply = await connector.reply?.(connection, {
+      onRemoteId: "urn:li:share:original",
+      text: "Agreed",
+    });
+    expect(reply?.remoteId).toBe("urn:li:comment:1");
+
+    const published = await connector.publish?.(connection, post("Temporary"));
+    expect(state.posts).toHaveLength(1);
+    await connector.deletePublication?.(connection, published?.remoteId ?? "");
+    expect(state.posts).toHaveLength(0);
+  });
+});
diff --git a/packages/connector-linkedin/src/index.ts b/packages/connector-linkedin/src/index.ts
new file mode 100644
index 0000000..983c113
--- /dev/null
+++ b/packages/connector-linkedin/src/index.ts
@@ -0,0 +1,525 @@
+import { randomUUID } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  Page,
+  Publication,
+  RemoteMedia,
+  Visibility,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  RateLimitedHttpClient,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "linkedin";
+const API_BASE = "https://api.linkedin.com";
+const LINKEDIN_VERSION = "202510";
+
+export const LINKEDIN_RATE_POLICY = { requestsPerSecond: 2 } as const;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  feed: false,
+  comments: true,
+  replies: true,
+  amplifyRepost: true,
+  amplifyQuote: true,
+  analytics: false,
+  deletePublication: true,
+  directMessages: false,
+  webhooks: false,
+  nativeScheduling: false,
+};
+
+export interface LinkedInConnectorOptions {
+  fetchImpl?: typeof fetch;
+  /** Supplies image bytes when MediaAsset.storageKey is not an HTTP(S) URL. */
+  openAsset?: (media: MediaAsset) => Promise<Uint8Array>;
+}
+
+interface UserInfo {
+  sub: string;
+  name?: string;
+  given_name?: string;
+  family_name?: string;
+  preferred_username?: string;
+  picture?: string;
+}
+
+interface RegisterUploadResponse {
+  value?: {
+    asset?: string;
+    uploadMechanism?: {
+      "com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest"?: {
+        uploadUrl?: string;
+        headers?: Record<string, string>;
+      };
+    };
+  };
+}
+
+interface LinkedInComment {
+  id?: string;
+  actor?: string;
+  message?: { text?: string };
+  created?: { time?: number };
+  lastModified?: { time?: number };
+}
+
+interface CommentsResponse {
+  elements?: LinkedInComment[];
+  paging?: { start?: number; count?: number; total?: number };
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function jsonBody(payload: Record<string, unknown>): RequestInit {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload),
+  };
+}
+
+function visibility(value: Visibility): "PUBLIC" | "CONNECTIONS" | "LOGGED_IN" {
+  switch (value) {
+    case "followers":
+    case "private":
+      return "CONNECTIONS";
+    case "unlisted":
+      return "LOGGED_IN";
+    case "public":
+    case "provider_default":
+      return "PUBLIC";
+  }
+}
+
+function nestedReshareParent(metadata: Record<string, unknown>): string | undefined {
+  const direct = nonEmptyString(metadata["reshareParent"])
+    ?? nonEmptyString(metadata["parentPostUrn"]);
+  if (direct !== undefined) return direct;
+  const context = metadata["reshareContext"];
+  return isRecord(context) ? nonEmptyString(context["parent"]) : undefined;
+}
+
+function draftId(metadata: Record<string, unknown>, fallback = "direct"): string {
+  return nonEmptyString(metadata["draftId"]) ?? fallback;
+}
+
+function mediaContent(mediaUrns: string[]): Record<string, unknown> | undefined {
+  if (mediaUrns.length === 0) return undefined;
+  if (mediaUrns.length === 1) return { media: { id: mediaUrns[0] } };
+  return { multiImage: { images: mediaUrns.map((id) => ({ id })) } };
+}
+
+function postUrnFromBody(body: unknown): string | undefined {
+  if (!isRecord(body)) return undefined;
+  const direct = nonEmptyString(body["id"]);
+  if (direct !== undefined) return direct;
+  const value = body["value"];
+  return isRecord(value) ? nonEmptyString(value["id"]) : undefined;
+}
+
+/** LinkedIn Posts API connector. Personal feed reads and analytics stay undeclared. */
+export function createLinkedInConnector(options: LinkedInConnectorOptions = {}): PlatformConnector {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: LINKEDIN_RATE_POLICY.requestsPerSecond,
+    fetchImpl,
+  });
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "LinkedIn",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "accessToken",
+        label: "Access token",
+        required: true,
+        secret: true,
+      },
+      {
+        name: "memberUrn",
+        label: "Member URN",
+        required: true,
+        secret: false,
+        pattern: "^urn:li:person:[A-Za-z0-9_-]+$",
+        placeholder: "urn:li:person:abc123",
+      },
+      {
+        name: "organizationUrn",
+        label: "Organization URN (optional)",
+        required: false,
+        secret: false,
+        pattern: "^urn:li:organization:[0-9]+$",
+        placeholder: "urn:li:organization:123456",
+      },
+    ],
+    oauth: {
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: "https://www.linkedin.com/oauth/v2/authorization",
+      scopes: [
+        "openid",
+        "profile",
+        "w_member_social",
+        "r_member_social",
+        "rw_organization_social",
+      ],
+    },
+    docsUrl: "https://learn.microsoft.com/linkedin/marketing/community-management/shares/posts-api",
+  };
+
+  function accessToken(connection: ConnectorConnection): string {
+    const token = nonEmptyString(connection.fields["accessToken"]);
+    if (token === undefined) {
+      throw new AuthError(`${PROVIDER}: missing accessToken connection field`, PROVIDER, false);
+    }
+    return token;
+  }
+
+  function memberUrn(connection: ConnectorConnection): string {
+    const urn = nonEmptyString(connection.fields["memberUrn"]);
+    if (urn === undefined) {
+      throw new ConnectorError(`${PROVIDER}: missing memberUrn connection field`, PROVIDER);
+    }
+    return urn;
+  }
+
+  function authorUrn(
+    connection: ConnectorConnection,
+    metadata: Record<string, unknown> = {},
+  ): string {
+    const member = memberUrn(connection);
+    const organization = nonEmptyString(connection.fields["organizationUrn"]);
+    const explicit = nonEmptyString(metadata["authorUrn"]);
+    if (explicit !== undefined && explicit !== member && explicit !== organization) {
+      throw new ConnectorError(
+        `${PROVIDER}: authorUrn must match the connection's memberUrn or organizationUrn`,
+        PROVIDER,
+      );
+    }
+    return explicit ?? organization ?? member;
+  }
+
+  async function errorFor(response: Response, method: string, url: string): Promise<Error> {
+    const detail = (await response.text()).trim();
+    const suffix = detail.length > 0 ? `: ${detail}` : "";
+    const message = `${PROVIDER}: HTTP ${response.status} ${method} ${new URL(url).pathname}${suffix}`;
+    if (response.status === 401 || response.status === 403) {
+      return new AuthError(message, PROVIDER, false);
+    }
+    return new ConnectorError(message, PROVIDER, { status: response.status });
+  }
+
+  async function api(
+    connection: ConnectorConnection,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<Response> {
+    const url = `${API_BASE}${path}`;
+    const headers = new Headers(init.headers);
+    headers.set("accept", "application/json");
+    headers.set("authorization", `Bearer ${accessToken(connection)}`);
+    headers.set("linkedin-version", LINKEDIN_VERSION);
+    headers.set("x-restli-protocol-version", "2.0.0");
+    const method = init.method ?? "GET";
+    const response = await client.request(PROVIDER, url, { ...init, headers });
+    if (!response.ok) throw await errorFor(response, method, url);
+    return response;
+  }
+
+  async function json<T>(
+    connection: ConnectorConnection,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<T> {
+    const response = await api(connection, path, init);
+    try {
+      return (await response.json()) as T;
+    } catch (cause) {
+      throw new ConnectorError(
+        `${PROVIDER}: non-JSON response from ${path} (HTTP ${response.status})`,
+        PROVIDER,
+        cause,
+      );
+    }
+  }
+
+  async function createdUrn(
+    connection: ConnectorConnection,
+    path: string,
+    payload: Record<string, unknown>,
+  ): Promise<string> {
+    const response = await api(connection, path, jsonBody(payload));
+    const headerUrn = nonEmptyString(response.headers.get("x-restli-id"))
+      ?? nonEmptyString(response.headers.get("x-linkedin-id"));
+    if (headerUrn !== undefined) return headerUrn;
+
+    const text = await response.text();
+    if (text.length > 0) {
+      try {
+        const bodyUrn = postUrnFromBody(JSON.parse(text) as unknown);
+        if (bodyUrn !== undefined) return bodyUrn;
+      } catch {
+        // The create response body is optional; the missing-id error below is clearer.
+      }
+    }
+    throw new ConnectorError(`${PROVIDER}: create response contained no resource URN`, PROVIDER);
+  }
+
+  function publication(
+    connection: ConnectorConnection,
+    remoteId: string,
+    sourceDraftId: string,
+    providerMetadata: Record<string, unknown>,
+  ): Publication {
+    return {
+      id: randomUUID(),
+      workspaceId: connection.workspaceId,
+      draftId: sourceDraftId,
+      connectionId: connection.id,
+      remoteId,
+      publishedAt: new Date(),
+      providerMetadata,
+    };
+  }
+
+  function postPayload(
+    connection: ConnectorConnection,
+    commentary: string,
+    postVisibility: Visibility,
+    metadata: Record<string, unknown>,
+    mediaUrns: string[] = [],
+    parent?: string,
+  ): Record<string, unknown> {
+    const payload: Record<string, unknown> = {
+      author: authorUrn(connection, metadata),
+      commentary,
+      visibility: visibility(postVisibility),
+      distribution: {
+        feedDistribution: "MAIN_FEED",
+        targetEntities: [],
+        thirdPartyDistributionChannels: [],
+      },
+      lifecycleState: "PUBLISHED",
+      isReshareDisabledByAuthor: false,
+    };
+    const content = mediaContent(mediaUrns);
+    if (content !== undefined) payload["content"] = content;
+    if (parent !== undefined) payload["reshareContext"] = { parent };
+    return payload;
+  }
+
+  async function imageBytes(media: MediaAsset): Promise<Uint8Array> {
+    if (options.openAsset !== undefined) return options.openAsset(media);
+    if (!/^https?:\/\//i.test(media.storageKey)) {
+      throw new ConnectorError(
+        `${PROVIDER}: uploadMedia needs openAsset when storageKey is not an HTTP(S) URL`,
+        PROVIDER,
+      );
+    }
+    const response = await fetchImpl(media.storageKey);
+    if (!response.ok) {
+      throw new ConnectorError(
+        `${PROVIDER}: could not read media bytes (HTTP ${response.status})`,
+        PROVIDER,
+      );
+    }
+    return new Uint8Array(await response.arrayBuffer());
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new ConnectorError(
+        `${PROVIDER}: start OAuth at ${manifest.oauth?.authorizeUrlTemplate ?? "the authorization endpoint"}, exchange the code with POST https://www.linkedin.com/oauth/v2/accessToken, then store accessToken and memberUrn`,
+        PROVIDER,
+      );
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      const user = await json<UserInfo>(connection, "/v2/userinfo");
+      const componentName = [user.given_name, user.family_name]
+        .map(nonEmptyString)
+        .filter((part): part is string => part !== undefined)
+        .join(" ");
+      const displayName = nonEmptyString(user.name)
+        ?? nonEmptyString(componentName)
+        ?? user.sub;
+      const handle = nonEmptyString(user.preferred_username) ?? displayName;
+      return {
+        provider: PROVIDER,
+        remoteId: user.sub,
+        handle,
+        displayName,
+        avatarUrl: nonEmptyString(user.picture),
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const parent = nestedReshareParent(post.providerMetadata);
+      const payload = postPayload(
+        connection,
+        post.text,
+        post.visibility,
+        post.providerMetadata,
+        post.mediaAssetIds,
+        parent,
+      );
+      const remoteId = await createdUrn(connection, "/rest/posts", payload);
+      return publication(connection, remoteId, draftId(post.providerMetadata), {
+        ...post.providerMetadata,
+        author: payload["author"],
+        mediaUrns: post.mediaAssetIds,
+        ...(parent === undefined ? {} : { reshareParent: parent }),
+      });
+    },
+
+    async uploadMedia(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia> {
+      if (!media.mimeType.startsWith("image/")) {
+        throw new CapabilityNotSupportedError(PROVIDER, `uploadMedia:${media.mimeType}`);
+      }
+      const owner = authorUrn(connection);
+      const registered = await json<RegisterUploadResponse>(
+        connection,
+        "/rest/assets?action=registerUpload",
+        jsonBody({
+          registerUploadRequest: {
+            recipes: ["urn:li:digitalmediaRecipe:feedshare-image"],
+            owner,
+            serviceRelationships: [
+              {
+                relationshipType: "OWNER",
+                identifier: "urn:li:userGeneratedContent",
+              },
+            ],
+          },
+        }),
+      );
+      const asset = nonEmptyString(registered.value?.asset);
+      const upload = registered.value?.uploadMechanism?.[
+        "com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest"
+      ];
+      const uploadUrl = nonEmptyString(upload?.uploadUrl);
+      if (asset === undefined || uploadUrl === undefined) {
+        throw new ConnectorError(`${PROVIDER}: registerUpload response is missing asset or uploadUrl`, PROVIDER);
+      }
+      const bytes = await imageBytes(media);
+      const headers = new Headers(upload?.headers);
+      if (!headers.has("content-type")) headers.set("content-type", media.mimeType);
+      const uploaded = await client.request(PROVIDER, uploadUrl, {
+        method: "PUT",
+        headers,
+        body: new Blob([bytes], { type: media.mimeType }),
+      });
+      if (!uploaded.ok) throw await errorFor(uploaded, "PUT", uploadUrl);
+      return {
+        remoteId: asset,
+        mimeType: media.mimeType,
+        width: media.width,
+        height: media.height,
+      };
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const start = Math.max(0, Number(request.cursor ?? "0") || 0);
+      const count = Math.max(1, Math.min(100, request.limit));
+      const path = `/rest/socialActions/${encodeURIComponent(request.onRemoteId)}/comments?start=${start}&count=${count}`;
+      const data = await json<CommentsResponse>(connection, path);
+      const elements = data.elements ?? [];
+      const items = elements.map((comment, index): Comment => {
+        const remoteId = nonEmptyString(comment.id) ?? `${request.onRemoteId}:comment:${start + index}`;
+        return {
+          id: remoteId,
+          provider: PROVIDER,
+          remoteId,
+          onRemoteId: request.onRemoteId,
+          authorHandle: nonEmptyString(comment.actor) ?? "unknown",
+          text: comment.message?.text ?? "",
+          createdAt: new Date(comment.created?.time ?? comment.lastModified?.time ?? 0),
+        };
+      });
+      const total = data.paging?.total;
+      const next = start + elements.length;
+      return {
+        items,
+        ...(total !== undefined && next < total ? { nextCursor: String(next) } : {}),
+      };
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const remoteId = await createdUrn(
+        connection,
+        `/rest/socialActions/${encodeURIComponent(request.onRemoteId)}/comments`,
+        {
+          actor: authorUrn(connection),
+          message: { text: request.text },
+        },
+      );
+      return publication(connection, remoteId, "reply", {
+        inReplyTo: request.onRemoteId,
+      });
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: {
+        kind: "repost" | "quote" | "share";
+        targetRemoteId: string;
+        commentary?: string;
+        quoteAssetIds?: string[];
+      },
+    ): Promise<Publication> {
+      if (request.kind === "share") {
+        throw new CapabilityNotSupportedError(PROVIDER, "amplifyShare");
+      }
+      const commentary = request.kind === "quote" ? request.commentary ?? "" : "";
+      const mediaUrns = request.kind === "quote" ? request.quoteAssetIds ?? [] : [];
+      const payload = postPayload(
+        connection,
+        commentary,
+        "public",
+        {},
+        mediaUrns,
+        request.targetRemoteId,
+      );
+      const remoteId = await createdUrn(connection, "/rest/posts", payload);
+      return publication(connection, remoteId, request.kind, {
+        kind: request.kind,
+        reshareParent: request.targetRemoteId,
+      });
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      await api(connection, `/rest/posts/${encodeURIComponent(remoteId)}`, { method: "DELETE" });
+    },
+  };
+}
diff --git a/packages/connector-linkedin/tsconfig.json b/packages/connector-linkedin/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-linkedin/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-mastodon/package.json b/packages/connector-mastodon/package.json
new file mode 100644
index 0000000..1a4b2bd
--- /dev/null
+++ b/packages/connector-mastodon/package.json
@@ -0,0 +1,29 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-mastodon",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  },
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  }
+}
diff --git a/packages/connector-mastodon/src/contract.test.ts b/packages/connector-mastodon/src/contract.test.ts
new file mode 100644
index 0000000..b26637b
--- /dev/null
+++ b/packages/connector-mastodon/src/contract.test.ts
@@ -0,0 +1,447 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { CapabilityNotSupportedError, InMemoryCredentials } from "@tactical-media-broadcast-hub/connector-sdk";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import {
+  AuthorizationRedirectRequired,
+  createMastodonConnector,
+  type MastodonAuthorizationRequest,
+} from "./index.js";
+
+/**
+ * Stubbed Mastodon instance: canned JSON per endpoint, real request/response
+ * shapes. Every call is recorded so tests can assert on what was sent.
+ */
+interface StubCall {
+  method: string;
+  url: URL;
+  init: RequestInit | undefined;
+}
+
+interface StubState {
+  calls: StubCall[];
+  nextStatusId: number;
+  /** Idempotency-Key → status id, like the instance's one-hour dedupe cache. */
+  idempotency?: Map<string, string>;
+  /** Statuses actually created (side effects, independent of responses). */
+  created?: string[];
+}
+
+const INSTANCE = "https://mastodon.example";
+const HOST = "mastodon.example";
+const TOKEN = "stub-access-token";
+const REDIRECT = "https://app.example.com/oauth/mastodon/callback";
+
+const ACCOUNT = {
+  id: "109000000000000001",
+  username: "anarchoposter",
+  acct: "anarchoposter",
+  display_name: "AnarchoPoster",
+  avatar: `${INSTANCE}/avatars/original/missing.png`,
+  url: `${INSTANCE}/@anarchoposter`,
+};
+
+const OTHER = {
+  id: "109000000000000002",
+  username: "alice",
+  acct: "alice@other.example",
+  display_name: "Alice",
+  avatar: "",
+  url: "https://other.example/@alice",
+};
+
+const connection: ConnectorConnection = {
+  id: "conn-mastodon",
+  workspaceId: "ws-1",
+  provider: "mastodon",
+  channelId: "conn-mastodon",
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: { instanceUrl: HOST },
+  createdAt: new Date(),
+};
+
+function status(
+  id: string,
+  overrides: Partial<Record<string, unknown>> = {},
+): Record<string, unknown> {
+  return {
+    id,
+    created_at: "2026-10-06T12:00:00.000Z",
+    url: `${INSTANCE}/@tactical-media-broadcast-hub/${id}`,
+    uri: `${INSTANCE}/users/anarchoposter/statuses/${id}`,
+    content: "<p>hello</p>",
+    visibility: "public",
+    account: ACCOUNT,
+    media_attachments: [],
+    mentions: [],
+    reblogs_count: 0,
+    replies_count: 0,
+    favourites_count: 0,
+    in_reply_to_id: null,
+    reblog: null,
+    ...overrides,
+  };
+}
+
+function json(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    ...init,
+    headers: { "content-type": "application/json", ...init.headers },
+  });
+}
+
+function jsonBody(init: RequestInit | undefined): Record<string, unknown> {
+  return JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+}
+
+function formBody(init: RequestInit | undefined): URLSearchParams {
+  return new URLSearchParams(String(init?.body ?? ""));
+}
+
+function headerOf(init: RequestInit | undefined, name: string): string | undefined {
+  return new Headers(init?.headers).get(name) ?? undefined;
+}
+
+function stubInstance(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const raw = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    const url = new URL(raw);
+    const method = (init?.method ?? "GET").toUpperCase();
+    state.calls.push({ method, url, init });
+    const route = `${method} ${url.pathname}`;
+
+    if (route === "POST /api/v1/apps") {
+      return json({
+        id: "563419",
+        name: formBody(init).get("client_name"),
+        client_id: "stub-client-id",
+        client_secret: "stub-client-secret",
+        redirect_uri: formBody(init).get("redirect_uris"),
+      });
+    }
+    if (route === "POST /oauth/token") {
+      const form = formBody(init);
+      if (form.get("code") !== "good-code") {
+        return json({ error: "invalid_grant", error_description: "The provided authorization grant is invalid" }, { status: 400 });
+      }
+      return json({ access_token: TOKEN, token_type: "Bearer", scope: "read write:statuses write:media", created_at: 1_760_000_000 });
+    }
+
+    // Everything below is an authenticated API call.
+    if (headerOf(init, "authorization") !== `Bearer ${TOKEN}`) {
+      return json({ error: "The access token is invalid" }, { status: 401 });
+    }
+
+    if (route === "GET /api/v1/accounts/verify_credentials") return json(ACCOUNT);
+
+    if (route === "POST /api/v1/statuses") {
+      const body = jsonBody(init);
+      const text = String(body["status"]);
+      if (text === "rate-limit-me") return json({ error: "Too many requests" }, { status: 429, headers: { "retry-after": "30" } });
+      if (text === "server-error-me") return json({ error: "Internal" }, { status: 500 });
+      if (text === "invalid-me") return json({ error: "Validation failed: Text can't be blank" }, { status: 422 });
+      const key = headerOf(init, "idempotency-key");
+      const seen = key === undefined ? undefined : state.idempotency?.get(key);
+      if (seen !== undefined) return json(status(seen, { content: `<p>${text}</p>` }));
+      const id = String((state.nextStatusId += 1));
+      if (key !== undefined) state.idempotency?.set(key, id);
+      state.created?.push(id);
+      if (typeof body["scheduled_at"] === "string") {
+        return json({ id: `s${id}`, scheduled_at: body["scheduled_at"], params: { text: body["status"] }, media_attachments: [] });
+      }
+      return json(
+        status(id, {
+          content: `<p>${String(body["status"])}</p>`,
+          visibility: body["visibility"] ?? "public",
+          ...(typeof body["quoted_status_id"] === "string"
+            ? { quote: { state: "accepted", quoted_status: status(body["quoted_status_id"], { account: OTHER }) } }
+            : {}),
+        }),
+      );
+    }
+
+    if (route === "GET /api/v1/timelines/home") {
+      return json(
+        [
+          status("300", {
+            account: OTHER,
+            content: "<p>first &amp; foremost<br>line two</p>",
+            media_attachments: [
+              { id: "m1", type: "image", url: "https://files.example/m1.png", preview_url: null },
+            ],
+            reblogs_count: 2,
+            replies_count: 1,
+            favourites_count: 5,
+          }),
+          status("299", { reblog: status("250", { account: OTHER, content: "<p>boosted</p>" }) }),
+        ],
+        { headers: { link: `<${INSTANCE}/api/v1/timelines/home?max_id=299>; rel="next", <${INSTANCE}/api/v1/timelines/home?min_id=300>; rel="prev"` } },
+      );
+    }
+
+    const reblog = /^POST \/api\/v1\/statuses\/([^/]+)\/reblog$/.exec(route);
+    if (reblog?.[1] !== undefined) {
+      const original = status(decodeURIComponent(reblog[1]), { account: OTHER });
+      return json(status(String((state.nextStatusId += 1)), { reblog: original, content: "" }));
+    }
+
+    return json({ error: `stub: no route for ${route}` }, { status: 404 });
+  };
+}
+
+interface Harness {
+  state: StubState;
+  connector: ReturnType<typeof createMastodonConnector>;
+  credentials: InMemoryCredentials;
+}
+
+async function createHarness(seedToken = true): Promise<Harness> {
+  const state: StubState = { calls: [], nextStatusId: 1000, idempotency: new Map(), created: [] };
+  const credentials = new InMemoryCredentials();
+  if (seedToken) await credentials.put(connection, "access_token", TOKEN);
+  const connector = createMastodonConnector({
+    fetchImpl: stubInstance(state),
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    credentials,
+  });
+  return { state, connector, credentials };
+}
+
+const leg1: MastodonAuthorizationRequest = {
+  redirectUri: REDIRECT,
+  workspaceId: "ws-1",
+  state: "csrf-1",
+  fields: { instanceUrl: HOST },
+};
+
+const post = (text: string) => ({
+  text,
+  mediaAssetIds: [],
+  visibility: "public" as const,
+  providerMetadata: {},
+});
+
+connectorContractTests((await createHarness()).connector, { connection });
+
+describe("mastodon connector: authorize + identity", () => {
+  it("leg 1 registers an app on the instance and redirects to its consent page", async () => {
+    const { state, connector } = await createHarness(false);
+    const error = await connector
+      .authorize(leg1)
+      .then(
+        () => undefined,
+        (e: unknown) => e,
+      );
+    expect(error).toBeInstanceOf(AuthorizationRedirectRequired);
+    const redirect = error as AuthorizationRedirectRequired;
+    const consent = new URL(redirect.authorizationUrl);
+    expect(consent.origin + consent.pathname).toBe(`${INSTANCE}/oauth/authorize`);
+    expect(consent.searchParams.get("client_id")).toBe("stub-client-id");
+    expect(consent.searchParams.get("redirect_uri")).toBe(REDIRECT);
+    expect(consent.searchParams.get("state")).toBe("csrf-1");
+    expect(redirect.connectionId).toBe(`mastodon:ws-1:${HOST}`);
+
+    const app = state.calls.find((c) => c.url.pathname === "/api/v1/apps");
+    expect(app?.method).toBe("POST");
+    expect(formBody(app?.init).get("scopes")).toBe("read write:statuses write:media");
+  });
+
+  it("leg 2 exchanges the code and the identity roundtrips through getIdentity", async () => {
+    const { state, connector } = await createHarness(false);
+    await expect(connector.authorize(leg1)).rejects.toBeInstanceOf(AuthorizationRedirectRequired);
+
+    const leg2: MastodonAuthorizationRequest = { ...leg1, providerMetadata: { code: "good-code" } };
+    const result = await connector.authorize(leg2);
+    const token = state.calls.find((c) => c.url.pathname === "/oauth/token");
+    const form = formBody(token?.init);
+    expect(form.get("grant_type")).toBe("authorization_code");
+    expect(form.get("client_id")).toBe("stub-client-id");
+    expect(form.get("client_secret")).toBe("stub-client-secret");
+    // Client registered once in leg 1, reused from the vault in leg 2.
+    expect(state.calls.filter((c) => c.url.pathname === "/api/v1/apps")).toHaveLength(1);
+
+    expect(result.connection.fields.instanceUrl).toBe(INSTANCE);
+    expect(result.identity).toEqual({
+      provider: "mastodon",
+      remoteId: ACCOUNT.id,
+      handle: `@anarchoposter@${HOST}`,
+      displayName: "AnarchoPoster",
+      avatarUrl: ACCOUNT.avatar,
+    });
+    expect(await connector.getIdentity(result.connection)).toEqual(result.identity);
+  });
+
+  it("maps a rejected code to a ConnectorError with the instance's description", async () => {
+    const { connector } = await createHarness(false);
+    const request: MastodonAuthorizationRequest = {
+      ...leg1,
+      fields: { instanceUrl: HOST, clientId: "cid", clientSecret: "csecret" },
+      providerMetadata: { code: "bad-code" },
+    };
+    await expect(connector.authorize(request)).rejects.toThrow(/authorization grant is invalid/);
+  });
+
+  it("getIdentity sends the bearer token and caches verify_credentials", async () => {
+    const { state, connector } = await createHarness();
+    const first = await connector.getIdentity(connection);
+    const second = await connector.getIdentity(connection);
+    expect(second).toEqual(first);
+    const calls = state.calls.filter((c) => c.url.pathname === "/api/v1/accounts/verify_credentials");
+    expect(calls).toHaveLength(1);
+    expect(headerOf(calls[0]?.init, "authorization")).toBe(`Bearer ${TOKEN}`);
+  });
+});
+
+describe("mastodon connector: publish", () => {
+  it("returns a Publication carrying the status id and url", async () => {
+    const { state, connector } = await createHarness();
+    const publication = await connector.publish?.(connection, post("hello fediverse"));
+    const call = state.calls.find((c) => c.url.pathname === "/api/v1/statuses");
+    expect(call?.method).toBe("POST");
+    expect(jsonBody(call?.init)).toEqual({ status: "hello fediverse", visibility: "public" });
+    expect(publication?.remoteId).toBe("1001");
+    expect(publication?.remoteUrl).toBe(`${INSTANCE}/@tactical-media-broadcast-hub/1001`);
+    expect(publication?.workspaceId).toBe("ws-1");
+    expect(publication?.connectionId).toBe("conn-mastodon");
+    expect(publication?.draftId).toBe("direct");
+    expect(publication?.publishedAt).toEqual(new Date("2026-10-06T12:00:00.000Z"));
+    expect(publication?.providerMetadata).toMatchObject({ visibility: "public" });
+  });
+
+  it("surfaces a far-future schedule as provider_scheduled with a scheduled: remote id", async () => {
+    const { connector } = await createHarness();
+    const scheduledAt = new Date(Date.now() + 60 * 60 * 1000);
+    const publication = await connector.publish?.(connection, {
+      ...post("later"),
+      scheduledAt,
+      providerMetadata: { draftId: "draft-from-user" },
+    });
+    expect(publication?.remoteId).toBe("scheduled:s1001");
+    expect(publication?.publishedAt).toEqual(scheduledAt);
+    expect(publication?.providerMetadata).toMatchObject({
+      outcome: "provider_scheduled",
+      scheduled: true,
+      scheduledStatusId: "s1001",
+    });
+    // Caller metadata never becomes the publication's draft identity.
+    expect(publication?.draftId).toBe("direct");
+  });
+
+  it("sends the injected idempotency key and replays to the same status", async () => {
+    const { state, connector } = await createHarness();
+    const key = "wp3:ws-1:draft-1:a1:publish";
+    const withKey = { ...post("once"), providerMetadata: { idempotencyKey: key, draftId: "draft-1" } };
+    const first = await connector.publish?.(connection, withKey);
+    const replay = await connector.publish?.(connection, withKey);
+    const posts = state.calls.filter((c) => c.method === "POST" && c.url.pathname === "/api/v1/statuses");
+    expect(posts.map((c) => headerOf(c.init, "idempotency-key"))).toEqual([key, key]);
+    expect(replay?.remoteId).toBe(first?.remoteId);
+    expect(state.created).toEqual(["1001"]);
+    expect(first?.providerMetadata).toMatchObject({ outcome: "published", idempotencyKey: key });
+    expect(first?.draftId).toBe("direct");
+  });
+
+  it("never resends a status POST on 5xx and reports unknown delivery", async () => {
+    const { state, connector } = await createHarness();
+    await expect(connector.publish?.(connection, post("server-error-me"))).rejects.toMatchObject({
+      name: "ProviderServerError",
+      status: 500,
+      delivery: "unknown",
+    });
+    expect(state.calls.filter((c) => c.url.pathname === "/api/v1/statuses")).toHaveLength(1);
+  });
+
+  it("surfaces a status POST 429 as a single-call RateLimitError with Retry-After", async () => {
+    const { state, connector } = await createHarness();
+    await expect(connector.publish?.(connection, post("rate-limit-me"))).rejects.toMatchObject({
+      name: "RateLimitError",
+      retryAfterMs: 30_000,
+      delivery: "rejected",
+    });
+    expect(state.calls.filter((c) => c.url.pathname === "/api/v1/statuses")).toHaveLength(1);
+  });
+
+  it("maps a validation 422 to ProviderRejectedError", async () => {
+    const { connector } = await createHarness();
+    await expect(connector.publish?.(connection, post("invalid-me"))).rejects.toMatchObject({
+      name: "ProviderRejectedError",
+      status: 422,
+      delivery: "rejected",
+    });
+  });
+
+  it("maps a 401 to AuthError", async () => {
+    const { connector, credentials } = await createHarness();
+    await credentials.put(connection, "access_token", "revoked");
+    await expect(connector.publish?.(connection, post("x"))).rejects.toMatchObject({ name: "AuthError" });
+  });
+});
+
+describe("mastodon connector: feed", () => {
+  it("home returns a Page<FeedItem> with plain text, unwrapped reblogs and a Link cursor", async () => {
+    const { state, connector } = await createHarness();
+    const page = await connector.getFeed?.(connection, { kind: "home", limit: 20, cursor: "400" });
+    const call = state.calls.find((c) => c.url.pathname === "/api/v1/timelines/home");
+    expect(call?.url.searchParams.get("limit")).toBe("20");
+    expect(call?.url.searchParams.get("max_id")).toBe("400");
+
+    expect(page?.items).toHaveLength(2);
+    expect(page?.nextCursor).toBe("299");
+    const [first, boosted] = page?.items ?? [];
+    expect(first).toEqual({
+      id: "300",
+      provider: "mastodon",
+      remoteId: "300",
+      authorHandle: "alice@other.example",
+      text: "first & foremost\nline two",
+      mediaUrls: ["https://files.example/m1.png"],
+      createdAt: new Date("2026-10-06T12:00:00.000Z"),
+      metrics: { reblogs: 2, replies: 1, favourites: 5 },
+    });
+    // The wrapper keeps its own id; content comes from the reblogged original.
+    expect(boosted?.id).toBe("299");
+    expect(boosted?.remoteId).toBe("250");
+    expect(boosted?.text).toBe("boosted");
+  });
+
+  it("refuses search queries that are not a single hashtag", async () => {
+    const { connector } = await createHarness();
+    await expect(
+      connector.getFeed?.(connection, { kind: "search", query: "two words", limit: 10 }),
+    ).rejects.toThrow(/single hashtag/);
+  });
+});
+
+describe("mastodon connector: amplify", () => {
+  it("repost reblogs the target and returns a Publication", async () => {
+    const { state, connector } = await createHarness();
+    const publication = await connector.amplify?.(connection, { kind: "repost", targetRemoteId: "250" });
+    const call = state.calls.find((c) => c.url.pathname === "/api/v1/statuses/250/reblog");
+    expect(call?.method).toBe("POST");
+    expect(publication?.remoteId).toBe("1001");
+    expect(publication?.draftId).toBe("amplify:repost");
+    expect(publication?.remoteUrl).toBe(`${INSTANCE}/@tactical-media-broadcast-hub/1001`);
+    expect(publication?.providerMetadata).toMatchObject({ amplifies: "250", kind: "repost" });
+  });
+
+  it("quote posts with quoted_status_id on a 4.5+ instance", async () => {
+    const { state, connector } = await createHarness();
+    const publication = await connector.amplify?.(connection, {
+      kind: "quote",
+      targetRemoteId: "250",
+      commentary: "worth a read",
+    });
+    const call = state.calls.find((c) => c.url.pathname === "/api/v1/statuses");
+    expect(jsonBody(call?.init)).toEqual({ status: "worth a read", quoted_status_id: "250" });
+    expect(publication?.providerMetadata).toMatchObject({ kind: "quote", quoteState: "accepted" });
+  });
+
+  it("share is not a Mastodon amplification kind", async () => {
+    const { connector } = await createHarness();
+    await expect(
+      connector.amplify?.(connection, { kind: "share", targetRemoteId: "250" }),
+    ).rejects.toBeInstanceOf(CapabilityNotSupportedError);
+  });
+});
diff --git a/packages/connector-mastodon/src/index.ts b/packages/connector-mastodon/src/index.ts
new file mode 100644
index 0000000..119e633
--- /dev/null
+++ b/packages/connector-mastodon/src/index.ts
@@ -0,0 +1,985 @@
+/**
+ * Mastodon connector — Mastodon REST API, one base URL per connection.
+ *
+ * Auth: per-instance OAuth2. Every instance is its own authorization server,
+ * so `authorize` registers an app on the instance (POST /api/v1/apps) unless
+ * client credentials are supplied, then runs a standard authorization-code
+ * exchange (POST /oauth/token). The instance comes from the connection field
+ * `instanceUrl`; a bare host gets an https:// prefix, plain http is refused
+ * outside localhost.
+ *
+ * Honest capability notes (verified against the Mastodon API):
+ * - Native scheduling: POST /api/v1/statuses with `scheduled_at` returns a
+ *   ScheduledStatus, not a Status. We surface it as remoteId
+ *   `scheduled:<id>` so deletePublication can cancel it, flagged with
+ *   providerMetadata.outcome = "provider_scheduled": it is NOT a published
+ *   status. Mastodon rejects `scheduled_at` under 5 minutes out, so nearer
+ *   times publish immediately. The publishing pipeline strips scheduledAt and
+ *   owns timing itself, so it always receives a real status.
+ * - Idempotency: providerMetadata.idempotencyKey (injected by the publishing
+ *   runtime) is sent as the Idempotency-Key header; Mastodon dedupes repeated
+ *   POSTs with the same key for up to one hour. Status POSTs are never
+ *   auto-retried by the HTTP client — retry decisions belong to the runtime.
+ * - Quote posts need Mastodon ≥ 4.5. Older servers silently drop
+ *   `quoted_status_id` and publish a plain post; we detect the missing
+ *   `quote` field, delete that post and throw CapabilityNotSupportedError.
+ * - Mentions come from GET /api/v1/notifications?types[]=mention — Mastodon
+ *   has no separate "reply" notification type; replies are mentions.
+ * - Search maps to hashtag timelines only (GET /api/v1/timelines/tag/:tag).
+ * - No webhooks for user accounts (only admin webhooks), no reactions
+ *   surface, no analytics API.
+ *
+ * Rate limits: 300 requests / 5 min per account by default. The SDK client
+ * runs at 0.5 requests/s per host — half the account budget, shared across
+ * every connection on the same instance.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  CredentialRef,
+  DirectMessage,
+  FeedItem,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  Page,
+  Publication,
+  RemoteMedia,
+  Visibility,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  InMemoryCredentials,
+  ProviderRejectedError,
+  pageOf,
+  RateLimitedHttpClient,
+  type AuthorizationRequest,
+  type AuthorizationResult,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "mastodon";
+const SCOPES = ["read", "write:statuses", "write:media"];
+const MAX_MEDIA = 4;
+const MIN_SCHEDULE_LEAD_MS = 5 * 60 * 1000;
+/** Conversations pages scanned when resolving a conversation id to its thread. */
+const CONVERSATION_SCAN_PAGES = 3;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  publishCarousel: true,
+  feed: true,
+  mentions: true,
+  comments: true,
+  replies: true,
+  amplifyRepost: true,
+  amplifyQuote: true,
+  directMessages: true,
+  nativeScheduling: true,
+  deletePublication: true,
+  webhooks: false,
+  reactions: false,
+  analytics: false,
+  publishVideo: false,
+};
+
+/** Credential keys stored per connection through the CredentialAccessor. */
+const SECRET = {
+  accessToken: "access_token",
+  refreshToken: "refresh_token",
+  clientId: "client_id",
+  clientSecret: "client_secret",
+} as const;
+
+export interface MastodonConnectorOptions {
+  env?: Record<string, string | undefined>;
+  /** fetch override for tests (same pattern as the other connectors). */
+  fetchImpl?: typeof fetch;
+  /** Requests per second per instance host. Default 0.5; tests raise it. */
+  requestsPerSecond?: number;
+  /** Sleep override for the rate limiter (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Secret store. Default: in-memory (dev + contract tests). */
+  credentials?: CredentialAccessor;
+  /** Resolve a media asset id to its metadata (needed by publish with media). */
+  loadAsset?: (assetId: string) => Promise<MediaAsset>;
+  /** Read asset bytes for multipart upload (needed by publish/uploadMedia). */
+  openAsset?: (media: MediaAsset) => Promise<{ bytes: Uint8Array; filename: string }>;
+  /** client_name shown on the instance's authorized-apps page. */
+  clientName?: string;
+  /** Public website advertised with the registered app. */
+  website?: string;
+}
+
+/**
+ * The SDK's AuthorizationRequest carries no provider input, so the second
+ * leg (code exchange) and the instance URL travel in these optional fields.
+ */
+export interface MastodonAuthorizationRequest extends AuthorizationRequest {
+  fields?: Record<string, string>;
+  providerMetadata?: Record<string, unknown>;
+}
+
+/**
+ * Thrown by the first authorize leg. AuthorizationResult has no slot for a
+ * redirect, so the authorization URL rides on this error; callers send the
+ * user there and call authorize again with providerMetadata.code.
+ */
+export class AuthorizationRedirectRequired extends ConnectorError {
+  constructor(
+    readonly authorizationUrl: string,
+    readonly connectionId: string,
+  ) {
+    super("redirect the user to the instance to authorize", PROVIDER);
+    this.name = "AuthorizationRedirectRequired";
+  }
+}
+
+interface MastodonAccount {
+  id: string;
+  username: string;
+  acct: string;
+  display_name: string;
+  avatar: string;
+  url: string;
+}
+
+interface MastodonMediaAttachment {
+  id: string;
+  type: string;
+  url: string | null;
+  preview_url: string | null;
+  meta?: { original?: { width?: number; height?: number } } | null;
+}
+
+interface MastodonStatus {
+  id: string;
+  created_at: string;
+  url: string | null;
+  uri: string;
+  content: string;
+  visibility: "public" | "unlisted" | "private" | "direct";
+  account: MastodonAccount;
+  media_attachments: MastodonMediaAttachment[];
+  mentions: { id: string; acct: string; username: string }[];
+  reblogs_count: number;
+  replies_count: number;
+  favourites_count: number;
+  in_reply_to_id: string | null;
+  reblog: MastodonStatus | null;
+  /** Mastodon ≥ 4.5 only. */
+  quote?: { state: string; quoted_status?: MastodonStatus | null } | null;
+}
+
+interface MastodonScheduledStatus {
+  id: string;
+  scheduled_at: string;
+  params: Record<string, unknown>;
+}
+
+interface MastodonNotification {
+  id: string;
+  type: string;
+  created_at: string;
+  account: MastodonAccount;
+  status?: MastodonStatus | null;
+}
+
+interface MastodonConversation {
+  id: string;
+  unread: boolean;
+  accounts: MastodonAccount[];
+  last_status: MastodonStatus | null;
+}
+
+interface MastodonContext {
+  ancestors: MastodonStatus[];
+  descendants: MastodonStatus[];
+}
+
+interface MastodonApp {
+  client_id: string;
+  client_secret: string;
+}
+
+interface MastodonToken {
+  access_token: string;
+  token_type: string;
+  scope: string;
+  created_at: number;
+  refresh_token?: string;
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+/** Accepts "mastodon.social", "https://mastodon.social/", etc. → origin. */
+export function normalizeInstanceUrl(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) throw new ConnectorError("instanceUrl is required", PROVIDER);
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  let url: URL;
+  try {
+    url = new URL(withScheme);
+  } catch (cause) {
+    throw new ConnectorError(`instanceUrl "${raw}" is not a valid URL`, PROVIDER, cause);
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+    throw new ConnectorError(`instanceUrl must use https (got ${url.protocol})`, PROVIDER);
+  }
+  return url.origin;
+}
+
+const VISIBILITY: Record<Visibility, MastodonStatus["visibility"] | undefined> = {
+  public: "public",
+  unlisted: "unlisted",
+  followers: "private",
+  private: "direct",
+  provider_default: undefined,
+};
+
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+
+/** Status content is sanitized HTML; FeedItem.text is plain text. */
+export function htmlToText(html: string): string {
+  return html
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>\s*<p[^>]*>/gi, "\n\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, entity: string) => {
+      if (entity.startsWith("#x") || entity.startsWith("#X")) {
+        return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+      }
+      if (entity.startsWith("#")) return String.fromCodePoint(Number(entity.slice(1)));
+      return ENTITIES[entity.toLowerCase()] ?? match;
+    })
+    .trim();
+}
+
+/** `Link: <…?max_id=123>; rel="next"` → "123". */
+function nextMaxId(response: Response): string | undefined {
+  const link = response.headers.get("link");
+  if (link === null) return undefined;
+  for (const part of link.split(",")) {
+    const match = /<([^>]+)>\s*;\s*rel="?next"?/.exec(part);
+    if (match?.[1] !== undefined) {
+      return new URL(match[1]).searchParams.get("max_id") ?? undefined;
+    }
+  }
+  return undefined;
+}
+
+function isScheduled(value: MastodonStatus | MastodonScheduledStatus): value is MastodonScheduledStatus {
+  return "scheduled_at" in value && "params" in value && !("content" in value);
+}
+
+export function createMastodonConnector(options: MastodonConnectorOptions = {}): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: options.requestsPerSecond ?? 0.5,
+    fetchImpl: options.fetchImpl,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  /** verify_credentials results per connection id — reply/DM mapping need "self". */
+  const accounts = new Map<string, MastodonAccount>();
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Mastodon",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "instanceUrl",
+        label: "Instance URL",
+        required: true,
+        secret: false,
+        placeholder: "mastodon.social",
+      },
+      {
+        name: "clientId",
+        label: "Client key (optional — registered automatically)",
+        required: false,
+        secret: false,
+      },
+      {
+        name: "clientSecret",
+        label: "Client secret (optional — registered automatically)",
+        required: false,
+        secret: true,
+      },
+    ],
+    oauth: {
+      kind: "per-instance-oauth2",
+      authorizeUrlTemplate: "{instanceUrl}/oauth/authorize",
+      scopes: SCOPES,
+      pkce: true,
+    },
+    docsUrl: "https://docs.joinmastodon.org/client/intro/",
+  };
+
+  function instanceOf(connection: ConnectorConnection): string {
+    const raw = connection.fields.instanceUrl;
+    if (raw === undefined) {
+      throw new ConnectorError(`connection ${connection.id} has no instanceUrl`, PROVIDER);
+    }
+    return normalizeInstanceUrl(raw);
+  }
+
+  /**
+   * Throws the SDK error taxonomy for non-2xx: AuthError for 401/403,
+   * ProviderRejectedError for other 4xx; 429/5xx/transport failures arrive as
+   * typed errors from the client (never auto-retried for POST).
+   */
+  async function send(url: string, init: RequestInit): Promise<Response> {
+    const response = await client.request(PROVIDER, url, {
+      ...init,
+      headers: { accept: "application/json", ...init.headers },
+    });
+    if (response.ok) return response;
+    let detail = "";
+    try {
+      const body = (await response.json()) as { error?: string; error_description?: string };
+      detail = body.error_description ?? body.error ?? "";
+    } catch {
+      detail = "";
+    }
+    const message = `HTTP ${response.status} ${init.method ?? "GET"} ${new URL(url).pathname}${detail ? `: ${detail}` : ""}`;
+    if (response.status === 401 || response.status === 403) {
+      throw new AuthError(message, PROVIDER, false);
+    }
+    throw new ProviderRejectedError(message, PROVIDER, response.status);
+  }
+
+  async function api<T>(
+    connection: ConnectorConnection,
+    method: string,
+    path: string,
+    body?: Record<string, unknown> | FormData,
+    extraHeaders: Record<string, string> = {},
+  ): Promise<{ data: T; response: Response }> {
+    const token = await credentials.getAccessToken(connection);
+    const headers: Record<string, string> = { authorization: `Bearer ${token}`, ...extraHeaders };
+    const init: RequestInit = { method, headers };
+    if (body instanceof FormData) {
+      init.body = body;
+    } else if (body !== undefined) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    const response = await send(`${instanceOf(connection)}${path}`, init);
+    const text = await response.text();
+    const data = (text.length > 0 ? JSON.parse(text) : {}) as T;
+    return { data, response };
+  }
+
+  async function form<T>(url: string, params: Record<string, string>): Promise<T> {
+    const response = await send(url, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams(params).toString(),
+    });
+    return (await response.json()) as T;
+  }
+
+  async function selfAccount(connection: ConnectorConnection): Promise<MastodonAccount> {
+    const cached = accounts.get(connection.id);
+    if (cached !== undefined) return cached;
+    const { data } = await api<MastodonAccount>(connection, "GET", "/api/v1/accounts/verify_credentials");
+    accounts.set(connection.id, data);
+    return data;
+  }
+
+  function identityOf(connection: ConnectorConnection, account: MastodonAccount): NormalizedIdentity {
+    const host = new URL(instanceOf(connection)).host;
+    const identity: NormalizedIdentity = {
+      provider: PROVIDER,
+      remoteId: account.id,
+      handle: `@${account.username}@${host}`,
+    };
+    if (account.display_name) identity.displayName = account.display_name;
+    if (account.avatar) identity.avatarUrl = account.avatar;
+    return identity;
+  }
+
+  function toPublication(
+    connection: ConnectorConnection,
+    status: MastodonStatus,
+    draftId: string,
+    providerMetadata: Record<string, unknown> = {},
+  ): Publication {
+    const publication: Publication = {
+      id: randomUUID(),
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId: status.id,
+      publishedAt: new Date(status.created_at),
+      providerMetadata: { visibility: status.visibility, ...providerMetadata },
+    };
+    const url = status.url ?? status.uri;
+    if (url) publication.remoteUrl = url;
+    return publication;
+  }
+
+  function toFeedItem(status: MastodonStatus): FeedItem {
+    const content = status.reblog ?? status;
+    return {
+      id: status.id,
+      provider: PROVIDER,
+      remoteId: content.id,
+      authorHandle: content.account.acct,
+      text: htmlToText(content.content),
+      mediaUrls: content.media_attachments
+        .map((m) => m.url ?? m.preview_url)
+        .filter((u): u is string => u !== null),
+      createdAt: new Date(content.created_at),
+      metrics: {
+        reblogs: content.reblogs_count,
+        replies: content.replies_count,
+        favourites: content.favourites_count,
+      },
+    };
+  }
+
+  async function uploadAsset(
+    connection: ConnectorConnection,
+    media: MediaAsset,
+    description?: string,
+  ): Promise<RemoteMedia> {
+    if (options.openAsset === undefined) {
+      throw new ConnectorError("media upload needs an openAsset option", PROVIDER);
+    }
+    const { bytes, filename } = await options.openAsset(media);
+    const body = new FormData();
+    body.append("file", new Blob([new Uint8Array(bytes)], { type: media.mimeType }), filename);
+    if (description !== undefined) body.append("description", description);
+    // 202 = still processing; /api/v1/statuses accepts the id immediately.
+    const { data } = await api<MastodonMediaAttachment>(connection, "POST", "/api/v2/media", body);
+    const remote: RemoteMedia = { remoteId: data.id, mimeType: media.mimeType };
+    if (data.url !== null) remote.url = data.url;
+    const width = data.meta?.original?.width ?? media.width;
+    const height = data.meta?.original?.height ?? media.height;
+    if (width !== undefined) remote.width = width;
+    if (height !== undefined) remote.height = height;
+    return remote;
+  }
+
+  /** Asset ids → instance media ids; providerMetadata.altText maps asset id → description. */
+  async function uploadAll(
+    connection: ConnectorConnection,
+    assetIds: string[],
+    altText: Record<string, unknown> = {},
+  ): Promise<string[]> {
+    if (assetIds.length === 0) return [];
+    if (assetIds.length > MAX_MEDIA) {
+      throw new ConnectorError(`at most ${MAX_MEDIA} media attachments per status`, PROVIDER);
+    }
+    if (options.loadAsset === undefined) {
+      throw new ConnectorError("publishing media needs a loadAsset option", PROVIDER);
+    }
+    const ids: string[] = [];
+    for (const assetId of assetIds) {
+      const asset = await options.loadAsset(assetId);
+      ids.push((await uploadAsset(connection, asset, str(altText[assetId]))).remoteId);
+    }
+    return ids;
+  }
+
+  async function getStatus(connection: ConnectorConnection, id: string): Promise<MastodonStatus> {
+    const { data } = await api<MastodonStatus>(connection, "GET", `/api/v1/statuses/${encodeURIComponent(id)}`);
+    return data;
+  }
+
+  async function deleteStatus(connection: ConnectorConnection, id: string): Promise<void> {
+    await api(connection, "DELETE", `/api/v1/statuses/${encodeURIComponent(id)}`);
+  }
+
+  async function statusPage(
+    connection: ConnectorConnection,
+    path: string,
+    params: URLSearchParams,
+    limit: number,
+  ): Promise<Page<FeedItem>> {
+    const { data, response } = await api<MastodonStatus[]>(connection, "GET", `${path}?${params}`);
+    const items = data.map(toFeedItem);
+    const fallback = data.length >= limit ? data[data.length - 1]?.id : undefined;
+    return pageOf(items, nextMaxId(response) ?? fallback);
+  }
+
+  async function storeTokens(connection: ConnectorConnection, token: MastodonToken): Promise<void> {
+    await credentials.put(connection, SECRET.accessToken, token.access_token);
+    if (token.refresh_token !== undefined) {
+      await credentials.put(connection, SECRET.refreshToken, token.refresh_token);
+    }
+    accounts.delete(connection.id);
+  }
+
+  async function secretOrUndefined(connection: ConnectorConnection, key: string): Promise<string | undefined> {
+    try {
+      return await credentials.getSecret(connection, key);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Client credentials: vault first, then connection fields. */
+  async function clientCredentials(
+    connection: ConnectorConnection,
+  ): Promise<{ clientId: string; clientSecret: string } | undefined> {
+    const clientId = (await secretOrUndefined(connection, SECRET.clientId)) ?? str(connection.fields.clientId);
+    const clientSecret =
+      (await secretOrUndefined(connection, SECRET.clientSecret)) ?? str(connection.fields.clientSecret);
+    return clientId !== undefined && clientSecret !== undefined ? { clientId, clientSecret } : undefined;
+  }
+
+  function messageOf(
+    conversationRemoteId: string,
+    status: MastodonStatus,
+    self: MastodonAccount,
+    participants: MastodonAccount[],
+  ): DirectMessage {
+    const recipients = status.mentions
+      .filter((m) => m.id !== status.account.id)
+      .map((m) => m.acct);
+    const fallback = participants.filter((a) => a.id !== status.account.id).map((a) => a.acct);
+    const to = recipients.length > 0 ? recipients : fallback.length > 0 ? fallback : [self.acct];
+    return {
+      id: status.id,
+      provider: PROVIDER,
+      conversationRemoteId,
+      fromHandle: status.account.acct,
+      toHandle: to.join(","),
+      text: htmlToText(status.content),
+      sentAt: new Date(status.created_at),
+    };
+  }
+
+  const connector: PlatformConnector = {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async buildAuthorizationUrl(input) {
+      try {
+        await connector.authorize(input);
+        throw new ConnectorError("authorization redirect missing", PROVIDER);
+      } catch (error) {
+        if (!(error instanceof AuthorizationRedirectRequired)) throw error;
+        const connection: ConnectorConnection = {
+          id: error.connectionId, workspaceId: input.workspaceId, provider: PROVIDER,
+          channelId: error.connectionId, credentialId: { kind: "credential-ref", id: error.connectionId },
+          fields: { instanceUrl: normalizeInstanceUrl(input.fields?.instanceUrl ?? "") }, createdAt: new Date(),
+        };
+        return { authorizationUrl: error.authorizationUrl, connection };
+      }
+    },
+
+    async exchangeCode(input) {
+      return connector.authorize({ ...input, providerMetadata: { code: input.code } } as MastodonAuthorizationRequest);
+    },
+
+    /**
+     * Leg 1 (no code): register an app on the instance when no client
+     * credentials exist, store them, throw AuthorizationRedirectRequired with
+     * the consent URL. Leg 2 (providerMetadata.code): exchange the code,
+     * store tokens, return the connection and identity.
+     */
+    async authorize(input: MastodonAuthorizationRequest): Promise<AuthorizationResult> {
+      const meta = input.providerMetadata ?? {};
+      const rawInstance = str(input.fields?.instanceUrl) ?? str(meta.instanceUrl);
+      if (rawInstance === undefined) {
+        throw new ConnectorError("authorize needs fields.instanceUrl", PROVIDER);
+      }
+      const instanceUrl = normalizeInstanceUrl(rawInstance);
+      const host = new URL(instanceUrl).host;
+      const connectionId = input.connectionId ?? str(meta.connectionId) ?? `${PROVIDER}:${input.workspaceId}:${host}`;
+      const fields: Record<string, string> = { instanceUrl };
+      const env = options.env ?? {};
+      const configuredInstance = env.MASTODON_INSTANCE_URL;
+      const useConfigured = configuredInstance !== undefined && normalizeInstanceUrl(configuredInstance) === instanceUrl;
+      const fieldClientId = str(input.fields?.clientId) ?? str(meta.clientId) ?? (useConfigured ? str(env.MASTODON_CLIENT_ID) : undefined);
+      if (fieldClientId !== undefined) fields.clientId = fieldClientId;
+      const credentialId: CredentialRef = { kind: "credential-ref", id: connectionId };
+      const connection: ConnectorConnection = {
+        id: connectionId,
+        workspaceId: input.workspaceId,
+        provider: PROVIDER,
+        channelId: str(meta.channelId) ?? connectionId,
+        credentialId,
+        fields,
+        createdAt: new Date(),
+      };
+
+      const fieldSecret = str(input.fields?.clientSecret) ?? str(meta.clientSecret) ?? (useConfigured ? str(env.MASTODON_CLIENT_SECRET) : undefined);
+      if (fieldClientId !== undefined && fieldSecret !== undefined) {
+        await credentials.put(connection, SECRET.clientId, fieldClientId);
+        await credentials.put(connection, SECRET.clientSecret, fieldSecret);
+      }
+      let client = await clientCredentials(connection);
+      if (client === undefined) {
+        const app = await form<MastodonApp>(`${instanceUrl}/api/v1/apps`, {
+          client_name: options.clientName ?? "AnarchoPoster",
+          redirect_uris: input.redirectUri,
+          scopes: SCOPES.join(" "),
+          ...(options.website !== undefined ? { website: options.website } : {}),
+        });
+        await credentials.put(connection, SECRET.clientId, app.client_id);
+        await credentials.put(connection, SECRET.clientSecret, app.client_secret);
+        client = { clientId: app.client_id, clientSecret: app.client_secret };
+      }
+
+      const code = str(meta.code);
+      if (code === undefined) {
+        const url = new URL(`${instanceUrl}/oauth/authorize`);
+        url.searchParams.set("client_id", client.clientId);
+        url.searchParams.set("redirect_uri", input.redirectUri);
+        url.searchParams.set("response_type", "code");
+        url.searchParams.set("scope", SCOPES.join(" "));
+        url.searchParams.set("state", input.state);
+        if (input.codeVerifier !== undefined) {
+          url.searchParams.set("code_challenge", createHash("sha256").update(input.codeVerifier).digest("base64url"));
+          url.searchParams.set("code_challenge_method", "S256");
+        }
+        throw new AuthorizationRedirectRequired(url.toString(), connectionId);
+      }
+
+      const token = await form<MastodonToken>(`${instanceUrl}/oauth/token`, {
+        grant_type: "authorization_code",
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        redirect_uri: input.redirectUri,
+        code,
+        scope: SCOPES.join(" "),
+        ...(input.codeVerifier !== undefined ? { code_verifier: input.codeVerifier } : {}),
+      });
+      await storeTokens(connection, token);
+      accounts.delete(connection.id);
+      const identity = identityOf(connection, await selfAccount(connection));
+      return { connection, identity };
+    },
+
+    async refreshCredentials(connection: ConnectorConnection): Promise<CredentialRef> {
+      const refreshToken = await secretOrUndefined(connection, SECRET.refreshToken);
+      if (refreshToken === undefined) {
+        throw new AuthError(
+          "no refresh token stored — this instance issued a non-expiring token; reauthorize if revoked",
+          PROVIDER,
+          false,
+        );
+      }
+      const client = await clientCredentials(connection);
+      if (client === undefined) throw new AuthError("no client credentials for refresh", PROVIDER, false);
+      const token = await form<MastodonToken>(`${instanceOf(connection)}/oauth/token`, {
+        grant_type: "refresh_token",
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        refresh_token: refreshToken,
+        scope: SCOPES.join(" "),
+      });
+      await storeTokens(connection, token);
+      return connection.credentialId;
+    },
+
+    async revokeCredentials(connection: ConnectorConnection): Promise<void> {
+      const client = await clientCredentials(connection);
+      if (client === undefined) throw new AuthError("no client credentials for revoke", PROVIDER, false);
+      await form<Record<string, never>>(`${instanceOf(connection)}/oauth/revoke`, {
+        client_id: client.clientId,
+        client_secret: client.clientSecret,
+        token: await credentials.getAccessToken(connection),
+      });
+      accounts.delete(connection.id);
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return identityOf(connection, await selfAccount(connection));
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const meta = post.providerMetadata;
+      const preUploaded = Array.isArray(meta.mediaIds)
+        ? meta.mediaIds.filter((id): id is string => typeof id === "string")
+        : [];
+      const altText =
+        typeof meta.altText === "object" && meta.altText !== null
+          ? (meta.altText as Record<string, unknown>)
+          : {};
+      const mediaIds = [...preUploaded, ...(await uploadAll(connection, post.mediaAssetIds, altText))];
+      if (mediaIds.length > MAX_MEDIA) {
+        throw new ConnectorError(`at most ${MAX_MEDIA} media attachments per status`, PROVIDER);
+      }
+
+      const body: Record<string, unknown> = { status: post.text };
+      if (mediaIds.length > 0) body.media_ids = mediaIds;
+      const visibility = VISIBILITY[post.visibility];
+      if (visibility !== undefined) body.visibility = visibility;
+      if (post.scheduledAt !== undefined && post.scheduledAt.getTime() - Date.now() >= MIN_SCHEDULE_LEAD_MS) {
+        body.scheduled_at = post.scheduledAt.toISOString();
+      }
+      const inReplyTo = str(meta.inReplyToId);
+      if (inReplyTo !== undefined) body.in_reply_to_id = inReplyTo;
+      const language = str(meta.language);
+      if (language !== undefined) body.language = language;
+      if (typeof meta.sensitive === "boolean") body.sensitive = meta.sensitive;
+      const spoiler = str(meta.spoilerText);
+      if (spoiler !== undefined) body.spoiler_text = spoiler;
+
+      const headers: Record<string, string> = {};
+      const idempotencyKey = str(meta.idempotencyKey);
+      if (idempotencyKey !== undefined) headers["idempotency-key"] = idempotencyKey;
+
+      const { data } = await api<MastodonStatus | MastodonScheduledStatus>(
+        connection,
+        "POST",
+        "/api/v1/statuses",
+        body,
+        headers,
+      );
+      // Draft identity is owned by the caller (the publishing runtime keys
+      // receipts by idempotency key); the returned id/draftId are local only.
+      const receipt = idempotencyKey === undefined ? {} : { idempotencyKey };
+      if (isScheduled(data)) {
+        return {
+          id: randomUUID(),
+          workspaceId: connection.workspaceId,
+          draftId: "direct",
+          connectionId: connection.id,
+          remoteId: `scheduled:${data.id}`,
+          publishedAt: new Date(data.scheduled_at),
+          providerMetadata: {
+            outcome: "provider_scheduled",
+            scheduled: true,
+            scheduledStatusId: data.id,
+            scheduledAt: data.scheduled_at,
+            ...receipt,
+          },
+        };
+      }
+      return toPublication(connection, data, "direct", { outcome: "published", ...receipt });
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      const path = remoteId.startsWith("scheduled:")
+        ? `/api/v1/scheduled_statuses/${encodeURIComponent(remoteId.slice("scheduled:".length))}`
+        : `/api/v1/statuses/${encodeURIComponent(remoteId)}`;
+      try {
+        await api(connection, "DELETE", path);
+      } catch (error) {
+        // Already gone counts as deleted — deletion is idempotent.
+        const status = error instanceof ConnectorError ? (error.cause as { status?: number } | undefined)?.status : undefined;
+        if (status !== 404) throw error;
+      }
+    },
+
+    async uploadMedia(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia> {
+      return uploadAsset(connection, media);
+    },
+
+    async getFeed(
+      connection: ConnectorConnection,
+      request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+    ): Promise<Page<FeedItem>> {
+      const limit = Math.max(1, Math.min(40, request.limit));
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (request.cursor !== undefined) params.set("max_id", request.cursor);
+
+      if (request.kind === "home") {
+        return statusPage(connection, "/api/v1/timelines/home", params, limit);
+      }
+      if (request.kind === "search") {
+        const tag = (request.query ?? "").trim().replace(/^#/, "");
+        if (!/^[\p{L}\p{N}_]+$/u.test(tag)) {
+          throw new ConnectorError("search supports a single hashtag only", PROVIDER);
+        }
+        return statusPage(connection, `/api/v1/timelines/tag/${encodeURIComponent(tag)}`, params, limit);
+      }
+      params.append("types[]", "mention");
+      const { data, response } = await api<MastodonNotification[]>(
+        connection,
+        "GET",
+        `/api/v1/notifications?${params}`,
+      );
+      const items = data
+        .map((n) => n.status)
+        .filter((s): s is MastodonStatus => s !== null && s !== undefined)
+        .map(toFeedItem);
+      const fallback = data.length >= limit ? data[data.length - 1]?.id : undefined;
+      return pageOf(items, nextMaxId(response) ?? fallback);
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const { data } = await api<MastodonContext>(
+        connection,
+        "GET",
+        `/api/v1/statuses/${encodeURIComponent(request.onRemoteId)}/context`,
+      );
+      // /context is not paginated; the cursor is an offset into descendants.
+      const start = request.cursor !== undefined ? Number(request.cursor) : 0;
+      const slice = data.descendants.slice(start, start + request.limit);
+      const comments = slice.map(
+        (s): Comment => ({
+          id: s.id,
+          provider: PROVIDER,
+          remoteId: s.id,
+          onRemoteId: s.in_reply_to_id ?? request.onRemoteId,
+          authorHandle: s.account.acct,
+          text: htmlToText(s.content),
+          createdAt: new Date(s.created_at),
+        }),
+      );
+      const next = start + request.limit;
+      return pageOf(comments, next < data.descendants.length ? String(next) : undefined);
+    },
+
+    /**
+     * Replies inherit the target's visibility (a reply to a DM stays direct)
+     * and mention the target's author so they are notified.
+     */
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const target = await getStatus(connection, request.onRemoteId);
+      const self = await selfAccount(connection);
+      const handle = `@${target.account.acct}`;
+      const needsMention =
+        target.account.id !== self.id && !request.text.toLowerCase().includes(handle.toLowerCase());
+      const { data } = await api<MastodonStatus>(connection, "POST", "/api/v1/statuses", {
+        status: needsMention ? `${handle} ${request.text}` : request.text,
+        in_reply_to_id: target.id,
+        visibility: target.visibility,
+      });
+      return toPublication(connection, data, "reply", { inReplyTo: target.id });
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: {
+        kind: "repost" | "quote" | "share";
+        targetRemoteId: string;
+        commentary?: string;
+        quoteAssetIds?: string[];
+      },
+    ): Promise<Publication> {
+      const target = encodeURIComponent(request.targetRemoteId);
+      if (request.kind === "repost") {
+        const { data } = await api<MastodonStatus>(connection, "POST", `/api/v1/statuses/${target}/reblog`);
+        return toPublication(connection, data, "amplify:repost", {
+          amplifies: request.targetRemoteId,
+          kind: "repost",
+        });
+      }
+      if (request.kind === "quote") {
+        const mediaIds = await uploadAll(connection, request.quoteAssetIds ?? []);
+        const body: Record<string, unknown> = {
+          status: request.commentary ?? "",
+          quoted_status_id: request.targetRemoteId,
+        };
+        if (mediaIds.length > 0) body.media_ids = mediaIds;
+        const { data } = await api<MastodonStatus>(connection, "POST", "/api/v1/statuses", body);
+        if (data.quote === undefined || data.quote === null) {
+          // Pre-4.5 server dropped quoted_status_id and posted a plain status.
+          await deleteStatus(connection, data.id);
+          throw new CapabilityNotSupportedError(PROVIDER, "amplifyQuote (instance older than 4.5)");
+        }
+        return toPublication(connection, data, "amplify:quote", {
+          amplifies: request.targetRemoteId,
+          kind: "quote",
+          quoteState: data.quote.state,
+        });
+      }
+      throw new CapabilityNotSupportedError(PROVIDER, "amplifyShare");
+    },
+
+    /**
+     * Reblog wrappers are undone via POST /:originalId/unreblog (the endpoint
+     * takes the original's id, not the wrapper's); quotes are deleted.
+     */
+    async unamplify(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      const status = await getStatus(connection, remoteId);
+      if (status.reblog !== null) {
+        await api(connection, "POST", `/api/v1/statuses/${encodeURIComponent(status.reblog.id)}/unreblog`);
+        return;
+      }
+      await deleteStatus(connection, status.id);
+    },
+
+    async getMessages(
+      connection: ConnectorConnection,
+      request: { conversationRemoteId?: string; cursor?: string; limit: number },
+    ): Promise<Page<DirectMessage>> {
+      const self = await selfAccount(connection);
+      const limit = Math.max(1, Math.min(40, request.limit));
+
+      if (request.conversationRemoteId === undefined) {
+        const params = new URLSearchParams({ limit: String(limit) });
+        if (request.cursor !== undefined) params.set("max_id", request.cursor);
+        const { data, response } = await api<MastodonConversation[]>(
+          connection,
+          "GET",
+          `/api/v1/conversations?${params}`,
+        );
+        const items = data
+          .filter((c) => c.last_status !== null)
+          .map((c) => messageOf(c.id, c.last_status as MastodonStatus, self, c.accounts));
+        // Conversation pagination ids are internal — only the Link header is authoritative.
+        return pageOf(items, nextMaxId(response));
+      }
+
+      // No GET /conversations/:id exists: find the conversation, then read its thread.
+      let found: MastodonConversation | undefined;
+      let maxId: string | undefined;
+      for (let page = 0; page < CONVERSATION_SCAN_PAGES && found === undefined; page += 1) {
+        const params = new URLSearchParams({ limit: "40" });
+        if (maxId !== undefined) params.set("max_id", maxId);
+        const { data, response } = await api<MastodonConversation[]>(
+          connection,
+          "GET",
+          `/api/v1/conversations?${params}`,
+        );
+        found = data.find((c) => c.id === request.conversationRemoteId);
+        maxId = nextMaxId(response);
+        if (maxId === undefined) break;
+      }
+      if (found?.last_status === null || found?.last_status === undefined) {
+        throw new ConnectorError(`conversation ${request.conversationRemoteId} not found`, PROVIDER);
+      }
+      const conversation = found;
+      const last = found.last_status;
+      const { data: context } = await api<MastodonContext>(
+        connection,
+        "GET",
+        `/api/v1/statuses/${encodeURIComponent(last.id)}/context`,
+      );
+      const thread = [...context.ancestors, last, ...context.descendants].filter((s) => s.visibility === "direct");
+      const start = request.cursor !== undefined ? Number(request.cursor) : 0;
+      const items = thread
+        .slice(start, start + limit)
+        .map((s) => messageOf(conversation.id, s, self, conversation.accounts));
+      const next = start + limit;
+      return pageOf(items, next < thread.length ? String(next) : undefined);
+    },
+  };
+  return connector;
+}
diff --git a/packages/connector-mastodon/tsconfig.json b/packages/connector-mastodon/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-mastodon/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-mock-livestream/package.json b/packages/connector-mock-livestream/package.json
new file mode 100644
index 0000000..25fce9a
--- /dev/null
+++ b/packages/connector-mock-livestream/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-mock-livestream",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-mock-livestream/src/contract.test.ts b/packages/connector-mock-livestream/src/contract.test.ts
new file mode 100644
index 0000000..d44e4b9
--- /dev/null
+++ b/packages/connector-mock-livestream/src/contract.test.ts
@@ -0,0 +1,44 @@
+import { describe, expect, it } from "vitest";
+import {
+  createMockLivestreamConnector,
+  createMockLivestreamState,
+  transitionMockLive,
+} from "./index.js";
+import {
+  connectorContractTests,
+  livestreamConnectorContractTests,
+} from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+
+const connection: ConnectorConnection = {
+  id: "conn-live",
+  workspaceId: "ws-1",
+  provider: "mock-livestream",
+  channelId: "ch-1",
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: {},
+  createdAt: new Date(),
+};
+
+connectorContractTests(createMockLivestreamConnector(createMockLivestreamState()), { connection });
+livestreamConnectorContractTests(
+  createMockLivestreamConnector(createMockLivestreamState()),
+  { connection },
+);
+
+describe("mock-livestream scripted transitions", () => {
+  it("state transitions are visible to the monitor side", async () => {
+    const state = createMockLivestreamState();
+    const connector = createMockLivestreamConnector(state);
+    const live = await connector.createLiveStream?.(connection, {
+      channelId: "ch-1",
+      title: "fixture",
+      permanent: false,
+      saveReplay: false,
+    });
+    expect(live?.state).toBe("created");
+    transitionMockLive(state, live!.remoteId, "live");
+    const page = await connector.getLiveStreams?.(connection, { limit: 10 });
+    expect(page?.items[0]?.state).toBe("live");
+  });
+});
diff --git a/packages/connector-mock-livestream/src/index.ts b/packages/connector-mock-livestream/src/index.ts
new file mode 100644
index 0000000..969c92c
--- /dev/null
+++ b/packages/connector-mock-livestream/src/index.ts
@@ -0,0 +1,190 @@
+/**
+ * Deterministic livestream mock: create/manage lives, live chat
+ * read/write/moderation, playback sources, and a scripted state transition
+ * hook for Auto Director tests.
+ */
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  LiveChatMessage,
+  LiveStream,
+  NormalizedIdentity,
+  Page,
+  StreamPlaybackSource,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  pageOf,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  livestreams: true,
+  createLivestream: true,
+  manageLivestream: true,
+  livePlaybackSource: true,
+  liveChatRead: true,
+  liveChatWrite: true,
+  liveChatModeration: true,
+  livestreamAnalytics: true,
+};
+
+let seq = 0;
+const nextId = (prefix: string): string => `${prefix}-${(seq += 1)}`;
+
+interface MockLive extends LiveStream {
+  chat: LiveChatMessage[];
+}
+
+export interface MockLivestreamState {
+  lives: Map<string, MockLive>;
+}
+
+export function createMockLivestreamState(): MockLivestreamState {
+  return { lives: new Map() };
+}
+
+export function createMockLivestreamConnector(
+  state: MockLivestreamState = createMockLivestreamState(),
+): PlatformConnector {
+  const manifest: ConnectorManifest = {
+    id: "mock-livestream",
+    displayName: "Mock Livestream",
+    capabilities: CAPABILITIES,
+    connectionFields: [{ name: "apiToken", label: "API token", required: true, secret: true }],
+  };
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new Error("mock-livestream uses token auth in tests only");
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return {
+        provider: manifest.id,
+        remoteId: connection.channelId,
+        handle: "mock@live",
+        displayName: "Mock Live Channel",
+      };
+    },
+
+    async createLiveStream(
+      _connection: ConnectorConnection,
+      request: { channelId: string; title: string; permanent: boolean; saveReplay: boolean },
+    ): Promise<LiveStream> {
+      const remoteId = nextId("live");
+      const live: MockLive = {
+        id: remoteId,
+        provider: manifest.id,
+        connectionId: "pending",
+        remoteId,
+        title: request.title,
+        state: "created",
+        streamKeyRef: { kind: "credential-ref", id: nextId("keyref") },
+        rtmpUrl: "rtmp://mock.local/live",
+        playbackUrls: [`https://mock.local/hls/${remoteId}/master.m3u8`],
+        chat: [],
+      };
+      state.lives.set(remoteId, live);
+      return live;
+    },
+
+    async updateLiveStream(
+      _connection: ConnectorConnection,
+      request: { remoteId: string; title?: string },
+    ): Promise<LiveStream> {
+      const live = state.lives.get(request.remoteId);
+      if (live === undefined) throw new Error(`no live ${request.remoteId}`);
+      if (request.title !== undefined) live.title = request.title;
+      return live;
+    },
+
+    async getLiveStreams(
+      _connection: ConnectorConnection,
+      request: { cursor?: string; limit: number },
+    ): Promise<Page<LiveStream>> {
+      const all = [...state.lives.values()];
+      const start = request.cursor ? Number(request.cursor) : 0;
+      const items = all.slice(start, start + request.limit);
+      const next = start + request.limit;
+      return next < all.length ? pageOf(items, String(next)) : pageOf(items);
+    },
+
+    async getStreamPlaybackSources(
+      _connection: ConnectorConnection,
+      request: { remoteId: string },
+    ): Promise<StreamPlaybackSource[]> {
+      const live = state.lives.get(request.remoteId);
+      if (live === undefined) return [];
+      return [
+        {
+          remoteId: live.remoteId,
+          url: `https://mock.local/hls/${live.remoteId}/master.m3u8`,
+          kind: "hls",
+          protocol: "https",
+        },
+      ];
+    },
+
+    async getLiveChat(
+      _connection: ConnectorConnection,
+      request: { liveRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<LiveChatMessage>> {
+      const live = state.lives.get(request.liveRemoteId);
+      if (live === undefined) return pageOf([]);
+      const start = request.cursor ? Number(request.cursor) : 0;
+      const items = live.chat.slice(start, start + request.limit);
+      const next = start + request.limit;
+      return next < live.chat.length ? pageOf(items, String(next)) : pageOf(items);
+    },
+
+    async sendLiveChatMessage(
+      _connection: ConnectorConnection,
+      request: { liveRemoteId: string; text: string },
+    ): Promise<LiveChatMessage> {
+      const live = state.lives.get(request.liveRemoteId);
+      if (live === undefined) throw new Error(`no live ${request.liveRemoteId}`);
+      const message: LiveChatMessage = {
+        id: nextId("msg"),
+        provider: manifest.id,
+        liveStreamId: live.remoteId,
+        authorHandle: "mock@live",
+        text: request.text,
+        sentAt: new Date(),
+        isModerated: false,
+      };
+      live.chat.push(message);
+      return message;
+    },
+
+    async moderateLiveChat(
+      _connection: ConnectorConnection,
+      request: { liveRemoteId: string; messageRemoteId: string; action: "delete" | "timeout" | "ban" },
+    ): Promise<void> {
+      const live = state.lives.get(request.liveRemoteId);
+      if (live === undefined) return;
+      for (const message of live.chat) {
+        if (message.id === request.messageRemoteId && request.action === "delete") {
+          message.isModerated = true;
+        }
+      }
+    },
+  };
+}
+
+/** Test hook: scripted state transitions for Auto Director fixtures. */
+export function transitionMockLive(
+  state: MockLivestreamState,
+  remoteId: string,
+  to: LiveStream["state"],
+): void {
+  const live = state.lives.get(remoteId);
+  if (live === undefined) throw new Error(`no live ${remoteId}`);
+  live.state = to;
+}
diff --git a/packages/connector-mock-livestream/tsconfig.json b/packages/connector-mock-livestream/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-mock-livestream/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-mock-social/package.json b/packages/connector-mock-social/package.json
new file mode 100644
index 0000000..15c3a80
--- /dev/null
+++ b/packages/connector-mock-social/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-mock-social",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-mock-social/src/contract.test.ts b/packages/connector-mock-social/src/contract.test.ts
new file mode 100644
index 0000000..f1eb574
--- /dev/null
+++ b/packages/connector-mock-social/src/contract.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, it } from "vitest";
+import { createMockSocialConnector, createMockSocialState } from "./index.js";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+
+const connection: ConnectorConnection = {
+  id: "conn-social",
+  workspaceId: "ws-1",
+  provider: "mock-social",
+  channelId: "ch-1",
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: {},
+  createdAt: new Date(),
+};
+
+connectorContractTests(createMockSocialConnector(createMockSocialState()), { connection });
+
+describe("mock-social behavior", () => {
+  it("publish then feed shows the post, delete removes it", async () => {
+    const state = createMockSocialState();
+    const connector = createMockSocialConnector(state);
+    const pub = await connector.publish?.(connection, {
+      text: "hello world",
+      mediaAssetIds: [],
+      visibility: "public",
+      providerMetadata: {},
+    });
+    expect(pub?.remoteId).toBeTruthy();
+    const feed = await connector.getFeed?.(connection, { kind: "home", limit: 10 });
+    expect(feed?.items[0]?.text).toBe("hello world");
+    await connector.deletePublication?.(connection, pub!.remoteId);
+    const after = await connector.getFeed?.(connection, { kind: "home", limit: 10 });
+    expect(after?.items.some((i) => i.remoteId === pub?.remoteId)).toBe(false);
+  });
+
+  it("amplify repost and quote create new feed items referencing the target", async () => {
+    const state = createMockSocialState();
+    const connector = createMockSocialConnector(state);
+    const pub = await connector.publish?.(connection, {
+      text: "original",
+      mediaAssetIds: [],
+      visibility: "public",
+      providerMetadata: {},
+    });
+    const repost = await connector.amplify?.(connection, {
+      kind: "repost",
+      targetRemoteId: pub!.remoteId,
+    });
+    expect(repost?.providerMetadata).toMatchObject({ amplifies: pub!.remoteId, kind: "repost" });
+    const quote = await connector.amplify?.(connection, {
+      kind: "quote",
+      targetRemoteId: pub!.remoteId,
+      commentary: "important",
+    });
+    const feed = await connector.getFeed?.(connection, { kind: "home", limit: 10 });
+    expect(feed?.items[0]?.text).toContain("important ↻ original");
+    expect(quote).toBeTruthy();
+  });
+});
diff --git a/packages/connector-mock-social/src/index.ts b/packages/connector-mock-social/src/index.ts
new file mode 100644
index 0000000..40b4728
--- /dev/null
+++ b/packages/connector-mock-social/src/index.ts
@@ -0,0 +1,199 @@
+/**
+ * Deterministic social mock: publish (text/images/carousel), feed, comments,
+ * replies, webhooks. In-memory state — CI runs need no network.
+ */
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  FeedItem,
+  NormalizedIdentity,
+  NormalizedPost,
+  NormalizedWebhookEvent,
+  Page,
+  Publication,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  pageOf,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  publishCarousel: true,
+  feed: true,
+  mentions: true,
+  comments: true,
+  replies: true,
+  amplifyRepost: true,
+  amplifyQuote: true,
+  webhooks: true,
+  deletePublication: true,
+};
+
+let seq = 0;
+const nextId = (prefix: string): string => `${prefix}-${(seq += 1)}`;
+
+export interface MockSocialState {
+  publications: Map<string, Publication>;
+  feed: FeedItem[];
+  comments: Map<string, Comment[]>;
+}
+
+export function createMockSocialState(): MockSocialState {
+  return { publications: new Map(), feed: [], comments: new Map() };
+}
+
+export function createMockSocialConnector(
+  state: MockSocialState = createMockSocialState(),
+): PlatformConnector {
+  const manifest: ConnectorManifest = {
+    id: "mock-social",
+    displayName: "Mock Social",
+    capabilities: CAPABILITIES,
+    connectionFields: [{ name: "apiToken", label: "API token", required: true, secret: true }],
+    webhookRoute: "/webhooks/mock-social",
+  };
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new Error("mock-social uses token auth in tests only");
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return {
+        provider: manifest.id,
+        remoteId: connection.channelId,
+        handle: "mock@social",
+        displayName: "Mock Social Account",
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const publication: Publication = {
+        id: nextId("pub"),
+        workspaceId: connection.workspaceId,
+        draftId: "direct",
+        connectionId: connection.id,
+        remoteId: nextId("remote"),
+        publishedAt: new Date(),
+        providerMetadata: post.providerMetadata,
+      };
+      state.publications.set(publication.remoteId, publication);
+      state.feed.unshift({
+        id: publication.remoteId,
+        provider: manifest.id,
+        remoteId: publication.remoteId,
+        authorHandle: "mock@social",
+        text: post.text,
+        mediaUrls: [],
+        createdAt: publication.publishedAt,
+        metrics: {},
+      });
+      return publication;
+    },
+
+    async deletePublication(_connection: ConnectorConnection, remoteId: string): Promise<void> {
+      state.publications.delete(remoteId);
+      state.feed = state.feed.filter((item) => item.remoteId !== remoteId);
+    },
+
+    async getFeed(
+      _connection: ConnectorConnection,
+      request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+    ): Promise<Page<FeedItem>> {
+      const filtered =
+        request.kind === "search" && request.query
+          ? state.feed.filter((item) => item.text.includes(request.query ?? ""))
+          : state.feed;
+      const start = request.cursor ? Number(request.cursor) : 0;
+      const items = filtered.slice(start, start + request.limit);
+      const next = start + request.limit;
+      return next < filtered.length ? pageOf(items, String(next)) : pageOf(items);
+    },
+
+    async getComments(
+      _connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const all = state.comments.get(request.onRemoteId) ?? [];
+      return pageOf(all.slice(0, request.limit));
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const existing = state.comments.get(request.onRemoteId) ?? [];
+      const comment: Comment = {
+        id: nextId("comment"),
+        provider: manifest.id,
+        remoteId: nextId("cremote"),
+        onRemoteId: request.onRemoteId,
+        authorHandle: "mock@social",
+        text: request.text,
+        createdAt: new Date(),
+      };
+      existing.push(comment);
+      state.comments.set(request.onRemoteId, existing);
+      return {
+        id: comment.id,
+        workspaceId: connection.workspaceId,
+        draftId: "reply",
+        connectionId: connection.id,
+        remoteId: comment.remoteId,
+        publishedAt: comment.createdAt,
+        providerMetadata: {},
+      };
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: { kind: "repost" | "quote" | "share"; targetRemoteId: string; commentary?: string },
+    ): Promise<Publication> {
+      const target = state.feed.find((item) => item.remoteId === request.targetRemoteId);
+      if (target === undefined) throw new Error(`no item ${request.targetRemoteId} to amplify`);
+      const amplified: Publication = {
+        id: nextId("amp"),
+        workspaceId: connection.workspaceId,
+        draftId: `amplify:${request.kind}`,
+        connectionId: connection.id,
+        remoteId: nextId("remote"),
+        publishedAt: new Date(),
+        providerMetadata: { amplifies: request.targetRemoteId, kind: request.kind },
+      };
+      state.feed.unshift({
+        id: amplified.remoteId,
+        provider: manifest.id,
+        remoteId: amplified.remoteId,
+        authorHandle: "mock@social",
+        text: request.kind === "quote" ? `${request.commentary ?? ""} ↻ ${target.text}` : `↻ ${target.text}`,
+        mediaUrls: [],
+        createdAt: amplified.publishedAt,
+        metrics: {},
+      });
+      return amplified;
+    },
+
+    async subscribeWebhooks() {
+      return { subscriptionId: nextId("hook") };
+    },
+
+    async handleWebhook(request: { headers: Record<string, string>; body: unknown }): Promise<NormalizedWebhookEvent> {
+      return {
+        provider: manifest.id,
+        eventType: "mock.event",
+        payload: (request.body as Record<string, unknown>) ?? {},
+        receivedAt: new Date(),
+      };
+    },
+  };
+}
diff --git a/packages/connector-mock-social/tsconfig.json b/packages/connector-mock-social/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-mock-social/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-mock-video/package.json b/packages/connector-mock-video/package.json
new file mode 100644
index 0000000..0882649
--- /dev/null
+++ b/packages/connector-mock-video/package.json
@@ -0,0 +1,21 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-mock-video",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-mock-video/src/contract.test.ts b/packages/connector-mock-video/src/contract.test.ts
new file mode 100644
index 0000000..7605b3e
--- /dev/null
+++ b/packages/connector-mock-video/src/contract.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import { createMockVideoConnector, createMockVideoState } from "./index.js";
+import { connectorContractTests, videoConnectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+
+const connection: ConnectorConnection = {
+  id: "conn-video",
+  workspaceId: "ws-1",
+  provider: "mock-video",
+  channelId: "ch-1",
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: {},
+  createdAt: new Date(),
+};
+
+connectorContractTests(createMockVideoConnector(createMockVideoState()), { connection });
+videoConnectorContractTests(createMockVideoConnector(createMockVideoState()), { connection });
+
+describe("mock-video processing machine", () => {
+  it("reaches ready after enough status polls", async () => {
+    const connector = createMockVideoConnector(createMockVideoState());
+    const upload = await connector.uploadVideo?.(connection, {
+      videoAssetId: "asset-1",
+      visibility: "provider_default",
+      formatIntent: "long_form",
+      providerMetadata: {},
+    });
+    expect(upload?.remoteId).toBeTruthy();
+    let status = await connector.getVideoStatus?.(connection, upload!.remoteId);
+    expect(status?.state).toBe("processing");
+    status = await connector.getVideoStatus?.(connection, upload!.remoteId);
+    expect(status?.state).toBe("ready");
+  });
+});
diff --git a/packages/connector-mock-video/src/index.ts b/packages/connector-mock-video/src/index.ts
new file mode 100644
index 0000000..2bcefbc
--- /dev/null
+++ b/packages/connector-mock-video/src/index.ts
@@ -0,0 +1,116 @@
+/**
+ * Deterministic video mock: upload → processing → ready state machine,
+ * library pagination, thumbnails/captions capability.
+ */
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  NormalizedIdentity,
+  NormalizedVideoPublication,
+  Page,
+  VideoProcessingStatus,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  pageOf,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishVideo: true,
+  longFormVideo: true,
+  videoThumbnails: true,
+  videoCaptions: true,
+  playlists: true,
+  videoAnalytics: true,
+};
+
+let seq = 0;
+const nextId = (prefix: string): string => `${prefix}-${(seq += 1)}`;
+
+interface MockVideo {
+  remoteId: string;
+  title?: string;
+  createdAt: Date;
+  processingAdvance: number;
+}
+
+export interface MockVideoState {
+  videos: MockVideo[];
+}
+
+export function createMockVideoState(): MockVideoState {
+  return { videos: [] };
+}
+
+export function createMockVideoConnector(
+  state: MockVideoState = createMockVideoState(),
+): PlatformConnector {
+  const manifest: ConnectorManifest = {
+    id: "mock-video",
+    displayName: "Mock Video",
+    capabilities: CAPABILITIES,
+    connectionFields: [{ name: "apiToken", label: "API token", required: true, secret: true }],
+  };
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new Error("mock-video uses token auth in tests only");
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return {
+        provider: manifest.id,
+        remoteId: connection.channelId,
+        handle: "mock@video",
+        displayName: "Mock Video Channel",
+      };
+    },
+
+    async uploadVideo(
+      _connection: ConnectorConnection,
+      video: NormalizedVideoPublication,
+    ): Promise<{ remoteId: string }> {
+      const remoteId = nextId("vid");
+      state.videos.push({
+        remoteId,
+        title: video.title,
+        createdAt: new Date(),
+        processingAdvance: 0,
+      });
+      return { remoteId };
+    },
+
+    async getVideoStatus(
+      _connection: ConnectorConnection,
+      remoteId: string,
+    ): Promise<VideoProcessingStatus> {
+      const video = state.videos.find((v) => v.remoteId === remoteId);
+      if (video === undefined) {
+        return { remoteId, state: "failed", error: "unknown remote id" };
+      }
+      video.processingAdvance = Math.min(100, video.processingAdvance + 50);
+      const state_: VideoProcessingStatus["state"] =
+        video.processingAdvance >= 100 ? "ready" : "processing";
+      return { remoteId, state: state_, progressPercent: video.processingAdvance };
+    },
+
+    async getVideos(
+      _connection: ConnectorConnection,
+      request: { cursor?: string; limit: number },
+    ): Promise<Page<{ remoteId: string; title?: string; createdAt?: Date }>> {
+      const start = request.cursor ? Number(request.cursor) : 0;
+      const items = state.videos
+        .slice(start, start + request.limit)
+        .map((v) => ({ remoteId: v.remoteId, title: v.title, createdAt: v.createdAt }));
+      const next = start + request.limit;
+      return next < state.videos.length ? pageOf(items, String(next)) : pageOf(items);
+    },
+  };
+}
diff --git a/packages/connector-mock-video/tsconfig.json b/packages/connector-mock-video/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-mock-video/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-peertube/package.json b/packages/connector-peertube/package.json
new file mode 100644
index 0000000..acd1dc7
--- /dev/null
+++ b/packages/connector-peertube/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-peertube",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-peertube/src/contract.test.ts b/packages/connector-peertube/src/contract.test.ts
new file mode 100644
index 0000000..7511ecb
--- /dev/null
+++ b/packages/connector-peertube/src/contract.test.ts
@@ -0,0 +1,842 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { AuthError, ConnectorError, InMemoryCredentials } from "@tactical-media-broadcast-hub/connector-sdk";
+import {
+  connectorContractTests,
+  livestreamConnectorContractTests,
+  videoConnectorContractTests,
+} from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import {
+  createPeerTubeConnector,
+  htmlToText,
+  normalizeHandle,
+  normalizeInstanceUrl,
+  streamKeySecretName,
+  type PeerTubeAuthorizationRequest,
+  type PeerTubeConnectorOptions,
+} from "./index.js";
+
+/**
+ * Stubbed PeerTube v8 REST API: one instance, one account with two
+ * channels, in-memory videos/lives/comments. Shapes follow the OpenAPI
+ * spec (docs/research/peertube-api-facts.md).
+ */
+const INSTANCE = "https://video.example";
+const HOST = "video.example";
+const ACCESS = "stub-access-1";
+const REFRESH = "stub-refresh-1";
+const SECRET_PASSWORD = "correct horse battery staple";
+const STREAM_KEY = "3fa1b2c4d5e6f708192a3b4c5d6e7f80";
+
+interface StubVideo {
+  id: number;
+  uuid: string;
+  name: string;
+  channelId: number;
+  isLive: boolean;
+  state: number;
+  createdAt: string;
+  permanentLive?: boolean;
+  saveReplay?: boolean;
+  latencyMode?: number;
+  privacy?: number;
+}
+
+interface StubCall {
+  method: string;
+  url: string;
+  init: RequestInit | undefined;
+}
+
+interface StubState {
+  calls: StubCall[];
+  videos: StubVideo[];
+  comments: { id: number; videoUuid: string; text: string; inReplyTo?: number }[];
+  validTokens: Set<string>;
+  tokenSeq: number;
+  /** When set, the next authenticated request with this token gets 401. */
+  expireToken?: string;
+  requireOtp: boolean;
+}
+
+function newState(): StubState {
+  return {
+    calls: [],
+    videos: [
+      {
+        id: 41,
+        uuid: "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
+        name: "Existing VOD",
+        channelId: 7,
+        isLive: false,
+        state: 1,
+        createdAt: "2026-10-01T10:00:00.000Z",
+      },
+    ],
+    comments: [],
+    validTokens: new Set([ACCESS]),
+    tokenSeq: 1,
+    requireOtp: false,
+  };
+}
+
+const ACCOUNT = {
+  id: 12,
+  name: "alice",
+  displayName: "Alice",
+  host: HOST,
+  avatars: [
+    { path: "/lazy-static/avatars/small.png", width: 48 },
+    { path: "/lazy-static/avatars/big.png", width: 120 },
+  ],
+};
+const CHANNELS = [
+  { id: 7, name: "alice_channel", displayName: "Alice's channel", host: HOST, avatars: [] },
+  { id: 8, name: "alice_live", displayName: "Alice Live", host: HOST, avatars: [] },
+];
+
+function json(body: unknown, status = 200, headers: Record<string, string> = {}): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json", ...headers },
+  });
+}
+
+function problem(status: number, detail: string, extra: Record<string, unknown> = {}): Response {
+  return json({ status, detail, ...extra }, status);
+}
+
+function urlOf(input: Parameters<typeof fetch>[0]): string {
+  return typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+}
+
+function header(init: RequestInit | undefined, name: string): string | undefined {
+  const headers = init?.headers;
+  if (headers === undefined || headers instanceof Headers || Array.isArray(headers)) return undefined;
+  return (headers as Record<string, string>)[name];
+}
+
+function jsonBody(init: RequestInit | undefined): Record<string, unknown> {
+  return JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+}
+
+function summary(video: StubVideo): Record<string, unknown> {
+  return {
+    id: video.id,
+    uuid: video.uuid,
+    shortUUID: `s${video.id}`,
+    name: video.name,
+    isLive: video.isLive,
+    state: { id: video.state, label: video.state === 7 ? "Transcoding failed" : "Published" },
+    createdAt: video.createdAt,
+    streamingPlaylists: video.isLive
+      ? []
+      : [{ id: 1, type: 1, playlistUrl: `${INSTANCE}/static/streaming-playlists/hls/${video.uuid}/aa11-master.m3u8` }],
+  };
+}
+
+function stubApi(state: StubState): typeof fetch {
+  return async (input, init) => {
+    const url = new URL(urlOf(input));
+    const method = init?.method ?? "GET";
+    state.calls.push({ method, url: url.href, init });
+    const path = url.pathname;
+
+    // Public endpoints.
+    if (path === "/api/v1/config/about") return json({ instance: { name: "Example Tube" } });
+    if (path === "/api/v1/oauth-clients/local") {
+      return json({ client_id: "local-client", client_secret: "local-client-secret" });
+    }
+    if (path === "/api/v1/users/token" && method === "POST") {
+      const form = new URLSearchParams(String(init?.body ?? ""));
+      if (form.get("client_id") !== "local-client" || form.get("client_secret") !== "local-client-secret") {
+        return problem(400, "Invalid client");
+      }
+      if (form.get("grant_type") === "password") {
+        if (form.get("username") !== "alice" || form.get("password") !== SECRET_PASSWORD) {
+          return problem(400, "Invalid grant: user credentials are invalid", { code: "invalid_grant" });
+        }
+        if (state.requireOtp && header(init, "x-peertube-otp") === undefined) {
+          return problem(401, "Missing two factor header", { code: "missing_two_factor" });
+        }
+        return json({ access_token: ACCESS, refresh_token: REFRESH, token_type: "Bearer", expires_in: 86400 });
+      }
+      if (form.get("grant_type") === "refresh_token") {
+        if (!String(form.get("refresh_token")).startsWith("stub-refresh")) return problem(400, "Invalid refresh token");
+        state.tokenSeq += 1;
+        const access = `stub-access-${state.tokenSeq}`;
+        state.validTokens.add(access);
+        return json({ access_token: access, refresh_token: `stub-refresh-${state.tokenSeq}`, token_type: "Bearer" });
+      }
+      return problem(400, "Unsupported grant");
+    }
+    if (path.startsWith("/static/")) return new Response("#EXTM3U", { status: 200 });
+
+    // Authenticated endpoints.
+    const bearer = header(init, "authorization")?.replace(/^Bearer /, "");
+    if (bearer === undefined || !state.validTokens.has(bearer)) return problem(401, "Token is invalid");
+    if (state.expireToken === bearer) {
+      state.validTokens.delete(bearer);
+      state.expireToken = undefined;
+      return problem(401, "Token is expired");
+    }
+
+    if (path === "/api/v1/users/me") {
+      return json({ id: 3, username: "alice", account: ACCOUNT, videoChannels: CHANNELS });
+    }
+    if (path === "/api/v1/users/revoke-token" && method === "POST") {
+      state.validTokens.delete(bearer);
+      return json({});
+    }
+    if (path === "/api/v1/accounts/alice/video-channels") return json({ total: 2, data: CHANNELS });
+    const channelMatch = /^\/api\/v1\/video-channels\/(.+)$/.exec(path);
+    if (channelMatch) {
+      const handle = decodeURIComponent(channelMatch[1] ?? "");
+      if (handle.startsWith("@")) return problem(404, "Video channel not found");
+      const name = handle.split("@")[0];
+      const channel = CHANNELS.find((c) => c.name === name) ?? (name === "channel-1" ? CHANNELS[1] : undefined);
+      return channel ? json(channel) : problem(404, "Video channel not found");
+    }
+    if (path === "/api/v1/server/stats") {
+      return json({ totalUsers: 40, totalLocalVideos: 120, totalLocalVideoViews: 9001, videosRedundancy: [] });
+    }
+    if (path === "/api/v1/users/me/videos") {
+      const start = Number(url.searchParams.get("start") ?? 0);
+      const count = Number(url.searchParams.get("count") ?? 15);
+      const onlyLive = url.searchParams.get("isLive") === "true";
+      const all = state.videos.filter((v) => !onlyLive || v.isLive).sort((a, b) => b.id - a.id);
+      return json({ total: all.length, data: all.slice(start, start + count).map(summary) });
+    }
+    if (path === "/api/v1/videos/upload" && method === "POST") {
+      const form = init?.body;
+      if (!(form instanceof FormData)) return problem(400, "multipart expected");
+      if (!(form.get("videofile") instanceof Blob)) return problem(400, "videofile missing");
+      const id = 100 + state.videos.length;
+      const video: StubVideo = {
+        id,
+        uuid: `a1b2c3d4-0000-4000-8000-${String(id).padStart(12, "0")}`,
+        name: String(form.get("name")),
+        channelId: Number(form.get("channelId")),
+        isLive: false,
+        state: 2,
+        createdAt: new Date().toISOString(),
+      };
+      state.videos.push(video);
+      return json({ video: { id, uuid: video.uuid, shortUUID: `s${id}` } });
+    }
+    if (path === "/api/v1/videos/live" && method === "POST") {
+      const body = jsonBody(init);
+      if (typeof body.channelId !== "number") return problem(400, "channelId must be a number");
+      if (body.saveReplay === true && body.permanentLive === true) return problem(400, "conflict");
+      const id = 200 + state.videos.length;
+      const video: StubVideo = {
+        id,
+        uuid: `b1c2d3e4-1111-4111-8111-${String(id).padStart(12, "0")}`,
+        name: String(body.name),
+        channelId: body.channelId,
+        isLive: true,
+        state: 4,
+        createdAt: new Date().toISOString(),
+        permanentLive: body.permanentLive === true,
+        saveReplay: body.saveReplay === true,
+        latencyMode: Number(body.latencyMode),
+        privacy: typeof body.privacy === "number" ? body.privacy : undefined,
+      };
+      state.videos.push(video);
+      return json({ video: { id, uuid: video.uuid, shortUUID: `s${id}` } });
+    }
+    const sessionsMatch = /^\/api\/v1\/videos\/live\/([^/]+)\/sessions$/.exec(path);
+    if (sessionsMatch) {
+      return json({
+        total: 2,
+        data: [
+          { id: 1, startDate: "2026-10-06T18:00:00.000Z", endDate: "2026-10-06T19:00:00.000Z", error: null },
+          { id: 2, startDate: "2026-10-07T18:00:00.000Z", endDate: null, error: null },
+        ],
+      });
+    }
+    const liveMatch = /^\/api\/v1\/videos\/live\/([^/]+)$/.exec(path);
+    if (liveMatch) {
+      const video = state.videos.find((v) => v.uuid === decodeURIComponent(liveMatch[1] ?? ""));
+      if (video === undefined || !video.isLive) return problem(404, "Live video not found");
+      return json({
+        rtmpUrl: `rtmp://${HOST}:1935/live`,
+        rtmpsUrl: null,
+        streamKey: STREAM_KEY,
+        saveReplay: video.saveReplay,
+        permanentLive: video.permanentLive,
+        latencyMode: video.latencyMode,
+      });
+    }
+    const statsMatch = /^\/api\/v1\/videos\/([^/]+)\/stats\/(overall|timeseries\/viewers)$/.exec(path);
+    if (statsMatch) {
+      if (statsMatch[2] === "overall") {
+        return json({ averageWatchTime: 42, totalWatchTime: 4200, viewersPeak: 17, totalViewers: 100, countries: [] });
+      }
+      return json({
+        groupInterval: "1 day",
+        data: [
+          { date: "2026-10-05T00:00:00.000Z", value: 30 },
+          { date: "2026-10-06T00:00:00.000Z", value: 70 },
+        ],
+      });
+    }
+    const threadsMatch = /^\/api\/v1\/videos\/([^/]+)\/comment-threads$/.exec(path);
+    if (threadsMatch) {
+      const videoUuid = decodeURIComponent(threadsMatch[1] ?? "");
+      if (method === "POST") {
+        const id = 500 + state.comments.length;
+        state.comments.push({ id, videoUuid, text: String(jsonBody(init).text) });
+        return json({ comment: { id, text: String(jsonBody(init).text), createdAt: new Date().toISOString(), url: `${INSTANCE}/videos/watch/${videoUuid};threadId=${id}` } });
+      }
+      return json({
+        total: 3,
+        data: [
+          { id: 1, text: "<p>Great &amp; <b>fun</b></p>", createdAt: "2026-10-06T10:00:00.000Z", isDeleted: false, account: { id: 99, name: "bob", host: "other.example" } },
+          { id: 2, text: "", createdAt: "2026-10-06T11:00:00.000Z", isDeleted: true, account: null },
+        ],
+      });
+    }
+    const replyMatch = /^\/api\/v1\/videos\/([^/]+)\/comments\/(\d+)$/.exec(path);
+    if (replyMatch && method === "POST") {
+      const id = 500 + state.comments.length;
+      state.comments.push({ id, videoUuid: decodeURIComponent(replyMatch[1] ?? ""), text: String(jsonBody(init).text), inReplyTo: Number(replyMatch[2]) });
+      return json({ comment: { id, text: String(jsonBody(init).text), createdAt: new Date().toISOString() } });
+    }
+    const videoMatch = /^\/api\/v1\/videos\/([^/]+)$/.exec(path);
+    if (videoMatch) {
+      const key = decodeURIComponent(videoMatch[1] ?? "");
+      const video = state.videos.find((v) => v.uuid === key || String(v.id) === key);
+      if (video === undefined) return problem(404, "Video not found");
+      if (method === "PUT") {
+        const form = init?.body;
+        if (!(form instanceof FormData)) return problem(400, "multipart expected");
+        const name = form.get("name");
+        if (typeof name === "string") video.name = name;
+        return new Response(null, { status: 204 });
+      }
+      return json(summary(video));
+    }
+    return problem(404, `no stub for ${method} ${path}`);
+  };
+}
+
+const connection: ConnectorConnection = {
+  id: "conn-peertube",
+  workspaceId: "ws-1",
+  provider: "peertube",
+  channelId: "7",
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: { instanceUrl: HOST, username: "alice" },
+  createdAt: new Date(),
+};
+
+interface Harness {
+  state: StubState;
+  credentials: InMemoryCredentials;
+  connector: ReturnType<typeof createPeerTubeConnector>;
+}
+
+function createHarness(overrides: Partial<PeerTubeConnectorOptions> = {}): Harness {
+  const state = newState();
+  const credentials = new InMemoryCredentials();
+  void credentials.put(connection, "access_token", ACCESS);
+  void credentials.put(connection, "refresh_token", REFRESH);
+  void credentials.put(connection, "client_id", "local-client");
+  void credentials.put(connection, "client_secret", "local-client-secret");
+  const connector = createPeerTubeConnector({
+    fetchImpl: stubApi(state),
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    credentials,
+    openAsset: async (assetId) =>
+      assetId.startsWith("thumb")
+        ? { bytes: new Uint8Array([137, 80, 78, 71]), filename: "thumb.png", mimeType: "image/png" }
+        : { bytes: new Uint8Array([0, 0, 0, 24]), filename: `${assetId}.mp4`, mimeType: "video/mp4" },
+    ...overrides,
+  });
+  return { state, credentials, connector };
+}
+
+const contractHarness = createHarness();
+connectorContractTests(contractHarness.connector, { connection });
+videoConnectorContractTests(contractHarness.connector, { connection });
+livestreamConnectorContractTests(contractHarness.connector, { connection });
+
+const authRequest = (
+  fields: Record<string, string>,
+  providerMetadata: Record<string, unknown> = {},
+): PeerTubeAuthorizationRequest => ({
+  redirectUri: "https://app.example.com/connections/callback",
+  workspaceId: "ws-1",
+  state: "st",
+  fields,
+  providerMetadata,
+});
+
+describe("peertube: manifest", () => {
+  it("declares the video/live surface and nothing text-shaped", () => {
+    const { connector } = createHarness();
+    const m = connector.manifest();
+    expect(m.id).toBe("peertube");
+    expect(m.displayName).toBe("PeerTube");
+    expect(m.capabilities).toMatchObject({
+      publishVideo: true,
+      longFormVideo: true,
+      comments: true,
+      replies: true,
+      livestreams: true,
+      createLivestream: true,
+      manageLivestream: true,
+      livePlaybackSource: true,
+      analytics: true,
+      publishText: false,
+      feed: false,
+      directMessages: false,
+      webhooks: false,
+    });
+    expect(m.oauth?.kind).toBe("per-instance-oauth2");
+    expect(connector.publish).toBeUndefined();
+    expect(connector.getFeed).toBeUndefined();
+    expect(connector.getMessages).toBeUndefined();
+    expect(connector.subscribeWebhooks).toBeUndefined();
+    // Core PeerTube has no live chat (plugin-only) → no method, no capability.
+    expect(connector.getLiveChat).toBeUndefined();
+  });
+
+  it("connection fields: instanceUrl + username in clear, account secret masked", () => {
+    const fields = createHarness().connector.manifest().connectionFields;
+    expect(fields.map((f) => [f.name, f.required, f.secret])).toEqual([
+      ["instanceUrl", true, false],
+      ["username", true, false],
+      ["accountSecret", true, true],
+    ]);
+  });
+});
+
+describe("peertube: authorize", () => {
+  it("fetches the local client, exchanges the password once, stores only tokens", async () => {
+    const state = newState();
+    const credentials = new InMemoryCredentials();
+    const connector = createPeerTubeConnector({
+      fetchImpl: stubApi(state),
+      requestsPerSecond: 1000,
+      sleep: async () => Promise.resolve(),
+      credentials,
+    });
+    const result = await connector.authorize(
+      authRequest({ instanceUrl: "https://video.example/", username: "alice", accountSecret: SECRET_PASSWORD }),
+    );
+    expect(state.calls.map((c) => `${c.method} ${new URL(c.url).pathname}`)).toEqual([
+      "GET /api/v1/config/about",
+      "GET /api/v1/oauth-clients/local",
+      "POST /api/v1/users/token",
+      "GET /api/v1/users/me",
+    ]);
+    const tokenForm = new URLSearchParams(String(state.calls[2]?.init?.body));
+    expect(tokenForm.get("grant_type")).toBe("password");
+    expect(tokenForm.get("client_id")).toBe("local-client");
+
+    const conn = result.connection;
+    expect(conn.fields).toEqual({ instanceUrl: INSTANCE, username: "alice" });
+    expect(JSON.stringify(conn)).not.toContain(SECRET_PASSWORD);
+    expect(await credentials.getAccessToken(conn)).toBe(ACCESS);
+    expect(await credentials.getSecret(conn, "refresh_token")).toBe(REFRESH);
+    for (const key of ["password", "accountSecret"]) {
+      await expect(credentials.getSecret(conn, key)).rejects.toThrow();
+    }
+    expect(result.identity).toMatchObject({
+      provider: "peertube",
+      remoteId: "12",
+      handle: "alice@video.example",
+      displayName: "Alice",
+      avatarUrl: "https://video.example/lazy-static/avatars/big.png",
+    });
+  });
+
+  it("rejects bad credentials with the instance's detail", async () => {
+    const { connector } = createHarness();
+    await expect(
+      connector.authorize(authRequest({ instanceUrl: HOST, username: "alice", accountSecret: "wrong" })),
+    ).rejects.toThrow(/user credentials are invalid/);
+  });
+
+  it("asks for a 2FA code and forwards it via x-peertube-otp", async () => {
+    const state = newState();
+    state.requireOtp = true;
+    const connector = createPeerTubeConnector({ fetchImpl: stubApi(state), requestsPerSecond: 1000 });
+    const fields = { instanceUrl: HOST, username: "alice", accountSecret: SECRET_PASSWORD };
+    await expect(connector.authorize(authRequest(fields))).rejects.toMatchObject({
+      name: "AuthError",
+      retryable: true,
+    });
+    const result = await connector.authorize(authRequest(fields, { otp: "123456" }));
+    expect(result.identity.handle).toBe("alice@video.example");
+    const tokenCall = state.calls.filter((c) => c.url.endsWith("/users/token")).at(-1);
+    expect(header(tokenCall?.init, "x-peertube-otp")).toBe("123456");
+  });
+
+  it("requires instanceUrl, username and accountSecret; refuses plain http", async () => {
+    const { connector } = createHarness();
+    await expect(connector.authorize(authRequest({ username: "alice", accountSecret: "x" }))).rejects.toThrow(/instanceUrl/);
+    await expect(connector.authorize(authRequest({ instanceUrl: HOST, accountSecret: "x" }))).rejects.toThrow(/username/);
+    await expect(connector.authorize(authRequest({ instanceUrl: HOST, username: "alice" }))).rejects.toThrow(/accountSecret/);
+    await expect(
+      connector.authorize(authRequest({ instanceUrl: "http://video.example", username: "a", accountSecret: "x" })),
+    ).rejects.toThrow(/https/);
+  });
+});
+
+describe("peertube: tokens", () => {
+  it("refreshes once on 401 and retries with the new token", async () => {
+    const { state, credentials, connector } = createHarness();
+    state.expireToken = ACCESS;
+    const identity = await connector.getIdentity(connection);
+    expect(identity.handle).toBe("alice@video.example");
+    expect(await credentials.getAccessToken(connection)).toBe("stub-access-2");
+    expect(await credentials.getSecret(connection, "refresh_token")).toBe("stub-refresh-2");
+    expect(state.calls.map((c) => new URL(c.url).pathname)).toEqual([
+      "/api/v1/users/me",
+      "/api/v1/users/token",
+      "/api/v1/users/me",
+    ]);
+  });
+
+  it("refreshCredentials uses the refresh_token grant with the stored client", async () => {
+    const { state, connector } = createHarness();
+    const ref = await connector.refreshCredentials?.(connection);
+    expect(ref).toEqual(connection.credentialId);
+    const form = new URLSearchParams(String(state.calls[0]?.init?.body));
+    expect(form.get("grant_type")).toBe("refresh_token");
+    expect(form.get("refresh_token")).toBe(REFRESH);
+    expect(form.get("client_secret")).toBe("local-client-secret");
+  });
+
+  it("surfaces AuthError when no token is stored", async () => {
+    const { connector } = createHarness({ credentials: new InMemoryCredentials() });
+    await expect(connector.getIdentity(connection)).rejects.toBeInstanceOf(AuthError);
+  });
+
+  it("revokeCredentials calls revoke-token", async () => {
+    const { state, connector } = createHarness();
+    await connector.revokeCredentials?.(connection);
+    expect(state.calls[0]?.url).toBe(`${INSTANCE}/api/v1/users/revoke-token`);
+    expect(state.validTokens.has(ACCESS)).toBe(false);
+  });
+});
+
+describe("peertube: channels", () => {
+  it("lists the account's channels as name@host handles", async () => {
+    const { connector } = createHarness();
+    const channels = await connector.getRemoteVideoChannels?.(connection);
+    expect(channels).toHaveLength(2);
+    expect(channels?.[0]).toMatchObject({
+      id: "peertube:video.example:7",
+      provider: "peertube",
+      instanceUrl: INSTANCE,
+      remoteChannelId: "7",
+      handle: "alice_channel@video.example",
+      displayName: "Alice's channel",
+    });
+    expect(channels?.[0]?.handle.startsWith("@")).toBe(false);
+    expect(channels?.[0]?.capabilities.createLivestream).toBe(true);
+  });
+
+  it("normalizes handles and instance URLs", () => {
+    expect(normalizeHandle("@alice@video.example")).toBe("alice@video.example");
+    expect(normalizeHandle("alice_channel@video.example")).toBe("alice_channel@video.example");
+    expect(normalizeInstanceUrl("video.example/")).toBe(INSTANCE);
+    expect(normalizeInstanceUrl("http://localhost:9000")).toBe("http://localhost:9000");
+    expect(() => normalizeInstanceUrl("ftp://video.example")).toThrow(/https/);
+  });
+});
+
+describe("peertube: video upload", () => {
+  it("uploads multipart with name, channel, privacy, tags and thumbnail", async () => {
+    const { state, connector } = createHarness();
+    const result = await connector.uploadVideo?.(connection, {
+      videoAssetId: "asset-9",
+      title: "Federation explained",
+      description: "A long-form talk",
+      tags: ["fediverse", "video"],
+      thumbnailAssetId: "thumb-1",
+      visibility: "unlisted",
+      formatIntent: "long_form",
+      providerMetadata: { channelId: "@alice_live@video.example", category: 15, nsfw: false },
+    });
+    expect(result?.remoteId).toMatch(/^a1b2c3d4-/);
+    const upload = state.calls.find((c) => c.url.endsWith("/api/v1/videos/upload"));
+    const form = upload?.init?.body as FormData;
+    expect(form.get("videofile")).toBeInstanceOf(Blob);
+    expect(form.get("thumbnailfile")).toBeInstanceOf(Blob);
+    expect(form.get("name")).toBe("Federation explained");
+    expect(form.get("channelId")).toBe("8"); // handle resolved, leading @ stripped
+    expect(form.get("privacy")).toBe("2");
+    expect(form.get("category")).toBe("15");
+    expect(form.get("nsfw")).toBe("false");
+    expect(form.get("tags[0]")).toBe("fediverse");
+    expect(form.get("tags[1]")).toBe("video");
+    const lookup = state.calls.find((c) => c.url.includes("/video-channels/"));
+    expect(lookup?.url).toBe(`${INSTANCE}/api/v1/video-channels/alice_live%40video.example`);
+  });
+
+  it("defaults to the account's first channel and filename-derived name", async () => {
+    const { state, connector } = createHarness();
+    await connector.uploadVideo?.(connection, {
+      videoAssetId: "talk",
+      visibility: "provider_default",
+      formatIntent: "provider_default",
+      providerMetadata: {},
+    });
+    const form = state.calls.find((c) => c.url.endsWith("/videos/upload"))?.init?.body as FormData;
+    expect(form.get("channelId")).toBe("7");
+    expect(form.get("name")).toBe("talk");
+    expect(form.get("privacy")).toBeNull();
+  });
+
+  it("refuses followers-only visibility, too many tags and bad names before uploading", async () => {
+    const { state, connector } = createHarness();
+    const base = { videoAssetId: "asset-1", formatIntent: "provider_default" as const, providerMetadata: {} };
+    await expect(connector.uploadVideo?.(connection, { ...base, title: "Hello", visibility: "followers" })).rejects.toThrow(
+      /no PeerTube equivalent/,
+    );
+    await expect(
+      connector.uploadVideo?.(connection, { ...base, title: "Hello", visibility: "public", tags: ["a", "b", "c", "d", "e", "f"] }),
+    ).rejects.toThrow(/at most 5 tags/);
+    await expect(connector.uploadVideo?.(connection, { ...base, title: "Hi", visibility: "public" })).rejects.toThrow(
+      /3–120 characters/,
+    );
+    expect(state.calls.some((c) => c.url.endsWith("/videos/upload"))).toBe(false);
+  });
+
+  it("requires an asset opener", async () => {
+    const { connector } = createHarness({ openAsset: undefined });
+    await expect(
+      connector.uploadVideo?.(connection, {
+        videoAssetId: "asset-1",
+        visibility: "public",
+        formatIntent: "provider_default",
+        providerMetadata: {},
+      }),
+    ).rejects.toThrow(/openAsset/);
+  });
+
+  it("maps VideoState to processing status", async () => {
+    const { state, connector } = createHarness();
+    const { remoteId } = (await connector.uploadVideo?.(connection, {
+      videoAssetId: "asset-1",
+      title: "Processing check",
+      visibility: "public",
+      formatIntent: "provider_default",
+      providerMetadata: {},
+    })) ?? { remoteId: "" };
+    expect((await connector.getVideoStatus?.(connection, remoteId))?.state).toBe("processing");
+    const video = state.videos.find((v) => v.uuid === remoteId);
+    if (video === undefined) throw new Error("stub video missing");
+    video.state = 1;
+    expect((await connector.getVideoStatus?.(connection, remoteId))?.state).toBe("ready");
+    video.state = 7;
+    const failed = await connector.getVideoStatus?.(connection, remoteId);
+    expect(failed).toMatchObject({ state: "failed", error: "Transcoding failed" });
+  });
+
+  it("pages the user's videos with an offset cursor", async () => {
+    const { connector } = createHarness();
+    for (const title of ["First video", "Second video"]) {
+      await connector.uploadVideo?.(connection, {
+        videoAssetId: "a",
+        title,
+        visibility: "public",
+        formatIntent: "provider_default",
+        providerMetadata: {},
+      });
+    }
+    const first = await connector.getVideos?.(connection, { limit: 2 });
+    expect(first?.items.map((v) => v.title)).toEqual(["Second video", "First video"]);
+    expect(first?.nextCursor).toBe("2");
+    const second = await connector.getVideos?.(connection, { limit: 2, cursor: first?.nextCursor });
+    expect(second?.items.map((v) => v.title)).toEqual(["Existing VOD"]);
+    expect(second?.items[0]?.createdAt).toBeInstanceOf(Date);
+    expect(second?.nextCursor).toBeUndefined();
+  });
+});
+
+describe("peertube: livestreams", () => {
+  it("creates a live with latencyMode, stores the stream key in the vault, returns a ref", async () => {
+    const { state, credentials, connector } = createHarness({ defaultLatencyMode: 3 });
+    const live = await connector.createLiveStream?.(connection, {
+      channelId: "peertube:video.example:8",
+      title: "Weekly stream",
+      permanent: true,
+      saveReplay: false,
+    });
+    const body = jsonBody(state.calls.find((c) => c.url.endsWith("/api/v1/videos/live"))?.init);
+    expect(body).toEqual({ channelId: 8, name: "Weekly stream", saveReplay: false, permanentLive: true, latencyMode: 3 });
+    expect(live?.state).toBe("created");
+    expect(live?.rtmpUrl).toBe("rtmp://video.example:1935/live");
+    expect(live?.streamKeyRef?.kind).toBe("credential-ref");
+    expect(JSON.stringify(live)).not.toContain(STREAM_KEY);
+    expect(await credentials.getSecret(connection, streamKeySecretName(live?.remoteId ?? ""))).toBe(STREAM_KEY);
+    expect(live?.playbackUrls).toEqual([
+      `${INSTANCE}/static/streaming-playlists/hls/${live?.remoteId}/master.m3u8`,
+    ]);
+  });
+
+  it("passes an explicit latencyMode and privacy", async () => {
+    const { state, connector } = createHarness();
+    const create = connector.createLiveStream;
+    await create?.(connection, {
+      channelId: "7",
+      title: "Low latency",
+      permanent: false,
+      saveReplay: true,
+      latencyMode: 2,
+      visibility: "unlisted",
+    } as Parameters<NonNullable<typeof create>>[1]);
+    const body = jsonBody(state.calls.find((c) => c.url.endsWith("/api/v1/videos/live"))?.init);
+    expect(body).toMatchObject({ channelId: 7, saveReplay: true, permanentLive: false, latencyMode: 2, privacy: 2 });
+  });
+
+  it("refuses saveReplay on a permanent live before calling the instance", async () => {
+    const { state, connector } = createHarness();
+    await expect(
+      connector.createLiveStream?.(connection, { channelId: "7", title: "Nope", permanent: true, saveReplay: true }),
+    ).rejects.toThrow(/permanent lives cannot save replays/);
+    expect(state.calls).toHaveLength(0);
+  });
+
+  it("detects running lives via isLive + PUBLISHED and attaches the latest session", async () => {
+    const { state, connector } = createHarness();
+    const waiting = await connector.createLiveStream?.(connection, { channelId: "7", title: "Waiting one", permanent: false, saveReplay: false });
+    const running = await connector.createLiveStream?.(connection, { channelId: "7", title: "Running one", permanent: false, saveReplay: false });
+    const ended = await connector.createLiveStream?.(connection, { channelId: "7", title: "Ended one", permanent: false, saveReplay: false });
+    const byUuid = (uuid: string | undefined) => state.videos.find((v) => v.uuid === uuid);
+    const runningVideo = byUuid(running?.remoteId);
+    const endedVideo = byUuid(ended?.remoteId);
+    if (runningVideo === undefined || endedVideo === undefined) throw new Error("stub lives missing");
+    runningVideo.state = 1;
+    endedVideo.state = 5;
+
+    const page = await connector.getLiveStreams?.(connection, { limit: 10 });
+    const states = Object.fromEntries(page?.items.map((l) => [l.title, l.state]) ?? []);
+    expect(states).toEqual({ "Waiting one": "waiting", "Running one": "live", "Ended one": "ended" });
+    expect(page?.items.some((l) => l.title === "Existing VOD")).toBe(false);
+    const live = page?.items.find((l) => l.remoteId === running?.remoteId);
+    expect(live?.startedAt?.toISOString()).toBe("2026-10-07T18:00:00.000Z");
+    expect(live?.endedAt).toBeUndefined();
+    expect(live?.streamKeyRef?.kind).toBe("credential-ref");
+    const listCall = state.calls.find((c) => c.url.includes("/users/me/videos"));
+    expect(new URL(listCall?.url ?? INSTANCE).searchParams.get("isLive")).toBe("true");
+    expect(waiting?.remoteId).toBeTruthy();
+  });
+
+  it("updateLiveStream renames through the video (multipart PUT)", async () => {
+    const { state, connector } = createHarness();
+    const live = await connector.createLiveStream?.(connection, { channelId: "7", title: "Old title", permanent: false, saveReplay: false });
+    const updated = await connector.updateLiveStream?.(connection, { remoteId: live?.remoteId ?? "", title: "New title" });
+    expect(updated?.title).toBe("New title");
+    expect(updated?.state).toBe("waiting");
+    const put = state.calls.find((c) => c.method === "PUT");
+    expect((put?.init?.body as FormData).get("name")).toBe("New title");
+  });
+
+  it("updateLiveStream refuses a non-live video", async () => {
+    const { connector } = createHarness();
+    await expect(
+      connector.updateLiveStream?.(connection, { remoteId: "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d" }),
+    ).rejects.toThrow(/not a live/);
+  });
+
+  it("playback: lives get the deterministic master.m3u8, VODs the API playlistUrl, both an embed", async () => {
+    const { connector } = createHarness();
+    const live = await connector.createLiveStream?.(connection, { channelId: "7", title: "Playback", permanent: false, saveReplay: false });
+    const liveSources = await connector.getStreamPlaybackSources?.(connection, { remoteId: live?.remoteId ?? "" });
+    expect(liveSources).toEqual([
+      { remoteId: live?.remoteId, url: `${INSTANCE}/static/streaming-playlists/hls/${live?.remoteId}/master.m3u8`, kind: "hls", protocol: "https" },
+      { remoteId: live?.remoteId, url: `${INSTANCE}/videos/embed/${live?.remoteId}`, kind: "embed", protocol: "https" },
+    ]);
+    const vod = await connector.getStreamPlaybackSources?.(connection, { remoteId: "41" });
+    expect(vod?.[0]?.url).toBe(`${INSTANCE}/static/streaming-playlists/hls/0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d/aa11-master.m3u8`);
+    expect(vod?.[1]?.kind).toBe("embed");
+  });
+});
+
+describe("peertube: comments", () => {
+  it("lists comment threads as plain text with federated handles, skipping deleted", async () => {
+    const { connector } = createHarness();
+    const page = await connector.getComments?.(connection, { onRemoteId: "vid-1", limit: 2 });
+    expect(page?.items).toHaveLength(1);
+    expect(page?.items[0]).toMatchObject({
+      provider: "peertube",
+      remoteId: "vid-1:1",
+      onRemoteId: "vid-1",
+      authorHandle: "bob@other.example",
+      text: "Great & fun",
+    });
+    expect(page?.nextCursor).toBe("2");
+  });
+
+  it("replies to a video (new thread) and to a comment", async () => {
+    const { state, connector } = createHarness();
+    const thread = await connector.reply?.(connection, { onRemoteId: "vid-1", text: "Thanks!" });
+    expect(thread?.remoteId).toBe("vid-1:500");
+    expect(thread?.remoteUrl).toContain("threadId=500");
+    const reply = await connector.reply?.(connection, { onRemoteId: "vid-1:1", text: "Glad you liked it" });
+    expect(reply?.remoteId).toBe("vid-1:501");
+    expect(reply?.providerMetadata).toMatchObject({ videoId: "vid-1", inReplyTo: "1" });
+    expect(state.comments[1]).toMatchObject({ inReplyTo: 1, text: "Glad you liked it" });
+    expect(jsonBody(state.calls.at(-1)?.init)).toEqual({ text: "Glad you liked it" });
+  });
+
+  it("rejects empty text and malformed targets", async () => {
+    const { connector } = createHarness();
+    await expect(connector.reply?.(connection, { onRemoteId: "vid-1", text: "  " })).rejects.toThrow(/empty/);
+    await expect(connector.reply?.(connection, { onRemoteId: "vid-1:abc", text: "x" })).rejects.toBeInstanceOf(
+      ConnectorError,
+    );
+  });
+
+  it("htmlToText flattens PeerTube comment HTML", () => {
+    expect(htmlToText("<p>a<br>b</p><p>c &#38; d</p>")).toBe("a\nb\n\nc & d");
+  });
+});
+
+describe("peertube: analytics", () => {
+  it("video stats: overall values + viewers series over the requested range", async () => {
+    const { state, connector } = createHarness();
+    const from = new Date("2026-10-01T00:00:00.000Z");
+    const to = new Date("2026-10-07T00:00:00.000Z");
+    const stats = await connector.getAnalytics?.(connection, { subjectRemoteId: "vid-1", from, to });
+    expect(stats?.values).toEqual({ averageWatchTime: 42, totalWatchTime: 4200, viewersPeak: 17, totalViewers: 100 });
+    expect(stats?.series).toEqual([
+      { at: new Date("2026-10-05T00:00:00.000Z"), values: { viewers: 30 } },
+      { at: new Date("2026-10-06T00:00:00.000Z"), values: { viewers: 70 } },
+    ]);
+    const overall = new URL(state.calls[0]?.url ?? INSTANCE);
+    expect(overall.pathname).toBe("/api/v1/videos/vid-1/stats/overall");
+    expect(overall.searchParams.get("startDate")).toBe(from.toISOString());
+  });
+
+  it("without a subject: instance stats from /server/stats", async () => {
+    const { connector } = createHarness();
+    const stats = await connector.getAnalytics?.(connection, { from: new Date(0), to: new Date() });
+    expect(stats).toEqual({ values: { totalUsers: 40, totalLocalVideos: 120, totalLocalVideoViews: 9001 }, series: [] });
+  });
+});
+
+describe("peertube: errors", () => {
+  it("maps 404 problem+json to ConnectorError with the detail", async () => {
+    const { connector } = createHarness();
+    await expect(connector.getVideoStatus?.(connection, "missing")).rejects.toThrow(/HTTP 404 GET .*Video not found/);
+  });
+
+  it("maps 429 to RateLimitError via the SDK client", async () => {
+    const connector = createPeerTubeConnector({
+      fetchImpl: async () => new Response("", { status: 429, headers: { "retry-after": "10" } }),
+      requestsPerSecond: 1000,
+      sleep: async () => Promise.resolve(),
+      credentials: createHarness().credentials,
+    });
+    await expect(connector.getIdentity(connection)).rejects.toMatchObject({ name: "RateLimitError", retryAfterMs: 10_000 });
+  });
+});
diff --git a/packages/connector-peertube/src/index.ts b/packages/connector-peertube/src/index.ts
new file mode 100644
index 0000000..849f9fa
--- /dev/null
+++ b/packages/connector-peertube/src/index.ts
@@ -0,0 +1,1177 @@
+/**
+ * PeerTube connector — federated video platform, one instance per connection.
+ *
+ * Auth: per-instance OAuth2 with the password grant (facts verified against
+ * PeerTube v8.3 — docs/research/peertube-api-facts.md):
+ * - Every instance exposes its own local OAuth client at
+ *   GET /api/v1/oauth-clients/local (client_id + client_secret). There is no
+ *   RFC 7591 registration endpoint; fetching the local client IS the
+ *   per-instance "registration".
+ * - POST /api/v1/users/token with grant_type=password trades
+ *   username + password for an access token (~1 day) and a refresh token
+ *   (~2 weeks). 2FA rides on the x-peertube-otp header.
+ * - The password is used for that single exchange and is NEVER persisted:
+ *   only access_token, refresh_token and the instance client credentials go
+ *   into the CredentialAccessor; the returned connection carries
+ *   instanceUrl + username only. Afterwards every call runs on the stored
+ *   tokens, and a 401 triggers one refresh_token round-trip and a retry.
+ * - The SDK forbids connection fields named "password" (so generic UIs and
+ *   logs never treat it as a stored account password); the one-time field is
+ *   therefore named `accountSecret`.
+ * - No granular scopes exist — authorization follows the account's role.
+ *
+ * Honest capability notes:
+ * - No text posts, feed or DMs — PeerTube is video-only, with comments.
+ * - Lives: POST /api/v1/videos/live, then GET /api/v1/videos/live/{id} for
+ *   rtmpUrl + streamKey (owner-only). The stream key goes straight into the
+ *   CredentialAccessor; LiveStream carries a credential-ref, never the key.
+ *   saveReplay + permanentLive is rejected by PeerTube (400), so we refuse it
+ *   before any request.
+ * - Live state: there is no LIVE VideoState. A running live is
+ *   PUBLISHED (1) with isLive=true; WAITING_FOR_LIVE=4, LIVE_ENDED=5.
+ * - Live chat: PeerTube core has none. Chat exists only through the
+ *   third-party livechat plugin (XMPP, instance-dependent), so liveChatRead /
+ *   liveChatWrite are not declared and getLiveChat is intentionally absent.
+ *   Comments on the live video are reachable through getComments.
+ * - Webhooks: PeerTube has no outbound webhooks (plugin action hooks only),
+ *   so `webhooks` is false and lives must be polled.
+ * - Analytics: per-video stats (/videos/{id}/stats/overall + viewers
+ *   timeseries) for owned videos, instance stats (/server/stats) otherwise.
+ *
+ * Rate limits: default instance config allows 50 API requests / 10 s per IP.
+ * We run the SDK client at 2 requests/s per host — well under that budget,
+ * shared by every connection on the same instance.
+ */
+import { createHash, randomUUID } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  CredentialRef,
+  LiveStream,
+  NormalizedIdentity,
+  NormalizedVideoPublication,
+  Page,
+  Publication,
+  RemoteVideoChannel,
+  StreamPlaybackSource,
+  VideoProcessingStatus,
+  Visibility,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  ConnectorError,
+  InMemoryCredentials,
+  pageOf,
+  RateLimitedHttpClient,
+  type AuthorizationRequest,
+  type AuthorizationResult,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+import { resolvePeerTubeSource } from "./resolve.js";
+
+const PROVIDER = "peertube";
+const OTP_HEADER = "x-peertube-otp";
+/** PeerTube validator bounds for video names and tags. */
+const NAME_MIN = 3;
+const NAME_MAX = 120;
+const TAGS_MAX = 5;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishVideo: true,
+  longFormVideo: true,
+  comments: true,
+  replies: true,
+  livestreams: true,
+  createLivestream: true,
+  manageLivestream: true,
+  livePlaybackSource: true,
+  analytics: true,
+  publishText: false,
+  feed: false,
+  directMessages: false,
+  webhooks: false,
+};
+
+/** What a single PeerTube channel can do — channels are the publishing unit. */
+const CHANNEL_CAPABILITIES: ConnectorCapabilities = {
+  publishVideo: true,
+  longFormVideo: true,
+  comments: true,
+  replies: true,
+  livestreams: true,
+  createLivestream: true,
+  manageLivestream: true,
+  livePlaybackSource: true,
+};
+
+/** Credential keys stored per connection through the CredentialAccessor. */
+const SECRET = {
+  accessToken: "access_token",
+  refreshToken: "refresh_token",
+  clientId: "client_id",
+  clientSecret: "client_secret",
+} as const;
+
+/** Vault key for a live's RTMP stream key (owner-only, treated as a credential). */
+export function streamKeySecretName(videoUuid: string): string {
+  return `live_stream_key:${videoUuid}`;
+}
+
+/** VideoState ids (server/core/initializers/constants.ts, v8.3). */
+export const VideoState = {
+  PUBLISHED: 1,
+  TO_TRANSCODE: 2,
+  TO_IMPORT: 3,
+  WAITING_FOR_LIVE: 4,
+  LIVE_ENDED: 5,
+  TO_MOVE_TO_EXTERNAL_STORAGE: 6,
+  TRANSCODING_FAILED: 7,
+  TO_MOVE_TO_EXTERNAL_STORAGE_FAILED: 8,
+  TO_EDIT: 9,
+  TO_MOVE_TO_FILE_SYSTEM: 10,
+  TO_MOVE_TO_FILE_SYSTEM_FAILED: 11,
+  TO_IMPORT_FAILED: 12,
+} as const;
+
+const FAILED_STATES: ReadonlySet<number> = new Set([
+  VideoState.TRANSCODING_FAILED,
+  VideoState.TO_MOVE_TO_EXTERNAL_STORAGE_FAILED,
+  VideoState.TO_MOVE_TO_FILE_SYSTEM_FAILED,
+  VideoState.TO_IMPORT_FAILED,
+]);
+
+/** LiveVideoLatencyMode: 1=Default, 2=High latency, 3=Small latency. */
+export type PeerTubeLatencyMode = 1 | 2 | 3;
+
+/** VideoPrivacy: 1=Public, 2=Unlisted, 3=Private, 4=Internal (instance users). */
+type PeerTubePrivacy = 1 | 2 | 3 | 4;
+
+const PRIVACY: Record<Visibility, PeerTubePrivacy | null | undefined> = {
+  public: 1,
+  unlisted: 2,
+  private: 3,
+  // PeerTube has no follower-only privacy; "internal" means instance users.
+  followers: null,
+  provider_default: undefined,
+};
+
+export interface PeerTubeVideoFile {
+  bytes: Uint8Array;
+  filename: string;
+  mimeType: string;
+}
+
+export interface PeerTubeConnectorOptions {
+  /** Stock PeerTube has no authorization-code grant; a bridge must issue API tokens. */
+  env?: Record<string, string | undefined>;
+  /** fetch override for tests (same pattern as the other connectors). */
+  fetchImpl?: typeof fetch;
+  /** Requests per second per instance host. Default 2; tests raise it. */
+  requestsPerSecond?: number;
+  /** Sleep override for the rate limiter (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Secret store. Default: in-memory (dev + contract tests). */
+  credentials?: CredentialAccessor;
+  /** Read asset bytes (video file, thumbnail) by asset id — needed by uploadVideo. */
+  openAsset?: (assetId: string) => Promise<PeerTubeVideoFile>;
+  /** latencyMode used when a createLiveStream request does not set one. */
+  defaultLatencyMode?: PeerTubeLatencyMode;
+}
+
+/**
+ * The SDK's AuthorizationRequest carries no provider input, so the
+ * instance, username and one-time account secret travel in `fields`
+ * (manifest field names) and an optional 2FA code in providerMetadata.otp.
+ */
+export interface PeerTubeAuthorizationRequest extends AuthorizationRequest {
+  fields?: Record<string, string>;
+  providerMetadata?: Record<string, unknown>;
+}
+
+/** createLiveStream input: the SDK request plus PeerTube-only knobs. */
+export interface PeerTubeCreateLiveRequest {
+  channelId: string;
+  title: string;
+  permanent: boolean;
+  saveReplay: boolean;
+  latencyMode?: PeerTubeLatencyMode;
+  visibility?: Visibility;
+}
+
+interface PtAvatar {
+  path?: string;
+  fileUrl?: string;
+  width?: number;
+}
+
+interface PtActor {
+  id: number;
+  name: string;
+  displayName?: string;
+  host: string;
+  avatars?: PtAvatar[];
+  avatar?: PtAvatar | null;
+}
+
+interface PtUserMe {
+  id: number;
+  username: string;
+  account: PtActor;
+  videoChannels?: PtActor[];
+}
+
+interface PtList<T> {
+  total: number;
+  data: T[];
+}
+
+interface PtStreamingPlaylist {
+  id: number;
+  /** 1 = HLS */
+  type: number;
+  playlistUrl: string;
+}
+
+interface PtVideo {
+  id: number;
+  uuid: string;
+  shortUUID?: string;
+  name: string;
+  isLive?: boolean;
+  state?: { id: number; label?: string };
+  createdAt?: string;
+  publishedAt?: string;
+  url?: string;
+  streamingPlaylists?: PtStreamingPlaylist[];
+}
+
+interface PtVideoRef {
+  video: { id: number; uuid: string; shortUUID?: string };
+}
+
+interface PtLive {
+  rtmpUrl?: string | null;
+  rtmpsUrl?: string | null;
+  streamKey?: string;
+  saveReplay?: boolean;
+  permanentLive?: boolean;
+  latencyMode?: number;
+}
+
+interface PtLiveSession {
+  id: number;
+  startDate: string;
+  endDate?: string | null;
+  error?: number | null;
+}
+
+interface PtComment {
+  id: number;
+  text: string;
+  createdAt: string;
+  url?: string;
+  isDeleted?: boolean;
+  account?: PtActor | null;
+}
+
+interface PtToken {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in?: number;
+}
+
+interface PtOAuthClient {
+  client_id: string;
+  client_secret: string;
+}
+
+interface PtAbout {
+  instance?: { name?: string };
+}
+
+interface PtTimeseries {
+  data?: { date: string; value: number }[];
+}
+
+function str(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Accepts "video.example", "https://video.example/", etc. → origin. */
+export function normalizeInstanceUrl(raw: string): string {
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) throw new ConnectorError("instanceUrl is required", PROVIDER);
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `https://${trimmed}`;
+  let url: URL;
+  try {
+    url = new URL(withScheme);
+  } catch (cause) {
+    throw new ConnectorError(`instanceUrl "${raw}" is not a valid URL`, PROVIDER, cause);
+  }
+  const local = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local)) {
+    throw new ConnectorError(`instanceUrl must use https (got ${url.protocol})`, PROVIDER);
+  }
+  return url.origin;
+}
+
+/**
+ * PeerTube handles are `name@host` without a leading `@` — a leading `@`
+ * splits into an empty name and 404s, so users' pasted `@alice@host` is
+ * normalized here.
+ */
+export function normalizeHandle(raw: string): string {
+  return raw.trim().replace(/^@+/, "");
+}
+
+const ENTITIES: Record<string, string> = {
+  amp: "&",
+  lt: "<",
+  gt: ">",
+  quot: '"',
+  apos: "'",
+  nbsp: " ",
+};
+
+/** Comment text arrives as sanitized HTML; flatten it for the inbox. */
+export function htmlToText(html: string): string {
+  return html
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>\s*<p>/gi, "\n\n")
+    .replace(/<[^>]+>/g, "")
+    .replace(/&(#\d+|[a-z]+);/gi, (match, entity: string) => {
+      if (entity.startsWith("#")) return String.fromCodePoint(Number(entity.slice(1)));
+      return ENTITIES[entity.toLowerCase()] ?? match;
+    })
+    .trim();
+}
+
+/** Every numeric top-level field of a stats payload, by name. */
+function numericValues(payload: unknown): Record<string, number> {
+  const values: Record<string, number> = {};
+  if (!isRecord(payload)) return values;
+  for (const [key, value] of Object.entries(payload)) {
+    if (typeof value === "number" && Number.isFinite(value)) values[key] = value;
+  }
+  return values;
+}
+
+function processingStateOf(video: PtVideo): VideoProcessingStatus["state"] {
+  const id = video.state?.id;
+  if (id === undefined) return "processing";
+  if (FAILED_STATES.has(id)) return "failed";
+  if (
+    id === VideoState.PUBLISHED ||
+    id === VideoState.WAITING_FOR_LIVE ||
+    id === VideoState.LIVE_ENDED
+  ) {
+    return "ready";
+  }
+  return "processing";
+}
+
+/** No LIVE VideoState exists: a running live is PUBLISHED with isLive=true. */
+function liveStateOf(video: PtVideo): LiveStream["state"] {
+  const id = video.state?.id;
+  if (id === VideoState.WAITING_FOR_LIVE) return "waiting";
+  if (id === VideoState.LIVE_ENDED) return "ended";
+  if (id === VideoState.PUBLISHED && video.isLive === true) return "live";
+  return "created";
+}
+
+export function createPeerTubeConnector(options: PeerTubeConnectorOptions = {}): PlatformConnector & { resolveSource: typeof resolvePeerTubeSource } {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: options.requestsPerSecond ?? 2,
+    fetchImpl: options.fetchImpl,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  /** GET /users/me per connection id — identity, account name, default channel. */
+  const selves = new Map<string, PtUserMe>();
+  let publicationSeq = 0;
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "PeerTube",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "instanceUrl",
+        label: "Instance URL",
+        required: true,
+        secret: false,
+        placeholder: "video.example.org",
+      },
+      {
+        name: "username",
+        label: "Username",
+        required: true,
+        secret: false,
+        placeholder: "alice",
+      },
+      {
+        // Account password, used once for the token exchange and never
+        // stored — only the issued access/refresh tokens are kept.
+        name: "accountSecret",
+        label: "Account password (used once to obtain tokens, never stored)",
+        required: true,
+        secret: true,
+      },
+    ],
+    oauth: {
+      kind: "per-instance-oauth2", pkce: true,
+      connectEnabled: Boolean(options.env?.PEERTUBE_AUTHORIZE_PATH && options.env?.PEERTUBE_TOKEN_PATH),
+      connectNote: "Redirect linking requires an instance OAuth bridge; stock PeerTube supports password grants only.",
+    },
+    docsUrl: "https://docs.joinpeertube.org/api-rest-reference.html",
+  };
+
+  function instanceOf(connection: ConnectorConnection): string {
+    const raw = connection.fields.instanceUrl;
+    if (raw === undefined) {
+      throw new ConnectorError(`connection ${connection.id} has no instanceUrl`, PROVIDER);
+    }
+    return normalizeInstanceUrl(raw);
+  }
+
+  async function secretOrUndefined(connection: ConnectorConnection, key: string): Promise<string | undefined> {
+    try {
+      return await credentials.getSecret(connection, key);
+    } catch {
+      return undefined;
+    }
+  }
+
+  /** Maps PeerTube's problem+json errors onto the SDK error taxonomy. */
+  async function toError(response: Response, method: string, url: string): Promise<Error> {
+    let detail = "";
+    let code: string | undefined;
+    try {
+      const body: unknown = await response.json();
+      if (isRecord(body)) {
+        detail = str(body.detail) ?? str(body.error) ?? str(body.title) ?? "";
+        code = str(body.code);
+      }
+    } catch {
+      detail = "";
+    }
+    const message = `${PROVIDER}: HTTP ${response.status} ${method} ${new URL(url).pathname}${detail ? `: ${detail}` : ""}`;
+    if (code === "missing_two_factor" || response.headers.get(OTP_HEADER) === "required") {
+      return new AuthError(
+        `${PROVIDER}: two-factor code required — retry authorize with providerMetadata.otp`,
+        PROVIDER,
+        true,
+      );
+    }
+    if (response.status === 401 || response.status === 403) {
+      return new AuthError(message, PROVIDER, false);
+    }
+    return new ConnectorError(message, PROVIDER, { status: response.status, code });
+  }
+
+  async function parse<T>(response: Response): Promise<T> {
+    const text = await response.text();
+    return (text.length > 0 ? JSON.parse(text) : {}) as T;
+  }
+
+  /** Unauthenticated request (instance discovery + token endpoint). */
+  async function publicCall<T>(url: string, init: RequestInit = {}): Promise<T> {
+    const response = await client.request(PROVIDER, url, {
+      ...init,
+      headers: { accept: "application/json", ...init.headers },
+    });
+    if (!response.ok) throw await toError(response, init.method ?? "GET", url);
+    return parse<T>(response);
+  }
+
+  async function tokenRequest(
+    instanceUrl: string,
+    params: Record<string, string>,
+    otp?: string,
+  ): Promise<PtToken> {
+    return publicCall<PtToken>(`${instanceUrl}/api/v1/users/token`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/x-www-form-urlencoded",
+        ...(otp !== undefined ? { [OTP_HEADER]: otp } : {}),
+      },
+      body: new URLSearchParams(params).toString(),
+    });
+  }
+
+  async function storeTokens(connection: ConnectorConnection, token: PtToken): Promise<void> {
+    await credentials.put(connection, SECRET.accessToken, token.access_token);
+    await credentials.put(connection, SECRET.refreshToken, token.refresh_token);
+  }
+
+  async function refresh(connection: ConnectorConnection): Promise<void> {
+    const refreshToken = await secretOrUndefined(connection, SECRET.refreshToken);
+    const clientId = await secretOrUndefined(connection, SECRET.clientId);
+    const clientSecret = await secretOrUndefined(connection, SECRET.clientSecret);
+    if (refreshToken === undefined || clientId === undefined || clientSecret === undefined) {
+      throw new AuthError(
+        `${PROVIDER}: no refresh token or client credentials stored — reconnect the account`,
+        PROVIDER,
+        false,
+      );
+    }
+    const token = await tokenRequest(instanceOf(connection), {
+      grant_type: "refresh_token",
+      client_id: clientId,
+      client_secret: clientSecret,
+      refresh_token: refreshToken,
+    });
+    await storeTokens(connection, token);
+  }
+
+  /**
+   * Authenticated call. Access tokens live ~1 day, so a 401 gets exactly one
+   * refresh_token round-trip and a retry before surfacing as AuthError.
+   */
+  async function api<T>(
+    connection: ConnectorConnection,
+    method: string,
+    path: string,
+    body?: Record<string, unknown> | FormData,
+    retried = false,
+  ): Promise<T> {
+    let token: string;
+    try {
+      token = await credentials.getAccessToken(connection);
+    } catch {
+      throw new AuthError(`${PROVIDER}: no access token for ${connection.id} — authorize first`, PROVIDER, false);
+    }
+    const headers: Record<string, string> = { accept: "application/json", authorization: `Bearer ${token}` };
+    const init: RequestInit = { method, headers };
+    if (body instanceof FormData) {
+      init.body = body;
+    } else if (body !== undefined) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    const url = `${instanceOf(connection)}${path}`;
+    const response = await client.request(PROVIDER, url, init);
+    if (response.status === 401 && !retried) {
+      const canRefresh = (await secretOrUndefined(connection, SECRET.refreshToken)) !== undefined;
+      if (canRefresh) {
+        await refresh(connection);
+        return api<T>(connection, method, path, body, true);
+      }
+    }
+    if (!response.ok) throw await toError(response, method, url);
+    return parse<T>(response);
+  }
+
+  async function self(connection: ConnectorConnection): Promise<PtUserMe> {
+    const cached = selves.get(connection.id);
+    if (cached !== undefined) return cached;
+    const me = await api<PtUserMe>(connection, "GET", "/api/v1/users/me");
+    selves.set(connection.id, me);
+    return me;
+  }
+
+  function avatarUrl(instanceUrl: string, actor: PtActor): string | undefined {
+    const candidates = [...(actor.avatars ?? []), ...(actor.avatar ? [actor.avatar] : [])];
+    const best = candidates.reduce<PtAvatar | undefined>(
+      (pick, avatar) => (pick === undefined || (avatar.width ?? 0) > (pick.width ?? 0) ? avatar : pick),
+      undefined,
+    );
+    if (best === undefined) return undefined;
+    if (best.fileUrl !== undefined) return best.fileUrl;
+    return best.path === undefined ? undefined : new URL(best.path, instanceUrl).toString();
+  }
+
+  function handleOf(actor: PtActor): string {
+    return `${actor.name}@${actor.host}`;
+  }
+
+  function identityOf(connection: ConnectorConnection, me: PtUserMe): NormalizedIdentity {
+    const identity: NormalizedIdentity = {
+      provider: PROVIDER,
+      remoteId: String(me.account.id),
+      handle: handleOf(me.account),
+      displayName: me.account.displayName ?? me.username,
+    };
+    const avatar = avatarUrl(instanceOf(connection), me.account);
+    if (avatar !== undefined) identity.avatarUrl = avatar;
+    return identity;
+  }
+
+  /**
+   * PeerTube wants a numeric channelId. Accepts a numeric id, a
+   * RemoteVideoChannel.id (`peertube:<host>:<id>`), or a channel handle
+   * (`name`, `name@host`, `@name@host`) resolved via /video-channels/{handle}.
+   * Absent → the account's first channel.
+   */
+  async function resolveChannelId(connection: ConnectorConnection, raw: string | undefined): Promise<number> {
+    if (raw === undefined) {
+      const first = (await self(connection)).videoChannels?.[0];
+      if (first === undefined) {
+        throw new ConnectorError(`${PROVIDER}: account has no video channel to publish to`, PROVIDER);
+      }
+      return first.id;
+    }
+    if (/^\d+$/.test(raw)) return Number(raw);
+    const prefixed = new RegExp(`^${PROVIDER}:[^:]+:(\\d+)$`).exec(raw);
+    if (prefixed?.[1] !== undefined) return Number(prefixed[1]);
+    const handle = normalizeHandle(raw);
+    const channel = await api<PtActor>(
+      connection,
+      "GET",
+      `/api/v1/video-channels/${encodeURIComponent(handle)}`,
+    );
+    return channel.id;
+  }
+
+  function privacyOf(visibility: Visibility | undefined, override: unknown): PeerTubePrivacy | undefined {
+    if (override === 1 || override === 2 || override === 3 || override === 4) return override;
+    if (visibility === undefined) return undefined;
+    const privacy = PRIVACY[visibility];
+    if (privacy === null) {
+      throw new ConnectorError(
+        `${PROVIDER}: visibility "${visibility}" has no PeerTube equivalent — use public, unlisted, private, or providerMetadata.privacy=4 (internal)`,
+        PROVIDER,
+      );
+    }
+    return privacy;
+  }
+
+  function videoPath(remoteId: string): string {
+    return `/api/v1/videos/${encodeURIComponent(remoteId)}`;
+  }
+
+  async function getVideo(connection: ConnectorConnection, remoteId: string): Promise<PtVideo> {
+    return api<PtVideo>(connection, "GET", videoPath(remoteId));
+  }
+
+  /** Live master playlist is always master.m3u8 under the video's HLS dir. */
+  function liveHlsUrl(connection: ConnectorConnection, uuid: string): string {
+    return `${instanceOf(connection)}/static/streaming-playlists/hls/${uuid}/master.m3u8`;
+  }
+
+  async function latestSession(
+    connection: ConnectorConnection,
+    remoteId: string,
+  ): Promise<PtLiveSession | undefined> {
+    const sessions = await api<PtList<PtLiveSession>>(
+      connection,
+      "GET",
+      `/api/v1/videos/live/${encodeURIComponent(remoteId)}/sessions`,
+    );
+    return sessions.data.reduce<PtLiveSession | undefined>(
+      (latest, session) =>
+        latest === undefined || Date.parse(session.startDate) > Date.parse(latest.startDate) ? session : latest,
+      undefined,
+    );
+  }
+
+  function streamKeyRef(connection: ConnectorConnection, uuid: string): CredentialRef {
+    return { kind: "credential-ref", id: `${connection.id}#${streamKeySecretName(uuid)}` };
+  }
+
+  async function toLiveStream(
+    connection: ConnectorConnection,
+    video: PtVideo,
+    withSession: boolean,
+  ): Promise<LiveStream> {
+    const state = liveStateOf(video);
+    const live: LiveStream = {
+      id: `${PROVIDER}:${connection.id}:${video.uuid}`,
+      provider: PROVIDER,
+      connectionId: connection.id,
+      remoteId: video.uuid,
+      title: video.name,
+      state,
+      playbackUrls: [liveHlsUrl(connection, video.uuid)],
+    };
+    if ((await secretOrUndefined(connection, streamKeySecretName(video.uuid))) !== undefined) {
+      live.streamKeyRef = streamKeyRef(connection, video.uuid);
+    }
+    if (withSession && (state === "live" || state === "ended")) {
+      const session = await latestSession(connection, video.uuid);
+      if (session !== undefined) {
+        live.startedAt = new Date(session.startDate);
+        if (session.endDate) live.endedAt = new Date(session.endDate);
+      }
+    }
+    return live;
+  }
+
+  function requireOpener(): (assetId: string) => Promise<PeerTubeVideoFile> {
+    const opener = options.openAsset;
+    if (opener === undefined) {
+      throw new ConnectorError(`${PROVIDER}: uploadVideo requires the openAsset option (asset id → bytes)`, PROVIDER);
+    }
+    return opener;
+  }
+
+  function commentRef(videoId: string, commentId: number): string {
+    return `${videoId}:${commentId}`;
+  }
+
+  function toComment(videoId: string, comment: PtComment): Comment {
+    return {
+      id: `${PROVIDER}:${commentRef(videoId, comment.id)}`,
+      provider: PROVIDER,
+      remoteId: commentRef(videoId, comment.id),
+      onRemoteId: videoId,
+      authorHandle: comment.account ? handleOf(comment.account) : "deleted",
+      text: htmlToText(comment.text),
+      createdAt: new Date(comment.createdAt),
+    };
+  }
+
+  function offsetOf(cursor: string | undefined): number {
+    if (cursor === undefined) return 0;
+    const start = Number(cursor);
+    if (!Number.isInteger(start) || start < 0) {
+      throw new ConnectorError(`${PROVIDER}: invalid cursor "${cursor}"`, PROVIDER);
+    }
+    return start;
+  }
+
+  function nextCursor(start: number, received: number, total: number): string | undefined {
+    const next = start + received;
+    return received > 0 && next < total ? String(next) : undefined;
+  }
+
+  const connector: PlatformConnector = {
+    async buildAuthorizationUrl(input) {
+      const env = options.env ?? {};
+      const instanceUrl = normalizeInstanceUrl(input.fields?.instanceUrl ?? "");
+      const authorizePath = env.PEERTUBE_AUTHORIZE_PATH;
+      const tokenPath = env.PEERTUBE_TOKEN_PATH;
+      if (!authorizePath?.startsWith("/") || authorizePath.startsWith("//") || authorizePath.includes("\\") || !tokenPath?.startsWith("/") || tokenPath.startsWith("//") || tokenPath.includes("\\")) {
+        throw new ConnectorError("PeerTube redirect linking requires a configured instance OAuth bridge", PROVIDER);
+      }
+      const connectionId = input.connectionId ?? randomUUID();
+      const connection: ConnectorConnection = {
+        id: connectionId, workspaceId: input.workspaceId, provider: PROVIDER, channelId: connectionId,
+        credentialId: { kind: "credential-ref", id: connectionId }, fields: { instanceUrl }, createdAt: new Date(),
+      };
+      const configured = env.PEERTUBE_INSTANCE_URL !== undefined && normalizeInstanceUrl(env.PEERTUBE_INSTANCE_URL) === instanceUrl;
+      const oauthClient = configured && env.PEERTUBE_CLIENT_ID && env.PEERTUBE_CLIENT_SECRET
+        ? { client_id: env.PEERTUBE_CLIENT_ID, client_secret: env.PEERTUBE_CLIENT_SECRET }
+        : await publicCall<PtOAuthClient>(`${instanceUrl}/api/v1/oauth-clients/local`);
+      await credentials.put(connection, SECRET.clientId, oauthClient.client_id);
+      await credentials.put(connection, SECRET.clientSecret, oauthClient.client_secret);
+      const url = new URL(authorizePath, instanceUrl);
+      url.search = new URLSearchParams({ client_id: oauthClient.client_id, redirect_uri: input.redirectUri, response_type: "code", state: input.state }).toString();
+      if (input.codeVerifier) {
+        url.searchParams.set("code_challenge", createHash("sha256").update(input.codeVerifier).digest("base64url"));
+        url.searchParams.set("code_challenge_method", "S256");
+      }
+      return { authorizationUrl: url.toString(), connection };
+    },
+
+    async exchangeCode(input) {
+      const instanceUrl = normalizeInstanceUrl(input.fields?.instanceUrl ?? "");
+      const connectionId = input.connectionId ?? randomUUID();
+      const connection: ConnectorConnection = {
+        id: connectionId, workspaceId: input.workspaceId, provider: PROVIDER, channelId: connectionId,
+        credentialId: { kind: "credential-ref", id: connectionId }, fields: { instanceUrl }, createdAt: new Date(),
+      };
+      const path = options.env?.PEERTUBE_TOKEN_PATH;
+      if (!path?.startsWith("/") || path.startsWith("//") || path.includes("\\")) throw new ConnectorError("OAuth bridge is not configured", PROVIDER);
+      const token = await publicCall<PtToken>(new URL(path, instanceUrl).toString(), {
+        method: "POST", headers: { "content-type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+          grant_type: "authorization_code", code: input.code, redirect_uri: input.redirectUri,
+          client_id: await credentials.getSecret(connection, SECRET.clientId),
+          client_secret: await credentials.getSecret(connection, SECRET.clientSecret),
+          ...(input.codeVerifier ? { code_verifier: input.codeVerifier } : {}),
+        }).toString(),
+      });
+      await storeTokens(connection, token);
+      selves.delete(connection.id);
+      return { connection, identity: identityOf(connection, await self(connection)) };
+    },
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    /**
+     * Single leg: verify the instance (GET /config/about), fetch the local
+     * OAuth client, exchange username + accountSecret for tokens, store the
+     * tokens and client credentials. The account secret is not stored and
+     * does not appear in the returned connection.
+     */
+    async authorize(input: PeerTubeAuthorizationRequest): Promise<AuthorizationResult> {
+      const fields = input.fields ?? {};
+      const meta = input.providerMetadata ?? {};
+      const rawInstance = str(fields.instanceUrl);
+      const username = str(fields.username);
+      const accountSecret = fields.accountSecret;
+      if (rawInstance === undefined) throw new ConnectorError(`${PROVIDER}: authorize needs fields.instanceUrl`, PROVIDER);
+      if (username === undefined) throw new ConnectorError(`${PROVIDER}: authorize needs fields.username`, PROVIDER);
+      if (accountSecret === undefined || accountSecret.length === 0) {
+        throw new ConnectorError(`${PROVIDER}: authorize needs fields.accountSecret (account password)`, PROVIDER);
+      }
+      const instanceUrl = normalizeInstanceUrl(rawInstance);
+      const host = new URL(instanceUrl).host;
+
+      // Instance discovery doubles as a "is this really PeerTube" check.
+      try {
+        await publicCall<PtAbout>(`${instanceUrl}/api/v1/config/about`);
+      } catch (cause) {
+        throw new ConnectorError(`${PROVIDER}: ${host} does not answer as a PeerTube instance`, PROVIDER, cause);
+      }
+      const oauthClient = await publicCall<PtOAuthClient>(`${instanceUrl}/api/v1/oauth-clients/local`);
+
+      const connectionId = str(meta.connectionId) ?? `${PROVIDER}:${input.workspaceId}:${username}@${host}`;
+      const connection: ConnectorConnection = {
+        id: connectionId,
+        workspaceId: input.workspaceId,
+        provider: PROVIDER,
+        channelId: str(meta.channelId) ?? connectionId,
+        credentialId: { kind: "credential-ref", id: connectionId },
+        fields: { instanceUrl, username },
+        createdAt: new Date(),
+      };
+
+      const token = await tokenRequest(
+        instanceUrl,
+        {
+          grant_type: "password",
+          client_id: oauthClient.client_id,
+          client_secret: oauthClient.client_secret,
+          username,
+          password: accountSecret,
+        },
+        str(meta.otp),
+      );
+      await credentials.put(connection, SECRET.clientId, oauthClient.client_id);
+      await credentials.put(connection, SECRET.clientSecret, oauthClient.client_secret);
+      await storeTokens(connection, token);
+      selves.delete(connection.id);
+      const identity = identityOf(connection, await self(connection));
+      return { connection, identity };
+    },
+
+    async refreshCredentials(connection: ConnectorConnection): Promise<CredentialRef> {
+      await refresh(connection);
+      return connection.credentialId;
+    },
+
+    async revokeCredentials(connection: ConnectorConnection): Promise<void> {
+      await api<Record<string, never>>(connection, "POST", "/api/v1/users/revoke-token");
+      selves.delete(connection.id);
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return identityOf(connection, await self(connection));
+    },
+
+    async getRemoteVideoChannels(connection: ConnectorConnection): Promise<RemoteVideoChannel[]> {
+      const me = await self(connection);
+      const instanceUrl = instanceOf(connection);
+      const channels = await api<PtList<PtActor>>(
+        connection,
+        "GET",
+        `/api/v1/accounts/${encodeURIComponent(me.account.name)}/video-channels?start=0&count=100`,
+      );
+      return channels.data.map((channel) => {
+        const remote: RemoteVideoChannel = {
+          id: `${PROVIDER}:${channel.host}:${channel.id}`,
+          provider: PROVIDER,
+          instanceUrl,
+          remoteChannelId: String(channel.id),
+          handle: handleOf(channel),
+          capabilities: CHANNEL_CAPABILITIES,
+        };
+        if (channel.displayName !== undefined) remote.displayName = channel.displayName;
+        const avatar = avatarUrl(instanceUrl, channel);
+        if (avatar !== undefined) remote.avatarUrl = avatar;
+        return remote;
+      });
+    },
+
+    /**
+     * Legacy multipart upload (POST /api/v1/videos/upload). providerMetadata:
+     * channelId (id or handle), privacy (1–4), category, licence, language,
+     * nsfw, waitTranscoding.
+     */
+    async uploadVideo(
+      connection: ConnectorConnection,
+      video: NormalizedVideoPublication,
+    ): Promise<{ remoteId: string }> {
+      const meta = video.providerMetadata;
+      const open = requireOpener();
+      const file = await open(video.videoAssetId);
+      const name = (video.title ?? file.filename.replace(/\.[^.]+$/, "")).trim();
+      if (name.length < NAME_MIN || name.length > NAME_MAX) {
+        throw new ConnectorError(
+          `${PROVIDER}: video name must be ${NAME_MIN}–${NAME_MAX} characters (got ${name.length})`,
+          PROVIDER,
+        );
+      }
+      const tags = video.tags ?? [];
+      if (tags.length > TAGS_MAX) {
+        throw new ConnectorError(`${PROVIDER}: at most ${TAGS_MAX} tags per video (got ${tags.length})`, PROVIDER);
+      }
+      const channelId = await resolveChannelId(connection, str(meta.channelId) ?? str(connection.fields.channelId));
+      const privacy = privacyOf(video.visibility, meta.privacy);
+
+      const form = new FormData();
+      form.append("videofile", new Blob([file.bytes], { type: file.mimeType }), file.filename);
+      form.append("name", name);
+      form.append("channelId", String(channelId));
+      if (privacy !== undefined) form.append("privacy", String(privacy));
+      if (video.description !== undefined) form.append("description", video.description);
+      // Same array encoding as PeerTube's own web client (objectToFormData).
+      tags.forEach((tag, index) => form.append(`tags[${index}]`, tag));
+      for (const key of ["category", "licence"] as const) {
+        if (typeof meta[key] === "number") form.append(key, String(meta[key]));
+      }
+      if (typeof meta.language === "string") form.append("language", meta.language);
+      if (typeof meta.nsfw === "boolean") form.append("nsfw", String(meta.nsfw));
+      if (typeof meta.waitTranscoding === "boolean") form.append("waitTranscoding", String(meta.waitTranscoding));
+      if (video.thumbnailAssetId !== undefined) {
+        const thumb = await open(video.thumbnailAssetId);
+        form.append("thumbnailfile", new Blob([thumb.bytes], { type: thumb.mimeType }), thumb.filename);
+      }
+
+      const result = await api<PtVideoRef>(connection, "POST", "/api/v1/videos/upload", form);
+      return { remoteId: result.video.uuid };
+    },
+
+    async getVideoStatus(connection: ConnectorConnection, remoteId: string): Promise<VideoProcessingStatus> {
+      const video = await getVideo(connection, remoteId);
+      const state = processingStateOf(video);
+      const status: VideoProcessingStatus = { remoteId: video.uuid, state };
+      if (state === "failed") status.error = video.state?.label ?? `state ${video.state?.id ?? "unknown"}`;
+      return status;
+    },
+
+    async getVideos(
+      connection: ConnectorConnection,
+      request: { cursor?: string; limit: number },
+    ): Promise<Page<{ remoteId: string; title?: string; createdAt?: Date }>> {
+      const start = offsetOf(request.cursor);
+      const params = new URLSearchParams({ start: String(start), count: String(request.limit), sort: "-createdAt" });
+      const list = await api<PtList<PtVideo>>(connection, "GET", `/api/v1/users/me/videos?${params}`);
+      const items = list.data.map((video) => {
+        const item: { remoteId: string; title?: string; createdAt?: Date } = { remoteId: video.uuid, title: video.name };
+        if (video.createdAt !== undefined) item.createdAt = new Date(video.createdAt);
+        return item;
+      });
+      return pageOf(items, nextCursor(start, list.data.length, list.total));
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const start = offsetOf(request.cursor);
+      const params = new URLSearchParams({ start: String(start), count: String(request.limit), sort: "-createdAt" });
+      const list = await api<PtList<PtComment>>(
+        connection,
+        "GET",
+        `${videoPath(request.onRemoteId)}/comment-threads?${params}`,
+      );
+      const items = list.data
+        .filter((comment) => comment.isDeleted !== true)
+        .map((comment) => toComment(request.onRemoteId, comment));
+      return pageOf(items, nextCursor(start, list.data.length, list.total));
+    },
+
+    /**
+     * onRemoteId `<video>` starts a new comment thread on the video;
+     * `<video>:<commentId>` (a Comment.remoteId) replies to that comment.
+     */
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      if (request.text.trim().length === 0) {
+        throw new ConnectorError(`${PROVIDER}: reply text is empty`, PROVIDER);
+      }
+      const separator = request.onRemoteId.lastIndexOf(":");
+      const videoId = separator === -1 ? request.onRemoteId : request.onRemoteId.slice(0, separator);
+      const commentId = separator === -1 ? undefined : request.onRemoteId.slice(separator + 1);
+      if (videoId.length === 0 || (commentId !== undefined && !/^\d+$/.test(commentId))) {
+        throw new ConnectorError(`${PROVIDER}: malformed reply target "${request.onRemoteId}"`, PROVIDER);
+      }
+      const path =
+        commentId === undefined
+          ? `${videoPath(videoId)}/comment-threads`
+          : `${videoPath(videoId)}/comments/${commentId}`;
+      const { comment } = await api<{ comment: PtComment }>(connection, "POST", path, { text: request.text });
+      const remoteId = commentRef(videoId, comment.id);
+      const publication: Publication = {
+        id: `pt-${(publicationSeq += 1)}-${remoteId}`,
+        workspaceId: connection.workspaceId,
+        draftId: "reply",
+        connectionId: connection.id,
+        remoteId,
+        publishedAt: new Date(comment.createdAt),
+        providerMetadata: { videoId, inReplyTo: commentId ?? null, commentId: comment.id },
+      };
+      if (comment.url !== undefined) publication.remoteUrl = comment.url;
+      return publication;
+    },
+
+    /**
+     * POST /api/v1/videos/live, then read the owner-only stream key and put
+     * it in the vault. The returned LiveStream carries a credential-ref.
+     */
+    async createLiveStream(
+      connection: ConnectorConnection,
+      request: PeerTubeCreateLiveRequest,
+    ): Promise<LiveStream> {
+      if (request.permanent && request.saveReplay) {
+        throw new ConnectorError(
+          `${PROVIDER}: permanent lives cannot save replays (PeerTube rejects saveReplay + permanentLive)`,
+          PROVIDER,
+        );
+      }
+      const title = request.title.trim();
+      if (title.length < NAME_MIN || title.length > NAME_MAX) {
+        throw new ConnectorError(`${PROVIDER}: live title must be ${NAME_MIN}–${NAME_MAX} characters`, PROVIDER);
+      }
+      const channelId = await resolveChannelId(connection, str(request.channelId));
+      const body: Record<string, unknown> = {
+        channelId,
+        name: title,
+        saveReplay: request.saveReplay,
+        permanentLive: request.permanent,
+        latencyMode: request.latencyMode ?? options.defaultLatencyMode ?? 1,
+      };
+      const privacy = privacyOf(request.visibility, undefined);
+      if (privacy !== undefined) body.privacy = privacy;
+
+      const created = await api<PtVideoRef>(connection, "POST", "/api/v1/videos/live", body);
+      const uuid = created.video.uuid;
+      const settings = await api<PtLive>(connection, "GET", `/api/v1/videos/live/${encodeURIComponent(uuid)}`);
+      const live: LiveStream = {
+        id: `${PROVIDER}:${connection.id}:${uuid}`,
+        provider: PROVIDER,
+        connectionId: connection.id,
+        remoteId: uuid,
+        title,
+        state: "created",
+        playbackUrls: [liveHlsUrl(connection, uuid)],
+      };
+      if (settings.streamKey !== undefined && settings.streamKey.length > 0) {
+        await credentials.put(connection, streamKeySecretName(uuid), settings.streamKey);
+        live.streamKeyRef = streamKeyRef(connection, uuid);
+      }
+      const ingest = settings.rtmpsUrl ?? settings.rtmpUrl;
+      if (ingest) live.rtmpUrl = ingest;
+      return live;
+    },
+
+    /**
+     * Title lives on the video (PUT /api/v1/videos/{id}, multipart), not on
+     * the live settings — so it can be renamed even while running.
+     */
+    async updateLiveStream(
+      connection: ConnectorConnection,
+      request: { remoteId: string; title?: string },
+    ): Promise<LiveStream> {
+      if (request.title !== undefined) {
+        const title = request.title.trim();
+        if (title.length < NAME_MIN || title.length > NAME_MAX) {
+          throw new ConnectorError(`${PROVIDER}: live title must be ${NAME_MIN}–${NAME_MAX} characters`, PROVIDER);
+        }
+        const form = new FormData();
+        form.append("name", title);
+        await api<Record<string, never>>(connection, "PUT", videoPath(request.remoteId), form);
+      }
+      const video = await getVideo(connection, request.remoteId);
+      if (video.isLive !== true) {
+        throw new ConnectorError(`${PROVIDER}: video ${request.remoteId} is not a live`, PROVIDER);
+      }
+      return toLiveStream(connection, video, true);
+    },
+
+    async getLiveStreams(
+      connection: ConnectorConnection,
+      request: { cursor?: string; limit: number },
+    ): Promise<Page<LiveStream>> {
+      const start = offsetOf(request.cursor);
+      const params = new URLSearchParams({
+        start: String(start),
+        count: String(request.limit),
+        sort: "-createdAt",
+        isLive: "true",
+      });
+      const list = await api<PtList<PtVideo>>(connection, "GET", `/api/v1/users/me/videos?${params}`);
+      // Filter again client-side: older servers may ignore the isLive filter.
+      const lives = list.data.filter((video) => video.isLive === true);
+      const items = await Promise.all(lives.map((video) => toLiveStream(connection, video, true)));
+      return pageOf(items, nextCursor(start, list.data.length, list.total));
+    },
+
+    /**
+     * Lives: the master playlist is deterministic (`master.m3u8` under the
+     * video's HLS directory) so monitors can probe it before the stream
+     * starts. VOD: the API's streamingPlaylists[].playlistUrl is the only
+     * reliable source (the filename is randomized). Plus the embed page.
+     */
+    async getStreamPlaybackSources(
+      connection: ConnectorConnection,
+      request: { remoteId: string },
+    ): Promise<StreamPlaybackSource[]> {
+      const video = await getVideo(connection, request.remoteId);
+      const instanceUrl = instanceOf(connection);
+      const hlsUrls =
+        video.isLive === true
+          ? [liveHlsUrl(connection, video.uuid)]
+          : (video.streamingPlaylists ?? []).filter((p) => p.type === 1).map((p) => p.playlistUrl);
+      const sources: StreamPlaybackSource[] = hlsUrls.map((url) => ({
+        remoteId: video.uuid,
+        url: new URL(url, instanceUrl).toString(),
+        kind: "hls",
+        protocol: "https",
+      }));
+      sources.push({
+        remoteId: video.uuid,
+        url: `${instanceUrl}/videos/embed/${video.uuid}`,
+        kind: "embed",
+        protocol: "https",
+      });
+      return sources;
+    },
+
+    /**
+     * With subjectRemoteId: owner video stats (overall + viewers timeseries).
+     * Without: instance-wide /server/stats (no time series — from/to unused).
+     */
+    async getAnalytics(
+      connection: ConnectorConnection,
+      request: { subjectRemoteId?: string; from: Date; to: Date },
+    ): Promise<{ values: Record<string, number>; series: { at: Date; values: Record<string, number> }[] }> {
+      if (request.subjectRemoteId === undefined) {
+        const stats = await api<unknown>(connection, "GET", "/api/v1/server/stats");
+        return { values: numericValues(stats), series: [] };
+      }
+      const range = new URLSearchParams({
+        startDate: request.from.toISOString(),
+        endDate: request.to.toISOString(),
+      });
+      const base = `${videoPath(request.subjectRemoteId)}/stats`;
+      const overall = await api<unknown>(connection, "GET", `${base}/overall?${range}`);
+      const viewers = await api<PtTimeseries>(connection, "GET", `${base}/timeseries/viewers?${range}`);
+      return {
+        values: numericValues(overall),
+        series: (viewers.data ?? []).map((point) => ({ at: new Date(point.date), values: { viewers: point.value } })),
+      };
+    },
+  };
+
+  // WP7 bulk-import seam: unauthenticated resolution over the supplied
+  // transport (an egress-backed fetch in the API, a stub in tests). Public
+  // endpoints only — resolving other users' channels never needs the token.
+  return Object.assign(connector, { resolveSource: resolvePeerTubeSource });
+}
diff --git a/packages/connector-peertube/src/resolve.test.ts b/packages/connector-peertube/src/resolve.test.ts
new file mode 100644
index 0000000..2cff90b
--- /dev/null
+++ b/packages/connector-peertube/src/resolve.test.ts
@@ -0,0 +1,116 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+  canonicalPeerTubeHost,
+  channelRemoteRef,
+  PeerTubeResolveError,
+  resolvePeerTubeSource,
+  videoRemoteRef,
+} from "./resolve.js";
+
+const INSTANCE = "https://video.example";
+const UUID = "0d1c2b3a-4e5f-4a6b-8c7d-9e0f1a2b3c4d";
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), { status, headers: { "content-type": "application/json" } });
+}
+
+describe("remote_ref canonicalization", () => {
+  it("IDNA-lowercases hosts in channel refs", () => {
+    expect(channelRemoteRef("alice", "VIDEO.Example.")).toBe("channel:alice@video.example");
+    expect(channelRemoteRef("Alice", "vïdeo.example")).toBe(channelRemoteRef("alice", "xn--vdeo-5pa.example"));
+  });
+
+  it("lowercases uuids in video refs", () => {
+    expect(videoRemoteRef(UUID.toUpperCase(), "video.example")).toBe(`video:${UUID}@video.example`);
+  });
+
+  it("canonicalPeerTubeHost strips brackets and trailing dots", () => {
+    expect(canonicalPeerTubeHost("[video.example].")).toBe("video.example");
+    expect(canonicalPeerTubeHost("")).toBe("");
+  });
+});
+
+describe("resolvePeerTubeSource", () => {
+  it("resolves a channel through the public video-channels endpoint", async () => {
+    const fetch = vi.fn(async (url: string) => {
+      expect(url).toBe(`${INSTANCE}/api/v1/video-channels/alice%40video.example`);
+      return json({ id: 7, name: "alice", host: "video.example", displayName: "Alice's channel" });
+    });
+    const result = await resolvePeerTubeSource("channel", "alice", "video.example", { fetch });
+    expect(result).toMatchObject({
+      remoteRef: "channel:alice@video.example",
+      instanceUrl: INSTANCE,
+      live: true,
+      label: "Alice's channel",
+      channelId: 7,
+    });
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("resolves a running live: isLive + PUBLISHED, deterministic master.m3u8", async () => {
+    const fetch = vi.fn(async () => json({ uuid: UUID, name: "My live", isLive: true, state: { id: 1, label: "Published" } }));
+    const result = await resolvePeerTubeSource("live", UUID, "video.example", { fetch });
+    expect(result.live).toBe(true);
+    expect(result.playbackHlsUrl).toBe(`${INSTANCE}/static/streaming-playlists/hls/${UUID}/master.m3u8`);
+    expect(result.remoteRef).toBe(`video:${UUID}@video.example`);
+  });
+
+  it("a WAITING_FOR_LIVE video is not live and carries no playback URL", async () => {
+    const fetch = vi.fn(async () => json({ uuid: UUID, name: "Waiting", isLive: true, state: { id: 4 } }));
+    const result = await resolvePeerTubeSource("live", UUID, "video.example", { fetch });
+    expect(result.live).toBe(false);
+    expect(result.playbackHlsUrl).toBeUndefined();
+  });
+
+  it("a VOD uses the API streamingPlaylists[].playlistUrl (type 1 only)", async () => {
+    const fetch = vi.fn(async () => json({
+      uuid: UUID, name: "VOD", isLive: false, state: { id: 1 },
+      streamingPlaylists: [
+        { id: 1, type: 2, playlistUrl: "/dash/manifest.mpd" },
+        { id: 2, type: 1, playlistUrl: "/static/streaming-playlists/hls/x/master.m3u8" },
+      ],
+    }));
+    const result = await resolvePeerTubeSource("live", UUID, "video.example", { fetch });
+    expect(result.live).toBe(false);
+    expect(result.playbackHlsUrl).toBe(`${INSTANCE}/static/streaming-playlists/hls/x/master.m3u8`);
+  });
+
+  it("404 maps to not_found (invalid row), 500 to upstream (failed row), 403 to denied", async () => {
+    for (const [status, reason] of [[404, "not_found"], [410, "not_found"], [500, "upstream"], [403, "denied"]] as const) {
+      const fetch = vi.fn(async () => json({ detail: "nope" }, status));
+      await expect(resolvePeerTubeSource("channel", "alice", "video.example", { fetch }))
+        .rejects.toMatchObject({ reason });
+      await expect(resolvePeerTubeSource("live", UUID, "video.example", { fetch }))
+        .rejects.toMatchObject({ reason });
+    }
+  });
+
+  it("transport failures are upstream, malformed payloads are upstream", async () => {
+    const dead = vi.fn(async () => { throw new TypeError("socket hang up"); });
+    await expect(resolvePeerTubeSource("channel", "alice", "video.example", { fetch: dead })).rejects.toMatchObject({ reason: "upstream" });
+    const garbage = vi.fn(async () => new Response("<html>not peertube</html>", { status: 200 }));
+    await expect(resolvePeerTubeSource("channel", "alice", "video.example", { fetch: garbage })).rejects.toBeInstanceOf(PeerTubeResolveError);
+    const notVideo = vi.fn(async () => json({ name: "not a video" }));
+    await expect(resolvePeerTubeSource("live", UUID, "video.example", { fetch: notVideo })).rejects.toMatchObject({ reason: "upstream" });
+  });
+
+  it("forwards the abort signal to the transport", async () => {
+    const fetch = vi.fn(async (_url: string, init?: RequestInit) => {
+      expect((init as { signal?: AbortSignal } | undefined)?.signal?.aborted).toBe(true);
+      return json({ uuid: UUID, isLive: false, name: "x", state: { id: 1 } });
+    });
+    const controller = new AbortController();
+    controller.abort();
+    await resolvePeerTubeSource("live", UUID, "video.example", { fetch, signal: controller.signal });
+    expect(fetch).toHaveBeenCalledOnce();
+  });
+
+  it("a shortUUID is passed through to the videos endpoint", async () => {
+    const fetch = vi.fn(async (url: string) => {
+      expect(url.endsWith("/api/v1/videos/abc123_XY")).toBe(true);
+      return json({ uuid: UUID, isLive: false, name: "x", state: { id: 1 } });
+    });
+    const result = await resolvePeerTubeSource("live", "abc123_XY", "video.example", { fetch });
+    expect(result.remoteRef).toBe(`video:${UUID}@video.example`);
+  });
+});
diff --git a/packages/connector-peertube/src/resolve.ts b/packages/connector-peertube/src/resolve.ts
new file mode 100644
index 0000000..a13a7c5
--- /dev/null
+++ b/packages/connector-peertube/src/resolve.ts
@@ -0,0 +1,236 @@
+/**
+ * WP7 bulk-import resolver: turn a pasted PeerTube handle / watch URL / video
+ * uuid into the canonical remote identity, using @tactical-media-broadcast-hub/egress for
+ * every network call (per-host budgets + outbound policy honored there).
+ *
+ * Kept in its own module because it must NOT depend on the connector's
+ * authenticated session: bulk import resolves *other people's* channels and
+ * lives, which are public data on every instance. Public endpoints only:
+ *   GET /api/v1/video-channels/{name@host}   -> channel actor (id, host)
+ *   GET /api/v1/videos/{uuid|shortUUID}      -> video (isLive, state, playlists)
+ *
+ * The connector's `fetchImpl` option stays the transport seam for tests; in
+ * production the API passes an egress-backed fetch (createEgressClient's
+ * egressFetch bound to hostClass "import"), so DNS pinning, SSRF denial,
+ * per-host budgets and redirect policy are all the egress package's.
+ *
+ * remote_ref canonical form (IDNA-lowercased host, lowercase name/uuid):
+ *   channel:{name}@{host}
+ *   video:{uuid}@{host}
+ */
+
+import { ConnectorError } from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "peertube";
+
+/** What the import service needs back per row. */
+export interface ResolvedPeerTubeSource {
+  remoteRef: string;
+  /** Canonical instance origin, e.g. https://video.example */
+  instanceUrl: string;
+  /** Playback HLS when the remote already exposes one (lives: master.m3u8). */
+  playbackHlsUrl?: string;
+  /** True when the resolved video is currently a live (isLive + PUBLISHED). */
+  live: boolean;
+  /** Display name for the source label (channel displayName / video name). */
+  label?: string;
+  /** Numeric channel id, when a channel was resolved. */
+  channelId?: number;
+}
+
+export class PeerTubeResolveError extends Error {
+  /** "not_found" -> row counted invalid; "upstream" -> row counted failed. */
+  constructor(readonly reason: "not_found" | "upstream" | "denied", message: string) {
+    super(message);
+    this.name = "PeerTubeResolveError";
+  }
+}
+
+interface PtChannelActor {
+  id: number;
+  name: string;
+  host: string;
+  displayName?: string;
+}
+
+interface PtResolveVideo {
+  uuid: string;
+  name: string;
+  isLive?: boolean;
+  state?: { id: number } | number;
+  streamingPlaylists?: { id: number; type: number; playlistUrl: string }[];
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+/** IDNA-lowercase host (brackets/dot stripped); "" when unusable. */
+export function canonicalPeerTubeHost(host: string): string {
+  const lowered = host.trim().replace(/[[\]]/g, "").replace(/[.]+$/, "").toLowerCase();
+  if (lowered === "") return "";
+  try {
+    const ascii = new URL(`https://${lowered}`).hostname;
+    return ascii === "" ? "" : ascii;
+  } catch {
+    return "";
+  }
+}
+
+/** Canonical, collision-free remote_ref for an imported channel or video. */
+export function channelRemoteRef(name: string, host: string): string {
+  return `channel:${name.toLowerCase()}@${canonicalPeerTubeHost(host)}`;
+}
+
+export function videoRemoteRef(uuid: string, host: string): string {
+  return `video:${uuid.toLowerCase()}@${canonicalPeerTubeHost(host)}`;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+async function readJson(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (text.length === 0) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    throw new PeerTubeResolveError("upstream", `${PROVIDER}: instance returned a non-JSON body`);
+  }
+}
+
+export interface PeerTubeResolverOptions {
+  /**
+   * Transport used for the two public GETs. Production: an egress client's
+   * egressFetch (per-host budgets). Tests: a stub.
+   */
+  fetch: (url: string, init?: RequestInit) => Promise<Response>;
+  /** Abort/deadline is the caller's responsibility; forwarded verbatim. */
+  signal?: AbortSignal;
+  /** Instance host used when a bare video uuid names no host. */
+  defaultHost?: string;
+}
+
+/**
+ * Resolves one already-normalized identity. `kind`/`name`/`host` come from
+ * the import normalizer (leading `@` stripped, host canonical, name lower).
+ */
+export async function resolvePeerTubeSource(
+  kind: "channel" | "live",
+  name: string,
+  host: string,
+  options: PeerTubeResolverOptions,
+): Promise<ResolvedPeerTubeSource> {
+  const origin = `https://${canonicalPeerTubeHost(host)}`;
+  if (origin === "https://") throw new PeerTubeResolveError("not_found", `${PROVIDER}: no instance host`);
+
+  if (kind === "channel") {
+    // Federated handle form name@host (docs/research/peertube-api-facts.md §2).
+    const handle = `${name}@${canonicalPeerTubeHost(host)}`;
+    let response: Response;
+    try {
+      response = await options.fetch(`${origin}/api/v1/video-channels/${encodeURIComponent(handle)}`, {
+        headers: { accept: "application/json" },
+        signal: options.signal,
+      });
+    } catch {
+      throw new PeerTubeResolveError("upstream", `${PROVIDER}: instance request failed`);
+    }
+    if (response.status === 404 || response.status === 410) {
+      throw new PeerTubeResolveError("not_found", `${PROVIDER}: channel not found on the instance`);
+    }
+    if (!response.ok) {
+      throw new PeerTubeResolveError(
+        response.status === 401 || response.status === 403 ? "denied" : "upstream",
+        `${PROVIDER}: instance answered HTTP ${response.status}`,
+      );
+    }
+    const body = await readJson(response);
+    if (!isRecord(body) || typeof body.name !== "string" || typeof body.host !== "string") {
+      throw new PeerTubeResolveError("upstream", `${PROVIDER}: instance returned an invalid channel payload`);
+    }
+    const actor = body as unknown as PtChannelActor;
+    return {
+      remoteRef: channelRemoteRef(actor.name, actor.host),
+      instanceUrl: origin,
+      // A channel source is a *candidate* feed; `live` only means "this row
+      // points at something live-capable", which a channel always is.
+      live: true,
+      label: actor.displayName ?? actor.name,
+      channelId: typeof actor.id === "number" ? actor.id : undefined,
+    };
+  }
+
+  // live/video: uuid or shortUUID.
+  const id = UUID.test(name) ? name.toLowerCase() : name;
+  let response: Response;
+  try {
+    response = await options.fetch(`${origin}/api/v1/videos/${encodeURIComponent(id)}`, {
+      headers: { accept: "application/json" },
+      signal: options.signal,
+    });
+  } catch {
+    throw new PeerTubeResolveError("upstream", `${PROVIDER}: instance request failed`);
+  }
+  if (response.status === 404 || response.status === 410) {
+    throw new PeerTubeResolveError("not_found", `${PROVIDER}: video not found on the instance`);
+  }
+  if (!response.ok) {
+    throw new PeerTubeResolveError(
+      response.status === 401 || response.status === 403 ? "denied" : "upstream",
+      `${PROVIDER}: instance answered HTTP ${response.status}`,
+    );
+  }
+  const body = await readJson(response);
+  if (!isRecord(body) || typeof body.uuid !== "string" || typeof body.isLive !== "boolean") {
+    throw new PeerTubeResolveError("upstream", `${PROVIDER}: instance returned an invalid video payload`);
+  }
+  const video = body as unknown as PtResolveVideo;
+  // A running live stays PUBLISHED (state 1); there is no LIVE VideoState.
+  const stateId = typeof video.state === "object" && video.state !== null
+    ? (video.state as { id?: unknown }).id
+    : video.state;
+  const live = video.isLive === true && (stateId === undefined || stateId === 1);
+  const result: ResolvedPeerTubeSource = {
+    remoteRef: videoRemoteRef(video.uuid, host),
+    instanceUrl: origin,
+    live,
+    label: typeof video.name === "string" ? video.name : undefined,
+  };
+  const hls = (video.streamingPlaylists ?? []).find((playlist) => playlist.type === 1)?.playlistUrl;
+  if (live) {
+    // Deterministic live master playlist (facts §5) — probeable before start.
+    result.playbackHlsUrl = `${origin}/static/streaming-playlists/hls/${video.uuid}/master.m3u8`;
+  } else if (typeof hls === "string" && hls.length > 0) {
+    result.playbackHlsUrl = new URL(hls, origin).toString();
+  }
+  return result;
+}
+
+/** Back-compat helper for callers holding a raw user string. */
+export async function resolvePeerTubeInput(input: string, options: PeerTubeResolverOptions): Promise<ResolvedPeerTubeSource> {
+  const text = input.trim().replace(/^@+/, "");
+  try {
+    const url = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(text) ? text : `https://${text}`);
+    const host = canonicalPeerTubeHost(url.hostname);
+    const segments = url.pathname.split("/").filter((part) => part !== "");
+    if ((segments[0] === "w" || segments[0] === "videos" || segments[0] === "embed") && segments.length === 2) {
+      return resolvePeerTubeSource("live", segments[1]!.split(";")[0]!, host, options);
+    }
+    if ((segments[0] === "c" || segments[0] === "a" || segments[0] === "video-channels") && segments.length === 2) {
+      return resolvePeerTubeSource("channel", decodeURIComponent(segments[1]!), host, options);
+    }
+    const handle = /^([^\s@/]+)@([^\s@/]+)$/.exec(text);
+    if (handle) {
+      const kind = UUID.test(handle[1]!) ? "live" : "channel";
+      return resolvePeerTubeSource(kind, handle[1]!, handle[2]!, options);
+    }
+    if (UUID.test(text)) {
+      if (!options.defaultHost) throw new PeerTubeResolveError("not_found", `${PROVIDER}: a bare video id needs an instance host`);
+      return resolvePeerTubeSource("live", text, options.defaultHost, options);
+    }
+  } catch (error) {
+    if (error instanceof PeerTubeResolveError) throw error;
+    if (error instanceof ConnectorError) throw error;
+  }
+  throw new PeerTubeResolveError("not_found", `${PROVIDER}: input is not a resolvable PeerTube source`);
+}
diff --git a/packages/connector-peertube/tsconfig.json b/packages/connector-peertube/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-peertube/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-reddit/package.json b/packages/connector-reddit/package.json
new file mode 100644
index 0000000..0bc129c
--- /dev/null
+++ b/packages/connector-reddit/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-reddit",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-reddit/src/contract.test.ts b/packages/connector-reddit/src/contract.test.ts
new file mode 100644
index 0000000..12edaaf
--- /dev/null
+++ b/packages/connector-reddit/src/contract.test.ts
@@ -0,0 +1,376 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createRedditConnector, REDDIT_RATE_POLICY } from "./index.js";
+
+interface StubCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
+interface StubState {
+  calls: StubCall[];
+  deleted: string[];
+}
+
+const connection: ConnectorConnection = {
+  id: "conn-reddit",
+  workspaceId: "ws-1",
+  provider: "reddit",
+  channelId: "u/anarchoposter",
+  credentialId: { kind: "credential-ref", id: "cred-reddit" },
+  fields: {
+    accessToken: "stub-access-token",
+    refreshToken: "stub-refresh-token",
+    username: "anarchoposter",
+  },
+  createdAt: new Date(),
+};
+
+function ok(body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function formBody(init: RequestInit | undefined): URLSearchParams {
+  const body = init?.body;
+  if (!(body instanceof URLSearchParams)) {
+    throw new Error("expected URLSearchParams request body");
+  }
+  return body;
+}
+
+function stubApi(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    state.calls.push({ url, init });
+    const parsed = new URL(url);
+
+    if (parsed.pathname === "/api/v1/me") {
+      return ok({
+        id: "reddit-user-1",
+        name: "anarchoposter",
+        icon_img: "https://styles.redditmedia.com/avatar.png?x=1&amp;y=2",
+      });
+    }
+
+    if (parsed.pathname === "/api/submit") {
+      const body = formBody(init);
+      const kind = body.get("kind");
+      if (kind === "crosspost") {
+        if (body.get("crosspost_fullname") !== "t3_original1") {
+          return new Response(JSON.stringify({ message: "Bad Request" }), { status: 400 });
+        }
+        return ok({
+          json: {
+            errors: [],
+            data: {
+              id: "cross123",
+              url: "https://www.reddit.com/r/news/comments/cross123/crosspost/",
+            },
+          },
+        });
+      }
+      return ok({
+        json: {
+          errors: [],
+          data: {
+            id: kind === "link" ? "link123" : "self123",
+            url: `https://www.reddit.com/r/${body.get("sr")}/comments/${kind === "link" ? "link123" : "self123"}/post/`,
+          },
+        },
+      });
+    }
+
+    if (parsed.pathname === "/api/comment") {
+      const body = formBody(init);
+      return ok({
+        json: {
+          errors: [],
+          data: {
+            id: "comment123",
+            name: "t1_comment123",
+            url: `https://www.reddit.com/comments/post123/_/${body.get("thing_id")}`,
+          },
+        },
+      });
+    }
+
+    if (parsed.pathname === "/r/typescript/hot") {
+      return ok({
+        data: {
+          after: "t3_next",
+          children: [
+            {
+              kind: "t3",
+              data: {
+                id: "feed123",
+                name: "t3_feed123",
+                title: "TypeScript 6 ships",
+                author: "compilerfan",
+                score: 314,
+                num_comments: 27,
+                permalink: "/r/typescript/comments/feed123/typescript_6_ships/",
+                selftext: "What changed in this release.",
+                created_utc: 1_800_000_000,
+              },
+            },
+          ],
+        },
+      });
+    }
+
+    if (parsed.pathname === "/comments/post123.json") {
+      return ok([
+        { data: { after: null, children: [] } },
+        {
+          data: {
+            after: null,
+            children: [
+              {
+                kind: "t1",
+                data: {
+                  id: "comment123",
+                  name: "t1_comment123",
+                  parent_id: "t3_post123",
+                  author: "reader",
+                  body: "Useful write-up.",
+                  created_utc: 1_800_000_100,
+                },
+              },
+            ],
+          },
+        },
+      ]);
+    }
+
+    if (parsed.pathname === "/api/v1/message/inbox") {
+      return ok({
+        data: {
+          after: "t4_next",
+          children: [
+            {
+              kind: "t4",
+              data: {
+                id: "message123",
+                name: "t4_message123",
+                author: "alice",
+                dest: "anarchoposter",
+                body: "Can you share the source?",
+                created_utc: 1_800_000_200,
+                first_message_name: "t4_thread123",
+              },
+            },
+          ],
+        },
+      });
+    }
+
+    if (parsed.pathname === "/api/del") {
+      state.deleted.push(String(formBody(init).get("id")));
+      return ok({});
+    }
+
+    return new Response(JSON.stringify({ message: `unhandled ${parsed.pathname}` }), { status: 404 });
+  };
+}
+
+function createHarness(): {
+  connector: ReturnType<typeof createRedditConnector>;
+  state: StubState;
+} {
+  const state: StubState = { calls: [], deleted: [] };
+  return {
+    state,
+    connector: createRedditConnector({ fetchImpl: stubApi(state) }),
+  };
+}
+
+function post(
+  text: string,
+  providerMetadata: Record<string, unknown>,
+): NormalizedPost {
+  return {
+    text,
+    mediaAssetIds: [],
+    visibility: "public",
+    providerMetadata,
+  };
+}
+
+connectorContractTests(createHarness().connector, { connection });
+
+describe("reddit connector: manifest and identity", () => {
+  it("declares the documented rate policy and honest capabilities", () => {
+    const manifest = createHarness().connector.manifest();
+    expect(REDDIT_RATE_POLICY).toEqual({ requestsPerSecond: 0.8 });
+    expect(manifest.capabilities).toMatchObject({
+      publishText: true,
+      publishImages: false,
+      feed: true,
+      comments: true,
+      replies: true,
+      amplifyShare: true,
+      amplifyRepost: false,
+      amplifyQuote: false,
+      directMessages: true,
+      deletePublication: true,
+      webhooks: false,
+      nativeScheduling: false,
+    });
+    expect(manifest.oauth).toEqual({
+      kind: "token",
+      scopes: ["identity", "submit", "read", "privatemessages", "edit"],
+    });
+  });
+
+  it("gets the current account with bearer authentication", async () => {
+    const { connector, state } = createHarness();
+    const identity = await connector.getIdentity(connection);
+    expect(identity).toEqual({
+      provider: "reddit",
+      remoteId: "reddit-user-1",
+      handle: "u/anarchoposter",
+      displayName: "anarchoposter",
+      avatarUrl: "https://styles.redditmedia.com/avatar.png?x=1&y=2",
+    });
+    expect(state.calls[0]?.init?.headers).toMatchObject({
+      authorization: "Bearer stub-access-token",
+    });
+  });
+
+  it("fails closed without an access token", async () => {
+    const { connector } = createHarness();
+    await expect(
+      connector.getIdentity({ ...connection, fields: { ...connection.fields, accessToken: "" } }),
+    ).rejects.toThrow(/missing OAuth access token/);
+  });
+});
+
+describe("reddit connector: publication roundtrips", () => {
+  it("submits a self post using the first line as title", async () => {
+    const { connector, state } = createHarness();
+    const publication = await connector.publish?.(
+      connection,
+      post("Release notes\nA detailed changelog.", { sr: "r/typescript", kind: "self" }),
+    );
+    const call = state.calls[0];
+    expect(call?.url).toBe("https://oauth.reddit.com/api/submit");
+    expect(Object.fromEntries(formBody(call?.init))).toEqual({
+      api_type: "json",
+      resubmit: "true",
+      sr: "typescript",
+      kind: "self",
+      title: "Release notes",
+      text: "A detailed changelog.",
+    });
+    expect(publication?.remoteId).toBe("self123");
+    expect(publication?.providerMetadata).toMatchObject({ sr: "typescript", kind: "self" });
+  });
+
+  it("submits a link post with providerMetadata.url", async () => {
+    const { connector, state } = createHarness();
+    const publication = await connector.publish?.(
+      connection,
+      post("Read this", {
+        sr: "typescript",
+        kind: "link",
+        url: "https://example.com/article",
+      }),
+    );
+    const body = formBody(state.calls[0]?.init);
+    expect(body.get("url")).toBe("https://example.com/article");
+    expect(body.get("text")).toBeNull();
+    expect(publication?.remoteId).toBe("link123");
+  });
+
+  it("crossposts without triggering the stub's 400 guard", async () => {
+    const { connector, state } = createHarness();
+    const publication = await connector.amplify(connection, {
+      kind: "share",
+      targetRemoteId: "original1",
+      providerMetadata: { sr: "news" },
+    });
+    const body = formBody(state.calls[0]?.init);
+    expect(body.get("kind")).toBe("crosspost");
+    expect(body.get("crosspost_fullname")).toBe("t3_original1");
+    expect(body.get("sr")).toBe("news");
+    expect(publication.remoteId).toBe("cross123");
+    expect(publication.draftId).toBe("amplify:share");
+  });
+
+  it("rejects repost and quote amplification", async () => {
+    const { connector } = createHarness();
+    await expect(
+      connector.amplify(connection, { kind: "repost", targetRemoteId: "post123" }),
+    ).rejects.toThrow(/amplify:repost/);
+  });
+});
+
+describe("reddit connector: feeds, comments, messages, and deletion", () => {
+  it("maps a subreddit hot listing and cursor", async () => {
+    const { connector, state } = createHarness();
+    const page = await connector.getFeed?.(connection, {
+      kind: "home",
+      query: "typescript",
+      cursor: "t3_previous",
+      limit: 25,
+    });
+    expect(state.calls[0]?.url).toContain("/r/typescript/hot?limit=25&after=t3_previous");
+    expect(page?.nextCursor).toBe("t3_next");
+    expect(page?.items[0]).toMatchObject({
+      remoteId: "feed123",
+      authorHandle: "u/compilerfan",
+      text: "TypeScript 6 ships\n\nWhat changed in this release.",
+      metrics: { score: 314, comments: 27 },
+    });
+  });
+
+  it("reads comments and submits top-level comments and replies", async () => {
+    const readHarness = createHarness();
+    const comments = await readHarness.connector.getComments?.(connection, {
+      onRemoteId: "post123",
+      limit: 25,
+    });
+    expect(comments?.items[0]).toMatchObject({
+      remoteId: "comment123",
+      onRemoteId: "t3_post123",
+      authorHandle: "u/reader",
+      text: "Useful write-up.",
+    });
+
+    const topLevel = createHarness();
+    await topLevel.connector.reply?.(connection, { onRemoteId: "post123", text: "Thanks!" });
+    expect(formBody(topLevel.state.calls[0]?.init).get("thing_id")).toBe("t3_post123");
+
+    const nested = createHarness();
+    const reply = await nested.connector.reply?.(connection, {
+      onRemoteId: "t1_comment123",
+      text: "Agreed.",
+    });
+    expect(formBody(nested.state.calls[0]?.init).get("thing_id")).toBe("t1_comment123");
+    expect(reply?.remoteId).toBe("comment123");
+  });
+
+  it("maps the inbox to direct messages", async () => {
+    const { connector } = createHarness();
+    const inbox = await connector.getMessages?.(connection, { limit: 25 });
+    expect(inbox?.nextCursor).toBe("t4_next");
+    expect(inbox?.items[0]).toMatchObject({
+      id: "t4_message123",
+      provider: "reddit",
+      conversationRemoteId: "t4_thread123",
+      fromHandle: "u/alice",
+      toHandle: "u/anarchoposter",
+      text: "Can you share the source?",
+    });
+  });
+
+  it("deletes a post by fullname", async () => {
+    const { connector, state } = createHarness();
+    await connector.deletePublication?.(connection, "post123");
+    expect(state.deleted).toEqual(["t3_post123"]);
+  });
+});
diff --git a/packages/connector-reddit/src/index.ts b/packages/connector-reddit/src/index.ts
new file mode 100644
index 0000000..ae2b7da
--- /dev/null
+++ b/packages/connector-reddit/src/index.ts
@@ -0,0 +1,560 @@
+/**
+ * Reddit connector — OAuth API access for posts, community feeds, comments,
+ * crossposts, inbox messages, and deletion.
+ *
+ * Reddit application registration happens at https://www.reddit.com/prefs/apps.
+ * The application exchanges authorization codes (and later refresh tokens) at
+ * https://www.reddit.com/api/v1/access_token using HTTP Basic client auth. The
+ * resulting access and refresh tokens are supplied as secret connection fields.
+ */
+import { randomUUID } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  DirectMessage,
+  FeedItem,
+  NormalizedIdentity,
+  NormalizedPost,
+  Page,
+  Publication,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  RateLimitedHttpClient,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "reddit";
+const API_BASE = "https://oauth.reddit.com";
+const TITLE_LIMIT = 300;
+const DEFAULT_FEED_LIMIT = 25;
+
+export const REDDIT_RATE_POLICY = { requestsPerSecond: 0.8 } as const;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: false,
+  feed: true,
+  comments: true,
+  replies: true,
+  amplifyRepost: false,
+  amplifyQuote: false,
+  amplifyShare: true,
+  directMessages: true,
+  deletePublication: true,
+  webhooks: false,
+  nativeScheduling: false,
+};
+
+export interface RedditConnectorOptions {
+  /** Fetch override used by contract tests and embedding applications. */
+  fetchImpl?: typeof fetch;
+}
+
+export interface RedditAmplifyRequest {
+  kind: "repost" | "quote" | "share";
+  targetRemoteId: string;
+  commentary?: string;
+  quoteAssetIds?: string[];
+  /** Destination community for the crosspost. */
+  providerMetadata?: Record<string, unknown>;
+}
+
+export interface RedditConnector extends Omit<PlatformConnector, "amplify"> {
+  amplify(
+    connection: ConnectorConnection,
+    request: RedditAmplifyRequest,
+  ): Promise<Publication>;
+}
+
+interface RedditMe {
+  id?: string;
+  name: string;
+  icon_img?: string;
+}
+
+interface RedditSubmitData {
+  id?: string;
+  name?: string;
+  url?: string;
+  things?: { data: RedditSubmitData }[];
+}
+
+interface RedditJsonResponse {
+  json: {
+    errors?: unknown[];
+    data?: RedditSubmitData;
+  };
+}
+
+interface RedditListing<T> {
+  data: {
+    after: string | null;
+    children: { kind: string; data: T }[];
+  };
+}
+
+interface RedditPost {
+  id: string;
+  name?: string;
+  title: string;
+  author: string;
+  score: number;
+  num_comments: number;
+  permalink: string;
+  selftext?: string;
+  created_utc: number;
+  url?: string;
+}
+
+interface RedditComment {
+  id: string;
+  name?: string;
+  parent_id?: string;
+  author: string;
+  body: string;
+  created_utc: number;
+}
+
+interface RedditMessage {
+  id: string;
+  name?: string;
+  author?: string;
+  dest?: string;
+  body: string;
+  created_utc: number;
+  first_message_name?: string;
+  parent_id?: string;
+}
+
+interface SubmitResult {
+  id: string;
+  url?: string;
+}
+
+function stringMetadata(metadata: Record<string, unknown>, key: string): string | undefined {
+  const value = metadata[key];
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function stripPrefix(value: string, prefix: string): string {
+  return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+
+function subredditName(value: string): string {
+  const normalized = value.trim().replace(/^\/?r\//i, "");
+  if (!/^[A-Za-z0-9_]{2,21}$/.test(normalized)) {
+    throw new ConnectorError(`${PROVIDER}: invalid subreddit "${value}"`, PROVIDER);
+  }
+  return normalized;
+}
+
+function fullname(remoteId: string, defaultKind: "t1" | "t3"): string {
+  if (/^t[13]_[A-Za-z0-9]+$/.test(remoteId)) return remoteId;
+  const id = remoteId.trim();
+  if (!/^[A-Za-z0-9]+$/.test(id)) {
+    throw new ConnectorError(`${PROVIDER}: invalid remote id "${remoteId}"`, PROVIDER);
+  }
+  return `${defaultKind}_${id}`;
+}
+
+function formPost(values: Record<string, string>): RequestInit {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(values),
+  };
+}
+
+function pageOf<T>(items: T[], nextCursor: string | null | undefined): Page<T> {
+  return nextCursor === null || nextCursor === undefined
+    ? { items }
+    : { items, nextCursor };
+}
+
+function normalizeAvatar(url: string | undefined): string | undefined {
+  return url?.replace(/&amp;/g, "&");
+}
+
+function postText(post: RedditPost): string {
+  const body = post.selftext?.trim();
+  return body === undefined || body.length === 0 ? post.title : `${post.title}\n\n${body}`;
+}
+
+function titleAndBody(post: NormalizedPost): { title: string; text: string } {
+  const explicitTitle = stringMetadata(post.providerMetadata, "title");
+  if (explicitTitle !== undefined) return { title: explicitTitle, text: post.text };
+
+  const normalized = post.text.trim();
+  const newline = normalized.indexOf("\n");
+  if (newline === -1) return { title: normalized, text: "" };
+  return {
+    title: normalized.slice(0, newline).trim(),
+    text: normalized.slice(newline + 1).trim(),
+  };
+}
+
+export function createRedditConnector(options: RedditConnectorOptions = {}): RedditConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: REDDIT_RATE_POLICY.requestsPerSecond,
+    fetchImpl: options.fetchImpl,
+  });
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Reddit",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "accessToken",
+        label: "OAuth access token",
+        required: true,
+        secret: true,
+      },
+      {
+        name: "refreshToken",
+        label: "OAuth refresh token",
+        required: true,
+        secret: true,
+      },
+      {
+        name: "username",
+        label: "Reddit username",
+        required: true,
+        secret: false,
+        placeholder: "your_username",
+      },
+    ],
+    oauth: {
+      kind: "token",
+      scopes: ["identity", "submit", "read", "privatemessages", "edit"],
+    },
+    docsUrl: "https://github.com/reddit-archive/reddit/wiki/OAuth2",
+  };
+
+  function accessToken(connection: ConnectorConnection): string {
+    const token = connection.fields["accessToken"];
+    if (token === undefined || token.trim().length === 0) {
+      throw new AuthError(
+        `${PROVIDER}: missing OAuth access token in the accessToken connection field`,
+        PROVIDER,
+        false,
+      );
+    }
+    return token;
+  }
+
+  async function send(
+    connection: ConnectorConnection,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<Response> {
+    const response = await client.request(PROVIDER, `${API_BASE}${path}`, {
+      ...init,
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${accessToken(connection)}`,
+        "user-agent": "AnarchoPoster/0.1 (Reddit connector)",
+        ...init.headers,
+      },
+    });
+    if (!response.ok) {
+      const message = `${PROVIDER}: HTTP ${response.status} for ${new URL(response.url || `${API_BASE}${path}`).pathname}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthError(message, PROVIDER, false);
+      }
+      throw new ConnectorError(message, PROVIDER, { status: response.status });
+    }
+    return response;
+  }
+
+  async function api<T>(
+    connection: ConnectorConnection,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<T> {
+    const response = await send(connection, path, init);
+    try {
+      return (await response.json()) as T;
+    } catch (cause) {
+      throw new ConnectorError(`${PROVIDER}: non-JSON response for ${path}`, PROVIDER, cause);
+    }
+  }
+
+  async function submit(
+    connection: ConnectorConnection,
+    values: Record<string, string>,
+  ): Promise<SubmitResult> {
+    const response = await api<RedditJsonResponse>(
+      connection,
+      "/api/submit",
+      formPost({ api_type: "json", resubmit: "true", ...values }),
+    );
+    const errors = response.json.errors ?? [];
+    if (errors.length > 0) {
+      throw new ConnectorError(`${PROVIDER}: submit rejected: ${JSON.stringify(errors)}`, PROVIDER);
+    }
+    const data = response.json.data;
+    const id = data?.id ?? (data?.name === undefined ? undefined : stripPrefix(data.name, "t3_"));
+    if (id === undefined || id.length === 0) {
+      throw new ConnectorError(`${PROVIDER}: submit response did not include a post id`, PROVIDER);
+    }
+    return { id, url: data?.url };
+  }
+
+  function publication(
+    connection: ConnectorConnection,
+    result: SubmitResult,
+    draftId: string,
+    providerMetadata: Record<string, unknown>,
+  ): Publication {
+    return {
+      id: randomUUID(),
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId: result.id,
+      remoteUrl: result.url,
+      publishedAt: new Date(),
+      providerMetadata,
+    };
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new ConnectorError(
+        `${PROVIDER}: register an app at reddit.com/prefs/apps, exchange the authorization code at /api/v1/access_token, then connect the access and refresh tokens`,
+        PROVIDER,
+      );
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      const me = await api<RedditMe>(connection, "/api/v1/me");
+      return {
+        provider: PROVIDER,
+        remoteId: me.id ?? me.name,
+        handle: `u/${me.name}`,
+        displayName: me.name,
+        avatarUrl: normalizeAvatar(me.icon_img),
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      if (post.mediaAssetIds.length > 0) {
+        throw new CapabilityNotSupportedError(PROVIDER, "publishImages");
+      }
+      const srValue = stringMetadata(post.providerMetadata, "sr");
+      if (srValue === undefined) {
+        throw new ConnectorError(`${PROVIDER}: providerMetadata.sr is required`, PROVIDER);
+      }
+      const sr = subredditName(srValue);
+      const kind = stringMetadata(post.providerMetadata, "kind") ?? "self";
+      if (kind !== "self" && kind !== "link") {
+        throw new ConnectorError(`${PROVIDER}: providerMetadata.kind must be self or link`, PROVIDER);
+      }
+      const { title, text } = titleAndBody(post);
+      if (title.length === 0) {
+        throw new ConnectorError(`${PROVIDER}: post title is required`, PROVIDER);
+      }
+      if (title.length > TITLE_LIMIT) {
+        throw new ConnectorError(
+          `${PROVIDER}: title is ${title.length} characters, over the ${TITLE_LIMIT} limit`,
+          PROVIDER,
+        );
+      }
+
+      const values: Record<string, string> = { sr, kind, title };
+      if (kind === "self") {
+        values["text"] = text;
+      } else {
+        const url = stringMetadata(post.providerMetadata, "url");
+        if (url === undefined) {
+          throw new ConnectorError(`${PROVIDER}: providerMetadata.url is required for link posts`, PROVIDER);
+        }
+        values["url"] = url;
+      }
+      const result = await submit(connection, values);
+      return publication(connection, result, "direct", {
+        ...post.providerMetadata,
+        sr,
+        kind,
+      });
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: RedditAmplifyRequest,
+    ): Promise<Publication> {
+      if (request.kind !== "share") {
+        throw new CapabilityNotSupportedError(PROVIDER, `amplify:${request.kind}`);
+      }
+      const srValue = request.providerMetadata === undefined
+        ? undefined
+        : stringMetadata(request.providerMetadata, "sr");
+      if (srValue === undefined) {
+        throw new ConnectorError(
+          `${PROVIDER}: providerMetadata.sr is required for a crosspost`,
+          PROVIDER,
+        );
+      }
+      const sr = subredditName(srValue);
+      const originalId = stripPrefix(request.targetRemoteId, "t3_");
+
+      // Manipulation-policy boundary: amplification creates a user-requested
+      // crosspost. It never calls /api/vote or performs automated voting;
+      // voting belongs only to an explicit, single user click in a manual UI.
+      const result = await submit(connection, {
+        sr,
+        kind: "crosspost",
+        crosspost_fullname: fullname(originalId, "t3"),
+        ...(request.commentary === undefined || request.commentary.length === 0
+          ? {}
+          : { title: request.commentary.slice(0, TITLE_LIMIT) }),
+      });
+      return publication(connection, result, "amplify:share", {
+        sr,
+        kind: "crosspost",
+        amplifies: originalId,
+      });
+    },
+
+    async getFeed(
+      connection: ConnectorConnection,
+      request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+    ): Promise<Page<FeedItem>> {
+      if (request.kind === "mentions") {
+        throw new CapabilityNotSupportedError(PROVIDER, "feed:mentions");
+      }
+      const srValue = request.query ?? connection.fields["subreddit"];
+      if (srValue === undefined || srValue.trim().length === 0) {
+        throw new ConnectorError(`${PROVIDER}: feed query must name a subreddit`, PROVIDER);
+      }
+      const sr = subredditName(srValue);
+      const limit = Math.max(1, Math.min(DEFAULT_FEED_LIMIT, request.limit));
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (request.cursor !== undefined) params.set("after", request.cursor);
+      const listing = await api<RedditListing<RedditPost>>(
+        connection,
+        `/r/${encodeURIComponent(sr)}/hot?${params}`,
+      );
+      const items = listing.data.children.map<FeedItem>(({ data }) => ({
+        id: data.name ?? `t3_${data.id}`,
+        provider: PROVIDER,
+        remoteId: data.id,
+        authorHandle: `u/${data.author}`,
+        text: postText(data),
+        mediaUrls: (data.selftext ?? "").trim().length === 0 && data.url !== undefined ? [data.url] : [],
+        createdAt: new Date(data.created_utc * 1000),
+        metrics: { score: data.score, comments: data.num_comments },
+      }));
+      return pageOf(items, listing.data.after);
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const id = stripPrefix(request.onRemoteId, "t3_");
+      const limit = Math.max(1, Math.min(100, request.limit));
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (request.cursor !== undefined) params.set("after", request.cursor);
+      const listings = await api<RedditListing<RedditPost | RedditComment>[]>(
+        connection,
+        `/comments/${encodeURIComponent(id)}.json?${params}`,
+      );
+      const comments = listings[1];
+      if (comments === undefined) return { items: [] };
+      const items = comments.data.children.flatMap<Comment>(({ kind, data }) => {
+        if (kind !== "t1" || !("body" in data)) return [];
+        return [{
+          id: data.name ?? `t1_${data.id}`,
+          provider: PROVIDER,
+          remoteId: data.id,
+          onRemoteId: data.parent_id ?? fullname(id, "t3"),
+          authorHandle: `u/${data.author}`,
+          text: data.body,
+          createdAt: new Date(data.created_utc * 1000),
+        }];
+      });
+      return pageOf(items, comments.data.after);
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const response = await api<RedditJsonResponse>(
+        connection,
+        "/api/comment",
+        formPost({
+          api_type: "json",
+          thing_id: fullname(request.onRemoteId, "t3"),
+          text: request.text,
+        }),
+      );
+      const errors = response.json.errors ?? [];
+      if (errors.length > 0) {
+        throw new ConnectorError(`${PROVIDER}: comment rejected: ${JSON.stringify(errors)}`, PROVIDER);
+      }
+      const responseData = response.json.data;
+      const data = responseData?.things?.[0]?.data ?? responseData;
+      const id = data?.id ?? (data?.name === undefined ? undefined : stripPrefix(data.name, "t1_"));
+      if (id === undefined || id.length === 0) {
+        throw new ConnectorError(`${PROVIDER}: comment response did not include an id`, PROVIDER);
+      }
+      return publication(connection, { id, url: data?.url }, "reply", {
+        onRemoteId: request.onRemoteId,
+      });
+    },
+
+    async getMessages(
+      connection: ConnectorConnection,
+      request: { conversationRemoteId?: string; cursor?: string; limit: number },
+    ): Promise<Page<DirectMessage>> {
+      const limit = Math.max(1, Math.min(100, request.limit));
+      const params = new URLSearchParams({ limit: String(limit) });
+      if (request.cursor !== undefined) params.set("after", request.cursor);
+      const listing = await api<RedditListing<RedditMessage>>(
+        connection,
+        `/api/v1/message/inbox?${params}`,
+      );
+      const messages = listing.data.children
+        .map(({ data }) => data)
+        .filter((message) => {
+          if (request.conversationRemoteId === undefined) return true;
+          const conversationId = message.first_message_name ?? message.parent_id ?? message.name ?? message.id;
+          return conversationId === request.conversationRemoteId;
+        })
+        .map<DirectMessage>((message) => ({
+          id: message.name ?? `t4_${message.id}`,
+          provider: PROVIDER,
+          conversationRemoteId: message.first_message_name ?? message.parent_id ?? message.name ?? message.id,
+          fromHandle: message.author === undefined ? "u/[deleted]" : `u/${message.author}`,
+          toHandle: `u/${message.dest ?? connection.fields["username"] ?? "unknown"}`,
+          text: message.body,
+          sentAt: new Date(message.created_utc * 1000),
+        }));
+      return pageOf(messages, listing.data.after);
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      // Successful /api/del replies may have an empty body, so deletion only
+      // relies on the HTTP status rather than attempting to decode JSON.
+      await send(
+        connection,
+        "/api/del",
+        formPost({ id: fullname(remoteId, "t3") }),
+      );
+    },
+  };
+}
diff --git a/packages/connector-reddit/tsconfig.json b/packages/connector-reddit/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-reddit/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-runtime/package.json b/packages/connector-runtime/package.json
new file mode 100644
index 0000000..65e9f23
--- /dev/null
+++ b/packages/connector-runtime/package.json
@@ -0,0 +1,30 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-runtime",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*",
+    "pg": "^8.23.1",
+    "@tactical-media-broadcast-hub/connector-mastodon": "workspace:*",
+    "@tactical-media-broadcast-hub/connector-telegram": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5",
+    "@types/pg": "^8.23.1"
+  }
+}
diff --git a/packages/connector-runtime/src/credentials.ts b/packages/connector-runtime/src/credentials.ts
new file mode 100644
index 0000000..d77820d
--- /dev/null
+++ b/packages/connector-runtime/src/credentials.ts
@@ -0,0 +1,34 @@
+import type { Pool } from "pg";
+import { AuthError, type CredentialAccessor } from "@tactical-media-broadcast-hub/connector-sdk";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { publishingContext } from "./execution-context.js";
+import { Vault } from "./vault.js";
+/** Caller owns pool lifecycle. Publishing never rotates or mutates credentials. */
+export function createPublishingCredentialAccessor(pool: Pool, vault = new Vault()): CredentialAccessor {
+  async function getSecret(connection: ConnectorConnection, key: string): Promise<string> {
+    const context = publishingContext(connection);
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [context.workspaceId]);
+      const result = await client.query<{ ciphertext: Buffer; key_version: number }>(`SELECT cr.ciphertext, cr.key_version FROM credentials cr
+        JOIN connections c ON c.id = cr.connection_id AND c.workspace_id = cr.workspace_id
+        WHERE cr.id = $1 AND cr.generation = $2 AND cr.connection_id = $3
+          AND cr.kind = 'connector-oauth' AND cr.revoked_at IS NULL AND c.disconnected_at IS NULL`,
+        [context.credentialId, context.credentialGeneration, context.connectionId]);
+      const row = result.rows[0];
+      if (!row) throw new AuthError("CREDENTIAL_CHANGED", connection.provider, false);
+      const plaintext = await vault.open(context.workspaceId, context.connectionId, { ciphertext: row.ciphertext, keyVersion: row.key_version });
+      const secrets: unknown = JSON.parse(plaintext.toString());
+      if (!secrets || typeof secrets !== "object" || Array.isArray(secrets)) throw new AuthError("CREDENTIAL_SHAPE", connection.provider, false);
+      const value = (secrets as Record<string, unknown>)[key];
+      if (typeof value !== "string" || !value) throw new AuthError("CREDENTIAL_SECRET_MISSING", connection.provider, false);
+      await client.query("COMMIT");
+      return value;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => undefined);
+      throw error;
+    } finally { client.release(); }
+  }
+  return { getSecret, getAccessToken: (connection) => getSecret(connection, "access_token"), put: async () => { throw new Error("PUBLISHING_CREDENTIAL_MUTATION_REFUSED"); } };
+}
diff --git a/packages/connector-runtime/src/execution-context.ts b/packages/connector-runtime/src/execution-context.ts
new file mode 100644
index 0000000..f3a6952
--- /dev/null
+++ b/packages/connector-runtime/src/execution-context.ts
@@ -0,0 +1,41 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { setHttpRequestHookProvider, type HttpRequestHook } from "@tactical-media-broadcast-hub/connector-sdk";
+
+/**
+ * Per-execution HTTP hook carried through AsyncLocalStorage, so concurrent
+ * publish activities in one process never share a "current job".
+ */
+const storage = new AsyncLocalStorage<HttpRequestHook>();
+let installed = false;
+
+function install(): void {
+  if (installed) return;
+  setHttpRequestHookProvider(() => storage.getStore());
+  installed = true;
+}
+
+/** Run `fn` with `hook` observing every SDK HTTP request it makes. */
+export function runWithHttpHook<T>(hook: HttpRequestHook, fn: () => Promise<T>): Promise<T> {
+  install();
+  return storage.run(hook, fn);
+}
+
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+export interface PublishingExecutionContext {
+  workspaceId: string;
+  connectionId: string;
+  credentialId: string;
+  credentialGeneration: string;
+  signal?: AbortSignal;
+}
+const executionStorage = new AsyncLocalStorage<PublishingExecutionContext>();
+export function runWithPublishingContext<T>(context: PublishingExecutionContext, fn: () => Promise<T>): Promise<T> {
+  return executionStorage.run(context, fn);
+}
+export function publishingContext(connection: ConnectorConnection): PublishingExecutionContext {
+  const context = executionStorage.getStore();
+  if (!context || connection.workspaceId !== context.workspaceId || connection.id !== context.connectionId || connection.credentialId.id !== context.connectionId) throw new Error("EXECUTION_CREDENTIAL_FENCE");
+  context.signal?.throwIfAborted();
+  return context;
+}
+export function executionSignal(): AbortSignal | undefined { return executionStorage.getStore()?.signal; }
diff --git a/packages/connector-runtime/src/idempotency.ts b/packages/connector-runtime/src/idempotency.ts
new file mode 100644
index 0000000..914cfde
--- /dev/null
+++ b/packages/connector-runtime/src/idempotency.ts
@@ -0,0 +1,52 @@
+import type { NormalizedPost } from "@tactical-media-broadcast-hub/core";
+
+/** providerMetadata keys owned by the publishing runtime, never by the author. */
+export const EXECUTION_METADATA_KEYS = ["idempotencyKey", "draftId"] as const;
+
+/** Author-supplied keys refused outright: remote media ids bypass asset ownership. */
+export const FORBIDDEN_POST_METADATA_KEYS = ["mediaIds"] as const;
+
+export class ExecutionMetadataError extends Error {
+  constructor(readonly key: string) {
+    super(`providerMetadata.${key} may not be supplied by the post author`);
+    this.name = "ExecutionMetadataError";
+  }
+}
+
+export { publishingIdempotencyKey } from "@tactical-media-broadcast-hub/core";
+export interface IdempotencyKeyParts { workspaceId: string; draftId: string; attemptNo: string | bigint | number }
+
+/** The post without runtime-owned metadata — what approval hashes cover. */
+export function stripExecutionMetadata(post: NormalizedPost): NormalizedPost {
+  const providerMetadata = { ...post.providerMetadata };
+  for (const key of EXECUTION_METADATA_KEYS) delete providerMetadata[key];
+  return { ...post, providerMetadata };
+}
+
+export interface DispatchPreparation {
+  idempotencyKey: string;
+  /**
+   * Keep post.scheduledAt so the provider schedules natively. Default false:
+   * the pipeline owns timing and the provider must publish immediately.
+   */
+  allowProviderScheduling?: boolean;
+}
+
+/**
+ * Build the post handed to connector.publish: refuse forbidden author keys,
+ * drop author-supplied execution keys, inject the attempt's idempotency key
+ * and strip scheduledAt unless provider scheduling is explicitly allowed.
+ */
+export function preparePostForDispatch(post: NormalizedPost, prep: DispatchPreparation): NormalizedPost {
+  for (const key of FORBIDDEN_POST_METADATA_KEYS) {
+    if (Object.prototype.hasOwnProperty.call(post.providerMetadata, key)) throw new ExecutionMetadataError(key);
+  }
+  const stripped = stripExecutionMetadata(post);
+  const prepared: NormalizedPost = {
+    ...stripped,
+    mediaAssetIds: [...post.mediaAssetIds],
+    providerMetadata: { ...stripped.providerMetadata, idempotencyKey: prep.idempotencyKey },
+  };
+  if (prep.allowProviderScheduling !== true) delete prepared.scheduledAt;
+  return prepared;
+}
diff --git a/packages/connector-runtime/src/index.ts b/packages/connector-runtime/src/index.ts
new file mode 100644
index 0000000..9b2ffd1
--- /dev/null
+++ b/packages/connector-runtime/src/index.ts
@@ -0,0 +1,9 @@
+export * from "./execution-context.js";
+export * from "./idempotency.js";
+export * from "./outcome.js";
+export * from "./policy.js";
+export * from "./publish.js";
+export * from "./vault.js";
+export * from "./provider-fetch.js";
+export * from "./credentials.js";
+export * from "./registry.js";
diff --git a/packages/connector-runtime/src/outcome.ts b/packages/connector-runtime/src/outcome.ts
new file mode 100644
index 0000000..2fb2e34
--- /dev/null
+++ b/packages/connector-runtime/src/outcome.ts
@@ -0,0 +1,67 @@
+/**
+ * Typed result of one publish dispatch. Only `retryable` permits calling
+ * connector.publish again with the same idempotency key; `unknown` means the
+ * send may have happened and must never be resent automatically.
+ */
+export type PublishFailureCode =
+  | "RATE_LIMITED"
+  | "PROVIDER_UNAVAILABLE"
+  | "TRANSPORT_FAILURE"
+  | "PUBLISH_AMBIGUOUS_DEDUPED"
+  | "CREDENTIAL_REJECTED"
+  | "PROVIDER_REJECTED"
+  | "INVALID_POST"
+  | "UNSUPPORTED"
+  | "PUBLISH_OUTCOME_UNKNOWN";
+
+/**
+ * Sanitized provider evidence. Deliberately omits the connector's local
+ * Publication.id and draftId: those are placeholders, never DB identities.
+ */
+export interface PublishReceipt {
+  provider: string;
+  connectionId: string;
+  idempotencyKey: string;
+  remoteId: string;
+  remoteUrl?: string;
+  publishedAt: Date;
+  providerMetadata: Record<string, unknown>;
+}
+
+interface FailureBase {
+  code: PublishFailureCode;
+  /** Whether any mutating provider request left the process in this call. */
+  dispatched: boolean;
+  /** SDK error class name — a fixed identifier, never the raw message. */
+  errorName?: string;
+  status?: number;
+}
+
+export type PublishOutcome =
+  | { kind: "published"; receipt: PublishReceipt }
+  | {
+      kind: "provider_scheduled";
+      receipt: PublishReceipt;
+      scheduledRemoteId: string;
+      scheduledAt: Date;
+    }
+  | (FailureBase & {
+      kind: "rejected_permanent";
+      code: "CREDENTIAL_REJECTED" | "PROVIDER_REJECTED" | "INVALID_POST" | "UNSUPPORTED";
+      /** Credential refused: pause for reauthorization, do not retry. */
+      needsReauthorization: boolean;
+    })
+  | (FailureBase & {
+      kind: "retryable";
+      code: "RATE_LIMITED" | "PROVIDER_UNAVAILABLE" | "TRANSPORT_FAILURE" | "PUBLISH_AMBIGUOUS_DEDUPED";
+      retryAfterMs?: number;
+      /**
+       * "not_delivered": the provider definitively did not apply the send.
+       * "deduplicated": delivery is ambiguous but a same-key resend is
+       * deduped by the provider inside its verified window.
+       */
+      resend: "not_delivered" | "deduplicated";
+    })
+  | (FailureBase & { kind: "unknown"; code: "PUBLISH_OUTCOME_UNKNOWN"; dispatched: true });
+
+export type PublishOutcomeKind = PublishOutcome["kind"];
diff --git a/packages/connector-runtime/src/policy.ts b/packages/connector-runtime/src/policy.ts
new file mode 100644
index 0000000..0dc23b1
--- /dev/null
+++ b/packages/connector-runtime/src/policy.ts
@@ -0,0 +1,48 @@
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+/**
+ * Provider publishing policies, declared at the composition boundary so the
+ * SDK publish/deletePublication signatures stay unchanged.
+ */
+export interface PublishingPolicy {
+  /**
+   * "token": the provider dedupes repeated sends carrying the same
+   * idempotency key, so an ambiguous send may be replayed with that key.
+   * "none": no key and no lookup — an ambiguous send is never replayed.
+   */
+  idempotency: "token" | "none";
+  /**
+   * How long after the attempt's first dispatch a same-key replay is trusted.
+   * Applies only to "token" policies and only on deployment-verified origins.
+   */
+  dedupeWindowMs?: number;
+}
+
+/**
+ * Mastodon documents Idempotency-Key retention of up to one hour; 30 minutes
+ * from first dispatch is the deployment cutoff (forks may keep less).
+ */
+export const MASTODON_DEDUPE_WINDOW_MS = 30 * 60 * 1000;
+
+export const PUBLISHING_POLICIES: Readonly<Record<string, PublishingPolicy>> = {
+  mastodon: { idempotency: "token", dedupeWindowMs: MASTODON_DEDUPE_WINDOW_MS },
+  telegram: { idempotency: "none" },
+};
+
+/** Unknown providers get the safe default: never replay an ambiguous send. */
+export function publishingPolicyFor(provider: string): PublishingPolicy {
+  return PUBLISHING_POLICIES[provider] ?? { idempotency: "none" };
+}
+
+export function verifiedDedupeOrigin(origin: string, configured = process.env.MASTODON_PUBLISH_DEDUPE_ORIGINS ?? ""): boolean {
+  return configured.split(",").map((value) => value.trim()).filter(Boolean).some((value) => {
+    try { const url = new URL(value); return url.protocol === "https:" && url.origin === value && url.origin === origin; } catch { return false; }
+  });
+}
+
+export function isPublishingProvider(provider: string): boolean { return Object.hasOwn(PUBLISHING_POLICIES, provider); }
+export function publishingDispatchPolicy(connection: ConnectorConnection): { policy: PublishingPolicy; origin: string; dedupeVerified: boolean } {
+  const policy = publishingPolicyFor(connection.provider);
+  let origin = "";
+  try { origin = new URL(connection.fields.instanceUrl ?? "").origin; } catch { /* invalid origins never authorize dedupe */ }
+  return { policy, origin, dedupeVerified: policy.idempotency === "token" && verifiedDedupeOrigin(origin) };
+}
diff --git a/packages/connector-runtime/src/provider-fetch.test.ts b/packages/connector-runtime/src/provider-fetch.test.ts
new file mode 100644
index 0000000..1bbb185
--- /dev/null
+++ b/packages/connector-runtime/src/provider-fetch.test.ts
@@ -0,0 +1,35 @@
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { createServer, type Server } from "node:http";
+import { providerFetch, publicAddress } from "./provider-fetch.js";
+describe("bounded pinned provider transport (local fixture)", () => {
+  let server: Server; let origin: string; let requests = 0;
+  beforeAll(async () => {
+    server = createServer((request, response) => {
+      requests += 1;
+      if (request.url === "/redirect") { response.writeHead(302, { location: "/ok" }); response.end(); }
+      else if (request.url === "/large") response.end(Buffer.alloc(1_048_577, "x"));
+      else if (request.url === "/stall") response.writeHead(200);
+      else response.end('{"ok":true}');
+    });
+    await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));
+    const address = server.address(); if (!address || typeof address === "string") throw new Error("fixture address missing");
+    origin = `http://127.0.0.1:${address.port}`;
+  });
+  afterAll(async () => { server.closeAllConnections(); await new Promise<void>((done) => server.close(() => done())); });
+  it("blocks private/documentation addresses and allows public destinations", () => {
+    for (const address of ["127.0.0.1", "10.0.0.1", "169.254.169.254", "::1", "::ffff:127.0.0.1", "2001:db8::1"]) expect(publicAddress(address)).toBe(false);
+    expect(publicAddress("8.8.8.8")).toBe(true);
+  });
+  it("honors cancellation before DNS/send and refuses redirects", async () => {
+    const before = requests; const controller = new AbortController(); controller.abort();
+    await expect(providerFetch(`${origin}/ok`, { signal: controller.signal })).rejects.toThrow();
+    expect(requests).toBe(before);
+    await expect(providerFetch(`${origin}/redirect`)).rejects.toThrow("redirect refused");
+    expect(requests).toBe(before+1);
+  });
+  it("bounds responses and cancels a stalled request", async () => {
+    await expect(providerFetch(`${origin}/large`)).rejects.toThrow();
+    await expect(providerFetch(`${origin}/stall`, { signal: AbortSignal.timeout(30) })).rejects.toThrow();
+    expect((await (await providerFetch(`${origin}/ok`)).json()) as unknown).toEqual({ ok: true });
+  });
+});
diff --git a/packages/connector-runtime/src/provider-fetch.ts b/packages/connector-runtime/src/provider-fetch.ts
new file mode 100644
index 0000000..7706dc8
--- /dev/null
+++ b/packages/connector-runtime/src/provider-fetch.ts
@@ -0,0 +1,66 @@
+import { lookup } from "node:dns/promises";
+import { isIP, BlockList } from "node:net";
+import { request as httpsRequest } from "node:https";
+import { request as httpRequest } from "node:http";
+
+const blocked = new BlockList();
+for (const [network, prefix] of [["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8], ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.168.0.0", 16], ["192.0.0.0", 24], ["192.0.2.0", 24], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24], ["224.0.0.0", 3]] as const) blocked.addSubnet(network, prefix);
+blocked.addSubnet("2001:db8::", 32, "ipv6");
+blocked.addSubnet("2001::", 32, "ipv6");
+blocked.addSubnet("2001:10::", 28, "ipv6");
+blocked.addSubnet("2001:20::", 28, "ipv6");
+blocked.addSubnet("2002::", 16, "ipv6");
+export function publicAddress(address: string): boolean {
+  const family = isIP(address);
+  if (family === 4) return !blocked.check(address);
+  // Reject mapped IPv4, local, multicast, transition and documentation ranges.
+  return family === 6 && /^[23][0-9a-f]{3}:/i.test(address) && !blocked.check(address, "ipv6");
+}
+
+/** Connect-only transport: DNS-pinned public destinations, no redirects, bounded JSON. */
+export const providerFetch: typeof fetch = async (input, init = {}) => {
+  const url = new URL(input instanceof Request ? input.url : String(input));
+  const hostname = url.hostname.replace(/^\[|\]$/g, "");
+  const local = process.env.NODE_ENV !== "production" && (hostname === "localhost" || hostname === "127.0.0.1");
+  if (url.username || url.password || (url.protocol !== "https:" && !(local && url.protocol === "http:"))) throw new Error("Invalid provider URL");
+  const signal = AbortSignal.any([AbortSignal.timeout(15_000), ...(init.signal ? [init.signal] : [])]);
+  signal.throwIfAborted();
+  const addresses = await Promise.race([lookup(hostname, { all: true }), new Promise<never>((_resolve, reject) => { signal.addEventListener("abort", () => reject(new Error("PROVIDER_TIMEOUT")), { once: true }); })]);
+  signal.throwIfAborted();
+  if (!addresses.length || (!local && addresses.some(({ address }) => !publicAddress(address)))) throw new Error("Provider must resolve to public addresses");
+  const pinned = addresses[0];
+  if (!pinned) throw new Error("Provider DNS unavailable");
+  if (init.body !== undefined && init.body !== null && typeof init.body !== "string") throw new Error("Unsupported authorization body");
+  const headers = Object.fromEntries(new Headers(init.headers).entries());
+  return new Promise<Response>((resolve, reject) => {
+    const request = (url.protocol === "https:" ? httpsRequest : httpRequest)(url, {
+      method: init.method ?? "GET", headers, family: pinned.family, signal,
+      lookup: (_name, _options, callback) => callback(null, pinned.address, pinned.family),
+    }, (response) => {
+      const chunks: Buffer[] = [];
+      let size = 0;
+      response.on("data", (chunk: Buffer) => {
+        size += chunk.length;
+        if (size > 1_048_576) request.destroy(new Error("Provider response too large"));
+        else chunks.push(chunk);
+      });
+      response.on("error", reject);
+      response.on("aborted", () => reject(new Error("Provider response aborted")));
+      response.on("end", () => {
+        const status = response.statusCode ?? 502;
+        if (status >= 300 && status < 400) { reject(new Error("Provider redirect refused")); return; }
+        const responseHeaders = new Headers();
+        for (const [key, value] of Object.entries(response.headers)) {
+          if (value !== undefined) responseHeaders.set(key, Array.isArray(value) ? value.join(", ") : value);
+        }
+        try {
+          resolve(new Response(status === 204 || status === 205 ? null : Buffer.concat(chunks), { status, headers: responseHeaders }));
+        } catch { reject(new Error("Invalid provider response")); }
+      });
+    });
+    request.setTimeout(15_000, () => request.destroy(new Error("Provider timeout")));
+    request.on("error", reject);
+    if (init.body) request.write(init.body);
+    request.end();
+  });
+};
diff --git a/packages/connector-runtime/src/publish.test.ts b/packages/connector-runtime/src/publish.test.ts
new file mode 100644
index 0000000..2c45788
--- /dev/null
+++ b/packages/connector-runtime/src/publish.test.ts
@@ -0,0 +1,355 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, NormalizedPost, Publication } from "@tactical-media-broadcast-hub/core";
+import {
+  AuthError,
+  ConnectorError,
+  ProviderRejectedError,
+  RateLimitedHttpClient,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+import {
+  DispatchFenceError,
+  ExecutionMetadataError,
+  MASTODON_DEDUPE_WINDOW_MS,
+  preparePostForDispatch,
+  publishingIdempotencyKey,
+  publishingPolicyFor,
+  publishWithPolicy,
+  stripExecutionMetadata,
+} from "./index.js";
+
+const KEY = "wp3:ws-1:draft-1:a1:publish";
+const ORIGIN = "https://provider.example";
+
+/** Records sends independently of the responses the connector sees. */
+interface Wire {
+  posts: { key: string | null; body: Record<string, unknown> }[];
+  gets: number;
+}
+
+type Reply = "ok" | "scheduled" | "500" | "429" | "401" | "422" | "drop";
+
+/**
+ * Minimal connector over the real SDK HTTP client: an identity GET, then the
+ * publish POST. The scripted reply for each POST is consumed in order.
+ */
+function fakeConnector(replies: Reply[], wire: Wire): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    fetchImpl: (async (input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+      const method = init?.method ?? "GET";
+      if (method === "GET") {
+        wire.gets += 1;
+        return new Response("{}");
+      }
+      const body = JSON.parse(String(init?.body)) as Record<string, unknown>;
+      wire.posts.push({ key: new Headers(init?.headers).get("idempotency-key"), body });
+      const reply = replies.shift() ?? "ok";
+      switch (reply) {
+        case "ok":
+          return Response.json({ id: `r${wire.posts.length}`, created_at: "2026-10-09T12:00:00Z" });
+        case "scheduled":
+          return Response.json({ id: "s9", scheduled_at: "2026-10-09T15:00:00.000Z" });
+        case "500":
+          return new Response("", { status: 500 });
+        case "429":
+          return new Response("", { status: 429, headers: { "retry-after": "12" } });
+        case "401":
+          return new Response("", { status: 401 });
+        case "422":
+          return new Response("", { status: 422 });
+        case "drop":
+          throw new TypeError("socket hang up");
+      }
+      void input;
+      throw new Error("unreachable");
+    }) as typeof fetch,
+  });
+
+  return {
+    manifest: () => {
+      throw new Error("not needed");
+    },
+    authorize: async () => {
+      throw new Error("not needed");
+    },
+    getIdentity: async () => {
+      throw new Error("not needed");
+    },
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      if (post.text === "too-long") throw new ConnectorError("text over limit", connection.provider);
+      await client.request(connection.provider, `${ORIGIN}/me`);
+      const key = post.providerMetadata["idempotencyKey"];
+      const response = await client.request(connection.provider, `${ORIGIN}/statuses`, {
+        method: "POST",
+        headers: typeof key === "string" ? { "idempotency-key": key } : {},
+        body: JSON.stringify({ status: post.text, scheduled_at: post.scheduledAt?.toISOString() }),
+      });
+      if (response.status === 401) throw new AuthError("revoked", connection.provider, false);
+      if (!response.ok) throw new ProviderRejectedError("refused", connection.provider, response.status);
+      const data = (await response.json()) as { id: string; created_at?: string; scheduled_at?: string };
+      const scheduled = data.scheduled_at !== undefined;
+      return {
+        id: "local-placeholder",
+        workspaceId: connection.workspaceId,
+        draftId: "direct",
+        connectionId: connection.id,
+        remoteId: scheduled ? `scheduled:${data.id}` : data.id,
+        publishedAt: new Date(data.scheduled_at ?? data.created_at ?? 0),
+        providerMetadata: scheduled
+          ? { outcome: "provider_scheduled", scheduledAt: data.scheduled_at }
+          : { outcome: "published" },
+      };
+    },
+  };
+}
+
+function connectionFor(provider: string): ConnectorConnection {
+  return {
+    id: `conn-${provider}`,
+    workspaceId: "ws-1",
+    provider,
+    channelId: "c",
+    credentialId: { kind: "credential-ref", id: "cred" },
+    fields: {},
+    createdAt: new Date(),
+  };
+}
+
+const post = (text = "hello", extra: Partial<NormalizedPost> = {}): NormalizedPost => ({
+  text,
+  mediaAssetIds: [],
+  visibility: "public",
+  providerMetadata: { connectionId: "conn-x", draftId: "user-draft", idempotencyKey: "user-key" },
+  ...extra,
+});
+
+function setup(provider: string, replies: Reply[]): { wire: Wire; connector: PlatformConnector; connection: ConnectorConnection } {
+  const wire: Wire = { posts: [], gets: 0 };
+  return { wire, connector: fakeConnector(replies, wire), connection: connectionFor(provider) };
+}
+
+describe("idempotency key + dispatch preparation", () => {
+  it("formats the per-attempt key and validates its parts", () => {
+    expect(publishingIdempotencyKey({ workspaceId: "ws-1", draftId: "draft-1", attemptNo: 1 })).toBe(KEY);
+    expect(() => publishingIdempotencyKey({ workspaceId: "ws:1", draftId: "d", attemptNo: 1 })).toThrow(RangeError);
+    expect(() => publishingIdempotencyKey({ workspaceId: "ws", draftId: "d", attemptNo: 0 })).toThrow(RangeError);
+  });
+
+  it("injects the key, drops author execution keys and strips scheduledAt", () => {
+    const original = post("x", { scheduledAt: new Date("2026-12-01T00:00:00Z") });
+    const prepared = preparePostForDispatch(original, { idempotencyKey: KEY });
+    expect(prepared.providerMetadata).toEqual({ connectionId: "conn-x", idempotencyKey: KEY });
+    expect(prepared.scheduledAt).toBeUndefined();
+    // Input untouched.
+    expect(original.providerMetadata["draftId"]).toBe("user-draft");
+    expect(original.scheduledAt).toBeDefined();
+    expect(preparePostForDispatch(original, { idempotencyKey: KEY, allowProviderScheduling: true }).scheduledAt).toEqual(
+      original.scheduledAt,
+    );
+  });
+
+  it("refuses author-supplied remote media ids", () => {
+    expect(() => preparePostForDispatch(post("x", { providerMetadata: { mediaIds: ["m1"] } }), { idempotencyKey: KEY })).toThrow(
+      ExecutionMetadataError,
+    );
+  });
+
+  it("stripExecutionMetadata removes only runtime-owned keys (approval hash input)", () => {
+    expect(stripExecutionMetadata(post()).providerMetadata).toEqual({ connectionId: "conn-x" });
+  });
+
+  it("declares token dedupe for Mastodon and none for Telegram/unknown providers", () => {
+    expect(publishingPolicyFor("mastodon")).toEqual({ idempotency: "token", dedupeWindowMs: MASTODON_DEDUPE_WINDOW_MS });
+    expect(publishingPolicyFor("telegram")).toEqual({ idempotency: "none" });
+    expect(publishingPolicyFor("bluesky")).toEqual({ idempotency: "none" });
+  });
+});
+
+describe("publishWithPolicy outcomes", () => {
+  it("published: receipt carries the injected key, never the local id/draftId", async () => {
+    const { wire, connector, connection } = setup("telegram", ["ok"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), { idempotencyKey: KEY });
+    expect(wire.posts).toHaveLength(1);
+    expect(wire.posts[0]?.key).toBe(KEY);
+    expect(wire.posts[0]?.body["scheduled_at"]).toBeUndefined();
+    expect(outcome).toMatchObject({ kind: "published", receipt: { remoteId: "r1", idempotencyKey: KEY, connectionId: "conn-telegram" } });
+    expect(outcome.kind === "published" && "id" in outcome.receipt).toBe(false);
+    expect(outcome.kind === "published" && "draftId" in outcome.receipt).toBe(false);
+  });
+
+  it("provider_scheduled when native scheduling is explicitly allowed", async () => {
+    const { connector, connection } = setup("mastodon", ["scheduled"]);
+    const outcome = await publishWithPolicy(connector, connection, post("x", { scheduledAt: new Date("2026-10-09T15:00:00Z") }), {
+      idempotencyKey: KEY,
+      allowProviderScheduling: true,
+    });
+    expect(outcome).toMatchObject({
+      kind: "provider_scheduled",
+      scheduledRemoteId: "scheduled:s9",
+      scheduledAt: new Date("2026-10-09T15:00:00.000Z"),
+    });
+  });
+
+  it("429 → retryable RATE_LIMITED with Retry-After, one send", async () => {
+    const { wire, connector, connection } = setup("telegram", ["429"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), { idempotencyKey: KEY });
+    expect(wire.posts).toHaveLength(1);
+    expect(outcome).toMatchObject({ kind: "retryable", code: "RATE_LIMITED", retryAfterMs: 12_000, resend: "not_delivered", dispatched: true });
+  });
+
+  it("401 → rejected_permanent needing reauthorization; 422 → PROVIDER_REJECTED", async () => {
+    const auth = setup("telegram", ["401"]);
+    expect(await publishWithPolicy(auth.connector, auth.connection, post(), { idempotencyKey: KEY })).toMatchObject({
+      kind: "rejected_permanent",
+      code: "CREDENTIAL_REJECTED",
+      needsReauthorization: true,
+    });
+    const invalid = setup("telegram", ["422"]);
+    expect(await publishWithPolicy(invalid.connector, invalid.connection, post(), { idempotencyKey: KEY })).toMatchObject({
+      kind: "rejected_permanent",
+      code: "PROVIDER_REJECTED",
+      status: 422,
+      needsReauthorization: false,
+    });
+  });
+
+  it("connector validation before any send → INVALID_POST, not dispatched", async () => {
+    const { wire, connector, connection } = setup("telegram", []);
+    const outcome = await publishWithPolicy(connector, connection, post("too-long"), { idempotencyKey: KEY });
+    expect(outcome).toMatchObject({ kind: "rejected_permanent", code: "INVALID_POST", dispatched: false });
+    expect(wire.posts).toHaveLength(0);
+  });
+
+  it("author-supplied media ids → INVALID_POST with zero HTTP", async () => {
+    const { wire, connector, connection } = setup("telegram", []);
+    const outcome = await publishWithPolicy(connector, connection, post("x", { providerMetadata: { mediaIds: ["1"] } }), {
+      idempotencyKey: KEY,
+    });
+    expect(outcome).toMatchObject({ kind: "rejected_permanent", code: "INVALID_POST" });
+    expect(wire.gets + wire.posts.length).toBe(0);
+  });
+});
+
+describe("ambiguous sends", () => {
+  it("no-token provider: 5xx and dropped responses are unknown, never retryable", async () => {
+    for (const reply of ["500", "drop"] as const) {
+      const { wire, connector, connection } = setup("telegram", [reply]);
+      const outcome = await publishWithPolicy(connector, connection, post(), { idempotencyKey: KEY });
+      expect(outcome).toMatchObject({ kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN", dispatched: true });
+      expect(wire.posts).toHaveLength(1);
+    }
+  });
+
+  it("token provider on a verified origin inside the window: retryable deduplicated", async () => {
+    const { connector, connection } = setup("mastodon", ["500"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), { idempotencyKey: KEY, dedupeVerified: true });
+    expect(outcome).toMatchObject({ kind: "retryable", code: "PUBLISH_AMBIGUOUS_DEDUPED", resend: "deduplicated", status: 500 });
+  });
+
+  it("token provider on an unverified origin is unknown", async () => {
+    const { connector, connection } = setup("mastodon", ["500"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), { idempotencyKey: KEY });
+    expect(outcome.kind).toBe("unknown");
+  });
+
+  it("token provider past the window (measured from first dispatch) is unknown", async () => {
+    const { connector, connection } = setup("mastodon", ["drop"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), {
+      idempotencyKey: KEY,
+      dedupeVerified: true,
+      firstDispatchAt: new Date(Date.now() - MASTODON_DEDUPE_WINDOW_MS - 1000),
+    });
+    expect(outcome.kind).toBe("unknown");
+  });
+
+  it("unsettled prior dispatch without dedupe: unknown with zero HTTP", async () => {
+    const { wire, connector, connection } = setup("telegram", ["ok"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), {
+      idempotencyKey: KEY,
+      unsettledPriorDispatch: true,
+      firstDispatchAt: new Date(),
+      dedupeVerified: true,
+    });
+    expect(outcome).toMatchObject({ kind: "unknown", dispatched: true });
+    expect(wire.gets + wire.posts.length).toBe(0);
+  });
+
+  it("unsettled prior dispatch with verified dedupe: replays the same key", async () => {
+    const { wire, connector, connection } = setup("mastodon", ["ok"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), {
+      idempotencyKey: KEY,
+      unsettledPriorDispatch: true,
+      firstDispatchAt: new Date(Date.now() - 60_000),
+      dedupeVerified: true,
+    });
+    expect(outcome.kind).toBe("published");
+    expect(wire.posts.map((p) => p.key)).toEqual([KEY]);
+  });
+
+  it("a definite refusal of a replay does not claim the earlier send was not delivered", async () => {
+    const { connector, connection } = setup("mastodon", ["429"]);
+    const outcome = await publishWithPolicy(connector, connection, post(), {
+      idempotencyKey: KEY,
+      unsettledPriorDispatch: true,
+      firstDispatchAt: new Date(),
+      dedupeVerified: true,
+    });
+    expect(outcome).toMatchObject({ kind: "retryable", code: "RATE_LIMITED", resend: "deduplicated" });
+  });
+});
+
+describe("dispatch fence", () => {
+  it("a failing fence blocks the mutating send; reads are not fenced", async () => {
+    const { wire, connector, connection } = setup("telegram", ["ok"]);
+    const error = await publishWithPolicy(connector, connection, post(), {
+      idempotencyKey: KEY,
+      beforeMutation: () => {
+        throw new Error("lease lost");
+      },
+    }).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(DispatchFenceError);
+    expect(error).toMatchObject({ dispatched: false });
+    expect(wire.gets).toBe(1);
+    expect(wire.posts).toHaveLength(0);
+  });
+
+  it("concurrent executions keep their own fences (AsyncLocalStorage isolation)", async () => {
+    const blocked = setup("telegram", ["ok"]);
+    const allowed = setup("telegram", ["ok"]);
+    const seen: string[] = [];
+    const [a, b] = await Promise.allSettled([
+      publishWithPolicy(blocked.connector, blocked.connection, post(), {
+        idempotencyKey: "wp3:ws-1:a:a1:publish",
+        beforeMutation: async () => {
+          await new Promise((r) => setTimeout(r, 5));
+          seen.push("blocked");
+          throw new Error("revoked");
+        },
+      }),
+      publishWithPolicy(allowed.connector, allowed.connection, post(), {
+        idempotencyKey: "wp3:ws-1:b:a1:publish",
+        beforeMutation: () => void seen.push("allowed"),
+      }),
+    ]);
+    expect(a.status).toBe("rejected");
+    expect(b).toMatchObject({ status: "fulfilled", value: { kind: "published" } });
+    expect(blocked.wire.posts).toHaveLength(0);
+    expect(allowed.wire.posts.map((p) => p.key)).toEqual(["wp3:ws-1:b:a1:publish"]);
+    expect(seen.sort()).toEqual(["allowed", "blocked"]);
+  });
+
+  it("calls outside a runtime execution are unaffected by the hook", async () => {
+    const { wire, connector, connection } = setup("telegram", ["ok"]);
+    await publishWithPolicy(connector, connection, post(), {
+      idempotencyKey: KEY,
+      beforeMutation: () => {
+        throw new Error("only inside");
+      },
+    }).catch(() => undefined);
+    const direct = await connector.publish?.(connection, post());
+    expect(direct?.remoteId).toBe("r1");
+    expect(wire.posts).toHaveLength(1);
+  });
+});
diff --git a/packages/connector-runtime/src/publish.ts b/packages/connector-runtime/src/publish.ts
new file mode 100644
index 0000000..bb47b55
--- /dev/null
+++ b/packages/connector-runtime/src/publish.ts
@@ -0,0 +1,239 @@
+/**
+ * Safe-replay wrapper around connector.publish (plan §4). It never retries by
+ * itself: it injects the attempt's idempotency key, observes whether any
+ * mutating request left the process, and classifies the result into a
+ * PublishOutcome the caller can act on without resending ambiguous work.
+ */
+import type { ConnectorConnection, NormalizedPost, Publication } from "@tactical-media-broadcast-hub/core";
+import {
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  deliveryCertaintyOf,
+  ProviderRejectedError,
+  ProviderServerError,
+  RateLimitError,
+  type HttpRequestEvent,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+import { runWithHttpHook } from "./execution-context.js";
+import { ExecutionMetadataError, preparePostForDispatch } from "./idempotency.js";
+import type { PublishOutcome, PublishReceipt } from "./outcome.js";
+import { publishingPolicyFor, type PublishingPolicy } from "./policy.js";
+
+export interface PublishAttempt {
+  idempotencyKey: string;
+  /** Defaults to the provider's registered policy. */
+  policy?: PublishingPolicy;
+  /** First dispatch time of this attempt, from the execution journal. */
+  firstDispatchAt?: Date;
+  /**
+   * An earlier dispatch of this attempt has neither a receipt nor a definite
+   * rejection. Only a verified token-dedupe provider inside its window may be
+   * called again; otherwise the outcome is unknown with zero sends.
+   */
+  unsettledPriorDispatch?: boolean;
+  /**
+   * The deployment verified this origin's token dedupe (e.g. listed in
+   * MASTODON_PUBLISH_DEDUPE_ORIGINS). Never derived from post metadata.
+   */
+  dedupeVerified?: boolean;
+  /** Keep post.scheduledAt for native provider scheduling (default false). */
+  allowProviderScheduling?: boolean;
+  /**
+   * Fence check run immediately before each mutating HTTP send, after
+   * rate-limiter waits. Throwing blocks that send; the wrapper rethrows the
+   * failure as DispatchFenceError.
+   */
+  beforeMutation?: (event: HttpRequestEvent) => void | Promise<void>;
+  aroundMutation?: (event: HttpRequestEvent, send: () => Promise<Response>) => Promise<Response>;
+  now?: () => Date;
+}
+
+/** The caller's fence refused a send; carries whether earlier sends happened. */
+export class DispatchFenceError extends Error {
+  constructor(
+    readonly dispatched: boolean,
+    override readonly cause: unknown,
+  ) {
+    super("publish dispatch blocked by execution fence");
+    this.name = "DispatchFenceError";
+  }
+}
+
+function canReplayAmbiguous(policy: PublishingPolicy, attempt: PublishAttempt, firstDispatchAt: Date | undefined, now: Date): boolean {
+  if (policy.idempotency !== "token" || attempt.dedupeVerified !== true) return false;
+  if (firstDispatchAt === undefined) return false;
+  return now.getTime() - firstDispatchAt.getTime() < (policy.dedupeWindowMs ?? 0);
+}
+
+function receiptOf(connection: ConnectorConnection, idempotencyKey: string, publication: Publication): PublishReceipt {
+  const receipt: PublishReceipt = {
+    provider: connection.provider,
+    connectionId: connection.id,
+    idempotencyKey,
+    remoteId: publication.remoteId,
+    publishedAt: publication.publishedAt,
+    providerMetadata: { ...publication.providerMetadata },
+  };
+  if (publication.remoteUrl !== undefined) receipt.remoteUrl = publication.remoteUrl;
+  return receipt;
+}
+
+function successOutcome(connection: ConnectorConnection, idempotencyKey: string, publication: Publication): PublishOutcome {
+  const receipt = receiptOf(connection, idempotencyKey, publication);
+  const meta = publication.providerMetadata;
+  const scheduled = publication.remoteId.startsWith("scheduled:") || meta["outcome"] === "provider_scheduled";
+  if (!scheduled) return { kind: "published", receipt };
+  const scheduledAt = typeof meta["scheduledAt"] === "string" ? new Date(meta["scheduledAt"]) : publication.publishedAt;
+  return { kind: "provider_scheduled", receipt, scheduledRemoteId: publication.remoteId, scheduledAt };
+}
+
+function statusOf(error: unknown): number | undefined {
+  if (error instanceof ProviderRejectedError || error instanceof ProviderServerError || error instanceof RateLimitError) {
+    return error.status;
+  }
+  return undefined;
+}
+
+function retryAfterOf(error: unknown): number | undefined {
+  if (error instanceof RateLimitError || error instanceof ProviderRejectedError || error instanceof ProviderServerError) {
+    return error.retryAfterMs;
+  }
+  return undefined;
+}
+
+/**
+ * Classify a publish failure. `dispatched`: a mutating request was sent in
+ * this call; `replayAmbiguous`: a same-key resend is provider-deduped now;
+ * `priorUnsettled`: an earlier send of this attempt is still ambiguous, so
+ * even a definite refusal of this call cannot prove "not delivered".
+ */
+export function classifyPublishError(
+  error: unknown,
+  dispatched: boolean,
+  replayAmbiguous: boolean,
+  priorUnsettled = false,
+): PublishOutcome {
+  const outcome = classifyCurrentCall(error, dispatched, replayAmbiguous);
+  if (priorUnsettled && outcome.kind === "retryable" && outcome.resend === "not_delivered") {
+    return { ...outcome, resend: "deduplicated" };
+  }
+  return outcome;
+}
+
+function classifyCurrentCall(error: unknown, dispatched: boolean, replayAmbiguous: boolean): PublishOutcome {
+  const base = {
+    dispatched,
+    errorName: error instanceof Error ? error.name : "UnknownError",
+    ...(statusOf(error) === undefined ? {} : { status: statusOf(error) }),
+  };
+  const retryAfterMs = retryAfterOf(error);
+  const retryAfter = retryAfterMs === undefined ? {} : { retryAfterMs };
+  const definite = deliveryCertaintyOf(error) === "rejected" || !dispatched;
+
+  if (!definite) {
+    if (replayAmbiguous) {
+      return { kind: "retryable", code: "PUBLISH_AMBIGUOUS_DEDUPED", resend: "deduplicated", ...base, ...retryAfter };
+    }
+    return { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN", ...base, dispatched: true };
+  }
+
+  if (error instanceof RateLimitError) {
+    return { kind: "retryable", code: "RATE_LIMITED", resend: "not_delivered", ...base, ...retryAfter };
+  }
+  if (error instanceof AuthError) {
+    return { kind: "rejected_permanent", code: "CREDENTIAL_REJECTED", needsReauthorization: true, ...base };
+  }
+  if (error instanceof ProviderRejectedError) {
+    // 408/425: the provider refused for timing reasons, not content.
+    if (error.status === 408 || error.status === 425) {
+      return { kind: "retryable", code: "PROVIDER_UNAVAILABLE", resend: "not_delivered", ...base, ...retryAfter };
+    }
+    return { kind: "rejected_permanent", code: "PROVIDER_REJECTED", needsReauthorization: false, ...base };
+  }
+  if (error instanceof ProviderServerError) {
+    return { kind: "retryable", code: "PROVIDER_UNAVAILABLE", resend: "not_delivered", ...base, ...retryAfter };
+  }
+  if (error instanceof CapabilityNotSupportedError) {
+    return { kind: "rejected_permanent", code: "UNSUPPORTED", needsReauthorization: false, ...base };
+  }
+  if (error instanceof ExecutionMetadataError) {
+    return { kind: "rejected_permanent", code: "INVALID_POST", needsReauthorization: false, ...base };
+  }
+  if (error instanceof ConnectorError) {
+    // Connector-side validation (limits, missing loaders) before any send.
+    return { kind: "rejected_permanent", code: "INVALID_POST", needsReauthorization: false, ...base };
+  }
+  // Raw transport/runtime failure before any mutating send: nothing delivered.
+  return { kind: "retryable", code: "TRANSPORT_FAILURE", resend: "not_delivered", ...base };
+}
+
+/**
+ * Publish one attempt through `connector.publish` (signature unchanged).
+ * Rethrows only DispatchFenceError; every provider result is an outcome.
+ */
+export async function publishWithPolicy(
+  connector: PlatformConnector,
+  connection: ConnectorConnection,
+  post: NormalizedPost,
+  attempt: PublishAttempt,
+): Promise<PublishOutcome> {
+  const now = attempt.now ?? (() => new Date());
+  const policy = attempt.policy ?? publishingPolicyFor(connection.provider);
+
+  if (connector.publish === undefined) {
+    return { kind: "rejected_permanent", code: "UNSUPPORTED", needsReauthorization: false, dispatched: false };
+  }
+  if (attempt.unsettledPriorDispatch === true && !canReplayAmbiguous(policy, attempt, attempt.firstDispatchAt, now())) {
+    return { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN", dispatched: true };
+  }
+
+  let prepared: NormalizedPost;
+  try {
+    prepared = preparePostForDispatch(post, {
+      idempotencyKey: attempt.idempotencyKey,
+      allowProviderScheduling: attempt.allowProviderScheduling,
+    });
+  } catch (error) {
+    return classifyPublishError(error, false, false);
+  }
+
+  let mutations = 0;
+  let firstMutationAt: Date | undefined;
+  let fenceFailure: DispatchFenceError | undefined;
+  const publish = connector.publish.bind(connector);
+  try {
+    const publication = await runWithHttpHook(
+      {
+        aroundMutation: async (event, send) => {
+          const observedSend = async (): Promise<Response> => {
+            mutations += 1;
+            firstMutationAt ??= now();
+            return send();
+          };
+          try {
+            await attempt.beforeMutation?.(event);
+          } catch (cause) {
+            fenceFailure = new DispatchFenceError(mutations > 0 || attempt.unsettledPriorDispatch === true, cause);
+            throw fenceFailure;
+          }
+          return attempt.aroundMutation ? attempt.aroundMutation(event, observedSend) : observedSend();
+        },
+      },
+      () => publish(connection, prepared),
+    );
+    return successOutcome(connection, attempt.idempotencyKey, publication);
+  } catch (error) {
+    if (fenceFailure !== undefined) throw fenceFailure;
+    if (error instanceof DispatchFenceError) throw error;
+    const dispatched = mutations > 0;
+    const firstDispatchAt = attempt.firstDispatchAt ?? firstMutationAt;
+    return classifyPublishError(
+      error,
+      dispatched,
+      canReplayAmbiguous(policy, attempt, firstDispatchAt, now()),
+      attempt.unsettledPriorDispatch === true,
+    );
+  }
+}
diff --git a/packages/connector-runtime/src/registry.test.ts b/packages/connector-runtime/src/registry.test.ts
new file mode 100644
index 0000000..ff2609d
--- /dev/null
+++ b/packages/connector-runtime/src/registry.test.ts
@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import type { Pool } from "pg";
+import { createPublishingRegistry, verifiedDedupeOrigin } from "./registry.js";
+import { createPublishingCredentialAccessor } from "./credentials.js";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { runWithPublishingContext } from "./execution-context.js";
+const connection: ConnectorConnection = { id: "connection", workspaceId: "workspace", provider: "mastodon", channelId: "channel", fields: {}, createdAt: new Date(), credentialId: { kind: "credential-ref", id: "connection" } };
+describe("production publishing registry", () => {
+  it("registers real Mastodon and Telegram connectors and rejects duplicates", () => {
+    const pool = {} as Pool;
+    const registry = createPublishingRegistry(pool);
+    expect(registry.list().map((c) => c.manifest().id).sort()).toEqual(["mastodon", "telegram"]);
+    expect(registry.get("mastodon").publish).toBeTypeOf("function");
+    expect(() => registry.register(registry.get("mastodon"))).toThrow(/already registered/);
+  });
+  it("trusts only explicitly configured HTTPS origins", () => {
+    expect(verifiedDedupeOrigin("https://social.test", "")).toBe(false);
+    expect(verifiedDedupeOrigin("https://social.test", "https://social.test")).toBe(true);
+    expect(verifiedDedupeOrigin("https://social.test", "https://social.test/path")).toBe(false);
+    expect(verifiedDedupeOrigin("http://social.test", "http://social.test")).toBe(false);
+  });
+  it("refuses absent or mismatched context and publishing credential mutation before SQL", async () => {
+    const accessor = createPublishingCredentialAccessor({} as Pool);
+    await expect(accessor.getAccessToken(connection)).rejects.toThrow("EXECUTION_CREDENTIAL_FENCE");
+    await expect(accessor.put(connection, "access_token", "secret")).rejects.toThrow("MUTATION_REFUSED");
+    await expect(runWithPublishingContext({ workspaceId: "other", connectionId: "connection", credentialId: "uuid", credentialGeneration: "1" }, () => accessor.getAccessToken(connection))).rejects.toThrow("EXECUTION_CREDENTIAL_FENCE");
+  });
+});
diff --git a/packages/connector-runtime/src/registry.ts b/packages/connector-runtime/src/registry.ts
new file mode 100644
index 0000000..03a4f4a
--- /dev/null
+++ b/packages/connector-runtime/src/registry.ts
@@ -0,0 +1,17 @@
+import type { Pool } from "pg";
+import { ConnectorRegistry } from "@tactical-media-broadcast-hub/connector-sdk";
+import { createMastodonConnector } from "@tactical-media-broadcast-hub/connector-mastodon";
+import { createTelegramConnector } from "@tactical-media-broadcast-hub/connector-telegram";
+import { createPublishingCredentialAccessor } from "./credentials.js";
+import { providerFetch } from "./provider-fetch.js";
+import { executionSignal } from "./execution-context.js";
+/** Production composition registers real connectors, once per worker process. */
+export function createPublishingRegistry(pool: Pool): ConnectorRegistry {
+  const registry = new ConnectorRegistry();
+  const fetchImpl: typeof fetch = (input, init) => providerFetch(input, { ...init, signal: executionSignal() ?? init?.signal });
+  const options = { credentials: createPublishingCredentialAccessor(pool), fetchImpl, env: process.env };
+  registry.register(createMastodonConnector(options));
+  registry.register(createTelegramConnector(options));
+  return registry;
+}
+export { verifiedDedupeOrigin } from "./policy.js";
diff --git a/packages/connector-runtime/src/vault.test.ts b/packages/connector-runtime/src/vault.test.ts
new file mode 100644
index 0000000..193aa23
--- /dev/null
+++ b/packages/connector-runtime/src/vault.test.ts
@@ -0,0 +1,13 @@
+import { describe, expect, it } from "vitest";
+import { Vault } from "./vault.js";
+describe("persistent APV1 compatibility", () => {
+  it("survives new vault instances, binds tenant and connection, and rejects tampering", async () => {
+    const sealed = await new Vault().seal("workspace", "connection", Buffer.from("canary-secret"));
+    expect(sealed.ciphertext.subarray(0, 4).toString()).toBe("APV1");
+    expect((await new Vault().open("workspace", "connection", sealed)).toString()).toBe("canary-secret");
+    await expect(new Vault().open("other", "connection", sealed)).rejects.toThrow();
+    await expect(new Vault().open("workspace", "other", sealed)).rejects.toThrow();
+    const ciphertext = Buffer.from(sealed.ciphertext); ciphertext[ciphertext.length - 1] = ciphertext[ciphertext.length - 1]! ^ 1;
+    await expect(new Vault().open("workspace", "connection", { ...sealed, ciphertext })).rejects.toThrow();
+  });
+});
diff --git a/packages/connector-runtime/src/vault.ts b/packages/connector-runtime/src/vault.ts
new file mode 100644
index 0000000..2fda4b6
--- /dev/null
+++ b/packages/connector-runtime/src/vault.ts
@@ -0,0 +1,121 @@
+import { createCipheriv, createDecipheriv, randomBytes, createHash } from "node:crypto";
+
+/**
+ * Envelope encryption vault.
+ * - Master KEK from env (32 bytes, base64). Dev fallback: derive a stable key
+ *   from a machine-local file so ciphertexts survive restarts in development.
+ * - Per-workspace DEK (AES-256-GCM) wrapped by the KEK.
+ * - Rotation: new DEK per workspace, key_version increments; old ciphertexts
+ *   stay readable until re-wrapped, then the old DEK is dropped.
+ */
+
+const ALGO = "aes-256-gcm";
+
+export function loadKek(): Buffer {
+  const env = process.env.SUPERPOSTER_KEK;
+  if (env !== undefined && env !== "") {
+    const kek = Buffer.from(env, "base64");
+    if (kek.length !== 32) throw new Error("SUPERPOSTER_KEK must be 32 bytes base64");
+    return kek;
+  }
+  // Dev fallback: deterministic from hostname — NEVER production.
+  if (process.env.NODE_ENV === "production") {
+    throw new Error("SUPERPOSTER_KEK is required in production");
+  }
+  return createHash("sha256").update(`dev-kek:${process.env.HOSTNAME ?? "local"}`).digest();
+}
+
+const KEK = loadKek();
+
+export interface SealedCredential {
+  ciphertext: Buffer;
+  keyVersion: number;
+}
+
+interface WrappedDek {
+  keyVersion: number;
+  wrapped: Buffer;
+}
+
+function aesEncrypt(key: Buffer, plaintext: Buffer): Buffer {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv(ALGO, key, iv);
+  return Buffer.concat([iv, cipher.update(plaintext), cipher.final(), cipher.getAuthTag()]);
+}
+
+function aesDecrypt(key: Buffer, sealed: Buffer): Buffer {
+  const iv = sealed.subarray(0, 12);
+  const tag = sealed.subarray(sealed.length - 16);
+  const body = sealed.subarray(12, sealed.length - 16);
+  const decipher = createDecipheriv(ALGO, key, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(body), decipher.final()]);
+}
+
+/** In-memory DEK cache; the persistent wrapped-DEK store arrives with the credentials table wiring. */
+export class Vault {
+  /** Self-contained envelope for persistent stores; AAD binds tenant and handle. */
+  async seal(workspaceId: string, credentialId: string, plaintext: Buffer): Promise<SealedCredential> {
+    const dek = randomBytes(32);
+    const wrapped = aesEncrypt(KEK, dek);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv(ALGO, dek, iv);
+    cipher.setAAD(Buffer.from(JSON.stringify([workspaceId, credentialId])));
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    return { keyVersion: 1, ciphertext: Buffer.concat([Buffer.from("APV1"), wrapped, iv, cipher.getAuthTag(), encrypted]) };
+  }
+
+  async open(workspaceId: string, credentialId: string, sealed: SealedCredential): Promise<Buffer> {
+    const blob = sealed.ciphertext;
+    if (blob.length < 92 || blob.subarray(0, 4).toString() !== "APV1") throw new Error("invalid vault envelope");
+    const dek = aesDecrypt(KEK, blob.subarray(4, 64));
+    const decipher = createDecipheriv(ALGO, dek, blob.subarray(64, 76));
+    decipher.setAAD(Buffer.from(JSON.stringify([workspaceId, credentialId])));
+    decipher.setAuthTag(blob.subarray(76, 92));
+    return Buffer.concat([decipher.update(blob.subarray(92)), decipher.final()]);
+  }
+  private readonly deks = new Map<string, { dek: Buffer; wrapped: WrappedDek }>();
+  private versions = new Map<string, number>();
+
+  async put(_workspaceId: string, credentialId: string, plaintext: Buffer): Promise<SealedCredential> {
+    const { dek, wrapped } = await this.ensureDek(_workspaceId);
+    this.deks.set(credentialId, { dek, wrapped });
+    const version = this.versions.get(_workspaceId) ?? 1;
+    return { ciphertext: aesEncrypt(dek, plaintext), keyVersion: version };
+  }
+
+  async get(_workspaceId: string, credentialId: string, sealed: SealedCredential): Promise<Buffer> {
+    const entry = this.deks.get(credentialId);
+    if (entry === undefined) throw new Error("credential not loaded into vault session");
+    return aesDecrypt(entry.dek, sealed.ciphertext);
+  }
+
+  /**
+   * Rotation: fresh DEK for the workspace, re-wrap given credentials,
+   * drop the old DEK so pre-rotation ciphertext becomes unreadable.
+   */
+  async rotate(workspaceId: string, secrets: Array<{ credentialId: string; plaintext: Buffer }>): Promise<Map<string, SealedCredential>> {
+    const nextVersion = (this.versions.get(workspaceId) ?? 1) + 1;
+    const newDek = randomBytes(32);
+    const wrapped: WrappedDek = { keyVersion: nextVersion, wrapped: aesEncrypt(KEK, newDek) };
+    this.versions.set(workspaceId, nextVersion);
+    const out = new Map<string, SealedCredential>();
+    for (const { credentialId, plaintext } of secrets) {
+      this.deks.set(credentialId, { dek: newDek, wrapped });
+      out.set(credentialId, { ciphertext: aesEncrypt(newDek, plaintext), keyVersion: nextVersion });
+    }
+    return out;
+  }
+
+  private async ensureDek(workspaceId: string): Promise<{ dek: Buffer; wrapped: WrappedDek }> {
+    const existing = [...this.deks.values()].find((e) => e.wrapped.keyVersion === (this.versions.get(workspaceId) ?? 1));
+    if (existing !== undefined) return existing;
+    const version = 1;
+    const dek = randomBytes(32);
+    const entry = { dek, wrapped: { keyVersion: version, wrapped: aesEncrypt(KEK, dek) } };
+    this.versions.set(workspaceId, version);
+    return entry;
+  }
+}
+
+export const vault = new Vault();
diff --git a/packages/connector-runtime/tsconfig.json b/packages/connector-runtime/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-runtime/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-sdk/package.json b/packages/connector-sdk/package.json
new file mode 100644
index 0000000..157c512
--- /dev/null
+++ b/packages/connector-sdk/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-sdk",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./testing": "./dist/testing/kits.js",
+    "./rate-policy": "./dist/rate-policy.js",
+    "./testing/fixtures": "./dist/testing/fixtures.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-sdk/src/__probe.ts b/packages/connector-sdk/src/__probe.ts
new file mode 100644
index 0000000..7301f30
--- /dev/null
+++ b/packages/connector-sdk/src/__probe.ts
@@ -0,0 +1,8 @@
+const g1: typeof fetch = globalThis.fetch;
+const g3: FormData | undefined = undefined;
+const g4: Blob | undefined = undefined;
+const g5: typeof process | undefined = undefined;
+const g6: Buffer | undefined = undefined;
+const g7: RequestInit | undefined = undefined;
+const g8: Response | undefined = undefined;
+export const probe = { g1, g3, g4, g5, g6, g7, g8 };
diff --git a/packages/connector-sdk/src/credentials.ts b/packages/connector-sdk/src/credentials.ts
new file mode 100644
index 0000000..3b74cd6
--- /dev/null
+++ b/packages/connector-sdk/src/credentials.ts
@@ -0,0 +1,36 @@
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+
+/**
+ * Opaque credential access — connectors never handle ciphertext or raw vault
+ * material. The vault (WP2) implements this port; the in-memory version here
+ * serves development and contract tests.
+ */
+export interface CredentialAccessor {
+  getAccessToken(connection: ConnectorConnection): Promise<string>;
+  getSecret(connection: ConnectorConnection, key: string): Promise<string>;
+  put(connection: ConnectorConnection, key: string, value: string): Promise<void>;
+}
+
+export class InMemoryCredentials implements CredentialAccessor {
+  private readonly store = new Map<string, string>();
+
+  private key(connection: ConnectorConnection, name: string): string {
+    return `${connection.id}:${name}`;
+  }
+
+  async getAccessToken(connection: ConnectorConnection): Promise<string> {
+    const token = this.store.get(this.key(connection, "access_token"));
+    if (token === undefined) throw new Error(`no access token for connection ${connection.id}`);
+    return token;
+  }
+
+  async getSecret(connection: ConnectorConnection, key: string): Promise<string> {
+    const secret = this.store.get(this.key(connection, key));
+    if (secret === undefined) throw new Error(`no secret "${key}" for connection ${connection.id}`);
+    return secret;
+  }
+
+  async put(connection: ConnectorConnection, key: string, value: string): Promise<void> {
+    this.store.set(this.key(connection, key), value);
+  }
+}
diff --git a/packages/connector-sdk/src/errors.ts b/packages/connector-sdk/src/errors.ts
new file mode 100644
index 0000000..29fa0d7
--- /dev/null
+++ b/packages/connector-sdk/src/errors.ts
@@ -0,0 +1,115 @@
+/**
+ * What a failed provider call proves about the side effect:
+ * - "rejected": the provider answered and definitively did not perform it.
+ * - "unknown": the request may have been applied (5xx/transport loss on a
+ *   non-idempotent request) — never resend without a provider dedupe key.
+ */
+export type DeliveryCertainty = "rejected" | "unknown";
+
+export class ConnectorError extends Error {
+  constructor(
+    message: string,
+    readonly provider: string,
+    override readonly cause?: unknown,
+  ) {
+    super(message);
+    this.name = "ConnectorError";
+  }
+}
+
+export class UnknownProviderError extends ConnectorError {
+  constructor(providerId: string) {
+    super(`no connector registered for provider "${providerId}"`, providerId);
+    this.name = "UnknownProviderError";
+  }
+}
+
+export class AuthError extends ConnectorError {
+  constructor(message: string, provider: string, readonly retryable: boolean) {
+    super(message, provider);
+    this.name = "AuthError";
+  }
+}
+
+export class RateLimitError extends ConnectorError {
+  /** A 429 is a refusal before processing, so nothing was delivered. */
+  readonly delivery: DeliveryCertainty = "rejected";
+
+  constructor(
+    provider: string,
+    readonly retryAfterMs?: number,
+    readonly status = 429,
+  ) {
+    super(`rate limited by ${provider}`, provider);
+    this.name = "RateLimitError";
+  }
+}
+
+/** The provider answered with a non-2xx status that is a definite refusal (4xx). */
+export class ProviderRejectedError extends ConnectorError {
+  readonly delivery: DeliveryCertainty = "rejected";
+
+  constructor(
+    message: string,
+    provider: string,
+    readonly status: number,
+    readonly retryAfterMs?: number,
+  ) {
+    // cause keeps the `{ status }` shape connectors already inspect.
+    super(message, provider, { status });
+    this.name = "ProviderRejectedError";
+  }
+}
+
+/**
+ * 5xx answer the SDK client did not retry (or stopped retrying). For
+ * non-idempotent requests delivery is "unknown": the server may have applied
+ * the write before failing.
+ */
+export class ProviderServerError extends ConnectorError {
+  constructor(
+    provider: string,
+    readonly status: number,
+    readonly method: string,
+    readonly delivery: DeliveryCertainty,
+    readonly retryAfterMs?: number,
+  ) {
+    super(`${provider}: HTTP ${status} on ${method}`, provider, { status });
+    this.name = "ProviderServerError";
+  }
+}
+
+/** fetch itself failed (socket loss, DNS, abort) on a non-idempotent request. */
+export class ProviderTransportError extends ConnectorError {
+  readonly delivery: DeliveryCertainty = "unknown";
+
+  constructor(
+    provider: string,
+    readonly method: string,
+    cause: unknown,
+  ) {
+    super(`${provider}: transport failure on ${method}`, provider, cause);
+    this.name = "ProviderTransportError";
+  }
+}
+
+/** Delivery certainty carried by an SDK error, if the error type records one. */
+export function deliveryCertaintyOf(error: unknown): DeliveryCertainty | undefined {
+  if (error instanceof AuthError) return "rejected";
+  if (
+    error instanceof RateLimitError ||
+    error instanceof ProviderRejectedError ||
+    error instanceof ProviderServerError ||
+    error instanceof ProviderTransportError
+  ) {
+    return error.delivery;
+  }
+  return undefined;
+}
+
+export class CapabilityNotSupportedError extends ConnectorError {
+  constructor(provider: string, capability: string) {
+    super(`${provider} does not support "${capability}"`, provider);
+    this.name = "CapabilityNotSupportedError";
+  }
+}
diff --git a/packages/connector-sdk/src/http.test.ts b/packages/connector-sdk/src/http.test.ts
new file mode 100644
index 0000000..5925ab5
--- /dev/null
+++ b/packages/connector-sdk/src/http.test.ts
@@ -0,0 +1,170 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { deliveryCertaintyOf, ProviderServerError, ProviderTransportError, RateLimitError } from "./errors.js";
+import { RateLimitedHttpClient, setHttpRequestHookProvider, type HttpRequestEvent } from "./http.js";
+
+const URL_ = "https://api.example.test/v1/things";
+
+function scripted(responses: (() => Response)[]): { fetchImpl: typeof fetch; calls: RequestInit[] } {
+  const calls: RequestInit[] = [];
+  const fetchImpl = (async (_input: Parameters<typeof fetch>[0], init?: RequestInit) => {
+    calls.push(init ?? {});
+    const next = responses[Math.min(calls.length - 1, responses.length - 1)];
+    if (next === undefined) throw new Error("no scripted response");
+    return next();
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+function client(fetchImpl: typeof fetch): RateLimitedHttpClient {
+  return new RateLimitedHttpClient({ fetchImpl, requestsPerSecond: 1000, sleep: async () => Promise.resolve() });
+}
+
+afterEach(() => setHttpRequestHookProvider(undefined));
+
+describe("http client retry classification", () => {
+  it("retries idempotent GET on 503 and 429", async () => {
+    const { fetchImpl, calls } = scripted([
+      () => new Response("", { status: 503 }),
+      () => new Response("", { status: 429 }),
+      () => new Response("ok", { status: 200 }),
+    ]);
+    const response = await client(fetchImpl).request("p", URL_);
+    expect(response.status).toBe(200);
+    expect(calls).toHaveLength(3);
+  });
+
+  it("retries PUT and DELETE", async () => {
+    for (const method of ["PUT", "DELETE"]) {
+      const { fetchImpl, calls } = scripted([() => new Response("", { status: 502 }), () => new Response(null, { status: 204 })]);
+      await client(fetchImpl).request("p", URL_, { method });
+      expect(calls).toHaveLength(2);
+    }
+  });
+
+  it("never resends a POST on 429: one call, RateLimitError with header Retry-After", async () => {
+    const { fetchImpl, calls } = scripted([() => new Response("", { status: 429, headers: { "retry-after": "7" } })]);
+    const error = await client(fetchImpl).request("p", URL_, { method: "POST" }).catch((e: unknown) => e);
+    expect(calls).toHaveLength(1);
+    expect(error).toBeInstanceOf(RateLimitError);
+    expect(error).toMatchObject({ retryAfterMs: 7000, delivery: "rejected", status: 429 });
+  });
+
+  it("reads retry_after from a JSON 429 body when no header is present", async () => {
+    const { fetchImpl } = scripted([
+      () => new Response(JSON.stringify({ ok: false, error_code: 429, parameters: { retry_after: 3 } }), { status: 429 }),
+    ]);
+    await expect(client(fetchImpl).request("p", URL_, { method: "POST" })).rejects.toMatchObject({ retryAfterMs: 3000 });
+  });
+
+  it("surfaces POST 5xx as ProviderServerError with unknown delivery, without resending", async () => {
+    const { fetchImpl, calls } = scripted([() => new Response("boom", { status: 500 })]);
+    const error = await client(fetchImpl).request("p", URL_, { method: "POST" }).catch((e: unknown) => e);
+    expect(calls).toHaveLength(1);
+    expect(error).toBeInstanceOf(ProviderServerError);
+    expect(error).not.toBeInstanceOf(RateLimitError);
+    expect(error).toMatchObject({ status: 500, method: "POST", delivery: "unknown" });
+    expect(deliveryCertaintyOf(error)).toBe("unknown");
+  });
+
+  it("wraps POST transport loss as ProviderTransportError (unknown delivery)", async () => {
+    let calls = 0;
+    const fetchImpl = (async () => {
+      calls += 1;
+      throw new TypeError("socket hang up");
+    }) as typeof fetch;
+    const error = await client(fetchImpl).request("p", URL_, { method: "POST" }).catch((e: unknown) => e);
+    expect(calls).toBe(1);
+    expect(error).toBeInstanceOf(ProviderTransportError);
+    expect(deliveryCertaintyOf(error)).toBe("unknown");
+  });
+
+  it("returns 4xx responses to the caller untouched", async () => {
+    const { fetchImpl } = scripted([() => new Response("{}", { status: 422 })]);
+    const response = await client(fetchImpl).request("p", URL_, { method: "POST" });
+    expect(response.status).toBe(422);
+  });
+
+  it("opts a read-only POST into retries and a mutation out of them", async () => {
+    const retried = scripted([() => new Response("", { status: 503 }), () => new Response("ok")]);
+    await client(retried.fetchImpl).request("p", URL_, { method: "POST" }, { retry: true });
+    expect(retried.calls).toHaveLength(2);
+
+    const once = scripted([() => new Response("", { status: 503 })]);
+    await expect(client(once.fetchImpl).request("p", URL_, { method: "PUT" }, { retry: false })).rejects.toBeInstanceOf(
+      ProviderServerError,
+    );
+    expect(once.calls).toHaveLength(1);
+  });
+
+  it("exhausted GET 5xx is a ProviderServerError, not a RateLimitError", async () => {
+    const { fetchImpl, calls } = scripted([() => new Response("", { status: 503 })]);
+    const error = await new RateLimitedHttpClient({ fetchImpl, maxRetries: 2, requestsPerSecond: 1000, sleep: async () => Promise.resolve() })
+      .request("p", URL_)
+      .catch((e: unknown) => e);
+    expect(calls).toHaveLength(3);
+    expect(error).toBeInstanceOf(ProviderServerError);
+    expect(error).toMatchObject({ delivery: "rejected" });
+  });
+
+  it("exhausted GET 429 stays a RateLimitError carrying Retry-After", async () => {
+    const { fetchImpl } = scripted([() => new Response("", { status: 429, headers: { "retry-after": "10" } })]);
+    await expect(client(fetchImpl).request("p", URL_)).rejects.toMatchObject({ name: "RateLimitError", retryAfterMs: 10_000 });
+  });
+});
+
+describe("http request hook", () => {
+  it("runs beforeRequest per actual send, without the URL path", async () => {
+    const events: HttpRequestEvent[] = [];
+    setHttpRequestHookProvider(() => ({ beforeRequest: (event) => void events.push(event) }));
+    const { fetchImpl } = scripted([() => new Response("", { status: 503 }), () => new Response("ok")]);
+    await client(fetchImpl).request("p", "https://api.example.test/bot123:secret/getMe");
+    expect(events.map((e) => e.attempt)).toEqual([0, 1]);
+    expect(events[0]).toEqual({ provider: "p", method: "GET", origin: "https://api.example.test", attempt: 0, mutating: false });
+    expect(JSON.stringify(events)).not.toContain("secret");
+  });
+
+  it("a throwing beforeRequest blocks the send entirely", async () => {
+    setHttpRequestHookProvider(() => ({
+      beforeRequest: () => {
+        throw new Error("fence lost");
+      },
+    }));
+    const { fetchImpl, calls } = scripted([() => new Response("ok")]);
+    await expect(client(fetchImpl).request("p", URL_, { method: "POST" })).rejects.toThrow("fence lost");
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("around-send dispatch serialization", () => {
+  it("holds the gate across the actual response, after the rate limiter", async () => {
+    const order: string[] = [];
+    const { fetchImpl } = scripted([() => { order.push("send"); return new Response("ok"); }]);
+    setHttpRequestHookProvider(() => ({ aroundMutation: async (_event, send) => { order.push("lock"); const response = await send(); order.push("unlock"); return response; } }));
+    await client(fetchImpl).request("p", URL_, { method: "POST" }, { retry: false });
+    expect(order).toEqual(["lock", "send", "unlock"]);
+  });
+  it("preserves gate errors and never classifies them as transport delivery", async () => {
+    const failure = new Error("gate refused"); const { fetchImpl, calls } = scripted([() => new Response("ok")]);
+    setHttpRequestHookProvider(() => ({ aroundMutation: async () => { throw failure; } }));
+    await expect(client(fetchImpl).request("p", URL_, { method: "POST" }, { retry: false })).rejects.toBe(failure);
+    expect(calls).toHaveLength(0);
+  });
+});
+
+describe("rate wait precedes the dispatch gate", () => {
+  it("does not acquire the mutation gate or stamp a send until the limiter releases", async () => {
+    vi.useFakeTimers();
+    try {
+      const { fetchImpl, calls } = scripted([() => new Response("ok")]);
+      const gate = vi.fn(async (_event: HttpRequestEvent, send: () => Promise<Response>) => send());
+      setHttpRequestHookProvider(() => ({ aroundMutation: gate }));
+      const http = new RateLimitedHttpClient({ fetchImpl, requestsPerSecond: 1 });
+      await http.request("p", URL_);
+      const pending = http.request("p", URL_, { method: "POST" }, { retry: false });
+      await vi.advanceTimersByTimeAsync(999);
+      expect(gate).not.toHaveBeenCalled(); expect(calls).toHaveLength(1);
+      await vi.advanceTimersByTimeAsync(1); await pending;
+      expect(gate).toHaveBeenCalledTimes(1); expect(calls).toHaveLength(2);
+    } finally { vi.useRealTimers(); }
+  });
+});
diff --git a/packages/connector-sdk/src/http.ts b/packages/connector-sdk/src/http.ts
new file mode 100644
index 0000000..233c0f5
--- /dev/null
+++ b/packages/connector-sdk/src/http.ts
@@ -0,0 +1,217 @@
+/**
+ * Rate-limited HTTP client for connector packages: per-host token bucket,
+ * exponential backoff with jitter on 429/5xx, fetch-based.
+ *
+ * Retry classification: only idempotent methods (GET/HEAD/OPTIONS/PUT/DELETE)
+ * are retried automatically. A non-idempotent request (POST/PATCH) that gets
+ * 429/5xx or loses its transport is never resent here — the caller receives a
+ * typed error recording whether delivery was definitely refused or unknown.
+ * Read-only POST endpoints can opt back in with `{ retry: true }`; publishing
+ * mutations can opt out entirely with `{ retry: false }`.
+ */
+import {
+  ProviderRejectedError,
+  ProviderServerError,
+  ProviderTransportError,
+  RateLimitError,
+} from "./errors.js";
+
+interface Bucket {
+  tokens: number;
+  lastRefillMs: number;
+}
+
+export interface HttpClientOptions {
+  /** Requests per second allowed per host (default 1). */
+  requestsPerSecond?: number;
+  /** Max backoff attempt count (default 4). */
+  maxRetries?: number;
+  fetchImpl?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface HttpRequestOptions {
+  /**
+   * Auto-retry on 429/5xx. Default: true for idempotent methods, false
+   * otherwise. `true` on a POST asserts the endpoint is side-effect free.
+   */
+  retry?: boolean;
+}
+
+/** Nonsecret request description handed to hooks — never the full URL. */
+export interface HttpRequestEvent {
+  provider: string;
+  method: string;
+  origin: string;
+  /** 0 for the first send, then one per automatic retry. */
+  attempt: number;
+  /** Whether this request may have side effects on the provider. */
+  mutating: boolean;
+}
+
+export interface HttpResponseEvent extends HttpRequestEvent {
+  status: number;
+}
+
+/**
+ * Per-execution hook, resolved for every request. `beforeRequest` runs after
+ * the rate-limiter wait and immediately before each actual send; throwing
+ * from it blocks the send (zero HTTP requests leave the process).
+ */
+export interface HttpRequestHook {
+  aroundMutation?(event: HttpRequestEvent, send: () => Promise<Response>): Promise<Response>;
+  beforeRequest?(event: HttpRequestEvent): void | Promise<void>;
+  afterResponse?(event: HttpResponseEvent): void;
+  afterTransportError?(event: HttpRequestEvent): void;
+}
+
+let hookProvider: (() => HttpRequestHook | undefined) | undefined;
+
+/**
+ * Install the resolver for the current execution's hook (e.g. an
+ * AsyncLocalStorage lookup in the publishing runtime). The resolver is
+ * consulted per request, so concurrent executions never share a hook.
+ * Pass undefined to uninstall.
+ */
+export function setHttpRequestHookProvider(provider: (() => HttpRequestHook | undefined) | undefined): void {
+  hookProvider = provider;
+}
+
+const IDEMPOTENT_METHODS = new Set(["GET", "HEAD", "OPTIONS", "PUT", "DELETE"]);
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+
+export function isIdempotentMethod(method: string): boolean {
+  return IDEMPOTENT_METHODS.has(method.toUpperCase());
+}
+
+const defaultSleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
+
+/** Retry-After header: delta-seconds or HTTP-date → ms. */
+function headerRetryAfterMs(response: Response): number | undefined {
+  const raw = response.headers.get("retry-after");
+  if (raw === null || raw.trim().length === 0) return undefined;
+  const seconds = Number(raw);
+  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);
+  const at = Date.parse(raw);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : undefined;
+}
+
+/** `retry_after` (seconds) in a JSON error body, top level or under `parameters`. */
+async function bodyRetryAfterMs(response: Response): Promise<number | undefined> {
+  try {
+    const body = (await response.json()) as {
+      retry_after?: unknown;
+      parameters?: { retry_after?: unknown } | null;
+    } | null;
+    const value = body?.parameters?.retry_after ?? body?.retry_after;
+    return typeof value === "number" && Number.isFinite(value) ? Math.max(0, value * 1000) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export class RateLimitedHttpClient {
+  private readonly buckets = new Map<string, Bucket>();
+  private readonly rps: number;
+  private readonly maxRetries: number;
+  private readonly fetchImpl: typeof fetch;
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  constructor(opts: HttpClientOptions = {}) {
+    this.rps = opts.requestsPerSecond ?? 1;
+    this.maxRetries = opts.maxRetries ?? 4;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.sleep = opts.sleep ?? defaultSleep;
+  }
+
+  private async takeToken(host: string): Promise<void> {
+    for (;;) {
+      const now = Date.now();
+      const bucket = this.buckets.get(host) ?? { tokens: 1, lastRefillMs: now };
+      const elapsed = (now - bucket.lastRefillMs) / 1000;
+      bucket.tokens = Math.min(1, bucket.tokens + elapsed * this.rps);
+      bucket.lastRefillMs = now;
+      if (bucket.tokens >= 1) {
+        bucket.tokens -= 1;
+        this.buckets.set(host, bucket);
+        return;
+      }
+      this.buckets.set(host, bucket);
+      const waitMs = Math.ceil(((1 - bucket.tokens) / this.rps) * 1000);
+      await this.sleep(waitMs);
+    }
+  }
+
+  /**
+   * Never resolves with a 429/5xx: those are retried (when allowed) and
+   * otherwise thrown as RateLimitError / ProviderServerError.
+   */
+  async request(
+    provider: string,
+    url: string,
+    init: RequestInit = {},
+    options: HttpRequestOptions = {},
+  ): Promise<Response> {
+    const parsed = new URL(url);
+    const method = (init.method ?? "GET").toUpperCase();
+    const retry = options.retry ?? isIdempotentMethod(method);
+    // A POST opted into retries is asserted side-effect free.
+    const mutating = !SAFE_METHODS.has(method) && !(options.retry === true && !isIdempotentMethod(method));
+    let attempt = 0;
+    for (;;) {
+      await this.takeToken(parsed.host);
+      const hook = hookProvider?.();
+      const event: HttpRequestEvent = { provider, method, origin: parsed.origin, attempt, mutating };
+      await hook?.beforeRequest?.(event);
+      const send = async (): Promise<Response> => {
+        try { return await this.fetchImpl(url, init); }
+        catch (cause) {
+          hook?.afterTransportError?.(event);
+          if (retry) throw cause;
+          throw new ProviderTransportError(provider, method, cause);
+        }
+      };
+      const response = event.mutating && hook?.aroundMutation !== undefined
+        ? await hook.aroundMutation(event, send)
+        : await send();
+      hook?.afterResponse?.({ ...event, status: response.status });
+      const failed = response.status === 429 || response.status >= 500;
+      if (!failed) {
+        return response;
+      }
+      const headerAfter = headerRetryAfterMs(response);
+      if (!retry || attempt >= this.maxRetries) {
+        if (response.status === 429) {
+          throw new RateLimitError(provider, headerAfter ?? (await bodyRetryAfterMs(response)));
+        }
+        const delivery = SAFE_METHODS.has(method) ? "rejected" : "unknown";
+        throw new ProviderServerError(provider, response.status, method, delivery, headerAfter);
+      }
+      const backoffMs = headerAfter ?? Math.min(30_000, 2 ** attempt * 500 + Math.random() * 250);
+      await this.sleep(backoffMs);
+      attempt += 1;
+    }
+  }
+
+  async json<T>(
+    provider: string,
+    url: string,
+    init: RequestInit = {},
+    options: HttpRequestOptions = {},
+  ): Promise<T> {
+    const response = await this.request(
+      provider,
+      url,
+      { ...init, headers: { accept: "application/json", ...init.headers } },
+      options,
+    );
+    if (!response.ok) {
+      throw new ProviderRejectedError(
+        `${provider}: HTTP ${response.status} for ${url}`,
+        provider,
+        response.status,
+      );
+    }
+    return (await response.json()) as T;
+  }
+}
diff --git a/packages/connector-sdk/src/index.ts b/packages/connector-sdk/src/index.ts
new file mode 100644
index 0000000..d626f2f
--- /dev/null
+++ b/packages/connector-sdk/src/index.ts
@@ -0,0 +1,8 @@
+export * from "./errors.js";
+export * from "./credentials.js";
+export * from "./http.js";
+export * from "./manifest.js";
+export * from "./page.js";
+export * from "./rate-policy.js";
+export * from "./registry.js";
+export * from "./types.js";
diff --git a/packages/connector-sdk/src/manifest.ts b/packages/connector-sdk/src/manifest.ts
new file mode 100644
index 0000000..d7a9175
--- /dev/null
+++ b/packages/connector-sdk/src/manifest.ts
@@ -0,0 +1,109 @@
+import type { PlatformConnector } from "./types.js";
+import type { ConnectorCapabilities } from "@tactical-media-broadcast-hub/core";
+
+export interface ConnectionField {
+  name: string;
+  label: string;
+  required: boolean;
+  /** Field is secret — UI masks it, vault stores it. */
+  secret: boolean;
+  /** Optional validation pattern (regex source). */
+  pattern?: string;
+  placeholder?: string;
+}
+
+export interface ConnectorManifest {
+  /** Unique provider id, e.g. "mock-social". Dots/kebab-case, no spaces. */
+  id: string;
+  displayName: string;
+  capabilities: ConnectorCapabilities;
+  /** Fields the UI renders when adding a connection (e.g. instanceUrl). */
+  connectionFields: ConnectionField[];
+  /** OAuth flavor for the generic authorization flow. */
+  oauth?: {
+    kind: "oauth2-redirect" | "token" | "per-instance-oauth2";
+    authorizeUrlTemplate?: string;
+    scopes?: string[];
+    pkce?: boolean;
+    /** False when this deployment cannot support a redirect connect flow. */
+    connectEnabled?: boolean;
+    connectNote?: string;
+    /** Token providers may require a publishing target besides the token. */
+    targetField?: string;
+  };
+  /**
+   * Streams-column capability (WP3 §2.2): the connector implements
+   * `search()` for keyword/hashtag columns. Optional so existing manifests
+   * compile untouched; boolean when present, and must agree with the method
+   * actually on the connector (validated in `assertValidManifest`).
+   */
+  search?: boolean;
+  /**
+   * Streams-column capability (WP3 §2.2): the connector implements
+   * `getUserFeed()` for account-list columns. Same optionality/consistency
+   * rules as `search`.
+   */
+  authorFeed?: boolean;
+  /** Base route this connector's webhooks are served under (verification is connector-side). */
+  webhookRoute?: string;
+  docsUrl?: string;
+  icon?: string;
+}
+
+/** Streams-column capability flags (WP3 §2.2) and the method each gates. */
+export const STREAMS_COLUMN_FLAGS = [
+  { flag: "search", method: "search" },
+  { flag: "authorFeed", method: "getUserFeed" },
+] as const satisfies ReadonlyArray<{ flag: "search" | "authorFeed"; method: "search" | "getUserFeed" }>;
+
+/**
+ * Validate a manifest. When a connector is supplied, streams-column capability
+ * flags are also cross-checked against the connector surface: a declared flag
+ * without the method, or a method behind an undeclared flag, is an error —
+ * mirrors never lie (same rule the contract kits enforce).
+ */
+export function assertValidManifest(m: ConnectorManifest, connector?: PlatformConnector): void {
+  if (!/^[a-z0-9][a-z0-9.-]*$/.test(m.id)) {
+    throw new Error(`manifest.id "${m.id}" must be kebab-case`);
+  }
+  if (m.id.length < 2) throw new Error("manifest.id too short");
+  if (!m.displayName) throw new Error("manifest.displayName required");
+  if (!m.capabilities) throw new Error("manifest.capabilities required");
+  for (const field of m.connectionFields) {
+    if (field.secret && field.name === "password") {
+      throw new Error("connectionFields must not include a password field — tokens only");
+    }
+  }
+  const caps = Object.entries(m.capabilities).filter(([, v]) => v === true).length;
+  if (caps === 0) throw new Error("manifest must declare at least one capability");
+  for (const { flag, method } of STREAMS_COLUMN_FLAGS) {
+    const value = m[flag];
+    if (value !== undefined && typeof value !== "boolean") {
+      throw new Error(`manifest.${flag} must be a boolean when present`);
+    }
+    if (connector === undefined) continue;
+    const implemented = typeof connector[method] === "function";
+    if (value === true && !implemented) {
+      throw new Error(`manifest.${flag} declared but connector.${method}() is not implemented`);
+    }
+    if (value !== true && implemented) {
+      throw new Error(
+        `connector.${method}() implemented but manifest.${flag} is not true — undeclared capability`,
+      );
+    }
+  }
+}
+
+/**
+ * Capability strings for `/feeds` meta: the existing capability strings plus
+ * the streams-column flags when declared ("search", "authorFeed"), so the UI
+ * gates keyword/author affordances with zero new endpoints (WP3 §2.2).
+ */
+export function manifestCapabilityStrings(m: ConnectorManifest): string[] {
+  const strings = Object.entries(m.capabilities)
+    .filter(([, v]) => v === true)
+    .map(([k]) => k);
+  if (m.search === true) strings.push("search");
+  if (m.authorFeed === true) strings.push("authorFeed");
+  return strings;
+}
diff --git a/packages/connector-sdk/src/page.ts b/packages/connector-sdk/src/page.ts
new file mode 100644
index 0000000..53bfe16
--- /dev/null
+++ b/packages/connector-sdk/src/page.ts
@@ -0,0 +1,13 @@
+/** Standardized cursor page — every list-shaped connector method returns this. */
+export interface Page<T, C = string> {
+  items: T[];
+  nextCursor?: C;
+}
+
+export function emptyPage<T>(): Page<T> {
+  return { items: [] };
+}
+
+export function pageOf<T>(items: T[], nextCursor?: string): Page<T> {
+  return nextCursor === undefined ? { items } : { items, nextCursor };
+}
diff --git a/packages/connector-sdk/src/rate-policy.test.ts b/packages/connector-sdk/src/rate-policy.test.ts
new file mode 100644
index 0000000..c0f2945
--- /dev/null
+++ b/packages/connector-sdk/src/rate-policy.test.ts
@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+import { capacitySnapshot, exceedsDocumentedCap, humanizeMs, resolveRatePolicy } from "./rate-policy.js";
+
+describe("rate policy resolution", () => {
+  it("falls back to documented defaults when nothing overrides", () => {
+    const policy = resolveRatePolicy("instagram", { dailyPostCap: 25, requestsPerSecond: 0.5 });
+    expect(policy.dailyPostCap).toBe(25);
+    expect(policy.requestsPerSecond).toBe(0.5);
+  });
+
+  it("connection override beats documented (news tier)", () => {
+    const policy = resolveRatePolicy(
+      "instagram",
+      { dailyPostCap: 25 },
+      { dailyPostCap: 100, tierNote: "news-publisher advanced access" },
+    );
+    expect(policy.dailyPostCap).toBe(100);
+    expect(policy.tierNote).toBe("news-publisher advanced access");
+  });
+
+  it("env beats documented, override beats env", () => {
+    process.env.CONNECTOR_RATE_THREADS_DAILY_POSTS = "500";
+    process.env.CONNECTOR_RATE_THREADS_RPS = "2";
+    const fromEnv = resolveRatePolicy("threads", { dailyPostCap: 250, requestsPerSecond: 0.5 });
+    expect(fromEnv.dailyPostCap).toBe(500);
+    expect(fromEnv.requestsPerSecond).toBe(2);
+    const fromOverride = resolveRatePolicy("threads", { dailyPostCap: 250 }, { dailyPostCap: 750 });
+    expect(fromOverride.dailyPostCap).toBe(750);
+    delete process.env.CONNECTOR_RATE_THREADS_DAILY_POSTS;
+    delete process.env.CONNECTOR_RATE_THREADS_RPS;
+  });
+
+  it("sanitize rejects zero/negative/garbage", () => {
+    const policy = resolveRatePolicy("x", { dailyPostCap: -5, requestsPerSecond: 0 }, { commentsPerHour: 0 });
+    expect(policy.dailyPostCap).toBe(FALLBACK_FOR("dailyPostCap"));
+    expect(policy.requestsPerSecond).toBe(FALLBACK_FOR("requestsPerSecond"));
+  });
+
+  it("cap-exceedance warning hook", () => {
+    expect(exceedsDocumentedCap({ dailyPostCap: 25 }, { dailyPostCap: 100 })).toBe(true);
+    expect(exceedsDocumentedCap({ dailyPostCap: 25 }, { dailyPostCap: 25 })).toBe(false);
+    expect(exceedsDocumentedCap({ dailyPostCap: 25 })).toBe(false);
+  });
+});
+
+describe("capacity snapshot (rolling window)", () => {
+  const HOUR = 3600_000;
+  const now = Date.now();
+  const ago = (h: number): string => new Date(now - h * HOUR).toISOString();
+
+  it("shows remaining under the cap", () => {
+    const snap = capacitySnapshot(
+      { used: 8, cap: 25, recentPublishes: [ago(1), ago(2), ago(3), ago(4), ago(5), ago(6), ago(7), ago(8)] },
+      resolveRatePolicy("x", { dailyPostCap: 25 }),
+    );
+    expect(snap.remaining).toBe(17);
+    expect(snap.label).toContain("17 of 25");
+  });
+
+  it("at cap: next slot frees when the oldest publish ages out", () => {
+    const publishes = [ago(3), ...Array.from({ length: 24 }, () => ago(1))];
+    const snap = capacitySnapshot(
+      { used: 25, cap: 25, recentPublishes: publishes },
+      resolveRatePolicy("x", { dailyPostCap: 25 }),
+    );
+    expect(snap.remaining).toBe(0);
+    expect(snap.nextSlotInMs).toBeDefined();
+    if (snap.nextSlotInMs !== undefined) {
+      expect(snap.nextSlotInMs).toBeGreaterThan(20 * HOUR);
+      expect(snap.nextSlotInMs).toBeLessThan(21 * HOUR);
+    }
+    expect(snap.label).toContain("next slot in");
+  });
+
+  it("uncapped connections say so", () => {
+    const snap = capacitySnapshot({ used: 40, recentPublishes: [] }, { requestsPerSecond: 1 });
+    expect(snap.remaining).toBeUndefined();
+    expect(snap.label).toContain("no cap");
+  });
+
+  it("stale publishes (outside 24h) do not count", () => {
+    const snap = capacitySnapshot(
+      { used: 1, cap: 25, recentPublishes: [ago(30)] },
+      resolveRatePolicy("x", { dailyPostCap: 25 }),
+    );
+    expect(snap.remaining).toBe(25);
+  });
+});
+
+describe("humanize", () => {
+  it("formats durations", () => {
+    expect(humanizeMs(0)).toBe("now");
+    expect(humanizeMs(5 * 60000)).toBe("5m");
+    expect(humanizeMs(90 * 60000)).toBe("1h 30m");
+    expect(humanizeMs(2 * HOUR_MS)).toBe("2h");
+  });
+});
+
+const HOUR_MS = 3600_000;
+
+function FALLBACK_FOR(key: "requestsPerSecond" | "dailyPostCap"): number {
+  const base = resolveRatePolicy("fallback-probe", {});
+  return key === "requestsPerSecond" ? base.requestsPerSecond : (base.dailyPostCap ?? -1);
+}
diff --git a/packages/connector-sdk/src/rate-policy.ts b/packages/connector-sdk/src/rate-policy.ts
new file mode 100644
index 0000000..7a6e0dc
--- /dev/null
+++ b/packages/connector-sdk/src/rate-policy.ts
@@ -0,0 +1,145 @@
+/**
+ * Rate & capacity policy — settings-driven, never hardcoded.
+ *
+ * Three sources, highest precedence first:
+ *   1. per-connection override (workspace settings / news-tier declarations)
+ *   2. deployment env: CONNECTOR_RATE_<PROVIDER>_RPS / _DAILY_POSTS / _COMMENTS_HR
+ *   3. documented provider defaults (what the platform's API documents for
+ *      standard access — e.g. Instagram 25 posts/24h, Threads 250/24h)
+ *
+ * IMPORTANT: documented caps are enforced SERVER-SIDE by the provider at the
+ * standard tier. Raising a value here does not bypass the provider — it
+ * declares what OUR tier actually permits (news/publisher programs raise
+ * real limits) so the scheduler can pace within true capacity. Setting a
+ * value above the provider's enforced cap just means publish attempts will
+ * be rejected upstream; the scheduler surfaces that, it never fakes it.
+ */
+
+export interface RatePolicy {
+  /** Client politeness toward the provider API (token bucket rate). */
+  requestsPerSecond: number;
+  /** Planning budget: max posts per rolling 24h per connection. */
+  dailyPostCap?: number;
+  /** Planning budget: max comment/reply calls per hour. */
+  commentsPerHour?: number;
+  /** Free-form tier note, e.g. "news-publisher advanced access". */
+  tierNote?: string;
+}
+
+export const FALLBACK_RATE_POLICY: RatePolicy = {
+  requestsPerSecond: 1,
+  dailyPostCap: 50,
+  commentsPerHour: 60,
+};
+
+function envNumber(name: string): number | undefined {
+  const raw = process.env[name];
+  if (raw === undefined || raw === "") return undefined;
+  const value = Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : undefined;
+}
+
+function envString(name: string): string | undefined {
+  const raw = process.env[name];
+  return raw !== undefined && raw !== "" ? raw : undefined;
+}
+
+function sanitize(partial: Partial<RatePolicy>): Partial<RatePolicy> {
+  const clean: Partial<RatePolicy> = {};
+  if (partial.requestsPerSecond !== undefined && partial.requestsPerSecond > 0) {
+    clean.requestsPerSecond = partial.requestsPerSecond;
+  }
+  if (partial.dailyPostCap !== undefined && partial.dailyPostCap > 0) clean.dailyPostCap = partial.dailyPostCap;
+  if (partial.commentsPerHour !== undefined && partial.commentsPerHour > 0) clean.commentsPerHour = partial.commentsPerHour;
+  if (partial.tierNote !== undefined && partial.tierNote !== "") clean.tierNote = partial.tierNote;
+  return clean;
+}
+
+/**
+ * Resolve the effective rate policy for a connection.
+ *
+ * @param provider   manifest id, e.g. "instagram" (used for env var names)
+ * @param documented provider-documented defaults for standard access
+ * @param override   per-connection override from workspace settings
+ */
+export function resolveRatePolicy(
+  provider: string,
+  documented: Partial<RatePolicy>,
+  override?: Partial<RatePolicy>,
+): RatePolicy {
+  const envPrefix = `CONNECTOR_RATE_${provider.toUpperCase().replace(/-/g, "_")}`;
+  const fromEnv: Partial<RatePolicy> = {
+    requestsPerSecond: envNumber(`${envPrefix}_RPS`),
+    dailyPostCap: envNumber(`${envPrefix}_DAILY_POSTS`),
+    commentsPerHour: envNumber(`${envPrefix}_COMMENTS_PER_HOUR`),
+    tierNote: envString(`${envPrefix}_TIER_NOTE`),
+  };
+  const merged: RatePolicy = {
+    ...FALLBACK_RATE_POLICY,
+    ...sanitize(documented),
+    ...sanitize(fromEnv),
+    ...sanitize(override ?? {}),
+  };
+  return merged;
+}
+
+/** True when the override would exceed the documented standard-access cap (UI warning hook). */
+export function exceedsDocumentedCap(documented: Partial<RatePolicy>, override?: Partial<RatePolicy>): boolean {
+  if (override?.dailyPostCap === undefined || documented.dailyPostCap === undefined) return false;
+  return override.dailyPostCap > documented.dailyPostCap;
+}
+
+export interface CapacityUsage {
+  /** Posts published via this connection in the current rolling 24h window. */
+  used: number;
+  /** Effective cap (resolved policy). Undefined when uncapped. */
+  cap?: number;
+  /** ISO timestamps of recent publishes (oldest first) for window math. */
+  recentPublishes: string[];
+}
+
+export interface CapacitySnapshot {
+  used: number;
+  cap?: number;
+  remaining?: number;
+  /** ms until the next slot frees (oldest publish exits the window). Undefined when full availability. */
+  nextSlotInMs?: number;
+  /** Human label, e.g. "17 left today · next slot in 2h 14m" */
+  label: string;
+}
+
+/**
+ * Rolling-window capacity snapshot for the UI.
+ * The window is a sliding 24h (provider caps are rolling, not calendar-day),
+ * so slots free up as old publishes age out.
+ */
+export function capacitySnapshot(usage: CapacityUsage, policy: RatePolicy): CapacitySnapshot {
+  const cap = policy.dailyPostCap;
+  const now = Date.now();
+  const windowMs = 24 * 60 * 60 * 1000;
+  const inWindow = usage.recentPublishes
+    .map((iso) => Date.parse(iso))
+    .filter((t) => Number.isFinite(t) && t > now - windowMs)
+    .sort((a, b) => a - b);
+  const used = usage.recentPublishes.length > 0 ? inWindow.length : usage.used;
+  if (cap === undefined) {
+    return { used, label: `${used} today · no cap` };
+  }
+  const remaining = Math.max(0, cap - used);
+  if (remaining > 0) {
+    return { used, cap, remaining, label: `${remaining} of ${cap} left · rolling 24h` };
+  }
+  const oldest = inWindow[0];
+  const nextSlotInMs = oldest !== undefined ? Math.max(0, oldest + windowMs - now) : undefined;
+  const human = nextSlotInMs !== undefined ? humanizeMs(nextSlotInMs) : "soon";
+  return { used, cap, remaining: 0, nextSlotInMs, label: `0 of ${cap} left · next slot in ${human}` };
+}
+
+export function humanizeMs(ms: number): string {
+  if (ms <= 0) return "now";
+  const minutes = Math.round(ms / 60000);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  const rem = minutes % 60;
+  return rem === 0 ? `${hours}h` : `${hours}h ${rem}m`;
+}
diff --git a/packages/connector-sdk/src/registry.ts b/packages/connector-sdk/src/registry.ts
new file mode 100644
index 0000000..f9f0f6d
--- /dev/null
+++ b/packages/connector-sdk/src/registry.ts
@@ -0,0 +1,41 @@
+import type { PlatformConnector } from "./types.js";
+import { UnknownProviderError } from "./errors.js";
+
+export type ConnectorFactory = () => PlatformConnector;
+
+/**
+ * Provider registry. Adding a connector = registering here; the rest of the
+ * application resolves by provider id and never switches on names.
+ */
+export class ConnectorRegistry {
+  private readonly connectors = new Map<string, PlatformConnector>();
+
+  register(connector: PlatformConnector): void {
+    const { id } = connector.manifest();
+    if (this.connectorsHas(id)) {
+      throw new Error(`connector "${id}" already registered`);
+    }
+    this.connectors.set(id, connector);
+  }
+
+  get(providerId: string): PlatformConnector {
+    const connector = this.connectors.get(providerId);
+    if (connector === undefined) throw new UnknownProviderError(providerId);
+    return connector;
+  }
+
+  has(providerId: string): boolean {
+    return this.connectors.has(providerId);
+  }
+
+  list(): PlatformConnector[] {
+    return [...this.connectors.values()];
+  }
+
+  private connectorsHas(id: string): boolean {
+    return this.connectors.has(id);
+  }
+
+}
+
+export const CONNECTOR_REGISTRY = Symbol("CONNECTOR_REGISTRY");
diff --git a/packages/connector-sdk/src/testing/contract-search.test.ts b/packages/connector-sdk/src/testing/contract-search.test.ts
new file mode 100644
index 0000000..9af4501
--- /dev/null
+++ b/packages/connector-sdk/src/testing/contract-search.test.ts
@@ -0,0 +1,123 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorManifest } from "../manifest.js";
+import { assertValidManifest, manifestCapabilityStrings, STREAMS_COLUMN_FLAGS } from "../manifest.js";
+import {
+  createNonCapableFixture,
+  createSearchCapableFixture,
+  fixtureConnection,
+  fixtureFeedItem,
+} from "./fixtures.js";
+import { connectorContractTests } from "./kits.js";
+
+/**
+ * P0b contract tests: capability gating for streams-column search surfaces.
+ * A connector may only expose `search()` / `getUserFeed()` when the manifest
+ * declares `search` / `authorFeed`, and a declared flag requires the method.
+ */
+
+describe("streams-column manifest validation", () => {
+  const base: ConnectorManifest = {
+    id: "fixture-search",
+    displayName: "Fixture Search Connector",
+    capabilities: { publishText: true },
+    connectionFields: [{ name: "instanceUrl", label: "Instance URL", required: false, secret: false }],
+  };
+
+  it("accepts flags true with methods present", () => {
+    const { connector } = createSearchCapableFixture();
+    expect(() => assertValidManifest(connector.manifest(), connector)).not.toThrow();
+  });
+
+  it("accepts manifests without the new flags (existing connectors untouched)", () => {
+    expect(() => assertValidManifest(base)).not.toThrow();
+  });
+
+  it("rejects non-boolean flags", () => {
+    for (const bad of [
+      { ...base, search: "yes" as unknown as boolean },
+      { ...base, authorFeed: 1 as unknown as boolean },
+    ]) {
+      expect(() => assertValidManifest(bad)).toThrow(/must be a boolean/);
+    }
+  });
+
+  it("rejects a declared flag without the implementing method", () => {
+    const { connector } = createNonCapableFixture();
+    const manifest = { ...connector.manifest(), search: true };
+    expect(() => assertValidManifest(manifest, connector)).toThrow(/declared but connector\.search\(\)/);
+  });
+
+  it("rejects the method behind an undeclared flag", () => {
+    const { connector } = createSearchCapableFixture();
+    const manifest = { ...connector.manifest(), search: false };
+    expect(() => assertValidManifest(manifest, connector)).toThrow(/undeclared capability/);
+  });
+
+  it("rejects authorFeed declared without getUserFeed", () => {
+    const { connector } = createNonCapableFixture();
+    const manifest = { ...connector.manifest(), authorFeed: true };
+    expect(() => assertValidManifest(manifest, connector)).toThrow(
+      /declared but connector\.getUserFeed\(\)/,
+    );
+  });
+
+  it("maps flags to capability strings for /feeds meta", () => {
+    const capable = manifestCapabilityStrings(createSearchCapableFixture().connector.manifest());
+    expect(capable).toContain("search");
+    expect(capable).toContain("authorFeed");
+    const plain = manifestCapabilityStrings(createNonCapableFixture().connector.manifest());
+    expect(plain).not.toContain("search");
+    expect(plain).not.toContain("authorFeed");
+  });
+
+  it("exposes the flag→method table", () => {
+    expect(STREAMS_COLUMN_FLAGS).toEqual([
+      { flag: "search", method: "search" },
+      { flag: "authorFeed", method: "getUserFeed" },
+    ]);
+  });
+});
+
+describe("streams-column fixtures", () => {
+  it("search-capable fixture serves keyword and hashtag queries, keyless and connected", async () => {
+    const { connector, calls } = createSearchCapableFixture();
+    const conn = fixtureConnection("fixture-search");
+
+    const keyless = await connector.search?.(null, { query: { text: "acampada26" }, limit: 10 });
+    expect(keyless?.items).toHaveLength(1);
+    expect(keyless?.items[0]?.text).toBe("search:acampada26");
+    expect(calls.search[0]).toMatchObject({ connectionWasNull: true, query: "acampada26", kind: undefined });
+
+    const tagged = await connector.search?.(conn, { query: { text: "#acampada26", kind: "hashtag" }, limit: 10 });
+    expect(tagged?.items).toHaveLength(1);
+    expect(calls.search[1]).toMatchObject({ connectionWasNull: false, query: "#acampada26", kind: "hashtag" });
+
+    const author = await connector.getUserFeed?.(null, { account: { handle: "@user@inst.test" }, limit: 5 });
+    expect(author?.items[0]?.text).toBe("user:@user@inst.test");
+    expect(calls.getUserFeed[0]).toMatchObject({ connectionWasNull: true, account: "@user@inst.test" });
+  });
+
+  it("non-capable fixture has neither method nor flag — the legacy connector shape", () => {
+    const { connector } = createNonCapableFixture();
+    const manifest = connector.manifest();
+    expect(manifest.search).toBeUndefined();
+    expect(manifest.authorFeed).toBeUndefined();
+    expect(connector.search).toBeUndefined();
+    expect(connector.getUserFeed).toBeUndefined();
+  });
+
+  it("fixture items are well-formed FeedItems", () => {
+    const item = fixtureFeedItem({ remoteId: "x-9" });
+    expect(item).toMatchObject({ provider: "fixture-search", remoteId: "x-9", authorHandle: "@fixture" });
+    expect(item.createdAt).toBeInstanceOf(Date);
+  });
+});
+
+describe("capability gating via the shared contract kit", () => {
+  connectorContractTests(createSearchCapableFixture().connector, {
+    connection: fixtureConnection("fixture-search"),
+  });
+  connectorContractTests(createNonCapableFixture().connector, {
+    connection: fixtureConnection("fixture-basic"),
+  });
+});
diff --git a/packages/connector-sdk/src/testing/fixtures.ts b/packages/connector-sdk/src/testing/fixtures.ts
new file mode 100644
index 0000000..8cb7b83
--- /dev/null
+++ b/packages/connector-sdk/src/testing/fixtures.ts
@@ -0,0 +1,136 @@
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  FeedItem,
+  ProviderId,
+} from "@tactical-media-broadcast-hub/core";
+import type { PlatformConnector } from "../types.js";
+import type { ConnectorManifest } from "../manifest.js";
+import { assertValidManifest } from "../manifest.js";
+import { pageOf, type Page } from "../page.js";
+
+/**
+ * Streams-column contract fixtures (WP3 §6 P0b): a search-capable and a
+ * non-capable fixture connector exercising the optional `search()` /
+ * `getUserFeed()` surface, capability flags, and the gating rules.
+ */
+
+/** Minimal in-memory FeedItem factory for fixtures and connector tests. */
+export function fixtureFeedItem(overrides: Partial<FeedItem> = {}): FeedItem {
+  const provider: ProviderId = overrides.provider ?? "fixture-search";
+  return {
+    id: `${provider}:item-1`,
+    provider,
+    remoteId: "item-1",
+    authorHandle: "@fixture",
+    text: "fixture post about acampada26",
+    mediaUrls: [],
+    createdAt: new Date("2024-01-01T00:00:00Z"),
+    metrics: { replies: 0, reposts: 0, likes: 0 },
+    ...overrides,
+  };
+}
+
+export function fixtureConnection(provider: ProviderId): ConnectorConnection {
+  return {
+    id: `conn-${provider}`,
+    workspaceId: "ws-1",
+    provider,
+    channelId: "channel-1",
+    credentialId: { kind: "credential-ref", id: "cred-1" },
+    fields: {},
+    createdAt: new Date(),
+  };
+}
+
+function fixtureManifest(overrides: Partial<ConnectorManifest>): ConnectorManifest {
+  const capabilities: ConnectorCapabilities = { feed: true };
+  return {
+    id: "fixture-search",
+    displayName: "Fixture Search Connector",
+    capabilities,
+    connectionFields: [{ name: "instanceUrl", label: "Instance URL", required: false, secret: false }],
+    ...overrides,
+  };
+}
+
+export interface FixtureCalls {
+  search: { connectionWasNull: boolean; query: string; kind: "keyword" | "hashtag" | undefined }[];
+  getUserFeed: { connectionWasNull: boolean; account: string }[];
+}
+
+/**
+ * Search-capable fixture: declares `search: true` + `authorFeed: true` and
+ * implements both methods. Records whether callers passed a keyless (`null`)
+ * connection so tests can assert the keyless contract.
+ */
+export function createSearchCapableFixture(): {
+  connector: PlatformConnector;
+  calls: FixtureCalls;
+} {
+  const calls: FixtureCalls = { search: [], getUserFeed: [] };
+
+  const connector: PlatformConnector = {
+    manifest() {
+      const manifest = fixtureManifest({ search: true, authorFeed: true });
+      assertValidManifest(manifest, connector);
+      return manifest;
+    },
+    async authorize() {
+      throw new Error("fixture: authorize not exercised");
+    },
+    async getIdentity() {
+      return { provider: "fixture-search", remoteId: "fixture-1", handle: "@fixture" };
+    },
+    async getFeed(_connection, request) {
+      if (request.kind === "search") {
+        throw new Error("fixture: use search() for keyword columns");
+      }
+      return pageOf([fixtureFeedItem()]);
+    },
+    async search(conn, request) {
+      calls.search.push({
+        connectionWasNull: conn === null,
+        query: request.query.text,
+        kind: request.query.kind,
+      });
+      return pageOf([fixtureFeedItem({ text: `search:${request.query.text}` })]);
+    },
+    async getUserFeed(conn, request) {
+      calls.getUserFeed.push({
+        connectionWasNull: conn === null,
+        account: request.account.handle ?? request.account.externalId ?? "",
+      });
+      return pageOf([fixtureFeedItem({ text: `user:${request.account.handle ?? request.account.externalId}` })]);
+    },
+  };
+  return { connector, calls };
+}
+
+/**
+ * Non-capable fixture: implements neither `search` nor `getUserFeed` and
+ * declares neither flag. Existing connectors compile untouched — this shape is
+ * exactly what every pre-columns connector already looks like.
+ */
+export function createNonCapableFixture(): { connector: PlatformConnector } {
+  const connector: PlatformConnector = {
+    manifest() {
+      const manifest = fixtureManifest({ id: "fixture-basic" });
+      assertValidManifest(manifest);
+      return manifest;
+    },
+    async authorize() {
+      throw new Error("fixture: authorize not exercised");
+    },
+    async getIdentity() {
+      return { provider: "fixture-basic", remoteId: "fixture-2", handle: "@basic" };
+    },
+    async getFeed() {
+      return pageOf([fixtureFeedItem({ provider: "fixture-basic", id: "fixture-basic:item-1" })]);
+    },
+  };
+  return { connector };
+}
+
+/** Type-level witness: a Page of FeedItem is what both methods return. */
+export type FixtureFeedPage = Page<FeedItem>;
diff --git a/packages/connector-sdk/src/testing/kits.ts b/packages/connector-sdk/src/testing/kits.ts
new file mode 100644
index 0000000..c66b2eb
--- /dev/null
+++ b/packages/connector-sdk/src/testing/kits.ts
@@ -0,0 +1,225 @@
+/**
+ * Capability-aware contract test kits. A connector that lies about its
+ * capabilities FAILS: declared capability without the matching method is an
+ * error; the kits only assert what the manifest declares.
+ */
+import { describe, expect, it } from "vitest";
+import type { PlatformConnector } from "../types.js";
+import { assertValidManifest, manifestCapabilityStrings } from "../manifest.js";
+import { ConnectorRegistry } from "../registry.js";
+import { UnknownProviderError } from "../errors.js";
+
+export interface ContractHarness {
+  /** A live-ish connection the connector can operate on (mock state ok). */
+  connection: import("@tactical-media-broadcast-hub/core").ConnectorConnection;
+}
+
+const CAPABILITY_METHOD: Record<string, keyof PlatformConnector> = {
+  search: "search",
+  authorFeed: "getUserFeed",
+  publishText: "publish",
+  publishImages: "publish",
+  publishCarousel: "publish",
+  publishVideo: "uploadVideo",
+  videoThumbnails: "uploadVideo",
+  playlists: "getVideos",
+  feed: "getFeed",
+  comments: "getComments",
+  replies: "reply",
+  amplifyRepost: "amplify",
+  amplifyQuote: "amplify",
+  amplifyShare: "amplify",
+  directMessages: "getMessages",
+  livestreams: "getLiveStreams",
+  createLivestream: "createLiveStream",
+  manageLivestream: "updateLiveStream",
+  livePlaybackSource: "getStreamPlaybackSources",
+  liveChatRead: "getLiveChat",
+  liveChatWrite: "sendLiveChatMessage",
+  liveChatModeration: "moderateLiveChat",
+  analytics: "getAnalytics",
+  webhooks: "subscribeWebhooks",
+  deletePublication: "deletePublication",
+};
+
+export function connectorContractTests(connector: PlatformConnector, harness: ContractHarness): void {
+  const manifest = connector.manifest();
+
+  describe(`connector contract: ${manifest.id}`, () => {
+    it("has a valid manifest", () => {
+      assertValidManifest(manifest);
+    });
+
+    it("declares no password field", () => {
+      for (const field of manifest.connectionFields) {
+        expect(field.name.toLowerCase()).not.toContain("password");
+      }
+    });
+
+    it("declared capabilities have implementing methods", () => {
+      for (const [capability, method] of Object.entries(CAPABILITY_METHOD)) {
+        if (manifest.capabilities[capability as keyof typeof manifest.capabilities] === true) {
+          expect(
+            connector[method],
+            `capability "${capability}" declared but method "${String(method)}" missing`,
+          ).toBeTypeOf("function");
+        }
+      }
+    });
+
+    it("methods behind undeclared capabilities are absent", () => {
+      const caps = manifest.capabilities;
+      if (!caps.feed) expect(connector.getFeed).toBeUndefined();
+      if (!caps.publishText) expect(connector.publish).toBeUndefined();
+      if (!caps.livestreams) expect(connector.getLiveStreams).toBeUndefined();
+    });
+
+    it("resolves in the registry and unknown providers throw", () => {
+      const registry = new ConnectorRegistry();
+      registry.register(connector);
+      expect(registry.get(manifest.id)).toBe(connector);
+      expect(() => registry.get("no-such-provider-xyz")).toThrow(UnknownProviderError);
+    });
+
+    it("returns a stable identity", async () => {
+      const identity = await connector.getIdentity(harness.connection);
+      expect(identity.provider).toBe(manifest.id);
+      expect(identity.handle).toBeTruthy();
+    });
+
+    // --- Streams-column capability gating (WP3 §6 P0b) -------------------
+
+    it("declares boolean streams-column flags when present", () => {
+      for (const flag of ["search", "authorFeed"] as const) {
+        const value = manifest[flag];
+        if (value !== undefined) expect(value, `manifest.${flag}`).toBeTypeOf("boolean");
+      }
+    });
+
+    it("declared search capability has an implementing search method", () => {
+      if (manifest.search === true) {
+        expect(connector.search, "manifest.search declared but search() missing").toBeTypeOf("function");
+      }
+    });
+
+    it("declared authorFeed capability has an implementing getUserFeed method", () => {
+      if (manifest.authorFeed === true) {
+        expect(connector.getUserFeed, "manifest.authorFeed declared but getUserFeed() missing").toBeTypeOf(
+          "function",
+        );
+      }
+    });
+
+    it("search is only callable when declared: absent otherwise", () => {
+      if (manifest.search !== true) {
+        expect(connector.search, "search() present but manifest.search not declared").toBeUndefined();
+      }
+    });
+
+    it("getUserFeed is only callable when declared: absent otherwise", () => {
+      if (manifest.authorFeed !== true) {
+        expect(connector.getUserFeed, "getUserFeed() present but manifest.authorFeed not declared").toBeUndefined();
+      }
+    });
+
+    it("returns FeedItem pages from search() with a keyless (null) connection", async () => {
+      if (manifest.search !== true) return;
+      const page = await connector.search?.(null, { query: { text: "acampada26", kind: "keyword" }, limit: 20 });
+      expect(page).toBeDefined();
+      expect(Array.isArray(page?.items)).toBe(true);
+      for (const item of page?.items ?? []) {
+        expect(item.provider).toBe(manifest.id);
+        expect(item.remoteId).toBeTruthy();
+        expect(item.authorHandle).toBeTruthy();
+      }
+    });
+
+    it("returns FeedItem pages from getUserFeed() with a keyless (null) connection", async () => {
+      if (manifest.authorFeed !== true) return;
+      const page = await connector.getUserFeed?.(null, { account: { handle: "@someone@instance.test" }, limit: 20 });
+      expect(page).toBeDefined();
+      expect(Array.isArray(page?.items)).toBe(true);
+      for (const item of page?.items ?? []) {
+        expect(item.provider).toBe(manifest.id);
+        expect(item.remoteId).toBeTruthy();
+      }
+    });
+
+    it("streams-column flags surface in capability strings", () => {
+      const strings = manifestCapabilityStrings(manifest);
+      if (manifest.search === true) expect(strings).toContain("search");
+      else expect(strings).not.toContain("search");
+      if (manifest.authorFeed === true) expect(strings).toContain("authorFeed");
+      else expect(strings).not.toContain("authorFeed");
+    });
+  });
+}
+
+export function videoConnectorContractTests(connector: PlatformConnector, harness: ContractHarness): void {
+  const manifest = connector.manifest();
+  if (manifest.capabilities.publishVideo !== true) return;
+
+  describe(`video contract: ${manifest.id}`, () => {
+    it("uploadVideo returns a remote id", async () => {
+      const result = await connector.uploadVideo?.(harness.connection, {
+        videoAssetId: "asset-1",
+        visibility: "provider_default",
+        formatIntent: "provider_default",
+        providerMetadata: {},
+      });
+      expect(result?.remoteId).toBeTruthy();
+    });
+
+    it("getVideoStatus reaches a terminal state", async () => {
+      const upload = await connector.uploadVideo?.(harness.connection, {
+        videoAssetId: "asset-2",
+        visibility: "provider_default",
+        formatIntent: "provider_default",
+        providerMetadata: {},
+      });
+      if (upload === undefined) return;
+      const status = await connector.getVideoStatus?.(harness.connection, upload.remoteId);
+      expect(["uploading", "processing", "ready", "failed"]).toContain(status?.state);
+    });
+  });
+}
+
+export function livestreamConnectorContractTests(
+  connector: PlatformConnector,
+  harness: ContractHarness,
+): void {
+  const manifest = connector.manifest();
+  if (manifest.capabilities.createLivestream !== true) return;
+
+  describe(`livestream contract: ${manifest.id}`, () => {
+    it("createLiveStream produces a stream key reference, never a raw key", async () => {
+      const stream = await connector.createLiveStream?.(harness.connection, {
+        channelId: "channel-1",
+        title: "contract test",
+        permanent: false,
+        saveReplay: false,
+      });
+      expect(stream?.remoteId).toBeTruthy();
+      if (stream?.streamKeyRef) {
+        expect(stream.streamKeyRef.kind).toBe("credential-ref");
+        expect(JSON.stringify(stream)).not.toMatch(/[a-z0-9]{20,}/i);
+      }
+    });
+
+    it("playback sources are absolute URLs", async () => {
+      const stream = await connector.createLiveStream?.(harness.connection, {
+        channelId: "channel-1",
+        title: "contract test 2",
+        permanent: false,
+        saveReplay: false,
+      });
+      if (stream === undefined) return;
+      const sources = await connector.getStreamPlaybackSources?.(harness.connection, {
+        remoteId: stream.remoteId,
+      });
+      for (const source of sources ?? []) {
+        expect(() => new URL(source.url)).not.toThrow();
+      }
+    });
+  });
+}
diff --git a/packages/connector-sdk/src/types.ts b/packages/connector-sdk/src/types.ts
new file mode 100644
index 0000000..acdc446
--- /dev/null
+++ b/packages/connector-sdk/src/types.ts
@@ -0,0 +1,233 @@
+import type {
+  Comment,
+  ConnectorConnection,
+  CredentialRef,
+  DirectMessage,
+  FeedItem,
+  LiveChatMessage,
+  LiveSourceResolution,
+  LiveStream,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  NormalizedVideoPublication,
+  NormalizedWebhookEvent,
+  Page,
+  Publication,
+  RemoteMedia,
+  RemoteVideoChannel,
+  StreamPlaybackSource,
+  VideoProcessingStatus,
+} from "@tactical-media-broadcast-hub/core";
+import type { ConnectorManifest } from "./manifest.js";
+
+export interface AuthorizationRequest {
+  /** Redirect back to the UI after the provider consent round-trip. */
+  redirectUri: string;
+  workspaceId: string;
+  state: string;
+  connectionId?: string;
+  fields?: Record<string, string>;
+  codeVerifier?: string;
+}
+
+export interface AuthorizationRedirect {
+  authorizationUrl: string;
+  connection: ConnectorConnection;
+}
+
+export interface CodeExchangeRequest extends AuthorizationRequest {
+  code: string;
+}
+
+/**
+ * Query for streams-column keyword search (WP3 §1.1 `keyword`/`saved_search`).
+ * The connector adapts it to its provider surface: `keyword` → full-text or
+ * video search, `hashtag` → the hashtag timeline where that is all the
+ * provider offers (e.g. Mastodon). Non-tag queries on such providers are
+ * reported unsupported by the caller, never invented as errors here.
+ */
+export interface SearchQuery {
+  text: string;
+  kind?: "keyword" | "hashtag";
+}
+
+/** Request shape for {@link PlatformConnector.search}. */
+export interface SearchRequest {
+  query: SearchQuery;
+  cursor?: string;
+  limit: number;
+}
+
+/**
+ * A remote author for author-timeline columns (`account_list`). Exactly one of
+ * `handle` / `externalId` is usually provided; connectors resolve what their
+ * provider needs (e.g. `@user@instance.social` → account id).
+ */
+export interface AccountRef {
+  handle?: string;
+  externalId?: string;
+}
+
+/** Request shape for {@link PlatformConnector.getUserFeed}. */
+export interface GetUserFeedRequest {
+  account: AccountRef;
+  cursor?: string;
+  limit: number;
+}
+
+export interface AuthorizationResult {
+  connection: ConnectorConnection;
+  identity: NormalizedIdentity;
+}
+
+export interface PlatformConnector {
+  manifest(): ConnectorManifest;
+
+  authorize(input: AuthorizationRequest): Promise<AuthorizationResult>;
+  buildAuthorizationUrl?(input: AuthorizationRequest): Promise<AuthorizationRedirect>;
+  exchangeCode?(input: CodeExchangeRequest): Promise<AuthorizationResult>;
+  validateToken?(input: { workspaceId: string; connectionId: string; token: string; fields: Record<string, string> }): Promise<AuthorizationResult>;
+
+  refreshCredentials?(connection: ConnectorConnection): Promise<CredentialRef>;
+
+  revokeCredentials?(connection: ConnectorConnection): Promise<void>;
+
+  getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity>;
+
+  publish?(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication>;
+
+  deletePublication?(connection: ConnectorConnection, remoteId: string): Promise<void>;
+
+  uploadMedia?(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia>;
+
+  uploadVideo?(
+    connection: ConnectorConnection,
+    video: NormalizedVideoPublication,
+  ): Promise<{ remoteId: string }>;
+
+  getVideoStatus?(
+    connection: ConnectorConnection,
+    remoteId: string,
+  ): Promise<VideoProcessingStatus>;
+
+  getVideos?(
+    connection: ConnectorConnection,
+    request: { cursor?: string; limit: number },
+  ): Promise<Page<{ remoteId: string; title?: string; createdAt?: Date }>>;
+
+  getFeed?(
+    connection: ConnectorConnection,
+    request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+  ): Promise<Page<FeedItem>>;
+
+  /**
+   * Keyword/hashtag discovery for streams columns (WP3 §2.2). `connection` is
+   * null for keyless sources (public Bluesky, Mastodon public/RSS, YouTube
+   * RSS) — implementations must not require credentials, or must refuse null
+   * with a ConnectorError. Declared by `manifest.search`; when the flag is not
+   * declared the method must be absent (contract-tested).
+   */
+  search?(
+    connection: ConnectorConnection | null,
+    request: SearchRequest,
+  ): Promise<Page<FeedItem>>;
+
+  /**
+   * Author timeline for account-list columns (WP3 §2.2). Same `connection |
+   * null` keyless contract as {@link PlatformConnector.search}. Declared by
+   * `manifest.authorFeed`; absent otherwise.
+   */
+  getUserFeed?(
+    connection: ConnectorConnection | null,
+    request: GetUserFeedRequest,
+  ): Promise<Page<FeedItem>>;
+
+  getComments?(
+    connection: ConnectorConnection,
+    request: { onRemoteId: string; cursor?: string; limit: number },
+  ): Promise<Page<Comment>>;
+
+  getMessages?(
+    connection: ConnectorConnection,
+    request: { conversationRemoteId?: string; cursor?: string; limit: number },
+  ): Promise<Page<DirectMessage>>;
+
+  reply?(
+    connection: ConnectorConnection,
+    request: { onRemoteId: string; text: string },
+  ): Promise<Publication>;
+
+  amplify?(
+    connection: ConnectorConnection,
+    request: {
+      kind: "repost" | "quote" | "share";
+      targetRemoteId: string;
+      commentary?: string;
+      quoteAssetIds?: string[];
+    },
+  ): Promise<Publication>;
+
+  unamplify?(connection: ConnectorConnection, remoteId: string): Promise<void>;
+
+  getRemoteVideoChannels?(connection: ConnectorConnection): Promise<RemoteVideoChannel[]>;
+
+  createLiveStream?(
+    connection: ConnectorConnection,
+    request: { channelId: string; title: string; permanent: boolean; saveReplay: boolean },
+  ): Promise<LiveStream>;
+
+  updateLiveStream?(
+    connection: ConnectorConnection,
+    request: { remoteId: string; title?: string },
+  ): Promise<LiveStream>;
+
+  getLiveStreams?(
+    connection: ConnectorConnection,
+    request: { cursor?: string; limit: number },
+  ): Promise<Page<LiveStream>>;
+
+  getStreamPlaybackSources?(
+    connection: ConnectorConnection,
+    request: { remoteId: string },
+  ): Promise<StreamPlaybackSource[]>;
+
+  /**
+   * Resolve a channel-level live source to a program-input HLS URL plus a
+   * liveness verdict (WP6 go-live slice). Unlike getStreamPlaybackSources,
+   * which addresses one already-known stream by remoteId, this resolves by
+   * channel identity (channelId or externalUrl) — the input side of the
+   * desired-state take/start path.
+   */
+  resolveLiveSource?(
+    connection: ConnectorConnection,
+    request: { channelId?: string; externalUrl?: string },
+  ): Promise<LiveSourceResolution>;
+
+  getLiveChat?(
+    connection: ConnectorConnection,
+    request: { liveRemoteId: string; cursor?: string; limit: number },
+  ): Promise<Page<LiveChatMessage>>;
+
+  sendLiveChatMessage?(
+    connection: ConnectorConnection,
+    request: { liveRemoteId: string; text: string },
+  ): Promise<LiveChatMessage>;
+
+  moderateLiveChat?(
+    connection: ConnectorConnection,
+    request: { liveRemoteId: string; messageRemoteId: string; action: "delete" | "timeout" | "ban" },
+  ): Promise<void>;
+
+  getAnalytics?(
+    connection: ConnectorConnection,
+    request: { subjectRemoteId?: string; from: Date; to: Date },
+  ): Promise<{ values: Record<string, number>; series: { at: Date; values: Record<string, number> }[] }>;
+
+  subscribeWebhooks?(
+    connection: ConnectorConnection,
+    request: { topics: string[] },
+  ): Promise<{ subscriptionId: string }>;
+
+  handleWebhook?(request: { headers: Record<string, string>; body: unknown }): Promise<NormalizedWebhookEvent>;
+}
diff --git a/packages/connector-sdk/tsconfig.json b/packages/connector-sdk/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-sdk/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-slack/package.json b/packages/connector-slack/package.json
new file mode 100644
index 0000000..c4ef81b
--- /dev/null
+++ b/packages/connector-slack/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-slack",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-slack/src/contract.test.ts b/packages/connector-slack/src/contract.test.ts
new file mode 100644
index 0000000..ebda537
--- /dev/null
+++ b/packages/connector-slack/src/contract.test.ts
@@ -0,0 +1,36 @@
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createSlackConnector } from "./index.js";
+
+const connection: ConnectorConnection = {
+  id: "conn-slack",
+  workspaceId: "ws-1",
+  provider: "slack",
+  channelId: "C0123456789",
+  credentialId: { kind: "credential-ref", id: "cred-slack" },
+  fields: {
+    botToken: "xoxb-test-token",
+    teamId: "T0123456789",
+  },
+  createdAt: new Date(),
+};
+
+const fetchImpl: typeof fetch = async (input, init): Promise<Response> => {
+  const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+  if (url === "https://slack.com/api/auth.test") {
+    if (new Headers(init?.headers).get("authorization") !== "Bearer xoxb-test-token") {
+      return new Response(JSON.stringify({ ok: false, error: "invalid_auth" }));
+    }
+    return new Response(JSON.stringify({
+      ok: true,
+      team: "AnarchoPoster",
+      team_id: "T0123456789",
+      user: "anarchoposter",
+      user_id: "U0123456789",
+      bot_id: "B0123456789",
+    }));
+  }
+  return new Response(JSON.stringify({ ok: false, error: `unexpected request: ${url}` }));
+};
+
+connectorContractTests(createSlackConnector({ fetchImpl }), { connection });
diff --git a/packages/connector-slack/src/index.ts b/packages/connector-slack/src/index.ts
new file mode 100644
index 0000000..e98ef06
--- /dev/null
+++ b/packages/connector-slack/src/index.ts
@@ -0,0 +1,446 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  FeedItem,
+  NormalizedIdentity,
+  NormalizedPost,
+  NormalizedWebhookEvent,
+  Page,
+  Publication,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  RateLimitError,
+  RateLimitedHttpClient,
+  type ConnectorManifest,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "slack";
+const API_BASE = "https://slack.com/api/";
+const SIGNATURE_VERSION = "v0";
+const MAX_WEBHOOK_AGE_SECONDS = 60 * 5;
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  feed: true,
+  comments: true,
+  replies: true,
+  directMessages: false,
+  amplifyRepost: false,
+  webhooks: true,
+};
+
+export interface SlackConnectorOptions {
+  fetchImpl?: typeof fetch;
+}
+
+interface SlackEnvelope {
+  ok: boolean;
+  error?: string;
+  needed?: string;
+  provided?: string;
+}
+
+interface SlackIdentity extends SlackEnvelope {
+  team?: string;
+  team_id?: string;
+  user?: string;
+  user_id?: string;
+  bot_id?: string;
+  url?: string;
+}
+
+interface SlackMessage {
+  type?: string;
+  ts: string;
+  text?: string;
+  user?: string;
+  bot_id?: string;
+  thread_ts?: string;
+  reply_count?: number;
+  reactions?: { count: number }[];
+}
+
+interface SlackPostMessage extends SlackEnvelope {
+  channel?: string;
+  ts?: string;
+  message?: SlackMessage;
+}
+
+interface SlackHistory extends SlackEnvelope {
+  messages?: SlackMessage[];
+  response_metadata?: { next_cursor?: string };
+}
+
+function headerValue(headers: Record<string, string>, name: string): string | undefined {
+  return Object.entries(headers).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1];
+}
+
+function timestampDate(timestamp: string): Date {
+  const seconds = Number(timestamp);
+  return Number.isFinite(seconds) ? new Date(seconds * 1000) : new Date(0);
+}
+
+function parseObject(raw: string): Record<string, unknown> {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (cause) {
+    throw new ConnectorError(`${PROVIDER}: webhook body is not JSON`, PROVIDER, cause);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new ConnectorError(`${PROVIDER}: malformed webhook payload`, PROVIDER);
+  }
+  return parsed as Record<string, unknown>;
+}
+
+export function createSlackConnector(options: SlackConnectorOptions = {}): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: 1,
+    fetchImpl: options.fetchImpl,
+  });
+  const signingSecrets = new Map<string, string>();
+  let publicationSequence = 0;
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Slack",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "botToken",
+        label: "Bot token",
+        required: true,
+        secret: true,
+        pattern: "^xoxb-",
+        placeholder: "xoxb-…",
+      },
+      {
+        name: "teamId",
+        label: "Workspace ID",
+        required: true,
+        secret: false,
+        pattern: "^[A-Z0-9]+$",
+      },
+    ],
+    oauth: { kind: "token" },
+    webhookRoute: "/webhooks/slack",
+    docsUrl: "https://api.slack.com/",
+  };
+
+  function tokenOf(connection: ConnectorConnection): string {
+    const token = connection.fields["botToken"];
+    if (token === undefined || token.trim().length === 0) {
+      throw new AuthError(`${PROVIDER}: missing botToken connection field`, PROVIDER, false);
+    }
+    return token;
+  }
+
+  function teamOf(connection: ConnectorConnection): string {
+    const teamId = connection.fields["teamId"];
+    if (teamId === undefined || teamId.trim().length === 0) {
+      throw new ConnectorError(`${PROVIDER}: missing teamId connection field`, PROVIDER);
+    }
+    return teamId;
+  }
+
+  function channelOf(connection: ConnectorConnection): string {
+    const channelId = connection.channelId || connection.fields["channelId"];
+    if (channelId === undefined || channelId.trim().length === 0) {
+      throw new ConnectorError(`${PROVIDER}: connection has no channelId`, PROVIDER);
+    }
+    return channelId;
+  }
+
+  async function api<T extends SlackEnvelope>(
+    connection: ConnectorConnection,
+    method: string,
+    init: RequestInit = {},
+    query?: URLSearchParams,
+  ): Promise<T> {
+    const suffix = query === undefined ? "" : `?${query}`;
+    const response = await client.request(PROVIDER, `${API_BASE}${method}${suffix}`, {
+      ...init,
+      headers: {
+        accept: "application/json",
+        authorization: `Bearer ${tokenOf(connection)}`,
+        ...init.headers,
+      },
+    });
+    let body: T;
+    try {
+      body = (await response.json()) as T;
+    } catch (cause) {
+      throw new ConnectorError(
+        `${PROVIDER}: non-JSON response from ${method} (HTTP ${response.status})`,
+        PROVIDER,
+        cause,
+      );
+    }
+    if (!response.ok) {
+      throw new ConnectorError(`${PROVIDER}: HTTP ${response.status} from ${method}`, PROVIDER);
+    }
+    if (!body.ok) {
+      const detail = body.error ?? "unknown Slack API error";
+      if (["invalid_auth", "not_authed", "token_revoked", "account_inactive"].includes(detail)) {
+        throw new AuthError(`${PROVIDER}: ${detail}`, PROVIDER, false);
+      }
+      if (detail === "ratelimited") {
+        const retryAfter = Number(response.headers.get("retry-after"));
+        throw new RateLimitError(
+          PROVIDER,
+          Number.isFinite(retryAfter) ? retryAfter * 1000 : undefined,
+        );
+      }
+      throw new ConnectorError(`${PROVIDER}: ${detail}`, PROVIDER);
+    }
+    return body;
+  }
+
+  function jsonPost(body: Record<string, unknown>): RequestInit {
+    return {
+      method: "POST",
+      headers: { "content-type": "application/json; charset=utf-8" },
+      body: JSON.stringify(body),
+    };
+  }
+
+  function publication(
+    connection: ConnectorConnection,
+    timestamp: string,
+    draftId: string,
+    metadata: Record<string, unknown>,
+  ): Publication {
+    return {
+      id: `slack-${(publicationSequence += 1)}-${timestamp}`,
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId: timestamp,
+      publishedAt: timestampDate(timestamp),
+      providerMetadata: metadata,
+    };
+  }
+
+  function feedItem(message: SlackMessage): FeedItem {
+    return {
+      id: message.ts,
+      provider: PROVIDER,
+      remoteId: message.ts,
+      authorHandle: message.user ?? message.bot_id ?? "unknown",
+      text: message.text ?? "",
+      mediaUrls: [],
+      createdAt: timestampDate(message.ts),
+      metrics: {
+        replies: message.reply_count ?? 0,
+        reactions: (message.reactions ?? []).reduce((total, reaction) => total + reaction.count, 0),
+      },
+    };
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new ConnectorError(
+        `${PROVIDER}: bot-token auth only — install a Slack app and connect its xoxb token`,
+        PROVIDER,
+      );
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      const identity = await api<SlackIdentity>(connection, "auth.test");
+      const configuredTeam = teamOf(connection);
+      if (identity.team_id !== undefined && identity.team_id !== configuredTeam) {
+        throw new AuthError(
+          `${PROVIDER}: token belongs to team ${identity.team_id}, not ${configuredTeam}`,
+          PROVIDER,
+          false,
+        );
+      }
+      const remoteId = identity.bot_id ?? identity.user_id;
+      if (remoteId === undefined) {
+        throw new ConnectorError(`${PROVIDER}: auth.test returned no bot or user id`, PROVIDER);
+      }
+      return {
+        provider: PROVIDER,
+        remoteId,
+        handle: identity.user ?? remoteId,
+        displayName: identity.team,
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const channel = channelOf(connection);
+      const blocks = Array.isArray(post.providerMetadata["blocks"])
+        ? post.providerMetadata["blocks"]
+        : [];
+      const result = await api<SlackPostMessage>(
+        connection,
+        "chat.postMessage",
+        jsonPost({ channel, text: post.text, blocks }),
+      );
+      const timestamp = result.ts ?? result.message?.ts;
+      if (timestamp === undefined) {
+        throw new ConnectorError(`${PROVIDER}: chat.postMessage returned no timestamp`, PROVIDER);
+      }
+      return publication(connection, timestamp, "direct", {
+        channel: result.channel ?? channel,
+        ...post.providerMetadata,
+      });
+    },
+
+    async getFeed(
+      connection: ConnectorConnection,
+      request: { kind: "home" | "mentions" | "search"; query?: string; cursor?: string; limit: number },
+    ): Promise<Page<FeedItem>> {
+      if (request.kind !== "home") {
+        throw new CapabilityNotSupportedError(PROVIDER, `feed:${request.kind}`);
+      }
+      const query = new URLSearchParams({
+        channel: channelOf(connection),
+        limit: String(Math.max(1, Math.min(100, request.limit))),
+      });
+      if (request.cursor !== undefined) query.set("cursor", request.cursor);
+      const result = await api<SlackHistory>(connection, "conversations.history", {}, query);
+      const cursor = result.response_metadata?.next_cursor;
+      return {
+        items: (result.messages ?? []).map(feedItem),
+        nextCursor: cursor === undefined || cursor.length === 0 ? undefined : cursor,
+      };
+    },
+
+    async getComments(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const query = new URLSearchParams({
+        channel: channelOf(connection),
+        ts: request.onRemoteId,
+        limit: String(Math.max(1, Math.min(100, request.limit))),
+      });
+      if (request.cursor !== undefined) query.set("cursor", request.cursor);
+      const result = await api<SlackHistory>(connection, "conversations.replies", {}, query);
+      const messages = (result.messages ?? []).filter((message) => message.ts !== request.onRemoteId);
+      const cursor = result.response_metadata?.next_cursor;
+      return {
+        items: messages.map((message) => ({
+          id: message.ts,
+          provider: PROVIDER,
+          remoteId: message.ts,
+          onRemoteId: request.onRemoteId,
+          authorHandle: message.user ?? message.bot_id ?? "unknown",
+          text: message.text ?? "",
+          createdAt: timestampDate(message.ts),
+        })),
+        nextCursor: cursor === undefined || cursor.length === 0 ? undefined : cursor,
+      };
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      const channel = channelOf(connection);
+      const result = await api<SlackPostMessage>(
+        connection,
+        "chat.postMessage",
+        jsonPost({ channel, text: request.text, thread_ts: request.onRemoteId }),
+      );
+      const timestamp = result.ts ?? result.message?.ts;
+      if (timestamp === undefined) {
+        throw new ConnectorError(`${PROVIDER}: threaded chat.postMessage returned no timestamp`, PROVIDER);
+      }
+      return publication(connection, timestamp, "reply", {
+        channel: result.channel ?? channel,
+        threadTs: request.onRemoteId,
+      });
+    },
+
+    async subscribeWebhooks(
+      connection: ConnectorConnection,
+      request: { topics: string[] },
+    ): Promise<{ subscriptionId: string }> {
+      const teamId = teamOf(connection);
+      const signingSecret = connection.fields["signingSecret"] ?? process.env["SLACK_SIGNING_SECRET"];
+      if (signingSecret === undefined || signingSecret.length === 0) {
+        throw new ConnectorError(
+          `${PROVIDER}: a signingSecret field or SLACK_SIGNING_SECRET is required for Events API verification`,
+          PROVIDER,
+        );
+      }
+      signingSecrets.set(teamId, signingSecret);
+      const topics = request.topics.length === 0 ? "events" : [...request.topics].sort().join(",");
+      return { subscriptionId: `slack-events:${teamId}:${topics}` };
+    },
+
+    async handleWebhook(request: {
+      headers: Record<string, string>;
+      body: unknown;
+    }): Promise<NormalizedWebhookEvent> {
+      if (typeof request.body !== "string" && !(request.body instanceof Uint8Array)) {
+        throw new ConnectorError(
+          `${PROVIDER}: handleWebhook needs the raw body (string or bytes)`,
+          PROVIDER,
+        );
+      }
+      const raw = typeof request.body === "string"
+        ? request.body
+        : Buffer.from(request.body).toString("utf8");
+      const timestamp = headerValue(request.headers, "x-slack-request-timestamp");
+      const signature = headerValue(request.headers, "x-slack-signature");
+      if (timestamp === undefined || signature === undefined) {
+        throw new AuthError(`${PROVIDER}: missing webhook signature headers`, PROVIDER, false);
+      }
+      const timestampSeconds = Number(timestamp);
+      if (
+        !Number.isFinite(timestampSeconds)
+        || Math.abs(Math.floor(Date.now() / 1000) - timestampSeconds) > MAX_WEBHOOK_AGE_SECONDS
+      ) {
+        throw new AuthError(`${PROVIDER}: stale webhook timestamp`, PROVIDER, false);
+      }
+      const payload = parseObject(raw);
+      const teamId = typeof payload["team_id"] === "string"
+        ? payload["team_id"]
+        : typeof payload["team"] === "string"
+          ? payload["team"]
+          : undefined;
+      const candidateSecrets = teamId === undefined
+        ? [...signingSecrets.values()]
+        : [signingSecrets.get(teamId)].filter((secret): secret is string => secret !== undefined);
+      const supplied = Buffer.from(signature);
+      const verified = candidateSecrets.some((secret) => {
+        const digest = createHmac("sha256", secret)
+          .update(`${SIGNATURE_VERSION}:${timestamp}:${raw}`)
+          .digest("hex");
+        const expected = Buffer.from(`${SIGNATURE_VERSION}=${digest}`);
+        return supplied.length === expected.length && timingSafeEqual(supplied, expected);
+      });
+      if (!verified) {
+        throw new AuthError(`${PROVIDER}: invalid webhook signature`, PROVIDER, false);
+      }
+      const outerType = typeof payload["type"] === "string" ? payload["type"] : "event";
+      const innerEvent = payload["event"];
+      const innerType = typeof innerEvent === "object" && innerEvent !== null
+        && typeof (innerEvent as Record<string, unknown>)["type"] === "string"
+        ? String((innerEvent as Record<string, unknown>)["type"])
+        : undefined;
+      return {
+        provider: PROVIDER,
+        eventType: outerType === "event_callback" && innerType !== undefined ? innerType : outerType,
+        connectionKey: teamId,
+        payload,
+        receivedAt: new Date(),
+      };
+    },
+  };
+}
diff --git a/packages/connector-slack/tsconfig.json b/packages/connector-slack/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-slack/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-telegram/package.json b/packages/connector-telegram/package.json
new file mode 100644
index 0000000..7312953
--- /dev/null
+++ b/packages/connector-telegram/package.json
@@ -0,0 +1,23 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-telegram",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-telegram/src/contract.test.ts b/packages/connector-telegram/src/contract.test.ts
new file mode 100644
index 0000000..ae4a735
--- /dev/null
+++ b/packages/connector-telegram/src/contract.test.ts
@@ -0,0 +1,609 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, MediaAsset } from "@tactical-media-broadcast-hub/core";
+import { ConnectorError } from "@tactical-media-broadcast-hub/connector-sdk";
+import { connectorContractTests } from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createTelegramConnector } from "./index.js";
+
+/**
+ * Stubbed Telegram Bot API: one in-memory channel + bot identity per test
+ * instance. The contract tests exercise real request/response shapes.
+ */
+interface StubMessage {
+  id: number;
+  chatId: string;
+  method: string;
+  caption?: string;
+}
+
+interface StubState {
+  calls: { url: string; init: RequestInit | undefined }[];
+  messages: StubMessage[];
+  webhookSecret?: string;
+}
+
+const TOKEN = "123456789:AAstubbed-token";
+const CHANNEL = "@anarchoposter_channel";
+const CHANNEL_ID = -1001234567890;
+const BOT = { id: 6262947712, is_bot: true, first_name: "AnarchoPoster Bot", username: "anarchoposter_bot" };
+const CHAT = { id: CHANNEL_ID, type: "channel", title: "AnarchoPoster News", username: "anarchoposter_channel" };
+
+const connection: ConnectorConnection = {
+  id: "conn-telegram",
+  workspaceId: "ws-1",
+  provider: "telegram",
+  channelId: CHANNEL,
+  credentialId: { kind: "credential-ref", id: "cred-1" },
+  fields: { botToken: TOKEN, channelId: CHANNEL },
+  createdAt: new Date(),
+};
+
+function apiOk<T>(result: T): Response {
+  return new Response(JSON.stringify({ ok: true, result }), { status: 200 });
+}
+
+function apiErr(
+  description: string,
+  error_code: number,
+  parameters?: { retry_after: number },
+): Response {
+  // The Bot API mirrors error_code in the HTTP status.
+  return new Response(JSON.stringify({ ok: false, description, error_code, parameters }), {
+    status: error_code,
+  });
+}
+
+function jsonBody(init: RequestInit | undefined): Record<string, unknown> {
+  return JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+}
+
+function stubApi(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+    state.calls.push({ url, init });
+    const method = url.split("/").pop() ?? "";
+    const now = Math.floor(Date.now() / 1000);
+
+    switch (method) {
+      case "getMe":
+        return apiOk(BOT);
+      case "getChat":
+        return apiOk(CHAT);
+      case "sendMessage": {
+        const body = jsonBody(init);
+        const text = String(body["text"] ?? "");
+        if (text.includes("rate-limit-me")) {
+          return apiErr("Too Many Requests: retry after 5", 429, { retry_after: 5 });
+        }
+        if (text.length > 4096) return apiErr("Bad Request: message is too long", 400);
+        if (text === "server-error-me") return apiErr("Bad Gateway", 502);
+        if (text === "forbidden-me") return apiErr("Forbidden: bot is not a member of the channel chat", 403);
+        if (text === "revoked-me") return apiErr("Unauthorized", 401);
+        if (text === "drop-response-me") {
+          // Telegram accepted and posted the message; the response is lost.
+          state.messages.push({ id: state.messages.length + 1, chatId: String(body["chat_id"]), method, caption: text });
+          throw new TypeError("fetch failed: socket hang up");
+        }
+        const id = state.messages.length + 1;
+        state.messages.push({ id, chatId: String(body["chat_id"]), method, caption: text });
+        return apiOk({ message_id: id, date: now, chat: CHAT, text });
+      }
+      case "forwardMessage":
+      case "copyMessage": {
+        const body = jsonBody(init);
+        if (String(body["from_chat_id"]).includes("protected")) {
+          return apiErr("Bad Request: message can't be forwarded because it's protected", 400);
+        }
+        const id = state.messages.length + 1;
+        const caption = body["caption"] === undefined ? undefined : String(body["caption"]);
+        state.messages.push({ id, chatId: String(body["chat_id"]), method, caption });
+        if (method === "copyMessage") return apiOk({ message_id: id });
+        return apiOk({ message_id: id, date: now, chat: CHAT, text: caption });
+      }
+      case "deleteMessage": {
+        const body = jsonBody(init);
+        const before = state.messages.length;
+        state.messages = state.messages.filter(
+          (message) => !(message.chatId === String(body["chat_id"]) && message.id === Number(body["message_id"])),
+        );
+        return apiOk(state.messages.length < before);
+      }
+      case "sendPhoto": {
+        const form = init?.body;
+        expect(form).toBeInstanceOf(FormData);
+        const id = state.messages.length + 1;
+        const caption = (form as FormData).get("caption");
+        state.messages.push({
+          id,
+          chatId: String((form as FormData).get("chat_id")),
+          method,
+          caption: caption === null ? undefined : String(caption),
+        });
+        return apiOk({
+          message_id: id,
+          date: now,
+          chat: CHAT,
+          photo: [{ file_id: "AgACAgIAAx0D", file_unique_id: "AQADqr", width: 1280, height: 720 }],
+        });
+      }
+      case "sendMediaGroup": {
+        const form = init?.body;
+        expect(form).toBeInstanceOf(FormData);
+        const media = JSON.parse(String((form as FormData).get("media"))) as {
+          type: string;
+          media: string;
+        }[];
+        const messages = media.map((_, index) => ({
+          message_id: state.messages.length + 1 + index,
+          date: now,
+          chat: CHAT,
+          photo: [{ file_id: `AgACAgIAAx0D${index}`, file_unique_id: `AQAD${index}`, width: 1280, height: 720 }],
+        }));
+        messages.forEach((message) => {
+          state.messages.push({ id: message.message_id, chatId: CHANNEL, method });
+        });
+        return apiOk(messages);
+      }
+      case "getWebhookInfo":
+        return apiOk({ url: "", has_custom_certificate: false, pending_update_count: 2 });
+      case "setWebhook": {
+        const body = jsonBody(init);
+        state.webhookSecret = String(body["secret_token"]);
+        return apiOk(true);
+      }
+      default:
+        return apiErr(`unknown method ${method}`, 404);
+    }
+  };
+}
+
+interface Harness {
+  state: StubState;
+  connector: ReturnType<typeof createTelegramConnector>;
+}
+
+function createHarness(overrides: Partial<Parameters<typeof createTelegramConnector>[0]> = {}): Harness {
+  const state: StubState = { calls: [], messages: [] };
+  const connector = createTelegramConnector({
+    fetchImpl: stubApi(state),
+    requestsPerSecond: 1000,
+    sleep: async () => Promise.resolve(),
+    env: {},
+    webhookPublicUrl: "https://app.example.com/webhooks/telegram",
+    loadAsset: async (assetId) => mediaAsset(assetId),
+    openAsset: async () => ({ bytes: new Uint8Array([137, 80, 78, 71]), filename: "photo.png" }),
+    ...overrides,
+  });
+  return { state, connector };
+}
+
+function mediaAsset(id: string): MediaAsset {
+  return {
+    id,
+    workspaceId: "ws-1",
+    storageKey: `s3://assets/${id}`,
+    mimeType: id.endsWith(".mp4") ? "video/mp4" : "image/png",
+    sizeBytes: 2048,
+    width: 1280,
+    height: 720,
+    createdAt: new Date(),
+  };
+}
+
+const post = (text: string, mediaAssetIds: string[] = []) => ({
+  text,
+  mediaAssetIds,
+  visibility: "public" as const,
+  providerMetadata: {},
+});
+
+connectorContractTests(createHarness().connector, { connection });
+
+describe("telegram connector: identity", () => {
+  it("getIdentity resolves the bot via getMe", async () => {
+    const { state, connector } = createHarness();
+    const identity = await connector.getIdentity(connection);
+    expect(identity.provider).toBe("telegram");
+    expect(identity.remoteId).toBe(String(BOT.id));
+    expect(identity.handle).toBe("@anarchoposter_bot");
+    expect(identity.displayName).toBe("AnarchoPoster Bot");
+    expect(state.calls[0]?.url).toBe(`https://api.telegram.org/bot${TOKEN}/getMe`);
+  });
+
+  it("fails closed when the token is missing or blank", async () => {
+    const blank = { ...connection, fields: { ...connection.fields, botToken: "" } };
+    const absent = { ...connection, fields: { channelId: CHANNEL } };
+    const { connector } = createHarness();
+    await expect(connector.getIdentity(blank)).rejects.toThrow(/missing bot token/);
+    await expect(connector.getIdentity(absent)).rejects.toThrow(/missing bot token/);
+  });
+
+  it("authorize explains there is no OAuth round-trip", async () => {
+    const { connector } = createHarness();
+    await expect(connector.authorize({ redirectUri: "https://x", workspaceId: "ws", state: "s" })).rejects.toThrow(
+      /@BotFather/,
+    );
+  });
+});
+
+describe("telegram connector: publish text", () => {
+  it("sends via sendMessage with HTML parse mode and escaped text", async () => {
+    const { state, connector } = createHarness();
+    const publication = await connector.publish?.(connection, post("Ship <it> & iterate"));
+    const call = state.calls[0];
+    expect(call?.url.endsWith("/sendMessage")).toBe(true);
+    const body = jsonBody(call?.init);
+    expect(body["chat_id"]).toBe(CHANNEL);
+    expect(body["parse_mode"]).toBe("HTML");
+    // Raw < > & are escaped so a post can never inject Telegram markup.
+    expect(body["text"]).toBe("Ship &lt;it&gt; &amp; iterate");
+    expect(publication?.remoteId).toBe("1");
+    expect(publication?.remoteUrl).toBe("https://t.me/anarchoposter_channel/1");
+    expect(publication?.providerMetadata).toMatchObject({ method: "sendMessage", chatId: CHANNEL });
+    expect(publication?.workspaceId).toBe("ws-1");
+    expect(publication?.connectionId).toBe("conn-telegram");
+  });
+
+  it("maps a Telegram 429 to RateLimitError carrying retry_after", async () => {
+    const { connector } = createHarness();
+    await expect(connector.publish?.(connection, post("rate-limit-me"))).rejects.toMatchObject({
+      name: "RateLimitError",
+      retryAfterMs: 5000,
+    });
+  });
+
+  it("sends a 429 exactly once and carries the body retry_after", async () => {
+    const { state, connector } = createHarness();
+    await connector.publish?.(connection, post("rate-limit-me")).catch(() => undefined);
+    expect(state.calls.filter((c) => c.url.endsWith("/sendMessage"))).toHaveLength(1);
+  });
+
+  it("never resends after a 5xx: unknown delivery ProviderServerError", async () => {
+    const { state, connector } = createHarness();
+    await expect(connector.publish?.(connection, post("server-error-me"))).rejects.toMatchObject({
+      name: "ProviderServerError",
+      status: 502,
+      delivery: "unknown",
+    });
+    expect(state.calls.filter((c) => c.url.endsWith("/sendMessage"))).toHaveLength(1);
+  });
+
+  it("an accepted send whose response is lost is one visible message and an unknown-delivery error", async () => {
+    const { state, connector } = createHarness();
+    await expect(connector.publish?.(connection, post("drop-response-me"))).rejects.toMatchObject({
+      name: "ProviderTransportError",
+      delivery: "unknown",
+    });
+    expect(state.calls.filter((c) => c.url.endsWith("/sendMessage"))).toHaveLength(1);
+    expect(state.messages).toHaveLength(1);
+  });
+
+  it("maps 403 to ProviderRejectedError and 401 to AuthError", async () => {
+    const { connector } = createHarness();
+    await expect(connector.publish?.(connection, post("forbidden-me"))).rejects.toMatchObject({
+      name: "ProviderRejectedError",
+      status: 403,
+      delivery: "rejected",
+    });
+    await expect(connector.publish?.(connection, post("revoked-me"))).rejects.toMatchObject({ name: "AuthError" });
+  });
+
+  it("echoes the injected idempotency key; draftId stays a local placeholder", async () => {
+    const { connector } = createHarness();
+    const publication = await connector.publish?.(connection, {
+      ...post("keyed"),
+      providerMetadata: { idempotencyKey: "wp3:ws-1:draft-1:a1:publish", draftId: "draft-1" },
+    });
+    expect(publication?.providerMetadata).toMatchObject({
+      method: "sendMessage",
+      messageId: 1,
+      idempotencyKey: "wp3:ws-1:draft-1:a1:publish",
+    });
+    expect(publication?.draftId).toBe("direct");
+  });
+
+  it("retries the read-only getChat lookup but not the send", async () => {
+    let getChatCalls = 0;
+    const base = createHarness();
+    const stub = stubApi(base.state);
+    const connector = createTelegramConnector({
+      fetchImpl: async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        if (url.endsWith("/getChat") && (getChatCalls += 1) === 1) return apiErr("Internal Server Error", 500);
+        return stub(input, init);
+      },
+      requestsPerSecond: 1000,
+      sleep: async () => Promise.resolve(),
+      env: {},
+    });
+    const numeric = { ...connection, fields: { botToken: TOKEN, channelId: String(CHANNEL_ID) }, channelId: String(CHANNEL_ID) };
+    const publication = await connector.publish?.(numeric, post("hi"));
+    expect(getChatCalls).toBe(2);
+    expect(publication?.remoteUrl).toBe("https://t.me/anarchoposter_channel/1");
+  });
+
+  it("rejects text over 4096 characters before any request", async () => {
+    const { state, connector } = createHarness();
+    await expect(connector.publish?.(connection, post("x".repeat(4097)))).rejects.toThrow(
+      /over the 4096 limit/,
+    );
+    expect(state.calls).toHaveLength(0);
+  });
+
+  it("omits the deep link when the chat has no public username", async () => {
+    const privateConnection: ConnectorConnection = {
+      ...connection,
+      fields: { botToken: TOKEN, channelId: "-1009999999999" },
+      channelId: "-1009999999999",
+    };
+    const noUsername = stubApi({ calls: [], messages: [] });
+    const connector = createTelegramConnector({
+      fetchImpl: async (input, init) => {
+        const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url;
+        // getChat for the private channel: no username field.
+        if (url.endsWith("/getChat")) {
+          return apiOk({ id: -1009999999999, type: "channel", title: "Private" });
+        }
+        return noUsername(input, init);
+      },
+      requestsPerSecond: 1000,
+      sleep: async () => Promise.resolve(),
+      env: {},
+    });
+    const publication = await connector.publish?.(privateConnection, post("internal note"));
+    expect(publication?.remoteId).toBe("1");
+    expect(publication?.remoteUrl).toBeUndefined();
+  });
+});
+
+describe("telegram connector: publish media", () => {
+  it("publishes a single photo via multipart sendPhoto with the caption", async () => {
+    const { state, connector } = createHarness();
+    const publication = await connector.publish?.(connection, post("chart of the week", ["asset-1"]));
+    const call = state.calls.find((c) => c.url.endsWith("/sendPhoto"));
+    expect(call).toBeDefined();
+    const form = call?.init?.body as FormData;
+    expect(form.get("chat_id")).toBe(CHANNEL);
+    expect(form.get("caption")).toBe("chart of the week");
+    expect(form.get("parse_mode")).toBe("HTML");
+    expect(form.get("photo")).toBeInstanceOf(Blob);
+    expect(publication?.providerMetadata).toMatchObject({
+      method: "sendPhoto",
+      mediaAssetIds: ["asset-1"],
+    });
+  });
+
+  it("publishes multiple photos as a media group, caption on the first item", async () => {
+    const { state, connector } = createHarness();
+    const publication = await connector.publish?.(
+      connection,
+      post("album", ["asset-1", "asset-2", "asset-3"]),
+    );
+    const call = state.calls.find((c) => c.url.endsWith("/sendMediaGroup"));
+    expect(call).toBeDefined();
+    const form = call?.init?.body as FormData;
+    const media = JSON.parse(String(form.get("media"))) as {
+      type: string;
+      media: string;
+      caption?: string;
+      parse_mode?: string;
+    }[];
+    expect(media).toHaveLength(3);
+    expect(media.every((item) => item.type === "photo")).toBe(true);
+    expect(media.map((item) => item.media)).toEqual(["attach://file0", "attach://file1", "attach://file2"]);
+    expect(media[0]?.caption).toBe("album");
+    expect(media[0]?.parse_mode).toBe("HTML");
+    expect(media[1]?.caption).toBeUndefined();
+    expect(form.get("file0")).toBeInstanceOf(Blob);
+    expect(publication?.providerMetadata.messageIds).toHaveLength(3);
+    expect(publication?.remoteUrl).toBe("https://t.me/anarchoposter_channel/1");
+  });
+
+  it("rejects captions over 1024 characters", async () => {
+    const { connector } = createHarness();
+    await expect(connector.publish?.(connection, post("x".repeat(1025), ["asset-1"]))).rejects.toThrow(
+      /over the 1024 limit/,
+    );
+  });
+
+  it("refuses non-image media — publishVideo is not a Telegram capability", async () => {
+    const { connector } = createHarness();
+    await expect(connector.publish?.(connection, post("clip", ["clip.mp4"]))).rejects.toThrow(
+      /publishVideo is not a Telegram capability/,
+    );
+  });
+
+  it("refuses media publishing when no asset loader is configured", async () => {
+    const { connector } = createHarness({ loadAsset: undefined, openAsset: undefined });
+    await expect(connector.publish?.(connection, post("photo", ["asset-1"]))).rejects.toThrow(/loadAsset/);
+  });
+});
+
+describe("telegram connector: uploadMedia", () => {
+  it("returns the file_id from sendPhoto with dimensions", async () => {
+    const { state, connector } = createHarness();
+    const remote = await connector.uploadMedia?.(connection, mediaAsset("asset-9"));
+    expect(remote?.remoteId).toBe("AgACAgIAAx0D");
+    expect(remote?.mimeType).toBe("image/png");
+    expect(remote?.width).toBe(1280);
+    expect(remote?.height).toBe(720);
+    expect(remote?.url).toBeUndefined(); // file bytes need the bot token → no url
+    expect(state.calls.some((c) => c.url.endsWith("/sendPhoto"))).toBe(true);
+  });
+
+  it("refuses non-image uploads", async () => {
+    const { connector } = createHarness();
+    await expect(connector.uploadMedia?.(connection, mediaAsset("clip.mp4"))).rejects.toThrow(
+      /images only/,
+    );
+  });
+});
+
+describe("telegram connector: amplify / unamplify", () => {
+  it("forwards a cross-chat message reference via forwardMessage", async () => {
+    const { state, connector } = createHarness();
+    const forwarded = await connector.amplify?.(connection, {
+      kind: "share",
+      targetRemoteId: "-1009876543210:42",
+    });
+    const call = state.calls.find((c) => c.url.endsWith("/forwardMessage"));
+    expect(call).toBeDefined();
+    expect(jsonBody(call?.init)).toEqual({
+      chat_id: CHANNEL,
+      from_chat_id: "-1009876543210",
+      message_id: 42,
+    });
+    expect(forwarded?.providerMetadata).toMatchObject({
+      kind: "share",
+      amplifies: "-1009876543210:42",
+      method: "forwardMessage",
+      fromChatId: "-1009876543210",
+    });
+    expect(forwarded?.draftId).toBe("amplify:share");
+  });
+
+  it("uses copyMessage with a caption when commentary is supplied", async () => {
+    const { state, connector } = createHarness();
+    const shared = await connector.amplify?.(connection, {
+      kind: "share",
+      targetRemoteId: "5",
+      commentary: "worth reading",
+    });
+    const call = state.calls.find((c) => c.url.endsWith("/copyMessage"));
+    expect(call).toBeDefined();
+    expect(jsonBody(call?.init)).toEqual({
+      chat_id: CHANNEL,
+      from_chat_id: CHANNEL,
+      message_id: 5,
+      caption: "worth reading",
+      parse_mode: "HTML",
+    });
+    expect(shared?.providerMetadata.method).toBe("copyMessage");
+    expect(shared?.publishedAt).toBeInstanceOf(Date);
+  });
+
+  it("surfaces protected content as a ConnectorError, not a silent no-op", async () => {
+    const { connector } = createHarness();
+    await expect(
+      connector.amplify?.(connection, { kind: "share", targetRemoteId: "@protected_channel:9" }),
+    ).rejects.toBeInstanceOf(ConnectorError);
+  });
+
+  it("rejects amplification kinds Telegram does not have", async () => {
+    const { connector } = createHarness();
+    await expect(connector.amplify?.(connection, { kind: "repost", targetRemoteId: "1" })).rejects.toThrow(
+      /forwarding only/,
+    );
+    await expect(connector.amplify?.(connection, { kind: "quote", targetRemoteId: "1" })).rejects.toThrow(
+      /forwarding only/,
+    );
+  });
+
+  it("unamplify and deletePublication both call deleteMessage", async () => {
+    const { state, connector } = createHarness();
+    await connector.unamplify?.(connection, "3");
+    await connector.deletePublication?.(connection, "-1009876543210:3");
+    const calls = state.calls.filter((c) => c.url.endsWith("/deleteMessage"));
+    expect(calls).toHaveLength(2);
+    expect(jsonBody(calls[0]?.init)).toEqual({ chat_id: CHANNEL, message_id: 3 });
+    expect(jsonBody(calls[1]?.init)).toEqual({ chat_id: "-1009876543210", message_id: 3 });
+  });
+
+  it("rejects malformed remote references", async () => {
+    const { connector } = createHarness();
+    await expect(connector.unamplify?.(connection, "not-a-number")).rejects.toThrow(/not a message id/);
+    await expect(connector.unamplify?.(connection, ":7")).rejects.toThrow(/malformed reference/);
+  });
+});
+
+describe("telegram connector: webhooks", () => {
+  it("subscribes via setWebhook with a generated secret", async () => {
+    const { state, connector } = createHarness();
+    const subscription = await connector.subscribeWebhooks?.(connection, { topics: [] });
+    const call = state.calls.find((c) => c.url.endsWith("/setWebhook"));
+    expect(call).toBeDefined();
+    const body = jsonBody(call?.init);
+    expect(body["url"]).toBe("https://app.example.com/webhooks/telegram");
+    expect(String(body["secret_token"])).toMatch(/^[0-9a-f]{64}$/);
+    // getWebhookInfo reported 2 pending updates → dropped, never replayed.
+    expect(body["drop_pending_updates"]).toBe(true);
+    expect(body["allowed_updates"]).toBeUndefined();
+    expect(subscription?.subscriptionId).toBe("telegram-webhook:conn-telegram");
+  });
+
+  it("forwards requested topics as allowed_updates", async () => {
+    const { state, connector } = createHarness();
+    await connector.subscribeWebhooks?.(connection, { topics: ["channel_post", "message"] });
+    const call = state.calls.find((c) => c.url.endsWith("/setWebhook"));
+    expect(jsonBody(call?.init)["allowed_updates"]).toEqual(["channel_post", "message"]);
+  });
+
+  it("prefers TELEGRAM_WEBHOOK_SECRET from the environment", async () => {
+    const state: StubState = { calls: [], messages: [] };
+    const connector = createTelegramConnector({
+      fetchImpl: stubApi(state),
+      requestsPerSecond: 1000,
+      sleep: async () => Promise.resolve(),
+      env: { TELEGRAM_WEBHOOK_SECRET: "env-secret-token" },
+      webhookPublicUrl: "https://app.example.com/webhooks/telegram",
+    });
+    await connector.subscribeWebhooks?.(connection, { topics: [] });
+    const call = state.calls.find((c) => c.url.endsWith("/setWebhook"));
+    expect(jsonBody(call?.init)["secret_token"]).toBe("env-secret-token");
+  });
+
+  it("requires a public webhook url before subscribing", async () => {
+    const { connector } = createHarness({ webhookPublicUrl: undefined, env: {} });
+    await expect(connector.subscribeWebhooks?.(connection, { topics: [] })).rejects.toThrow(
+      /TELEGRAM_WEBHOOK_URL/,
+    );
+  });
+
+  it("accepts a signed channel post and normalizes the update", async () => {
+    const { state, connector } = createHarness();
+    await connector.subscribeWebhooks?.(connection, { topics: [] });
+    const secret = state.webhookSecret;
+    expect(secret).toBeDefined();
+    const event = await connector.handleWebhook?.({
+      headers: { "X-Telegram-Bot-Api-Secret-Token": secret ?? "" },
+      body: {
+        update_id: 712,
+        channel_post: { message_id: 12, chat: CHAT, text: "hi" },
+      },
+    });
+    expect(event?.provider).toBe("telegram");
+    expect(event?.eventType).toBe("channel_post");
+    expect(event?.connectionKey).toBe("conn-telegram");
+    expect(event?.payload["update_id"]).toBe(712);
+    expect(event?.receivedAt).toBeInstanceOf(Date);
+  });
+
+  it("rejects unsigned webhooks", async () => {
+    const { connector } = createHarness({ env: { TELEGRAM_WEBHOOK_SECRET: "s3cret" } });
+    await expect(
+      connector.handleWebhook?.({
+        headers: {},
+        body: { update_id: 1, message: { message_id: 1, chat: { id: 1, type: "private" }, text: "x" } },
+      }),
+    ).rejects.toThrow(/secret/);
+  });
+
+  it("rejects a mismatched secret", async () => {
+    const { connector } = createHarness({ env: { TELEGRAM_WEBHOOK_SECRET: "s3cret" } });
+    await expect(
+      connector.handleWebhook?.({
+        headers: { "x-telegram-bot-api-secret-token": "not-the-secret" },
+        body: { update_id: 1, message: { message_id: 1, chat: { id: 1, type: "private" }, text: "x" } },
+      }),
+    ).rejects.toThrow(/mismatch/);
+  });
+
+  it("rejects a body that is not a Telegram Update", async () => {
+    const { connector } = createHarness({ env: { TELEGRAM_WEBHOOK_SECRET: "s3cret" } });
+    await expect(
+      connector.handleWebhook?.({
+        headers: { "x-telegram-bot-api-secret-token": "s3cret" },
+        body: { nope: true },
+      }),
+    ).rejects.toThrow(/malformed webhook/);
+  });
+});
diff --git a/packages/connector-telegram/src/index.ts b/packages/connector-telegram/src/index.ts
new file mode 100644
index 0000000..3861149
--- /dev/null
+++ b/packages/connector-telegram/src/index.ts
@@ -0,0 +1,731 @@
+/**
+ * Telegram connector — Bot API via a @BotFather bot token.
+ *
+ * Auth: no OAuth. A connection is a bot token (secret field `botToken`) plus
+ * the target channel chat id (field `channelId`, numeric id or @username).
+ * Liveness check is GET /bot<token>/getMe.
+ *
+ * Honest capability limits (verified against the Bot API):
+ * - Bots cannot back-read channel history → `feed` is false; getUpdates only
+ *   sees updates that arrive after the bot was added, so we never fake a feed.
+ * - Channel-post comment threads are not reachable through the Bot API →
+ *   `comments` is false.
+ * - Bots cannot read arbitrary DM conversations → `directMessages` is false.
+ * - sendVideo exists, but Telegram exposes no upload/processing lifecycle a
+ *   connector could poll, so `publishVideo` stays false rather than reporting
+ *   a fake state machine. Photos are supported (publishImages) via
+ *   sendPhoto/sendMediaGroup.
+ * - Amplification maps to forwarding: `amplifyShare` = forwardMessage, or
+ *   copyMessage when commentary is supplied (a forward cannot carry a caption).
+ *   has_protected_content surfaces as a ConnectorError, never a silent no-op.
+ * - Webhooks: setWebhook with a secret_token; handleWebhook verifies the
+ *   X-Telegram-Bot-Api-Secret-Token header before trusting the payload.
+ *
+ * Rate limits: ~30 messages/s globally, ~20/min per group. We run the SDK's
+ * RateLimitedHttpClient at 1 request/s by default — well inside both bounds.
+ *
+ * Delivery safety: Bot API send methods take no idempotency key and offer no
+ * lookup, so a send is never resent automatically. 429 surfaces as
+ * RateLimitError (retry_after from the body), other refusals as
+ * ProviderRejectedError, 5xx/transport loss as unknown-delivery SDK errors.
+ * An injected providerMetadata.idempotencyKey is echoed into the returned
+ * Publication for receipt correlation only. The Publication's id and
+ * draftId ("direct") are local placeholders, never authoritative.
+ */
+import { randomBytes } from "node:crypto";
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  MediaAsset,
+  NormalizedIdentity,
+  NormalizedPost,
+  NormalizedWebhookEvent,
+  Publication,
+  RemoteMedia,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  ConnectorError,
+  InMemoryCredentials,
+  ProviderRejectedError,
+  RateLimitError,
+  RateLimitedHttpClient,
+  type HttpRequestOptions,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "telegram";
+const API_BASE = "https://api.telegram.org";
+const TEXT_LIMIT = 4096;
+const CAPTION_LIMIT = 1024;
+const WEBHOOK_SECRET_HEADER = "x-telegram-bot-api-secret-token";
+const WEBHOOK_SECRET_KEY = "telegramWebhookSecret";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  publishVideo: false,
+  feed: false,
+  directMessages: false,
+  comments: false,
+  amplifyShare: true,
+  webhooks: true,
+  deletePublication: true,
+};
+
+export interface TelegramConnectorOptions {
+  /** fetch override for tests (same pattern as the other connectors). */
+  fetchImpl?: typeof fetch;
+  /**
+   * Requests per second handed to the rate limiter. Default 1 — Telegram
+   * allows ~30 msg/s globally and ~20/min per group, so 1/s is safe for
+   * publishing. Tests raise this to run unthrottled.
+   */
+  requestsPerSecond?: number;
+  /** Sleep override for the rate limiter (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Secret store. Default: in-memory (dev + contract tests). */
+  credentials?: CredentialAccessor;
+  /** Environment read for TELEGRAM_WEBHOOK_SECRET / TELEGRAM_WEBHOOK_URL. */
+  env?: Record<string, string | undefined>;
+  /** Public https base the platform serves webhooks under. */
+  webhookPublicUrl?: string;
+  /** Resolve a media asset id to its metadata (needed by publish with media). */
+  loadAsset?: (assetId: string) => Promise<MediaAsset>;
+  /** Read asset bytes for multipart upload (needed by publish/uploadMedia). */
+  openAsset?: (media: MediaAsset) => Promise<{ bytes: Uint8Array; filename: string }>;
+}
+
+interface TelegramUser {
+  id: number;
+  is_bot: boolean;
+  first_name: string;
+  username?: string;
+}
+
+interface TelegramChat {
+  id: number;
+  type: string;
+  title?: string;
+  username?: string;
+}
+
+interface TelegramPhotoSize {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+}
+
+interface TelegramMessage {
+  message_id: number;
+  date: number;
+  chat: TelegramChat;
+  text?: string;
+  photo?: TelegramPhotoSize[];
+}
+
+/** Typed hand-off for WP15 archive consumers; webhook behavior stays unchanged. */
+export interface TelegramArchiveWebhookUpdate {
+  update_id: number;
+  channel_post?: Record<string, unknown>;
+  edited_channel_post?: Record<string, unknown>;
+  my_chat_member?: Record<string, unknown>;
+}
+
+export function archiveUpdateFromWebhook(event: NormalizedWebhookEvent): TelegramArchiveWebhookUpdate | null {
+  if (event.provider !== PROVIDER || !["channel_post", "edited_channel_post", "my_chat_member"].includes(event.eventType)) return null;
+  const payload = event.payload;
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return null;
+  const update = payload as Record<string, unknown>;
+  if (!Number.isSafeInteger(update["update_id"])) return null;
+  return update as unknown as TelegramArchiveWebhookUpdate;
+}
+
+interface TelegramWebhookInfo {
+  url: string;
+  has_custom_certificate: boolean;
+  pending_update_count: number;
+}
+
+type TelegramResponse<T> =
+  | { ok: true; result: T }
+  | { ok: false; description: string; error_code?: number; parameters?: { retry_after?: number } };
+
+const UPDATE_EVENT_KEYS = [
+  "message",
+  "edited_message",
+  "channel_post",
+  "edited_channel_post",
+  "callback_query",
+  "my_chat_member",
+] as const;
+
+function escapeHtml(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+function jsonPost(payload: Record<string, unknown>): RequestInit {
+  return {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(payload),
+  };
+}
+
+/** Largest photo variant is the source of truth for dimensions/file ids. */
+function largestPhoto(photo: TelegramPhotoSize[]): TelegramPhotoSize | undefined {
+  return photo.reduce<TelegramPhotoSize | undefined>(
+    (best, size) => (best === undefined || size.width > best.width ? size : best),
+    undefined,
+  );
+}
+
+export function createTelegramConnector(options: TelegramConnectorOptions = {}): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: options.requestsPerSecond ?? 1,
+    fetchImpl: options.fetchImpl,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  const env = options.env ?? process.env;
+  /** Generated webhook secrets seen by this instance: secret → connection id. */
+  const webhookSecrets = new Map<string, string>();
+  /** Resolved public usernames per chat target, so deep links cost one getChat. */
+  const chatUsernames = new Map<string, string>();
+  let publicationSeq = 0;
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Telegram",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "botToken",
+        label: "Bot token (@BotFather)",
+        required: true,
+        secret: true,
+        placeholder: "123456789:AA…",
+      },
+      {
+        name: "channelId",
+        label: "Channel chat id or @username",
+        required: true,
+        secret: false,
+        placeholder: "@yourchannel or -1001234567890",
+        pattern: "^@[A-Za-z0-9_]{4,}$|^-?\\d{3,}$",
+      },
+    ],
+    oauth: { kind: "token", targetField: "channelId", connectNote: "Link a bot token from BotFather; select a chat or channel to publish to. Revoke the bot token in BotFather." },
+    webhookRoute: "/webhooks/telegram",
+    docsUrl: "https://core.telegram.org/bots/api",
+  };
+
+  async function botToken(connection: ConnectorConnection): Promise<string> {
+    const field = connection.fields["botToken"];
+    if (field !== undefined && field.length > 0) return field;
+    try {
+      return await credentials.getSecret(connection, "botToken");
+    } catch {
+      throw new AuthError(
+        `${PROVIDER}: missing bot token — set the botToken connection field or vault secret`,
+        PROVIDER,
+        false,
+      );
+    }
+  }
+
+  function chatTarget(connection: ConnectorConnection): string {
+    const field = connection.fields["channelId"];
+    const target = field !== undefined && field.length > 0 ? field : connection.channelId;
+    if (target.length === 0) {
+      throw new ConnectorError(`${PROVIDER}: connection has no channelId`, PROVIDER);
+    }
+    return target;
+  }
+
+  function toError(body: {
+    description: string;
+    error_code?: number;
+    parameters?: { retry_after?: number };
+  }): Error {
+    const code = body.error_code ?? 0;
+    const description = body.description ?? "unknown Telegram error";
+    // 404 = unknown bot token path, 401 = revoked token.
+    if (code === 401 || code === 404 || /unauthorized/i.test(description)) {
+      return new AuthError(`${PROVIDER}: ${description}`, PROVIDER, false);
+    }
+    if (code === 429) {
+      const retryAfter = body.parameters?.retry_after;
+      return new RateLimitError(PROVIDER, retryAfter === undefined ? undefined : retryAfter * 1000);
+    }
+    // The Bot API answered ok:false, so the request was refused, not applied.
+    return new ProviderRejectedError(`${PROVIDER}: ${description}`, PROVIDER, code >= 400 ? code : 400);
+  }
+
+  async function call<T>(
+    token: string,
+    method: string,
+    init: RequestInit = {},
+    requestOptions: HttpRequestOptions = {},
+  ): Promise<T> {
+    const response = await client.request(PROVIDER, `${API_BASE}/bot${token}/${method}`, init, requestOptions);
+    let body: TelegramResponse<T>;
+    try {
+      body = (await response.json()) as TelegramResponse<T>;
+    } catch (cause) {
+      throw new ConnectorError(
+        `${PROVIDER}: non-JSON reply from ${method} (HTTP ${response.status})`,
+        PROVIDER,
+        cause,
+      );
+    }
+    if (!body.ok) throw toError(body);
+    return body.result;
+  }
+
+  /**
+   * Public username of the chat, when it has one — needed for t.me deep links.
+   * Numeric channel ids are resolved once via getChat; private chats have none.
+   */
+  async function resolveChatUsername(token: string, target: string): Promise<string | undefined> {
+    const cached = chatUsernames.get(target);
+    if (cached !== undefined) return cached;
+    if (target.startsWith("@")) {
+      const username = target.slice(1);
+      chatUsernames.set(target, username);
+      return username;
+    }
+    try {
+      // getChat is a read-only POST: safe to retry on 429/5xx.
+      const chat = await call<TelegramChat>(token, "getChat", jsonPost({ chat_id: target }), { retry: true });
+      if (chat.username === undefined) return undefined;
+      chatUsernames.set(target, chat.username);
+      return chat.username;
+    } catch {
+      // Private or inaccessible chat: no deep link, publishing still fine.
+      return undefined;
+    }
+  }
+
+  function toPublication(
+    connection: ConnectorConnection,
+    draftId: string,
+    message: { messageId: number; at: Date },
+    providerMetadata: Record<string, unknown>,
+    username: string | undefined,
+  ): Publication {
+    const remoteId = String(message.messageId);
+    return {
+      id: `tg-${(publicationSeq += 1)}-${remoteId}`,
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId,
+      remoteUrl: username === undefined ? undefined : `https://t.me/${username}/${remoteId}`,
+      publishedAt: message.at,
+      providerMetadata,
+    };
+  }
+
+  /**
+   * `chatId:messageId` references carry the source chat (forwards live in the
+   * destination chat, so bare ids always mean this connection's channel).
+   */
+  function parseTargetReference(
+    connection: ConnectorConnection,
+    remoteId: string,
+  ): { chatId: string; messageId: number } {
+    const separator = remoteId.indexOf(":");
+    if (separator === -1) {
+      const messageId = Number(remoteId);
+      if (!Number.isInteger(messageId)) {
+        throw new ConnectorError(`${PROVIDER}: "${remoteId}" is not a message id`, PROVIDER);
+      }
+      return { chatId: chatTarget(connection), messageId };
+    }
+    const chatId = remoteId.slice(0, separator);
+    const messageId = Number(remoteId.slice(separator + 1));
+    if (chatId.length === 0 || !Number.isInteger(messageId)) {
+      throw new ConnectorError(`${PROVIDER}: malformed reference "${remoteId}"`, PROVIDER);
+    }
+    return { chatId, messageId };
+  }
+
+  function requireAssetLoader(): (assetId: string) => Promise<MediaAsset> {
+    const loader = options.loadAsset;
+    if (loader === undefined) {
+      throw new ConnectorError(
+        `${PROVIDER}: publishing media requires the loadAsset option (asset id → MediaAsset)`,
+        PROVIDER,
+      );
+    }
+    return loader;
+  }
+
+  function requireAssetReader(): (
+    media: MediaAsset,
+  ) => Promise<{ bytes: Uint8Array; filename: string }> {
+    const reader = options.openAsset;
+    if (reader === undefined) {
+      throw new ConnectorError(
+        `${PROVIDER}: media upload requires the openAsset option (asset → bytes)`,
+        PROVIDER,
+      );
+    }
+    return reader;
+  }
+
+  function assertTextLimit(text: string, limit: number, what: string): void {
+    if (text.length > limit) {
+      throw new ConnectorError(
+        `${PROVIDER}: ${what} is ${text.length} characters, over the ${limit} limit`,
+        PROVIDER,
+      );
+    }
+  }
+
+  async function sendPhoto(
+    token: string,
+    target: string,
+    media: MediaAsset,
+    bytes: Uint8Array,
+    filename: string,
+    caption?: string,
+  ): Promise<TelegramMessage> {
+    const form = new FormData();
+    form.append("chat_id", target);
+    const photo = new Blob([bytes], { type: media.mimeType });
+    form.append("photo", photo, filename);
+    if (caption !== undefined && caption.length > 0) {
+      form.append("caption", caption);
+      form.append("parse_mode", "HTML");
+    }
+    return call<TelegramMessage>(token, "sendPhoto", { method: "POST", body: form });
+  }
+
+  async function sendMediaGroup(
+    token: string,
+    target: string,
+    assets: { media: MediaAsset; bytes: Uint8Array; filename: string }[],
+    caption?: string,
+  ): Promise<TelegramMessage[]> {
+    const form = new FormData();
+    form.append("chat_id", target);
+    const inputMedia = assets.map((asset, index) => ({
+      type: "photo",
+      media: `attach://file${index}`,
+      ...(index === 0 && caption !== undefined && caption.length > 0
+        ? { caption, parse_mode: "HTML" }
+        : {}),
+    }));
+    form.append("media", JSON.stringify(inputMedia));
+    assets.forEach((asset, index) => {
+      const file = new Blob([asset.bytes], { type: asset.media.mimeType });
+      form.append(`file${index}`, file, asset.filename);
+    });
+    return call<TelegramMessage[]>(token, "sendMediaGroup", { method: "POST", body: form });
+  }
+
+  async function deleteMessage(connection: ConnectorConnection, remoteId: string): Promise<void> {
+    const token = await botToken(connection);
+    const { chatId, messageId } = parseTargetReference(connection, remoteId);
+    await call<boolean>(token, "deleteMessage", jsonPost({ chat_id: chatId, message_id: messageId }));
+  }
+
+  async function ensureWebhookSecret(
+    connection: ConnectorConnection,
+  ): Promise<{ secret: string; fromEnv: boolean }> {
+    const fromEnv = env["TELEGRAM_WEBHOOK_SECRET"];
+    if (fromEnv !== undefined && fromEnv.length > 0) return { secret: fromEnv, fromEnv: true };
+    const secret = randomBytes(32).toString("hex");
+    await credentials.put(connection, WEBHOOK_SECRET_KEY, secret);
+    return { secret, fromEnv: false };
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new ConnectorError(
+        `${PROVIDER}: bot-token auth only — create a bot with @BotFather and connect its token, no OAuth round-trip`,
+        PROVIDER,
+      );
+    },
+
+    async validateToken(input) {
+      if (!/^\d+:[A-Za-z0-9_-]+$/.test(input.token)) throw new AuthError("Invalid bot token", PROVIDER, false);
+      const me = await call<TelegramUser>(input.token, "getMe");
+      if (!me.is_bot || !Number.isSafeInteger(me.id) || me.id <= 0) throw new AuthError("Invalid bot identity", PROVIDER, false);
+      const connection: ConnectorConnection = {
+        id: input.connectionId, workspaceId: input.workspaceId, provider: PROVIDER,
+        channelId: input.fields.channelId || String(me.id),
+        credentialId: { kind: "credential-ref", id: input.connectionId },
+        fields: { ...(input.fields.channelId ? { channelId: input.fields.channelId } : {}) }, createdAt: new Date(),
+      };
+      await credentials.put(connection, "botToken", input.token);
+      return { connection, identity: {
+        provider: PROVIDER, remoteId: String(me.id), handle: me.username ? `@${me.username}` : me.first_name,
+        displayName: me.first_name,
+      } };
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      const token = await botToken(connection);
+      const me = await call<TelegramUser>(token, "getMe");
+      return {
+        provider: PROVIDER,
+        // The identity is the bot itself; the channel it posts to is the
+        // connection's channelId field.
+        remoteId: String(me.id),
+        handle: me.username === undefined ? me.first_name : `@${me.username}`,
+        displayName: me.first_name,
+      };
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const token = await botToken(connection);
+      const target = chatTarget(connection);
+      const text = escapeHtml(post.text);
+      const idempotencyKey = post.providerMetadata["idempotencyKey"];
+      const receipt = typeof idempotencyKey === "string" && idempotencyKey.length > 0 ? { idempotencyKey } : {};
+
+      if (post.mediaAssetIds.length === 0) {
+        assertTextLimit(text, TEXT_LIMIT, "message text");
+        const message = await call<TelegramMessage>(
+          token,
+          "sendMessage",
+          jsonPost({ chat_id: target, text, parse_mode: "HTML" }),
+        );
+        const username = await resolveChatUsername(token, target);
+        return toPublication(
+          connection,
+          "direct",
+          { messageId: message.message_id, at: new Date(message.date * 1000) },
+          { method: "sendMessage", chatId: target, messageId: message.message_id, ...receipt },
+          username,
+        );
+      }
+
+      const load = requireAssetLoader();
+      const read = requireAssetReader();
+      const assets = await Promise.all(
+        post.mediaAssetIds.map(async (assetId) => {
+          const media = await load(assetId);
+          if (!media.mimeType.startsWith("image/")) {
+            throw new ConnectorError(
+              `${PROVIDER}: media ${assetId} is "${media.mimeType}" — only image publishing is supported (publishVideo is not a Telegram capability)`,
+              PROVIDER,
+            );
+          }
+          const { bytes, filename } = await read(media);
+          return { media, bytes, filename };
+        }),
+      );
+
+      const username = await resolveChatUsername(token, target);
+      if (assets.length === 1) {
+        assertTextLimit(text, CAPTION_LIMIT, "photo caption");
+        const asset = assets[0];
+        if (asset === undefined) throw new ConnectorError(`${PROVIDER}: no media resolved`, PROVIDER);
+        const message = await sendPhoto(token, target, asset.media, asset.bytes, asset.filename, text);
+        return toPublication(
+          connection,
+          "direct",
+          { messageId: message.message_id, at: new Date(message.date * 1000) },
+          {
+            method: "sendPhoto",
+            chatId: target,
+            messageId: message.message_id,
+            mediaAssetIds: post.mediaAssetIds,
+            ...receipt,
+          },
+          username,
+        );
+      }
+
+      assertTextLimit(text, CAPTION_LIMIT, "media group caption");
+      const messages = await sendMediaGroup(token, target, assets, text);
+      const first = messages[0];
+      if (first === undefined) {
+        throw new ConnectorError(`${PROVIDER}: sendMediaGroup returned nothing`, PROVIDER);
+      }
+      return toPublication(
+        connection,
+        "direct",
+        { messageId: first.message_id, at: new Date(first.date * 1000) },
+        {
+          method: "sendMediaGroup",
+          chatId: target,
+          messageId: first.message_id,
+          messageIds: messages.map((message) => message.message_id),
+          mediaAssetIds: post.mediaAssetIds,
+          ...receipt,
+        },
+        username,
+      );
+    },
+
+    async uploadMedia(connection: ConnectorConnection, media: MediaAsset): Promise<RemoteMedia> {
+      if (!media.mimeType.startsWith("image/")) {
+        throw new ConnectorError(
+          `${PROVIDER}: uploadMedia accepts images only ("${media.mimeType}")`,
+          PROVIDER,
+        );
+      }
+      const token = await botToken(connection);
+      const target = chatTarget(connection);
+      const { bytes, filename } = await requireAssetReader()(media);
+      // Telegram has no media library: "upload" = sending the photo once and
+      // keeping the returned file_id, which later sends can reference.
+      const message = await sendPhoto(token, target, media, bytes, filename);
+      const photo = largestPhoto(message.photo ?? []);
+      if (photo === undefined) {
+        throw new ConnectorError(`${PROVIDER}: sendPhoto returned no file id`, PROVIDER);
+      }
+      return {
+        remoteId: photo.file_id,
+        // No url on purpose: fetching file bytes requires the bot token, so
+        // file_id is the only safe long-lived reference.
+        mimeType: media.mimeType,
+        width: photo.width,
+        height: photo.height,
+      };
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: {
+        kind: "repost" | "quote" | "share";
+        targetRemoteId: string;
+        commentary?: string;
+      },
+    ): Promise<Publication> {
+      if (request.kind !== "share") {
+        throw new ConnectorError(
+          `${PROVIDER}: amplification is forwarding only — "${request.kind}" is not a capability`,
+          PROVIDER,
+        );
+      }
+      const token = await botToken(connection);
+      const target = chatTarget(connection);
+      const { chatId, messageId } = parseTargetReference(connection, request.targetRemoteId);
+
+      // forwardMessage cannot attach text; a share with commentary becomes a
+      // copyMessage carrying a fresh caption instead.
+      const hasCommentary = request.commentary !== undefined && request.commentary.length > 0;
+      const method = hasCommentary ? "copyMessage" : "forwardMessage";
+      const payload = hasCommentary
+        ? {
+            chat_id: target,
+            from_chat_id: chatId,
+            message_id: messageId,
+            caption: escapeHtml(request.commentary ?? ""),
+            parse_mode: "HTML",
+          }
+        : { chat_id: target, from_chat_id: chatId, message_id: messageId };
+      const result = await call<TelegramMessage | { message_id: number }>(
+        token,
+        method,
+        jsonPost(payload),
+      );
+      const username = await resolveChatUsername(token, target);
+      return toPublication(
+        connection,
+        `amplify:${request.kind}`,
+        {
+          messageId: result.message_id,
+          // forwardMessage returns the full message; copyMessage only a
+          // MessageId wrapper, so the local receive time stands in for it.
+          at: "date" in result ? new Date(result.date * 1000) : new Date(),
+        },
+        { amplifies: request.targetRemoteId, kind: request.kind, method, fromChatId: chatId, chatId: target, messageId: result.message_id },
+        username,
+      );
+    },
+
+    async unamplify(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      await deleteMessage(connection, remoteId);
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      await deleteMessage(connection, remoteId);
+    },
+
+    async subscribeWebhooks(
+      connection: ConnectorConnection,
+      request: { topics: string[] },
+    ): Promise<{ subscriptionId: string }> {
+      const url = options.webhookPublicUrl ?? env["TELEGRAM_WEBHOOK_URL"];
+      if (url === undefined || url.length === 0) {
+        throw new ConnectorError(
+          `${PROVIDER}: pass webhookPublicUrl or set TELEGRAM_WEBHOOK_URL before subscribing`,
+          PROVIDER,
+        );
+      }
+      const token = await botToken(connection);
+      const { secret, fromEnv } = await ensureWebhookSecret(connection);
+      if (!fromEnv) webhookSecrets.set(secret, connection.id);
+      const info = await call<TelegramWebhookInfo>(token, "getWebhookInfo");
+      const result = await call<boolean>(
+        token,
+        "setWebhook",
+        jsonPost({
+          url,
+          secret_token: secret,
+          allowed_updates: request.topics.length > 0 ? request.topics : undefined,
+          // Drop a pre-existing backlog so a re-subscribe does not replay old
+          // updates (getUpdates never yields history, and neither should we).
+          drop_pending_updates: info.pending_update_count > 0,
+        }),
+      );
+      if (!result) throw new ConnectorError(`${PROVIDER}: setWebhook rejected`, PROVIDER);
+      return { subscriptionId: `telegram-webhook:${connection.id}` };
+    },
+
+    async handleWebhook(request: {
+      headers: Record<string, string>;
+      body: unknown;
+    }): Promise<NormalizedWebhookEvent> {
+      const header = Object.entries(request.headers).find(
+        ([name]) => name.toLowerCase() === WEBHOOK_SECRET_HEADER,
+      )?.[1];
+      if (header === undefined || header.length === 0) {
+        throw new ConnectorError(
+          `${PROVIDER}: webhook missing ${WEBHOOK_SECRET_HEADER} header`,
+          PROVIDER,
+        );
+      }
+      const expected = env["TELEGRAM_WEBHOOK_SECRET"];
+      const matches =
+        expected !== undefined && expected.length > 0
+          ? header === expected
+          : // Secrets generated per connection live in this instance (single
+            // process); multi-instance deployments must set the env secret.
+            webhookSecrets.has(header);
+      if (!matches) throw new ConnectorError(`${PROVIDER}: webhook secret mismatch`, PROVIDER);
+
+      const update = request.body as Record<string, unknown> | null;
+      if (update === null || typeof update !== "object" || typeof update["update_id"] !== "number") {
+        throw new ConnectorError(
+          `${PROVIDER}: malformed webhook payload — expected a Telegram Update`,
+          PROVIDER,
+        );
+      }
+      const eventType = UPDATE_EVENT_KEYS.find((key) => update[key] !== undefined) ?? "update";
+      return {
+        provider: PROVIDER,
+        eventType,
+        connectionKey: webhookSecrets.get(header),
+        payload: update,
+        receivedAt: new Date(),
+      };
+    },
+  };
+}
diff --git a/packages/connector-telegram/tsconfig.json b/packages/connector-telegram/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-telegram/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-threads/package.json b/packages/connector-threads/package.json
new file mode 100644
index 0000000..64caaca
--- /dev/null
+++ b/packages/connector-threads/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-threads",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-threads/src/contract.test.ts b/packages/connector-threads/src/contract.test.ts
new file mode 100644
index 0000000..cd28f27
--- /dev/null
+++ b/packages/connector-threads/src/contract.test.ts
@@ -0,0 +1,391 @@
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection, NormalizedPost } from "@tactical-media-broadcast-hub/core";
+import {
+  connectorContractTests,
+  videoConnectorContractTests,
+} from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createThreadsConnector, type ThreadsConnectorOptions } from "./index.js";
+
+interface StubContainer {
+  id: string;
+  params: Record<string, string>;
+}
+
+interface StubCall {
+  method: string;
+  url: URL;
+  body: URLSearchParams;
+  authorization: string | null;
+}
+
+interface StubState {
+  calls: StubCall[];
+  containers: Map<string, StubContainer>;
+  nextContainer: number;
+  nextPublication: number;
+}
+
+const TOKEN = "THQVJstubbed-long-lived-token";
+const THREADS_USER_ID = "10001234567890";
+
+const connection: ConnectorConnection = {
+  id: "conn-threads",
+  workspaceId: "ws-1",
+  provider: "threads",
+  channelId: "threads-channel",
+  credentialId: { kind: "credential-ref", id: "cred-threads" },
+  fields: { accessToken: TOKEN, threadsUserId: THREADS_USER_ID },
+  createdAt: new Date(),
+};
+
+function state(): StubState {
+  return {
+    calls: [],
+    containers: new Map(),
+    nextContainer: 1,
+    nextPublication: 1,
+  };
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function graphError(message: string, code: number, status = 400): Response {
+  return json({ error: { message, code } }, status);
+}
+
+function stubGraph(stub: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const href = typeof input === "string"
+      ? input
+      : input instanceof URL
+        ? input.href
+        : input.url;
+    const url = new URL(href);
+    const method = init?.method ?? "GET";
+    const body = new URLSearchParams(typeof init?.body === "string" ? init.body : "");
+    const authorization = new Headers(init?.headers).get("authorization");
+    stub.calls.push({ method, url, body, authorization });
+
+    if (url.pathname === "/refresh_access_token") {
+      return json({
+        access_token: "THQVJrefreshed-token",
+        token_type: "bearer",
+        expires_in: 5_184_000,
+      });
+    }
+    if (authorization !== `Bearer ${TOKEN}` && authorization !== "Bearer THQVJrefreshed-token") {
+      return graphError("Invalid OAuth access token.", 190, 401);
+    }
+
+    const parts = url.pathname.split("/").filter((part) => part.length > 0);
+    if (parts[0] === "v1.0") parts.shift();
+    const [node, edge] = parts;
+
+    if (node === "me" && method === "GET") {
+      return json({
+        id: THREADS_USER_ID,
+        username: "anarchoposter",
+        threads_profile_picture_url: "https://cdn.example.com/avatar.jpg",
+      });
+    }
+
+    if (node === THREADS_USER_ID && edge === "threads" && method === "POST") {
+      const id = `container-${stub.nextContainer++}`;
+      stub.containers.set(id, { id, params: Object.fromEntries(body) });
+      return json({ id });
+    }
+
+    if (node === THREADS_USER_ID && edge === "threads_publish" && method === "POST") {
+      const creationId = body.get("creation_id") ?? "";
+      if (!stub.containers.has(creationId)) return graphError("Unknown container", 100);
+      return json({ id: `thread-${stub.nextPublication++}` });
+    }
+
+    if (node === THREADS_USER_ID && edge === "threads" && method === "GET") {
+      return json({
+        data: [
+          {
+            id: "thread-feed-1",
+            text: "Own-thread read surface",
+            timestamp: "2026-10-05T12:00:00+0000",
+            permalink: "https://www.threads.net/@tactical-media-broadcast-hub/post/abc",
+            reply_count: 7,
+          },
+        ],
+        paging: {
+          cursors: { before: "before-1", after: "after-1" },
+          next: "https://graph.threads.net/v1.0/next",
+        },
+      });
+    }
+
+    if (node === THREADS_USER_ID && edge === "threads_insights" && method === "GET") {
+      return json({
+        data: [
+          {
+            name: "views",
+            period: "day",
+            values: [
+              { value: 10, end_time: "2026-10-01T07:00:00+0000" },
+              { value: 12, end_time: "2026-10-02T07:00:00+0000" },
+            ],
+            total_value: { value: 22 },
+          },
+          { name: "likes", period: "day", total_value: { value: 5 } },
+        ],
+      });
+    }
+
+    if (node !== undefined && stub.containers.has(node) && edge === undefined && method === "GET") {
+      return json({ id: node, status: "FINISHED" });
+    }
+
+    if (node !== undefined && edge === "repost" && method === "POST") {
+      return json({ id: `repost-${node}` });
+    }
+
+    if (node !== undefined && edge === "unrepost" && method === "POST") {
+      return json({ success: true });
+    }
+
+    if (node !== undefined && edge === undefined && method === "DELETE") {
+      return json({ success: true });
+    }
+
+    return graphError(`Unknown path ${url.pathname}`, 100, 404);
+  };
+}
+
+interface Harness {
+  state: StubState;
+  connector: ReturnType<typeof createThreadsConnector>;
+}
+
+function harness(extra: ThreadsConnectorOptions = {}): Harness {
+  const stub = state();
+  return {
+    state: stub,
+    connector: createThreadsConnector({
+      fetchImpl: stubGraph(stub),
+      requestsPerSecond: 100_000,
+      pollIntervalMs: 0,
+      maxPollAttempts: 2,
+      sleep: async () => undefined,
+      ...extra,
+    }),
+  };
+}
+
+function post(
+  text: string,
+  mediaAssetIds: string[] = [],
+  providerMetadata: Record<string, unknown> = {},
+): NormalizedPost {
+  return {
+    text,
+    mediaAssetIds,
+    visibility: "public",
+    providerMetadata,
+  };
+}
+
+const contractHarness = harness();
+connectorContractTests(contractHarness.connector, { connection });
+videoConnectorContractTests(contractHarness.connector, { connection });
+
+describe("threads connector: manifest and identity", () => {
+  it("declares the OAuth scopes and honest read capabilities", async () => {
+    const { connector } = harness();
+    const manifest = connector.manifest();
+    expect(manifest.oauth).toEqual({
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: "https://threads.net/oauth/authorize",
+      scopes: [
+        "threads_basic",
+        "threads_content_publish",
+        "threads_manage_replies",
+        "threads_manage_insights",
+      ],
+    });
+    expect(manifest.capabilities).toMatchObject({
+      feed: true,
+      replies: true,
+      comments: false,
+      directMessages: false,
+      webhooks: false,
+    });
+    const identity = await connector.getIdentity(connection);
+    expect(identity).toEqual({
+      provider: "threads",
+      remoteId: THREADS_USER_ID,
+      handle: "@anarchoposter",
+      displayName: "anarchoposter",
+      avatarUrl: "https://cdn.example.com/avatar.jpg",
+    });
+  });
+
+  it("rejects a missing token without making a request", async () => {
+    const { connector, state: stub } = harness();
+    const missing: ConnectorConnection = {
+      ...connection,
+      fields: { threadsUserId: THREADS_USER_ID },
+    };
+    await expect(connector.getIdentity(missing)).rejects.toMatchObject({ name: "AuthError" });
+    expect(stub.calls).toHaveLength(0);
+  });
+});
+
+describe("threads connector: two-step publishing", () => {
+  it("creates and publishes a text container", async () => {
+    const { connector, state: stub } = harness();
+    const result = await connector.publish?.(connection, post("Hello Threads"));
+    expect(result?.remoteId).toBe("thread-1");
+    expect(result?.providerMetadata).toMatchObject({
+      creationId: "container-1",
+      kind: "text",
+      dailyPostCap: 250,
+    });
+    expect(stub.calls.map((call) => [call.method, call.url.pathname])).toEqual([
+      ["POST", `/v1.0/${THREADS_USER_ID}/threads`],
+      ["POST", `/v1.0/${THREADS_USER_ID}/threads_publish`],
+    ]);
+    expect(stub.calls[0]?.body.get("media_type")).toBe("TEXT");
+    expect(stub.calls[0]?.body.get("text")).toBe("Hello Threads");
+    expect(stub.calls[1]?.body.get("creation_id")).toBe("container-1");
+  });
+
+  it("creates carousel children, a parent, then publishes the parent", async () => {
+    const { connector, state: stub } = harness();
+    const result = await connector.publish?.(
+      connection,
+      post("A carousel", [], {
+        media: [
+          { url: "https://cdn.example.com/one.jpg", kind: "image" },
+          { url: "https://cdn.example.com/two.jpg", kind: "image" },
+        ],
+      }),
+    );
+    const createCalls = stub.calls.filter((call) => call.url.pathname.endsWith("/threads"));
+    expect(createCalls).toHaveLength(3);
+    expect(createCalls[0]?.body.get("is_carousel_item")).toBe("true");
+    expect(createCalls[1]?.body.get("is_carousel_item")).toBe("true");
+    expect(createCalls[2]?.body.get("media_type")).toBe("CAROUSEL");
+    expect(createCalls[2]?.body.get("children")).toBe("container-1,container-2");
+    expect(result?.providerMetadata).toMatchObject({
+      kind: "carousel",
+      children: ["container-1", "container-2"],
+    });
+  });
+
+  it("polls a video container before publishing it", async () => {
+    const { connector, state: stub } = harness();
+    const result = await connector.publish?.(
+      connection,
+      post("Video", ["https://cdn.example.com/video.mp4"]),
+    );
+    expect(result?.remoteId).toBe("thread-1");
+    expect(stub.calls.map((call) => call.method)).toEqual(["POST", "GET", "POST"]);
+    expect(stub.calls[0]?.body.get("media_type")).toBe("VIDEO");
+    expect(stub.calls[1]?.url.pathname).toBe("/v1.0/container-1");
+  });
+
+  it("enforces the 500-character text limit before the API call", async () => {
+    const { connector, state: stub } = harness();
+    await expect(connector.publish?.(connection, post("x".repeat(501)))).rejects.toThrow(
+      /500 characters/,
+    );
+    expect(stub.calls).toHaveLength(0);
+  });
+});
+
+describe("threads connector: replies and amplification", () => {
+  it("publishes replies through a TEXT container with reply_to_id", async () => {
+    const { connector, state: stub } = harness();
+    const result = await connector.reply?.(connection, {
+      onRemoteId: "thread-original",
+      text: "A reply",
+    });
+    expect(stub.calls[0]?.body.get("reply_to_id")).toBe("thread-original");
+    expect(result?.providerMetadata).toMatchObject({
+      kind: "reply",
+      inReplyTo: "thread-original",
+    });
+  });
+
+  it("uses the native repost and unrepost endpoints", async () => {
+    const { connector, state: stub } = harness();
+    const result = await connector.amplify?.(connection, {
+      kind: "repost",
+      targetRemoteId: "thread-original",
+    });
+    await connector.unamplify?.(connection, "thread-original");
+    expect(result?.remoteId).toBe("repost-thread-original");
+    expect(stub.calls.map((call) => call.url.pathname)).toEqual([
+      "/v1.0/thread-original/repost",
+      "/v1.0/thread-original/unrepost",
+    ]);
+  });
+
+  it("publishes a quote through quote_post_id", async () => {
+    const { connector, state: stub } = harness();
+    const result = await connector.amplify?.(connection, {
+      kind: "quote",
+      targetRemoteId: "thread-original",
+      commentary: "Worth reading",
+    });
+    expect(stub.calls[0]?.body.get("quote_post_id")).toBe("thread-original");
+    expect(stub.calls[0]?.body.get("text")).toBe("Worth reading");
+    expect(result?.providerMetadata.kind).toBe("quote");
+  });
+});
+
+describe("threads connector: own feed and analytics", () => {
+  it("maps only the connected account's own threads", async () => {
+    const { connector, state: stub } = harness();
+    await connector.getIdentity(connection);
+    const feed = await connector.getFeed?.(connection, { kind: "home", limit: 25 });
+    expect(feed).toEqual({
+      items: [
+        {
+          id: "thread-feed-1",
+          provider: "threads",
+          remoteId: "thread-feed-1",
+          authorHandle: "@anarchoposter",
+          text: "Own-thread read surface",
+          mediaUrls: [],
+          createdAt: new Date("2026-10-05T12:00:00+0000"),
+          metrics: { replies: 7 },
+        },
+      ],
+      nextCursor: "after-1",
+    });
+    const feedCall = stub.calls.find((call) => call.url.pathname.endsWith("/threads"));
+    expect(feedCall?.url.searchParams.get("fields")).toBe(
+      "id,text,timestamp,permalink,reply_count",
+    );
+    await expect(
+      connector.getFeed?.(connection, { kind: "search", query: "news", limit: 10 }),
+    ).rejects.toThrow(/own threads/);
+  });
+
+  it("maps account insight totals and daily series", async () => {
+    const { connector, state: stub } = harness();
+    const analytics = await connector.getAnalytics?.(connection, {
+      from: new Date("2026-10-01T00:00:00Z"),
+      to: new Date("2026-10-03T00:00:00Z"),
+    });
+    expect(analytics?.values).toEqual({ views: 22, likes: 5 });
+    expect(analytics?.series).toEqual([
+      { at: new Date("2026-10-01T07:00:00+0000"), values: { views: 10 } },
+      { at: new Date("2026-10-02T07:00:00+0000"), values: { views: 12 } },
+    ]);
+    const call = stub.calls[0];
+    expect(call?.url.pathname).toBe(`/v1.0/${THREADS_USER_ID}/threads_insights`);
+    expect(call?.url.searchParams.get("metric")).toContain("views");
+  });
+});
diff --git a/packages/connector-threads/src/index.ts b/packages/connector-threads/src/index.ts
new file mode 100644
index 0000000..c2b618a
--- /dev/null
+++ b/packages/connector-threads/src/index.ts
@@ -0,0 +1,724 @@
+/**
+ * Threads connector — Threads API on graph.threads.net.
+ *
+ * Publishing is URL-backed and two-step: create a container, wait for video
+ * processing when applicable, then publish the container. `mediaAssetIds`
+ * therefore need to be public URLs, or callers can provide `resolveMediaUrl`.
+ * Reads deliberately expose only the connected account's own threads; the API
+ * endpoint is not a home timeline. Threads does not document webhooks.
+ */
+import { randomUUID } from "node:crypto";
+import type {
+  ConnectorCapabilities,
+  ConnectorConnection,
+  FeedItem,
+  NormalizedIdentity,
+  NormalizedPost,
+  NormalizedVideoPublication,
+  Page,
+  Publication,
+  VideoProcessingStatus,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  InMemoryCredentials,
+  pageOf,
+  RateLimitedHttpClient,
+  RateLimitError,
+  resolveRatePolicy,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "threads";
+const API_ROOT = "https://graph.threads.net";
+const API_BASE = `${API_ROOT}/v1.0`;
+const TEXT_LIMIT = 500;
+const FEED_FIELDS = "id,text,timestamp,permalink,reply_count";
+const INSIGHT_METRICS = "views,likes,replies,reposts,quotes,followers_count";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: true,
+  publishImages: true,
+  publishCarousel: true,
+  publishVideo: true,
+  replies: true,
+  feed: true,
+  amplifyRepost: true,
+  amplifyQuote: true,
+  analytics: true,
+  directMessages: false,
+  webhooks: false,
+  comments: false,
+  deletePublication: true,
+};
+
+type MediaKind = "image" | "video";
+
+export interface ThreadsMediaInput {
+  url: string;
+  kind: MediaKind;
+}
+
+export interface ThreadsConnectorOptions {
+  fetchImpl?: typeof fetch;
+  /** Test/deployment override; the documented default remains 0.5 req/s. */
+  requestsPerSecond?: number;
+  /** Secret store. Connection fields remain a development/test fallback. */
+  credentials?: CredentialAccessor;
+  /** Resolve a AnarchoPoster asset id to a publicly fetchable image/video URL. */
+  resolveMediaUrl?: (assetId: string) => Promise<string | ThreadsMediaInput>;
+  /** Video-container polling delay. Default 10 seconds. */
+  pollIntervalMs?: number;
+  /** Maximum status reads while publishing a video. Default 30. */
+  maxPollAttempts?: number;
+  /** Polling sleep override for tests. */
+  sleep?: (ms: number) => Promise<void>;
+}
+
+interface GraphErrorBody {
+  error?: {
+    message?: string;
+    code?: number;
+    error_subcode?: number;
+    error_user_msg?: string;
+  };
+}
+
+interface GraphIdResponse {
+  id?: string;
+  success?: boolean;
+}
+
+interface ThreadsIdentity {
+  id: string;
+  username?: string;
+  threads_profile_picture_url?: string;
+}
+
+interface ThreadsContainer {
+  id: string;
+  status?: string;
+  status_code?: string;
+  error_message?: string;
+}
+
+interface ThreadsPost {
+  id: string;
+  text?: string;
+  timestamp?: string;
+  permalink?: string;
+  reply_count?: number;
+}
+
+interface GraphPaging {
+  cursors?: { before?: string; after?: string };
+  next?: string;
+}
+
+interface GraphList<T> {
+  data: T[];
+  paging?: GraphPaging;
+}
+
+interface ThreadsInsight {
+  name: string;
+  period?: string;
+  values?: { value: number | Record<string, number>; end_time?: string }[];
+  total_value?: { value: number | Record<string, number> };
+}
+
+interface RefreshedToken {
+  access_token: string;
+  token_type?: string;
+  expires_in?: number;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function assertText(text: string, allowEmpty: boolean): void {
+  const length = [...text].length;
+  if (!allowEmpty && length === 0) {
+    throw new ConnectorError(`${PROVIDER}: text cannot be empty`, PROVIDER);
+  }
+  if (length > TEXT_LIMIT) {
+    throw new ConnectorError(`${PROVIDER}: text exceeds ${TEXT_LIMIT} characters`, PROVIDER);
+  }
+}
+
+function inferredKind(value: string): MediaKind {
+  const pathname = (() => {
+    try {
+      return new URL(value).pathname;
+    } catch {
+      return value;
+    }
+  })();
+  return /\.(?:mp4|mov|m4v|webm)$/i.test(pathname) ? "video" : "image";
+}
+
+/** Map Threads container states onto the SDK video state machine. */
+export function mapThreadsContainerStatus(
+  remoteId: string,
+  container: ThreadsContainer,
+): VideoProcessingStatus {
+  const status = (container.status_code ?? container.status ?? "IN_PROGRESS").toUpperCase();
+  if (status === "FINISHED" || status === "PUBLISHED") {
+    return { remoteId, state: "ready", progressPercent: 100 };
+  }
+  if (status === "ERROR" || status === "FAILED" || status === "EXPIRED") {
+    return {
+      remoteId,
+      state: "failed",
+      error: container.error_message ?? `container ${status.toLowerCase()}`,
+    };
+  }
+  if (status === "UPLOADING") return { remoteId, state: "uploading" };
+  return { remoteId, state: "processing" };
+}
+
+export function createThreadsConnector(options: ThreadsConnectorOptions = {}): PlatformConnector {
+  const ratePolicy = resolveRatePolicy(
+    PROVIDER,
+    { dailyPostCap: 250, requestsPerSecond: 0.5 },
+    options.requestsPerSecond === undefined
+      ? undefined
+      : { requestsPerSecond: options.requestsPerSecond },
+  );
+  const client = new RateLimitedHttpClient({
+    requestsPerSecond: ratePolicy.requestsPerSecond,
+    fetchImpl: options.fetchImpl,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const pollIntervalMs = options.pollIntervalMs ?? 10_000;
+  const maxPollAttempts = options.maxPollAttempts ?? 30;
+  const handles = new Map<string, string>();
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Threads",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "accessToken",
+        label: "Long-lived access token",
+        required: true,
+        secret: true,
+      },
+      {
+        name: "threadsUserId",
+        label: "Threads user ID",
+        required: true,
+        secret: false,
+        pattern: "^[0-9]+$",
+      },
+    ],
+    oauth: {
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: "https://threads.net/oauth/authorize",
+      scopes: [
+        "threads_basic",
+        "threads_content_publish",
+        "threads_manage_replies",
+        "threads_manage_insights",
+      ],
+    },
+    docsUrl: "https://developers.facebook.com/docs/threads/",
+  };
+
+  function userIdOf(connection: ConnectorConnection): string {
+    const id = nonEmptyString(connection.fields["threadsUserId"]);
+    if (id === undefined) {
+      throw new ConnectorError(
+        `${PROVIDER}: connection ${connection.id} has no threadsUserId`,
+        PROVIDER,
+      );
+    }
+    return id;
+  }
+
+  async function accessTokenOf(connection: ConnectorConnection): Promise<string> {
+    try {
+      return await credentials.getAccessToken(connection);
+    } catch {
+      const token = nonEmptyString(connection.fields["accessToken"]);
+      if (token !== undefined) return token;
+      throw new AuthError(
+        `${PROVIDER}: no access token for connection ${connection.id}`,
+        PROVIDER,
+        false,
+      );
+    }
+  }
+
+  function parseJson(text: string): unknown {
+    if (text.length === 0) return {};
+    try {
+      return JSON.parse(text) as unknown;
+    } catch (cause) {
+      throw new ConnectorError(`${PROVIDER}: Graph API returned non-JSON`, PROVIDER, cause);
+    }
+  }
+
+  function graphError(
+    response: Response,
+    method: string,
+    url: URL,
+    body: unknown,
+  ): Error {
+    const graph = body as GraphErrorBody;
+    const error = graph.error;
+    const detail = error?.error_user_msg ?? error?.message ?? "Graph API request failed";
+    const message = `${PROVIDER}: HTTP ${response.status} ${method} ${url.pathname}: ${detail}`;
+    const code = error?.code;
+    if (response.status === 429 || code === 4 || code === 17 || code === 32 || code === 613) {
+      return new RateLimitError(PROVIDER);
+    }
+    if (response.status === 401 || code === 190) {
+      return new AuthError(message, PROVIDER, false);
+    }
+    if (response.status === 403 || code === 10 || (code !== undefined && code >= 200 && code < 300)) {
+      return new AuthError(`${message} (missing Threads permission?)`, PROVIDER, false);
+    }
+    return new ConnectorError(message, PROVIDER, {
+      status: response.status,
+      code,
+      subcode: error?.error_subcode,
+    });
+  }
+
+  async function graph<T>(
+    connection: ConnectorConnection,
+    method: "GET" | "POST" | "DELETE",
+    path: string,
+    params: Record<string, string> = {},
+  ): Promise<T> {
+    const url = new URL(`${API_BASE}${path}`);
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      authorization: `Bearer ${await accessTokenOf(connection)}`,
+    };
+    const init: RequestInit = { method, headers };
+    if (method === "POST") {
+      headers["content-type"] = "application/x-www-form-urlencoded";
+      init.body = new URLSearchParams(params).toString();
+    } else {
+      for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
+    }
+    const response = await client.request(PROVIDER, url.toString(), init);
+    const body = parseJson(await response.text());
+    if (!response.ok) throw graphError(response, method, url, body);
+    return body as T;
+  }
+
+  async function createContainer(
+    connection: ConnectorConnection,
+    params: Record<string, string>,
+  ): Promise<string> {
+    const result = await graph<GraphIdResponse>(
+      connection,
+      "POST",
+      `/${userIdOf(connection)}/threads`,
+      params,
+    );
+    if (result.id === undefined) {
+      throw new ConnectorError(`${PROVIDER}: container creation returned no id`, PROVIDER);
+    }
+    return result.id;
+  }
+
+  async function containerStatus(
+    connection: ConnectorConnection,
+    containerId: string,
+  ): Promise<ThreadsContainer> {
+    return graph<ThreadsContainer>(connection, "GET", `/${encodeURIComponent(containerId)}`, {
+      fields: "id,status,error_message",
+    });
+  }
+
+  async function awaitContainer(
+    connection: ConnectorConnection,
+    containerId: string,
+  ): Promise<void> {
+    for (let attempt = 0; attempt < maxPollAttempts; attempt += 1) {
+      const status = mapThreadsContainerStatus(
+        containerId,
+        await containerStatus(connection, containerId),
+      );
+      if (status.state === "ready") return;
+      if (status.state === "failed") {
+        throw new ConnectorError(
+          `${PROVIDER}: container ${containerId} failed: ${status.error ?? "unknown error"}`,
+          PROVIDER,
+        );
+      }
+      if (attempt + 1 < maxPollAttempts) await sleep(pollIntervalMs);
+    }
+    throw new ConnectorError(
+      `${PROVIDER}: container ${containerId} still processing after ${maxPollAttempts} polls`,
+      PROVIDER,
+    );
+  }
+
+  function publication(
+    connection: ConnectorConnection,
+    remoteId: string,
+    draftId: string,
+    providerMetadata: Record<string, unknown>,
+  ): Publication {
+    return {
+      id: randomUUID(),
+      workspaceId: connection.workspaceId,
+      draftId,
+      connectionId: connection.id,
+      remoteId,
+      publishedAt: new Date(),
+      providerMetadata,
+    };
+  }
+
+  async function publishContainer(
+    connection: ConnectorConnection,
+    creationId: string,
+    draftId: string,
+    providerMetadata: Record<string, unknown>,
+  ): Promise<Publication> {
+    const result = await graph<GraphIdResponse>(
+      connection,
+      "POST",
+      `/${userIdOf(connection)}/threads_publish`,
+      { creation_id: creationId },
+    );
+    if (result.id === undefined) {
+      throw new ConnectorError(`${PROVIDER}: publish returned no media id`, PROVIDER);
+    }
+    return publication(connection, result.id, draftId, {
+      creationId,
+      dailyPostCap: ratePolicy.dailyPostCap,
+      ...providerMetadata,
+    });
+  }
+
+  function metadataMedia(metadata: Record<string, unknown>): ThreadsMediaInput[] {
+    if (!Array.isArray(metadata["media"])) return [];
+    const media: ThreadsMediaInput[] = [];
+    for (const entry of metadata["media"] as unknown[]) {
+      if (typeof entry !== "object" || entry === null) continue;
+      const item = entry as Record<string, unknown>;
+      const url = nonEmptyString(item["url"]);
+      const kind = item["kind"] === "image" || item["kind"] === "video" ? item["kind"] : undefined;
+      if (url !== undefined && kind !== undefined) media.push({ url, kind });
+    }
+    return media;
+  }
+
+  async function resolveAsset(assetId: string): Promise<ThreadsMediaInput> {
+    const resolved = options.resolveMediaUrl === undefined
+      ? assetId
+      : await options.resolveMediaUrl(assetId);
+    if (typeof resolved === "string") return { url: resolved, kind: inferredKind(resolved) };
+    return resolved;
+  }
+
+  async function mediaFor(post: NormalizedPost): Promise<ThreadsMediaInput[]> {
+    const media = metadataMedia(post.providerMetadata);
+    for (const assetId of post.mediaAssetIds) media.push(await resolveAsset(assetId));
+    return media;
+  }
+
+  async function createTextPublication(
+    connection: ConnectorConnection,
+    text: string,
+    params: Record<string, string>,
+    draftId: string,
+    metadata: Record<string, unknown>,
+    allowEmpty = false,
+  ): Promise<Publication> {
+    assertText(text, allowEmpty);
+    const containerParams: Record<string, string> = {
+      media_type: "TEXT",
+      ...params,
+    };
+    if (text.length > 0) containerParams.text = text;
+    const creationId = await createContainer(connection, containerParams);
+    return publishContainer(connection, creationId, draftId, metadata);
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize() {
+      throw new ConnectorError(
+        `${PROVIDER}: start OAuth at https://threads.net/oauth/authorize, exchange the code at ${API_ROOT}/oauth/access_token, then store accessToken and threadsUserId`,
+        PROVIDER,
+      );
+    },
+
+    async refreshCredentials(connection: ConnectorConnection) {
+      const url = new URL(`${API_ROOT}/refresh_access_token`);
+      url.searchParams.set("grant_type", "th_refresh_token");
+      url.searchParams.set("access_token", await accessTokenOf(connection));
+      const response = await client.request(PROVIDER, url.toString(), {
+        headers: { accept: "application/json" },
+      });
+      const body = parseJson(await response.text());
+      if (!response.ok) throw graphError(response, "GET", url, body);
+      const token = body as RefreshedToken;
+      if (nonEmptyString(token.access_token) === undefined) {
+        throw new AuthError(`${PROVIDER}: token refresh returned no access token`, PROVIDER, false);
+      }
+      await credentials.put(connection, "access_token", token.access_token);
+      return connection.credentialId;
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      const me = await graph<ThreadsIdentity>(connection, "GET", "/me", {
+        fields: "id,username,threads_profile_picture_url",
+      });
+      const username = me.username ?? me.id;
+      const handle = `@${username}`;
+      handles.set(connection.id, handle);
+      const identity: NormalizedIdentity = {
+        provider: PROVIDER,
+        remoteId: me.id,
+        handle,
+      };
+      if (me.username !== undefined) identity.displayName = me.username;
+      if (me.threads_profile_picture_url !== undefined) {
+        identity.avatarUrl = me.threads_profile_picture_url;
+      }
+      return identity;
+    },
+
+    async publish(connection: ConnectorConnection, post: NormalizedPost): Promise<Publication> {
+      const draftId = nonEmptyString(post.providerMetadata["draftId"]) ?? "direct";
+      const existing = nonEmptyString(post.providerMetadata["creationId"]);
+      if (existing !== undefined) {
+        await awaitContainer(connection, existing);
+        return publishContainer(connection, existing, draftId, { kind: "existing-container" });
+      }
+
+      assertText(post.text, post.mediaAssetIds.length > 0 || metadataMedia(post.providerMetadata).length > 0);
+      const media = await mediaFor(post);
+      if (media.length === 0) {
+        return createTextPublication(connection, post.text, {}, draftId, { kind: "text" });
+      }
+
+      const first = media[0];
+      if (media.length === 1 && first !== undefined) {
+        const params: Record<string, string> = first.kind === "image"
+          ? { media_type: "IMAGE", image_url: first.url }
+          : { media_type: "VIDEO", video_url: first.url };
+        if (post.text.length > 0) params.text = post.text;
+        const creationId = await createContainer(connection, params);
+        if (first.kind === "video") await awaitContainer(connection, creationId);
+        return publishContainer(connection, creationId, draftId, { kind: first.kind });
+      }
+
+      const children: string[] = [];
+      for (const item of media) {
+        const params: Record<string, string> = item.kind === "image"
+          ? { media_type: "IMAGE", image_url: item.url, is_carousel_item: "true" }
+          : { media_type: "VIDEO", video_url: item.url, is_carousel_item: "true" };
+        const childId = await createContainer(connection, params);
+        if (item.kind === "video") await awaitContainer(connection, childId);
+        children.push(childId);
+      }
+      const parentParams: Record<string, string> = {
+        media_type: "CAROUSEL",
+        children: children.join(","),
+      };
+      if (post.text.length > 0) parentParams.text = post.text;
+      const parentId = await createContainer(connection, parentParams);
+      return publishContainer(connection, parentId, draftId, { kind: "carousel", children });
+    },
+
+    async uploadVideo(
+      connection: ConnectorConnection,
+      video: NormalizedVideoPublication,
+    ): Promise<{ remoteId: string }> {
+      const explicitUrl = nonEmptyString(video.providerMetadata["videoUrl"]);
+      const resolved = explicitUrl === undefined
+        ? await resolveAsset(video.videoAssetId)
+        : { url: explicitUrl, kind: "video" as const };
+      const text = [video.title, video.description].filter((part): part is string => !!part).join("\n\n");
+      assertText(text, true);
+      const params: Record<string, string> = {
+        media_type: "VIDEO",
+        video_url: resolved.url,
+      };
+      if (text.length > 0) params.text = text;
+      return { remoteId: await createContainer(connection, params) };
+    },
+
+    async getVideoStatus(
+      connection: ConnectorConnection,
+      remoteId: string,
+    ): Promise<VideoProcessingStatus> {
+      return mapThreadsContainerStatus(remoteId, await containerStatus(connection, remoteId));
+    },
+
+    async reply(
+      connection: ConnectorConnection,
+      request: { onRemoteId: string; text: string },
+    ): Promise<Publication> {
+      return createTextPublication(
+        connection,
+        request.text,
+        { reply_to_id: request.onRemoteId },
+        "reply",
+        { kind: "reply", inReplyTo: request.onRemoteId },
+      );
+    },
+
+    async amplify(
+      connection: ConnectorConnection,
+      request: {
+        kind: "repost" | "quote" | "share";
+        targetRemoteId: string;
+        commentary?: string;
+        quoteAssetIds?: string[];
+      },
+    ): Promise<Publication> {
+      if (request.kind === "share") {
+        throw new CapabilityNotSupportedError(PROVIDER, "amplifyShare");
+      }
+      if (request.kind === "repost") {
+        const result = await graph<GraphIdResponse>(
+          connection,
+          "POST",
+          `/${encodeURIComponent(request.targetRemoteId)}/repost`,
+        );
+        return publication(
+          connection,
+          result.id ?? request.targetRemoteId,
+          "amplify:repost",
+          { kind: "repost", amplifies: request.targetRemoteId },
+        );
+      }
+      if ((request.quoteAssetIds?.length ?? 0) > 0) {
+        throw new CapabilityNotSupportedError(PROVIDER, "quote posts with media");
+      }
+      const commentary = request.commentary ?? "";
+      return createTextPublication(
+        connection,
+        commentary,
+        { quote_post_id: request.targetRemoteId },
+        "amplify:quote",
+        { kind: "quote", amplifies: request.targetRemoteId },
+        true,
+      );
+    },
+
+    async unamplify(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      await graph(connection, "POST", `/${encodeURIComponent(remoteId)}/unrepost`);
+    },
+
+    async deletePublication(connection: ConnectorConnection, remoteId: string): Promise<void> {
+      try {
+        await graph(connection, "DELETE", `/${encodeURIComponent(remoteId)}`);
+      } catch (error) {
+        const status = error instanceof ConnectorError
+          ? (error.cause as { status?: number } | undefined)?.status
+          : undefined;
+        if (status !== 404) throw error;
+      }
+    },
+
+    async getFeed(
+      connection: ConnectorConnection,
+      request: {
+        kind: "home" | "mentions" | "search";
+        query?: string;
+        cursor?: string;
+        limit: number;
+      },
+    ): Promise<Page<FeedItem>> {
+      if (request.kind !== "home") {
+        throw new CapabilityNotSupportedError(
+          PROVIDER,
+          `feed:${request.kind} (Threads exposes only the connected account's own threads)`,
+        );
+      }
+      const params: Record<string, string> = {
+        fields: FEED_FIELDS,
+        limit: String(Math.max(1, Math.min(100, request.limit))),
+      };
+      if (request.cursor !== undefined) params.after = request.cursor;
+      const result = await graph<GraphList<ThreadsPost>>(
+        connection,
+        "GET",
+        `/${userIdOf(connection)}/threads`,
+        params,
+      );
+      const authorHandle = handles.get(connection.id) ?? `@${userIdOf(connection)}`;
+      const items = result.data.map(
+        (thread): FeedItem => ({
+          id: thread.id,
+          provider: PROVIDER,
+          remoteId: thread.id,
+          authorHandle,
+          text: thread.text ?? "",
+          mediaUrls: [],
+          createdAt: thread.timestamp === undefined ? new Date(0) : new Date(thread.timestamp),
+          metrics: { replies: thread.reply_count ?? 0 },
+        }),
+      );
+      const nextCursor = result.paging?.next === undefined
+        ? undefined
+        : result.paging.cursors?.after;
+      return pageOf(items, nextCursor);
+    },
+
+    async getAnalytics(
+      connection: ConnectorConnection,
+      request: { subjectRemoteId?: string; from: Date; to: Date },
+    ): Promise<{
+      values: Record<string, number>;
+      series: { at: Date; values: Record<string, number> }[];
+    }> {
+      if (request.subjectRemoteId !== undefined) {
+        throw new CapabilityNotSupportedError(
+          PROVIDER,
+          "per-publication analytics (this connector exposes account threads_insights)",
+        );
+      }
+      const result = await graph<GraphList<ThreadsInsight>>(
+        connection,
+        "GET",
+        `/${userIdOf(connection)}/threads_insights`,
+        {
+          metric: INSIGHT_METRICS,
+          since: String(Math.floor(request.from.getTime() / 1000)),
+          until: String(Math.floor(request.to.getTime() / 1000)),
+        },
+      );
+      const values: Record<string, number> = {};
+      const byTime = new Map<string, Record<string, number>>();
+      for (const insight of result.data) {
+        const total = insight.total_value?.value;
+        if (typeof total === "number") values[insight.name] = total;
+        for (const point of insight.values ?? []) {
+          if (point.end_time === undefined || typeof point.value !== "number") continue;
+          const at = byTime.get(point.end_time) ?? {};
+          at[insight.name] = point.value;
+          byTime.set(point.end_time, at);
+        }
+      }
+      const series = [...byTime.entries()]
+        .map(([at, pointValues]) => ({ at: new Date(at), values: pointValues }))
+        .sort((left, right) => left.at.getTime() - right.at.getTime());
+      return { values, series };
+    },
+  };
+}
diff --git a/packages/connector-threads/tsconfig.json b/packages/connector-threads/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/connector-threads/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/connector-twitch/package.json b/packages/connector-twitch/package.json
new file mode 100644
index 0000000..7ba9145
--- /dev/null
+++ b/packages/connector-twitch/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/connector-twitch",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/connector-sdk": "workspace:*",
+    "@tactical-media-broadcast-hub/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/connector-twitch/src/contract.test.ts b/packages/connector-twitch/src/contract.test.ts
new file mode 100644
index 0000000..2c9db5e
--- /dev/null
+++ b/packages/connector-twitch/src/contract.test.ts
@@ -0,0 +1,415 @@
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import type { ConnectorConnection } from "@tactical-media-broadcast-hub/core";
+import {
+  connectorContractTests,
+  livestreamConnectorContractTests,
+} from "@tactical-media-broadcast-hub/connector-sdk/testing";
+import { createTwitchConnector, type TwitchConnectorOptions } from "./index.js";
+
+const CLIENT_ID = "client-id-for-tests";
+const TOKEN = "oauth-token-for-tests";
+const BROADCASTER_ID = "141981764";
+const WEBHOOK_SECRET = "eventsub-secret-for-tests";
+
+const connection: ConnectorConnection = {
+  id: "conn-twitch",
+  workspaceId: "ws-1",
+  provider: "twitch",
+  channelId: BROADCASTER_ID,
+  credentialId: { kind: "credential-ref", id: "cred-twitch" },
+  fields: {
+    clientId: CLIENT_ID,
+    accessToken: TOKEN,
+    broadcasterId: BROADCASTER_ID,
+  },
+  createdAt: new Date(),
+};
+
+interface StubCall {
+  url: URL;
+  init: RequestInit | undefined;
+}
+
+interface StubState {
+  calls: StubCall[];
+  live: boolean;
+  subscriptions: number;
+}
+
+const user = {
+  id: BROADCASTER_ID,
+  login: "tmbh_live",
+  display_name: "TMBH Live",
+  profile_image_url: "https://static.example/avatar.png",
+  broadcaster_type: "partner",
+};
+
+const stream = {
+  id: "stream-9001",
+  user_id: BROADCASTER_ID,
+  user_login: user.login,
+  user_name: user.display_name,
+  type: "live",
+  title: "Building in public",
+  viewer_count: 321,
+  started_at: "2026-10-07T10:00:00Z",
+  game_name: "Software and Game Development",
+  thumbnail_url: "https://static.example/live/{width}x{height}.jpg",
+};
+
+function json(value: unknown, status = 200): Response {
+  return new Response(JSON.stringify(value), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function requestUrl(input: Parameters<typeof fetch>[0]): URL {
+  if (typeof input === "string") return new URL(input);
+  if (input instanceof URL) return input;
+  return new URL(input.url);
+}
+
+function header(init: RequestInit | undefined, name: string): string | null {
+  return new Headers(init?.headers).get(name);
+}
+
+function body(init: RequestInit | undefined): Record<string, unknown> {
+  return JSON.parse(String(init?.body ?? "{}")) as Record<string, unknown>;
+}
+
+function stubHelix(state: StubState): typeof fetch {
+  return async (input: Parameters<typeof fetch>[0], init?: RequestInit): Promise<Response> => {
+    const url = requestUrl(input);
+    state.calls.push({ url, init });
+    expect(header(init, "client-id")).toBe(CLIENT_ID);
+    expect(header(init, "authorization")).toBe(`Bearer ${TOKEN}`);
+
+    if (url.pathname === "/helix/users") return json({ data: [user] });
+    if (url.pathname === "/helix/streams") {
+      return json({ data: state.live ? [stream] : [], pagination: {} });
+    }
+    if (url.pathname === "/helix/analytics/streams") {
+      return json({
+        data: [
+          {
+            started_at: "2026-10-06T10:00:00Z",
+            metrics: { unique_viewers: 80, average_viewers: 25 },
+          },
+          {
+            started_at: "2026-10-07T10:00:00Z",
+            metrics: { unique_viewers: 100, average_viewers: 30 },
+          },
+        ],
+        pagination: {},
+      });
+    }
+    if (url.pathname === "/helix/eventsub/subscriptions" && init?.method === "POST") {
+      state.subscriptions += 1;
+      return json({ data: [{ id: `eventsub-${state.subscriptions}`, status: "webhook_callback_verification_pending" }] });
+    }
+    return json({ error: "Not Found", status: 404, message: `${init?.method ?? "GET"} ${url.pathname}` }, 404);
+  };
+}
+
+interface Harness {
+  state: StubState;
+  connector: ReturnType<typeof createTwitchConnector>;
+}
+
+function harness(overrides: TwitchConnectorOptions = {}): Harness {
+  const state: StubState = { calls: [], live: true, subscriptions: 0 };
+  return {
+    state,
+    connector: createTwitchConnector({
+      fetchImpl: stubHelix(state),
+      requestsPerSecond: 1000,
+      sleep: async () => Promise.resolve(),
+      webhookPublicUrl: "https://app.example.com/webhooks/twitch",
+      webhookSecret: WEBHOOK_SECRET,
+      env: {},
+      ...overrides,
+    }),
+  };
+}
+
+function signedWebhook(
+  payload: Record<string, unknown>,
+  secret = WEBHOOK_SECRET,
+): { headers: Record<string, string>; body: string } {
+  const raw = JSON.stringify(payload);
+  const messageId = "evt-message-1";
+  const timestamp = "2026-10-07T10:01:00Z";
+  const signature = `sha256=${createHmac("sha256", secret)
+    .update(messageId)
+    .update(timestamp)
+    .update(raw)
+    .digest("hex")}`;
+  return {
+    headers: {
+      "Twitch-Eventsub-Message-Id": messageId,
+      "Twitch-Eventsub-Message-Timestamp": timestamp,
+      "Twitch-Eventsub-Message-Signature": signature,
+      "Twitch-Eventsub-Message-Type": "notification",
+    },
+    body: raw,
+  };
+}
+
+connectorContractTests(harness().connector, { connection });
+livestreamConnectorContractTests(harness().connector, { connection });
+
+describe("twitch connector: manifest and identity", () => {
+  it("declares the requested honest capability surface", () => {
+    const manifest = harness().connector.manifest();
+    expect(manifest).toMatchObject({
+      id: "twitch",
+      displayName: "Twitch",
+      capabilities: {
+        publishText: false,
+        feed: false,
+        comments: true,
+        amplifyRepost: false,
+        amplifyQuote: false,
+        amplifyShare: false,
+        livestreams: true,
+        createLivestream: false,
+        manageLivestream: false,
+        livePlaybackSource: true,
+        liveChatRead: true,
+        liveChatModeration: true,
+        analytics: true,
+        livestreamAnalytics: true,
+        webhooks: true,
+      },
+    });
+    expect(manifest.connectionFields).toEqual([
+      expect.objectContaining({ name: "clientId", required: true, secret: false }),
+      expect.objectContaining({ name: "accessToken", required: true, secret: true }),
+      expect.objectContaining({ name: "broadcasterId", required: true, secret: false }),
+    ]);
+  });
+
+  it("maps /helix/users and sends both required auth headers", async () => {
+    const { state, connector } = harness();
+    await expect(connector.getIdentity(connection)).resolves.toEqual({
+      provider: "twitch",
+      remoteId: BROADCASTER_ID,
+      handle: "tmbh_live",
+      displayName: "TMBH Live",
+      avatarUrl: "https://static.example/avatar.png",
+    });
+    expect(state.calls[0]?.url.pathname).toBe("/helix/users");
+  });
+});
+
+describe("twitch connector: livestreams", () => {
+  it("maps a live Helix stream and replaces the thumbnail template", async () => {
+    const { state, connector } = harness();
+    const result = await connector.getLiveStreams?.(connection, { limit: 10 });
+    expect(result).toEqual({
+      items: [
+        {
+          id: stream.id,
+          provider: "twitch",
+          connectionId: connection.id,
+          remoteId: stream.id,
+          title: stream.title,
+          state: "live",
+          startedAt: new Date(stream.started_at),
+          playbackUrls: ["https://static.example/live/1280x720.jpg"],
+        },
+      ],
+    });
+    const call = state.calls[0];
+    expect(call?.url.searchParams.get("user_id")).toBe(BROADCASTER_ID);
+    expect(call?.url.searchParams.get("first")).toBe("10");
+  });
+
+  it("maps empty stream data to offline (an empty page)", async () => {
+    const { state, connector } = harness();
+    state.live = false;
+    await expect(connector.getLiveStreams?.(connection, { limit: 10 })).resolves.toEqual({ items: [] });
+  });
+
+  it("resolves a channel live source by channelId through /helix/streams?user_login=", async () => {
+    const { state, connector } = harness();
+    await expect(
+      connector.resolveLiveSource?.(connection, { channelId: "tmbh_live" }),
+    ).resolves.toEqual({
+      playbackHlsUrl: "https://usher.ttvnw.net/api/channel/hls/tmbh_live.m3u8",
+      live: true,
+    });
+    const call = state.calls[0];
+    expect(call?.url.pathname).toBe("/helix/streams");
+    expect(call?.url.searchParams.get("user_login")).toBe("tmbh_live");
+  });
+
+  it("derives the login from an external URL (path and ?channel=)", async () => {
+    const { state, connector } = harness();
+    await expect(
+      connector.resolveLiveSource?.(connection, { externalUrl: "https://www.twitch.tv/TMBH_Live" }),
+    ).resolves.toMatchObject({ live: true });
+    expect(state.calls[0]?.url.searchParams.get("user_login")).toBe("tmbh_live");
+    await expect(
+      connector.resolveLiveSource?.(connection, { externalUrl: "https://player.example.com/embed?channel=TMBH_Live" }),
+    ).resolves.toMatchObject({ live: true });
+  });
+
+  it("reports offline with a null playback URL and no caller error", async () => {
+    const offline = harness();
+    offline.state.live = false;
+    const { connector } = offline;
+    await expect(
+      connector.resolveLiveSource?.(connection, { channelId: "tmbh_live" }),
+    ).resolves.toEqual({ playbackHlsUrl: null, live: false });
+  });
+
+  it("constructs the Twitch HLS source for the requested live stream", async () => {
+    const { connector } = harness();
+    await expect(
+      connector.getStreamPlaybackSources?.(connection, { remoteId: stream.id }),
+    ).resolves.toEqual([
+      {
+        remoteId: stream.id,
+        url: "https://usher.ttvnw.net/api/channel/hls/tmbh_live.m3u8",
+        kind: "hls",
+        protocol: "https",
+      },
+    ]);
+    await expect(
+      connector.getStreamPlaybackSources?.(connection, { remoteId: "not-live" }),
+    ).resolves.toEqual([]);
+  });
+});
+
+describe("twitch connector: EventSub chat and webhooks", () => {
+  it("creates EventSub subscriptions with condition, callback and secret", async () => {
+    const { state, connector } = harness();
+    const result = await connector.subscribeWebhooks?.(connection, {
+      topics: ["stream.online", "channel.chat.message"],
+    });
+    expect(result?.subscriptionId).toBe("eventsub-1,eventsub-2");
+    const calls = state.calls.filter((call) => call.url.pathname === "/helix/eventsub/subscriptions");
+    expect(calls).toHaveLength(2);
+    expect(body(calls[0]?.init)).toEqual({
+      type: "stream.online",
+      version: "1",
+      condition: { broadcaster_user_id: BROADCASTER_ID },
+      transport: {
+        method: "webhook",
+        callback: "https://app.example.com/webhooks/twitch",
+        secret: WEBHOOK_SECRET,
+      },
+    });
+    expect(body(calls[1]?.init)).toMatchObject({
+      type: "channel.chat.message",
+      condition: { broadcaster_user_id: BROADCASTER_ID, user_id: BROADCASTER_ID },
+    });
+  });
+
+  it("verifies HMAC-SHA256, normalizes, and buffers chat for both read surfaces", async () => {
+    const { connector } = harness();
+    await connector.getLiveStreams?.(connection, { limit: 10 });
+    await connector.subscribeWebhooks?.(connection, { topics: ["stream.online"] });
+    const signed = signedWebhook({
+      subscription: { id: "sub-chat", type: "channel.chat.message", status: "enabled" },
+      event: {
+        broadcaster_user_id: BROADCASTER_ID,
+        chatter_user_login: "viewer_one",
+        message_id: "chat-1",
+        message: { text: "hello chat" },
+      },
+    });
+    const event = await connector.handleWebhook?.(signed);
+    expect(event).toMatchObject({
+      provider: "twitch",
+      eventType: "channel.chat.message",
+      connectionKey: connection.id,
+      receivedAt: new Date("2026-10-07T10:01:00Z"),
+    });
+    const chat = await connector.getLiveChat?.(connection, { liveRemoteId: stream.id, limit: 10 });
+    expect(chat?.items[0]).toMatchObject({
+      id: "chat-1",
+      authorHandle: "viewer_one",
+      text: "hello chat",
+      liveStreamId: stream.id,
+      isModerated: false,
+    });
+    const comments = await connector.getComments?.(connection, { onRemoteId: stream.id, limit: 10 });
+    expect(comments?.items[0]).toMatchObject({
+      remoteId: "chat-1",
+      onRemoteId: stream.id,
+      authorHandle: "viewer_one",
+      text: "hello chat",
+    });
+  });
+
+  it("rejects an invalid EventSub signature and non-raw bodies", async () => {
+    const { connector } = harness();
+    await connector.subscribeWebhooks?.(connection, { topics: ["stream.online"] });
+    const payload = {
+      subscription: { id: "sub-1", type: "stream.online", status: "enabled" },
+      event: { broadcaster_user_id: BROADCASTER_ID },
+    };
+    await expect(connector.handleWebhook?.(signedWebhook(payload, "wrong-secret"))).rejects.toThrow(
+      /signature mismatch/,
+    );
+    await expect(
+      connector.handleWebhook?.({ headers: signedWebhook(payload).headers, body: payload }),
+    ).rejects.toThrow(/raw body/);
+  });
+
+  it("documents the IRC requirement and delegates when an adapter is supplied", async () => {
+    const withoutIrc = harness().connector;
+    await expect(
+      withoutIrc.moderateLiveChat?.(connection, {
+        liveRemoteId: stream.id,
+        messageRemoteId: "chat-1",
+        action: "delete",
+      }),
+    ).rejects.toThrow(/IRC adapter/);
+
+    const calls: string[] = [];
+    const withIrc = harness({
+      ircModerate: async (_connection, request) => {
+        calls.push(`${request.action}:${request.messageRemoteId}`);
+      },
+    }).connector;
+    await withIrc.moderateLiveChat?.(connection, {
+      liveRemoteId: stream.id,
+      messageRemoteId: "chat-1",
+      action: "delete",
+    });
+    expect(calls).toEqual(["delete:chat-1"]);
+  });
+});
+
+describe("twitch connector: analytics", () => {
+  it("maps stream analytics totals and chronological series", async () => {
+    const { state, connector } = harness();
+    const result = await connector.getAnalytics?.(connection, {
+      subjectRemoteId: stream.id,
+      from: new Date("2026-10-06T00:00:00Z"),
+      to: new Date("2026-10-08T00:00:00Z"),
+    });
+    expect(result).toEqual({
+      values: { unique_viewers: 180, average_viewers: 55 },
+      series: [
+        {
+          at: new Date("2026-10-06T10:00:00Z"),
+          values: { unique_viewers: 80, average_viewers: 25 },
+        },
+        {
+          at: new Date("2026-10-07T10:00:00Z"),
+          values: { unique_viewers: 100, average_viewers: 30 },
+        },
+      ],
+    });
+    const call = state.calls[0];
+    expect(call?.url.pathname).toBe("/helix/analytics/streams");
+    expect(call?.url.searchParams.get("broadcaster_id")).toBe(BROADCASTER_ID);
+    expect(call?.url.searchParams.get("stream_id")).toBe(stream.id);
+  });
+});
diff --git a/packages/connector-twitch/src/index.ts b/packages/connector-twitch/src/index.ts
new file mode 100644
index 0000000..8f9a4ae
--- /dev/null
+++ b/packages/connector-twitch/src/index.ts
@@ -0,0 +1,688 @@
+/**
+ * Twitch connector — Helix reads plus EventSub webhooks.
+ *
+ * Streams are created by pushing RTMP, not by a Helix create call, so this
+ * connector deliberately exposes neither createLiveStream nor
+ * updateLiveStream. Live chat has no history/polling endpoint: EventSub chat
+ * notifications received by handleWebhook are buffered for getLiveChat and
+ * getComments. Sending and moderation require IRC; only moderation is part of
+ * this connector's declared surface and needs an injected IRC adapter.
+ *
+ * Stream keys are credentials. This connector never returns a stream key or
+ * includes one in a LiveStream. An integration which retrieves one must put it
+ * into CredentialAccessor rather than expose the raw value to callers.
+ */
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import type {
+  Comment,
+  ConnectorCapabilities,
+  ConnectorConnection,
+  CredentialRef,
+  LiveChatMessage,
+  LiveStream,
+  NormalizedIdentity,
+  LiveSourceResolution,
+  NormalizedWebhookEvent,
+  Page,
+  StreamPlaybackSource,
+} from "@tactical-media-broadcast-hub/core";
+import {
+  assertValidManifest,
+  AuthError,
+  CapabilityNotSupportedError,
+  ConnectorError,
+  InMemoryCredentials,
+  pageOf,
+  RateLimitedHttpClient,
+  RateLimitError,
+  type AuthorizationRequest,
+  type AuthorizationResult,
+  type ConnectorManifest,
+  type CredentialAccessor,
+  type PlatformConnector,
+} from "@tactical-media-broadcast-hub/connector-sdk";
+
+const PROVIDER = "twitch";
+const API_BASE = "https://api.twitch.tv/helix";
+const SIGNATURE_HEADER = "twitch-eventsub-message-signature";
+const MESSAGE_ID_HEADER = "twitch-eventsub-message-id";
+const TIMESTAMP_HEADER = "twitch-eventsub-message-timestamp";
+const DEFAULT_WEBHOOK_TOPICS = ["stream.online", "stream.offline"];
+const WEBHOOK_SECRET_KEY = "eventsub_webhook_secret";
+const ACCESS_TOKEN_KEY = "access_token";
+
+const CAPABILITIES: ConnectorCapabilities = {
+  publishText: false,
+  feed: false,
+  comments: true,
+  amplifyRepost: false,
+  amplifyQuote: false,
+  amplifyShare: false,
+  livestreams: true,
+  createLivestream: false,
+  manageLivestream: false,
+  livePlaybackSource: true,
+  liveChatRead: true,
+  liveChatWrite: false,
+  liveChatModeration: true,
+  analytics: true,
+  livestreamAnalytics: true,
+  webhooks: true,
+};
+
+export interface TwitchConnectorOptions {
+  fetchImpl?: typeof fetch;
+  requestsPerSecond?: number;
+  sleep?: (ms: number) => Promise<void>;
+  credentials?: CredentialAccessor;
+  /** Public HTTPS EventSub callback URL. */
+  webhookPublicUrl?: string;
+  /** Stable EventSub secret; overrides TWITCH_EVENTSUB_SECRET. */
+  webhookSecret?: string;
+  env?: Record<string, string | undefined>;
+  /** IRC bridge supplied by the host application for moderation operations. */
+  ircModerate?: (
+    connection: ConnectorConnection,
+    request: {
+      liveRemoteId: string;
+      messageRemoteId: string;
+      action: "delete" | "timeout" | "ban";
+    },
+  ) => Promise<void>;
+}
+
+export interface TwitchAuthorizationRequest extends AuthorizationRequest {
+  fields?: Record<string, string>;
+  providerMetadata?: Record<string, unknown>;
+}
+
+interface HelixList<T> {
+  data: T[];
+  pagination?: { cursor?: string };
+}
+
+interface TwitchUser {
+  id: string;
+  login: string;
+  display_name?: string;
+  profile_image_url?: string;
+  broadcaster_type?: string;
+}
+
+interface TwitchStream {
+  id: string;
+  user_id: string;
+  user_login?: string;
+  user_name?: string;
+  type?: string;
+  title?: string;
+  viewer_count?: number;
+  started_at?: string;
+  game_name?: string;
+  thumbnail_url?: string;
+}
+
+interface EventSubSubscription {
+  id: string;
+  type?: string;
+  status?: string;
+}
+
+interface EventSubEnvelope {
+  subscription?: { id?: string; type?: string; status?: string };
+  event?: Record<string, unknown>;
+  challenge?: string;
+}
+
+interface StoredWebhookSecret {
+  secret: string;
+  connectionId: string;
+}
+
+function nonEmpty(value: unknown): string | undefined {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+function headerValue(headers: Record<string, string>, name: string): string | undefined {
+  return Object.entries(headers).find(([key]) => key.toLowerCase() === name)?.[1];
+}
+
+function rawBodyBytes(body: unknown): Uint8Array {
+  if (typeof body === "string") return Buffer.from(body);
+  if (body instanceof Uint8Array) return body;
+  throw new ConnectorError(
+    `${PROVIDER}: handleWebhook needs the raw body (string or bytes) for signature verification`,
+    PROVIDER,
+  );
+}
+
+function thumbnailUrl(template: string | undefined): string | undefined {
+  if (template === undefined || template.length === 0) return undefined;
+  return template.replace("{width}", "1280").replace("{height}", "720");
+}
+
+/** Extract a twitch channel login from a URL path or ?channel= query. */
+function loginFromUrl(raw: string | undefined): string | undefined {
+  if (raw === undefined || raw.length === 0) return undefined;
+  let url: URL;
+  try { url = new URL(raw); } catch { return undefined; }
+  const query = url.searchParams.get("channel");
+  if (query !== null && query.length > 0) return query.toLowerCase();
+  const segments = url.pathname.split("/").filter((segment) => segment.length > 0);
+  return segments.length > 0 ? segments[segments.length - 1]!.toLowerCase() : undefined;
+}
+
+function hlsUrl(login: string): string {
+  return `https://usher.ttvnw.net/api/channel/hls/${encodeURIComponent(login)}.m3u8`;
+}
+
+function mapLiveStream(connection: ConnectorConnection, stream: TwitchStream): LiveStream {
+  const preview = thumbnailUrl(stream.thumbnail_url);
+  const result: LiveStream = {
+    id: stream.id,
+    provider: PROVIDER,
+    connectionId: connection.id,
+    remoteId: stream.id,
+    title: stream.title ?? stream.user_name ?? stream.user_login ?? "Twitch livestream",
+    state: stream.type === "live" ? "live" : "waiting",
+    playbackUrls: preview === undefined ? [] : [preview],
+  };
+  if (stream.started_at !== undefined) result.startedAt = new Date(stream.started_at);
+  return result;
+}
+
+function eventText(event: Record<string, unknown>): string | undefined {
+  const message = event.message;
+  if (typeof message !== "object" || message === null) return undefined;
+  return nonEmpty((message as Record<string, unknown>).text);
+}
+
+function numericMetrics(record: Record<string, unknown>): Record<string, number> {
+  const result: Record<string, number> = {};
+  for (const [key, value] of Object.entries(record)) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      result[key] = value;
+      continue;
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) continue;
+    for (const [nestedKey, nestedValue] of Object.entries(value as Record<string, unknown>)) {
+      if (typeof nestedValue === "number" && Number.isFinite(nestedValue)) {
+        result[nestedKey] = nestedValue;
+      }
+    }
+  }
+  return result;
+}
+
+export function createTwitchConnector(options: TwitchConnectorOptions = {}): PlatformConnector {
+  const client = new RateLimitedHttpClient({
+    fetchImpl: options.fetchImpl,
+    requestsPerSecond: options.requestsPerSecond ?? 2,
+    sleep: options.sleep,
+  });
+  const credentials = options.credentials ?? new InMemoryCredentials();
+  const env = options.env ?? process.env;
+  const configuredWebhookSecret = options.webhookSecret ?? env.TWITCH_EVENTSUB_SECRET;
+  const webhookSecrets: StoredWebhookSecret[] =
+    configuredWebhookSecret === undefined || configuredWebhookSecret.length === 0
+      ? []
+      : [{ secret: configuredWebhookSecret, connectionId: "" }];
+  const chatByStream = new Map<string, LiveChatMessage[]>();
+  const activeStreamByBroadcaster = new Map<string, string>();
+
+  const manifest: ConnectorManifest = {
+    id: PROVIDER,
+    displayName: "Twitch",
+    capabilities: CAPABILITIES,
+    connectionFields: [
+      {
+        name: "clientId",
+        label: "Client ID",
+        required: true,
+        secret: false,
+      },
+      {
+        name: "accessToken",
+        label: "OAuth access token",
+        required: true,
+        secret: true,
+      },
+      {
+        name: "broadcasterId",
+        label: "Broadcaster user ID",
+        required: true,
+        secret: false,
+        pattern: "^[0-9]+$",
+      },
+    ],
+    oauth: {
+      kind: "oauth2-redirect",
+      authorizeUrlTemplate: "https://id.twitch.tv/oauth2/authorize",
+      scopes: [
+        "analytics:read:games",
+        "channel:manage:broadcast",
+        "user:read:chat",
+        "moderator:manage:chat_messages",
+      ],
+    },
+    webhookRoute: "/webhooks/twitch",
+    docsUrl: "https://dev.twitch.tv/docs/api/",
+  };
+
+  function clientIdOf(connection: ConnectorConnection): string {
+    const clientId = nonEmpty(connection.fields.clientId);
+    if (clientId === undefined) {
+      throw new AuthError(`${PROVIDER}: connection ${connection.id} has no clientId`, PROVIDER, false);
+    }
+    return clientId;
+  }
+
+  function broadcasterIdOf(connection: ConnectorConnection): string {
+    const broadcasterId = nonEmpty(connection.fields.broadcasterId) ?? nonEmpty(connection.channelId);
+    if (broadcasterId === undefined) {
+      throw new ConnectorError(`${PROVIDER}: connection ${connection.id} has no broadcasterId`, PROVIDER);
+    }
+    return broadcasterId;
+  }
+
+  async function tokenOf(connection: ConnectorConnection): Promise<string> {
+    try {
+      return await credentials.getAccessToken(connection);
+    } catch {
+      const token = nonEmpty(connection.fields.accessToken);
+      if (token !== undefined) return token;
+      throw new AuthError(`${PROVIDER}: connection ${connection.id} has no access token`, PROVIDER, false);
+    }
+  }
+
+  async function helix<T>(
+    connection: ConnectorConnection,
+    method: "GET" | "POST",
+    path: string,
+    query: Record<string, string> = {},
+    body?: Record<string, unknown>,
+  ): Promise<T> {
+    const url = new URL(`${API_BASE}${path}`);
+    for (const [key, value] of Object.entries(query)) url.searchParams.set(key, value);
+    const headers: Record<string, string> = {
+      accept: "application/json",
+      "Client-ID": clientIdOf(connection),
+      Authorization: `Bearer ${await tokenOf(connection)}`,
+    };
+    const init: RequestInit = { method, headers };
+    if (body !== undefined) {
+      headers["content-type"] = "application/json";
+      init.body = JSON.stringify(body);
+    }
+    const response = await client.request(PROVIDER, url.toString(), init);
+    if (!response.ok) {
+      let detail = "";
+      try {
+        const error = (await response.json()) as { message?: unknown };
+        if (typeof error.message === "string") detail = `: ${error.message}`;
+      } catch {
+        detail = "";
+      }
+      const message = `${PROVIDER}: HTTP ${response.status} ${method} ${url.pathname}${detail}`;
+      if (response.status === 401 || response.status === 403) {
+        throw new AuthError(message, PROVIDER, false);
+      }
+      if (response.status === 429) throw new RateLimitError(PROVIDER);
+      throw new ConnectorError(message, PROVIDER);
+    }
+    const text = await response.text();
+    return (text.length === 0 ? {} : JSON.parse(text)) as T;
+  }
+
+  async function identity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+    const response = await helix<HelixList<TwitchUser>>(connection, "GET", "/users");
+    const user = response.data[0];
+    if (user === undefined) {
+      throw new AuthError(`${PROVIDER}: /users returned no identity for this token`, PROVIDER, false);
+    }
+    const result: NormalizedIdentity = {
+      provider: PROVIDER,
+      remoteId: user.id,
+      handle: user.login,
+    };
+    if (user.display_name !== undefined) result.displayName = user.display_name;
+    if (user.profile_image_url !== undefined) result.avatarUrl = user.profile_image_url;
+    return result;
+  }
+
+  async function streams(
+    connection: ConnectorConnection,
+    cursor: string | undefined,
+    limit: number,
+  ): Promise<HelixList<TwitchStream>> {
+    const query: Record<string, string> = {
+      user_id: broadcasterIdOf(connection),
+      first: String(Math.max(1, Math.min(100, limit))),
+    };
+    if (cursor !== undefined) query.after = cursor;
+    return helix<HelixList<TwitchStream>>(connection, "GET", "/streams", query);
+  }
+
+  function registerWebhookSecret(connection: ConnectorConnection, secret: string): void {
+    const configured = webhookSecrets.find(
+      (item) => item.connectionId.length === 0 && item.secret === secret,
+    );
+    if (configured !== undefined) {
+      configured.connectionId = connection.id;
+      return;
+    }
+    const existing = webhookSecrets.find((item) => item.connectionId === connection.id);
+    if (existing === undefined) webhookSecrets.push({ secret, connectionId: connection.id });
+    else existing.secret = secret;
+  }
+
+  async function webhookSecretFor(connection: ConnectorConnection): Promise<string> {
+    const configured = options.webhookSecret ?? env.TWITCH_EVENTSUB_SECRET;
+    if (configured !== undefined && configured.length > 0) {
+      registerWebhookSecret(connection, configured);
+      return configured;
+    }
+    try {
+      const saved = await credentials.getSecret(connection, WEBHOOK_SECRET_KEY);
+      registerWebhookSecret(connection, saved);
+      return saved;
+    } catch {
+      const generated = randomBytes(32).toString("hex");
+      await credentials.put(connection, WEBHOOK_SECRET_KEY, generated);
+      registerWebhookSecret(connection, generated);
+      return generated;
+    }
+  }
+
+  function verifyWebhook(
+    headers: Record<string, string>,
+    bytes: Uint8Array,
+  ): StoredWebhookSecret {
+    const signature = headerValue(headers, SIGNATURE_HEADER);
+    const messageId = headerValue(headers, MESSAGE_ID_HEADER);
+    const timestamp = headerValue(headers, TIMESTAMP_HEADER);
+    if (signature === undefined || messageId === undefined || timestamp === undefined) {
+      throw new AuthError(`${PROVIDER}: webhook is missing Twitch EventSub signature headers`, PROVIDER, false);
+    }
+    const supplied = Buffer.from(signature);
+    for (const candidate of webhookSecrets) {
+      const expected = Buffer.from(
+        `sha256=${createHmac("sha256", candidate.secret)
+          .update(messageId)
+          .update(timestamp)
+          .update(bytes)
+          .digest("hex")}`,
+      );
+      if (supplied.length === expected.length && timingSafeEqual(supplied, expected)) return candidate;
+    }
+    throw new AuthError(`${PROVIDER}: webhook signature mismatch`, PROVIDER, false);
+  }
+
+  function bufferChatEvent(event: Record<string, unknown>, receivedAt: Date): void {
+    const messageId = nonEmpty(event.message_id);
+    const text = eventText(event);
+    const broadcasterId = nonEmpty(event.broadcaster_user_id);
+    if (messageId === undefined || text === undefined || broadcasterId === undefined) return;
+    const streamId = activeStreamByBroadcaster.get(broadcasterId) ?? broadcasterId;
+    const message: LiveChatMessage = {
+      id: messageId,
+      provider: PROVIDER,
+      liveStreamId: streamId,
+      authorHandle:
+        nonEmpty(event.chatter_user_login) ?? nonEmpty(event.chatter_user_name) ?? "unknown",
+      text,
+      sentAt: receivedAt,
+      isModerated: false,
+    };
+    const messages = chatByStream.get(streamId) ?? [];
+    messages.push(message);
+    chatByStream.set(streamId, messages);
+  }
+
+  function chatPage(streamId: string, cursor: string | undefined, limit: number): Page<LiveChatMessage> {
+    const all = chatByStream.get(streamId) ?? [];
+    const parsed = cursor === undefined ? 0 : Number(cursor);
+    const start = Number.isInteger(parsed) && parsed >= 0 ? parsed : 0;
+    const items = all.slice(start, start + Math.max(0, limit));
+    const next = start + items.length;
+    return next < all.length ? pageOf(items, String(next)) : pageOf(items);
+  }
+
+  return {
+    manifest: () => {
+      assertValidManifest(manifest);
+      return manifest;
+    },
+
+    async authorize(input: TwitchAuthorizationRequest): Promise<AuthorizationResult> {
+      const fields = input.fields ?? {};
+      const clientId = nonEmpty(fields.clientId);
+      const accessToken = nonEmpty(fields.accessToken);
+      const broadcasterId = nonEmpty(fields.broadcasterId);
+      if (clientId === undefined || accessToken === undefined || broadcasterId === undefined) {
+        throw new ConnectorError(
+          `${PROVIDER}: complete OAuth first, then provide fields.clientId, fields.accessToken and fields.broadcasterId`,
+          PROVIDER,
+        );
+      }
+      const metadata = input.providerMetadata ?? {};
+      const connectionId = nonEmpty(metadata.connectionId) ?? `${PROVIDER}:${input.workspaceId}:${broadcasterId}`;
+      const credentialId: CredentialRef = { kind: "credential-ref", id: connectionId };
+      const connection: ConnectorConnection = {
+        id: connectionId,
+        workspaceId: input.workspaceId,
+        provider: PROVIDER,
+        channelId: broadcasterId,
+        credentialId,
+        fields: { clientId, broadcasterId },
+        createdAt: new Date(),
+      };
+      await credentials.put(connection, ACCESS_TOKEN_KEY, accessToken);
+      return { connection, identity: await identity(connection) };
+    },
+
+    async getIdentity(connection: ConnectorConnection): Promise<NormalizedIdentity> {
+      return identity(connection);
+    },
+
+    async getLiveStreams(
+      connection: ConnectorConnection,
+      request: { cursor?: string; limit: number },
+    ): Promise<Page<LiveStream>> {
+      const response = await streams(connection, request.cursor, request.limit);
+      const items = response.data.map((stream) => {
+        activeStreamByBroadcaster.set(stream.user_id, stream.id);
+        return mapLiveStream(connection, stream);
+      });
+      return pageOf(items, response.pagination?.cursor);
+    },
+
+    async resolveLiveSource(
+      connection: ConnectorConnection,
+      request: { channelId?: string; externalUrl?: string },
+    ): Promise<LiveSourceResolution> {
+      // A login may arrive as a channel id field or inside an external URL;
+      // Helix answers both through user_login.
+      const login = nonEmpty(request.channelId) ?? loginFromUrl(request.externalUrl);
+      if (login === undefined) {
+        throw new ConnectorError(`${PROVIDER}: resolveLiveSource needs a channelId or externalUrl`, PROVIDER);
+      }
+      const response = await helix<HelixList<TwitchStream>>(connection, "GET", "/streams", {
+        user_login: login,
+        first: "1",
+      });
+      const stream = response.data[0];
+      if (stream === undefined || stream.type !== "live" || stream.user_login === undefined) {
+        return { playbackHlsUrl: null, live: false };
+      }
+      return { playbackHlsUrl: hlsUrl(stream.user_login), live: true };
+    },
+
+    async getStreamPlaybackSources(
+      connection: ConnectorConnection,
+      request: { remoteId: string },
+    ): Promise<StreamPlaybackSource[]> {
+      const response = await streams(connection, undefined, 100);
+      const stream = response.data.find((candidate) => candidate.id === request.remoteId);
+      if (stream === undefined || stream.type !== "live") return [];
+      const login = nonEmpty(stream.user_login);
+      if (login === undefined) {
+        throw new ConnectorError(`${PROVIDER}: stream ${stream.id} has no user_login for HLS playback`, PROVIDER);
+      }
+      return [
+        {
+          remoteId: stream.id,
+          url: hlsUrl(login),
+          kind: "hls",
+          protocol: "https",
+        },
+      ];
+    },
+
+    async getLiveChat(
+      _connection: ConnectorConnection,
+      request: { liveRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<LiveChatMessage>> {
+      return chatPage(request.liveRemoteId, request.cursor, request.limit);
+    },
+
+    async getComments(
+      _connection: ConnectorConnection,
+      request: { onRemoteId: string; cursor?: string; limit: number },
+    ): Promise<Page<Comment>> {
+      const page = chatPage(request.onRemoteId, request.cursor, request.limit);
+      return {
+        items: page.items.map((message) => ({
+          id: message.id,
+          provider: PROVIDER,
+          remoteId: message.id,
+          onRemoteId: request.onRemoteId,
+          authorHandle: message.authorHandle,
+          text: message.text,
+          createdAt: message.sentAt,
+        })),
+        ...(page.nextCursor === undefined ? {} : { nextCursor: page.nextCursor }),
+      };
+    },
+
+    async moderateLiveChat(
+      connection: ConnectorConnection,
+      request: {
+        liveRemoteId: string;
+        messageRemoteId: string;
+        action: "delete" | "timeout" | "ban";
+      },
+    ): Promise<void> {
+      if (options.ircModerate === undefined) {
+        throw new CapabilityNotSupportedError(
+          PROVIDER,
+          "live chat moderation without an IRC adapter (Twitch provides no REST operation for this connector)",
+        );
+      }
+      await options.ircModerate(connection, request);
+      const messages = chatByStream.get(request.liveRemoteId) ?? [];
+      const message = messages.find((candidate) => candidate.id === request.messageRemoteId);
+      if (message !== undefined) message.isModerated = true;
+    },
+
+    async getAnalytics(
+      connection: ConnectorConnection,
+      request: { subjectRemoteId?: string; from: Date; to: Date },
+    ): Promise<{ values: Record<string, number>; series: { at: Date; values: Record<string, number> }[] }> {
+      const response = await helix<HelixList<Record<string, unknown>>>(
+        connection,
+        "GET",
+        "/analytics/streams",
+        {
+          broadcaster_id: broadcasterIdOf(connection),
+          started_at: request.from.toISOString(),
+          ended_at: request.to.toISOString(),
+          ...(request.subjectRemoteId === undefined ? {} : { stream_id: request.subjectRemoteId }),
+        },
+      );
+      const values: Record<string, number> = {};
+      const series: { at: Date; values: Record<string, number> }[] = [];
+      for (const record of response.data) {
+        const metrics = numericMetrics(record);
+        for (const [name, value] of Object.entries(metrics)) values[name] = (values[name] ?? 0) + value;
+        const at = nonEmpty(record.started_at) ?? nonEmpty(record.timestamp) ?? nonEmpty(record.date);
+        if (at !== undefined) series.push({ at: new Date(at), values: metrics });
+      }
+      series.sort((left, right) => left.at.getTime() - right.at.getTime());
+      return { values, series };
+    },
+
+    async subscribeWebhooks(
+      connection: ConnectorConnection,
+      request: { topics: string[] },
+    ): Promise<{ subscriptionId: string }> {
+      const callback = options.webhookPublicUrl ?? env.TWITCH_EVENTSUB_CALLBACK_URL;
+      if (callback === undefined || callback.length === 0) {
+        throw new ConnectorError(
+          `${PROVIDER}: pass webhookPublicUrl or set TWITCH_EVENTSUB_CALLBACK_URL before subscribing`,
+          PROVIDER,
+        );
+      }
+      const secret = await webhookSecretFor(connection);
+      const topics = request.topics.length > 0 ? request.topics : DEFAULT_WEBHOOK_TOPICS;
+      const subscriptions: string[] = [];
+      for (const topic of topics) {
+        const condition: Record<string, string> = {
+          broadcaster_user_id: broadcasterIdOf(connection),
+        };
+        if (topic === "channel.chat.message") condition.user_id = broadcasterIdOf(connection);
+        const response = await helix<HelixList<EventSubSubscription>>(
+          connection,
+          "POST",
+          "/eventsub/subscriptions",
+          {},
+          {
+            type: topic,
+            version: "1",
+            condition,
+            transport: { method: "webhook", callback, secret },
+          },
+        );
+        const id = response.data[0]?.id;
+        if (id === undefined) {
+          throw new ConnectorError(`${PROVIDER}: EventSub returned no subscription id for ${topic}`, PROVIDER);
+        }
+        subscriptions.push(id);
+      }
+      return { subscriptionId: subscriptions.join(",") };
+    },
+
+    async handleWebhook(request: {
+      headers: Record<string, string>;
+      body: unknown;
+    }): Promise<NormalizedWebhookEvent> {
+      const bytes = rawBodyBytes(request.body);
+      const matched = verifyWebhook(request.headers, bytes);
+      let parsed: unknown;
+      try {
+        parsed = JSON.parse(Buffer.from(bytes).toString("utf8"));
+      } catch (cause) {
+        throw new ConnectorError(`${PROVIDER}: webhook body is not JSON`, PROVIDER, cause);
+      }
+      if (typeof parsed !== "object" || parsed === null) {
+        throw new ConnectorError(`${PROVIDER}: malformed EventSub payload`, PROVIDER);
+      }
+      const envelope = parsed as EventSubEnvelope;
+      const eventType = nonEmpty(envelope.subscription?.type);
+      if (eventType === undefined) {
+        throw new ConnectorError(`${PROVIDER}: EventSub payload has no subscription type`, PROVIDER);
+      }
+      const receivedAt = new Date(headerValue(request.headers, TIMESTAMP_HEADER) ?? Date.now());
+      if (eventType === "channel.chat.message" && envelope.event !== undefined) {
+        bufferChatEvent(envelope.event, receivedAt);
+      }
+      return {
+        provider: PROVIDER,
+        eventType,
+        payload: parsed as Record<string, unknown>,
+        receivedAt,
+        ...(matched.connectionId.length === 0 ? {} : { connectionKey: matched.connectionId }),
+      };
+    },
+  };
+}
diff --git a/packages/connector-twitch/tsconfig.json b/packages/connector-twitch/tsconfig.json
new file mode 100644
index 0000000..815323b
--- /dev/null
+++ b/packages/connector-twitch/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "preserveSymlinks": true,
+    "lib": ["ES2022", "DOM"]
+  },
+  "include": ["src"]
+}
diff --git a/packages/core/package.json b/packages/core/package.json
new file mode 100644
index 0000000..014f96f
--- /dev/null
+++ b/packages/core/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@tactical-media-broadcast-hub/core",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/core/src/capabilities.ts b/packages/core/src/capabilities.ts
new file mode 100644
index 0000000..9a1ff8f
--- /dev/null
+++ b/packages/core/src/capabilities.ts
@@ -0,0 +1,49 @@
+/**
+ * Declarative connector capabilities. The UI renders from these flags:
+ * an undeclared capability renders nothing, never a grayed-out lie.
+ */
+export interface ConnectorCapabilities {
+  publishText?: boolean;
+  publishImages?: boolean;
+  publishCarousel?: boolean;
+
+  publishVideo?: boolean;
+  shortFormVideo?: boolean;
+  longFormVideo?: boolean;
+
+  videoThumbnails?: boolean;
+  videoCaptions?: boolean;
+  playlists?: boolean;
+
+  feed?: boolean;
+  mentions?: boolean;
+  comments?: boolean;
+  replies?: boolean;
+  reactions?: boolean;
+  directMessages?: boolean;
+
+  /** Amplification: repost/boost/retweet an existing remote item. */
+  amplifyRepost?: boolean;
+  /** Amplification: quote-post / reshare with commentary. */
+  amplifyQuote?: boolean;
+  /** Amplification: share to story / crosspost variants. */
+  amplifyShare?: boolean;
+
+  livestreams?: boolean;
+  createLivestream?: boolean;
+  manageLivestream?: boolean;
+
+  livePlaybackSource?: boolean;
+
+  liveChatRead?: boolean;
+  liveChatWrite?: boolean;
+  liveChatModeration?: boolean;
+
+  analytics?: boolean;
+  videoAnalytics?: boolean;
+  livestreamAnalytics?: boolean;
+
+  webhooks?: boolean;
+  nativeScheduling?: boolean;
+  deletePublication?: boolean;
+}
diff --git a/packages/core/src/chat-contract.schema.ts b/packages/core/src/chat-contract.schema.ts
new file mode 100644
index 0000000..f2708b2
--- /dev/null
+++ b/packages/core/src/chat-contract.schema.ts
@@ -0,0 +1,201 @@
+/**
+ * Handwritten JSON Schema for the frozen S5 chat contract (§3.5).
+ *
+ * Written by hand rather than generated so the schema stays reviewable and the
+ * package gains no dependency; `chat-contract.test.ts` proves the schema
+ * accepts every type-shaped fixture and rejects the mutations that matter.
+ * Clients (Opticast S5b) validate a recorded WS transcript against these.
+ */
+import type { ChatMessage, Delivery, LiveChatCapability } from "./chat-contract.js";
+
+export const CHAT_MESSAGE_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://tactical-media-broadcast-hub.dev/schemas/chat-message.json",
+  title: "ChatMessage",
+  type: "object",
+  additionalProperties: false,
+  required: [
+    "seq",
+    "id",
+    "liveStreamId",
+    "connectionId",
+    "provider",
+    "providerMessageId",
+    "author",
+    "text",
+    "sentAt",
+    "receivedAt",
+    "isModerated",
+    "source",
+  ],
+  properties: {
+    seq: { type: "integer", minimum: 1 },
+    id: { type: "string", minLength: 1 },
+    liveStreamId: { type: "string", minLength: 1 },
+    connectionId: { type: "string", minLength: 1 },
+    provider: { type: "string", minLength: 1 },
+    providerMessageId: { type: "string", minLength: 1 },
+    author: {
+      type: "object",
+      additionalProperties: false,
+      required: ["handle", "color"],
+      properties: {
+        handle: { type: "string", minLength: 1 },
+        displayName: { type: "string" },
+        avatarUrl: { type: "string" },
+        badges: { type: "array", items: { type: "string" } },
+        color: { type: "string", pattern: "^(hsl\\(|#|rgb\\()[^)]*\\)?" },
+      },
+    },
+    text: { type: "string", minLength: 0, maxLength: 5000 },
+    sentAt: { type: "string", format: "date-time" },
+    receivedAt: { type: "string", format: "date-time" },
+    isModerated: { type: "boolean" },
+    replyTo: { type: "string" },
+    source: { enum: ["live-chat", "social-reply", "system"] },
+  },
+} as const;
+
+export const DELIVERY_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://tactical-media-broadcast-hub.dev/schemas/delivery.json",
+  title: "Delivery",
+  type: "object",
+  additionalProperties: false,
+  required: ["connectionId", "provider", "status"],
+  properties: {
+    connectionId: { type: "string", minLength: 1 },
+    provider: { type: "string", minLength: 1 },
+    status: { enum: ["queued", "sent", "failed", "unsupported"] },
+    error: { type: "string" },
+  },
+} as const;
+
+export const LIVE_CHAT_CAPABILITY_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://tactical-media-broadcast-hub.dev/schemas/live-chat-capability.json",
+  title: "LiveChatCapability",
+  type: "object",
+  additionalProperties: false,
+  required: ["connectionId", "provider", "read", "reply", "moderate", "state"],
+  properties: {
+    connectionId: { type: "string", minLength: 1 },
+    provider: { type: "string", minLength: 1 },
+    read: { type: "boolean" },
+    reply: { type: "boolean" },
+    moderate: { type: "boolean" },
+    state: { enum: ["ok", "paused:quota", "paused:rate", "degraded"] },
+    reason: { type: "string" },
+  },
+} as const;
+
+/** A `msg` frame payload on the livechat topic. */
+export const CHAT_HUB_FRAME_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://tactical-media-broadcast-hub.dev/schemas/chat-hub-frame.json",
+  title: "ChatHubFrame",
+  oneOf: [ { required: ["message"] }, { required: ["action", "targetMessageId"] }, { required: ["messageId", "delivery"] }, { required: ["provider", "reason"] } ],
+  type: "object",
+  additionalProperties: false,
+  required: ["kind", "liveStreamId", "channelId", "seq"],
+  properties: {
+    kind: { const: "chat" },
+    liveStreamId: { type: "string", minLength: 1 },
+    channelId: { type: "string", minLength: 1 },
+    seq: { type: "integer", minimum: 1 },
+    message: CHAT_MESSAGE_SCHEMA,
+    action: { enum: ["delete", "timeout", "ban"] },
+    targetMessageId: { type: "string" },
+    targetHandle: { type: "string" },
+    messageId: { type: "string" },
+    delivery: { type: "array", items: DELIVERY_SCHEMA },
+    provider: { type: "string" },
+    reason: { type: "string" },
+  },
+} as const;
+
+export const DEVICE_PAIRING_SCHEMA = {
+  type: "object", additionalProperties: false, required: ["pairingCode", "qrPayload", "expiresAt"],
+  properties: { pairingCode: { type: "string", pattern: "^[A-Z0-9]{4}-[A-Z0-9]{4}$" }, qrPayload: { type: "string" }, expiresAt: { type: "string", format: "date-time" } },
+} as const;
+export const DEVICE_REDEEM_BODY_SCHEMA = {
+  type: "object", additionalProperties: false, required: ["pairingCode", "deviceName"],
+  properties: { pairingCode: { type: "string", pattern: "^[A-Z0-9]{4}-[A-Z0-9]{4}$" }, deviceName: { type: "string", minLength: 1, maxLength: 120 } },
+} as const;
+export const DEVICE_REDEEM_RESPONSE_SCHEMA = {
+  type: "object", additionalProperties: false, required: ["deviceToken", "workspaceId"],
+  properties: { deviceToken: { type: "string", minLength: 1 }, workspaceId: { type: "string", minLength: 1 } },
+} as const;
+export const SEND_CHAT_BODY_SCHEMA = {
+  type: "object", additionalProperties: false, required: ["text", "targets"],
+  properties: { text: { type: "string", minLength: 1, maxLength: 500 }, replyTo: { type: "string" }, targets: { oneOf: [{ const: "all" }, { type: "array", minItems: 1, maxItems: 32, items: { type: "string", minLength: 1 } }] } },
+} as const;
+export const MODERATE_CHAT_BODY_SCHEMA = {
+  type: "object", additionalProperties: false, required: ["action"],
+  properties: { action: { enum: ["delete", "timeout", "ban"] }, durationSeconds: { type: "integer", minimum: 1, maximum: 1209600 } },
+  if: { properties: { action: { const: "timeout" } } }, then: { required: ["durationSeconds"] },
+} as const;
+const wsObject = (op: string, required: readonly string[] = [], properties: Record<string, unknown> = {}) => ({
+  type: "object", additionalProperties: false, required: ["op", ...required], properties: { op: { const: op }, ...properties },
+});
+export const LIVE_CHAT_WS_SCHEMA = {
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://tactical-media-broadcast-hub.dev/schemas/live-chat-ws.json",
+  oneOf: [
+    wsObject("auth", ["token"], { token: { type: "string", minLength: 1 } }),
+    wsObject("ready"), wsObject("close", ["reason"], { reason: { type: "string" } }),
+    wsObject("subscribe", ["id", "topic", "liveId"], { id: { type: "string", minLength: 1 }, topic: { const: "livechat" }, liveId: { type: "string", minLength: 1 }, lastSeq: { type: "integer", minimum: 0 } }),
+    wsObject("subscribe", ["id", "topic", "channelId"], { id: { type: "string", minLength: 1 }, topic: { const: "channel" }, channelId: { type: "string", minLength: 1 }, lastSeq: { type: "integer", minimum: 0 } }),
+    wsObject("ack", ["id", "fromSeq"], { id: { type: "string" }, fromSeq: { type: "integer", minimum: 0 } }),
+    wsObject("nack", ["id", "reason"], { id: { type: "string" }, reason: { type: "string" } }),
+    wsObject("msg", ["topic", "seq", "type", "payload"], { topic: { enum: ["livechat", "channel"] }, seq: { type: "integer", minimum: 1 }, type: { enum: ["chat.message", "chat.moderated", "chat.delivery", "chat.gap", "stream.state", "capability"] }, payload: { type: "object" } }),
+    wsObject("resync", ["topic"], { topic: { enum: ["livechat", "channel"] } }),
+    wsObject("unsubscribe", ["id"], { id: { type: "string" } }), wsObject("ping"), wsObject("pong"),
+  ],
+} as const;
+
+export const CHAT_CONTRACT_SCHEMAS = {
+  ws: LIVE_CHAT_WS_SCHEMA,
+  devicePairing: DEVICE_PAIRING_SCHEMA,
+  deviceRedeemBody: DEVICE_REDEEM_BODY_SCHEMA,
+  deviceRedeemResponse: DEVICE_REDEEM_RESPONSE_SCHEMA,
+  sendBody: SEND_CHAT_BODY_SCHEMA,
+  moderateBody: MODERATE_CHAT_BODY_SCHEMA,
+  chatMessage: CHAT_MESSAGE_SCHEMA,
+  delivery: DELIVERY_SCHEMA,
+  capability: LIVE_CHAT_CAPABILITY_SCHEMA,
+  chatHubFrame: CHAT_HUB_FRAME_SCHEMA,
+} as const;
+
+export type ChatContractSchemaName = keyof typeof CHAT_CONTRACT_SCHEMAS;
+
+/** Reference fixtures typed by the TS contract (used by tests and clients). */
+export const CHAT_CONTRACT_EXAMPLES: {
+  chatMessage: ChatMessage;
+  delivery: Delivery;
+  capability: LiveChatCapability;
+} = {
+  chatMessage: {
+    seq: 1,
+    id: "00000000-0000-4000-8000-000000000001",
+    liveStreamId: "live-1",
+    connectionId: "00000000-0000-4000-8000-000000000002",
+    provider: "mock-livestream",
+    providerMessageId: "msg-1",
+    author: { handle: "viewer@example", color: "hsl(120 70% 62%)" },
+    text: "hello from the contract",
+    sentAt: "2026-10-07T10:00:00.000Z",
+    receivedAt: "2026-10-07T10:00:00.050Z",
+    isModerated: false,
+    source: "live-chat",
+  },
+  delivery: { connectionId: "00000000-0000-4000-8000-000000000002", provider: "mock-livestream", status: "sent" },
+  capability: {
+    connectionId: "00000000-0000-4000-8000-000000000002",
+    provider: "mock-livestream",
+    read: true,
+    reply: true,
+    moderate: true,
+    state: "ok",
+  },
+};
diff --git a/packages/core/src/chat-contract.test.ts b/packages/core/src/chat-contract.test.ts
new file mode 100644
index 0000000..5d594ea
--- /dev/null
+++ b/packages/core/src/chat-contract.test.ts
@@ -0,0 +1,108 @@
+import { describe, expect, it } from "vitest";
+import {
+  CHAT_CONTRACT_EXAMPLES,
+  CHAT_CONTRACT_SCHEMAS,
+  CHAT_MESSAGE_SCHEMA,
+  CHAT_HUB_FRAME_SCHEMA,
+} from "./chat-contract.schema.js";
+import { authorColor, isValidChatMessage, type ChatMessage } from "./chat-contract.js";
+
+/** Minimal draft-2020 subset validator — enough to prove schema/type parity
+ * without a dependency. Checks the constraints this contract relies on. */
+function validate(schema: unknown, value: unknown, path = "$"): string[] {
+  const errors: string[] = [];
+  const s = schema as Record<string, unknown>;
+  if (Array.isArray(s.oneOf) && s.oneOf.filter(branch => validate(branch, value).length === 0).length !== 1) errors.push(`${path}: oneOf`);
+  if (s.if && validate(s.if, value).length === 0 && s.then) errors.push(...validate(s.then, value, path));
+  if (Array.isArray(value)) {
+    if (typeof s.minItems === "number" && value.length < s.minItems) errors.push(`${path}: minItems`);
+    if (typeof s.maxItems === "number" && value.length > s.maxItems) errors.push(`${path}: maxItems`);
+  }
+  if (s.const !== undefined && JSON.stringify(value) !== JSON.stringify(s.const)) errors.push(`${path}: const mismatch`);
+  if (s.enum !== undefined && !(s.enum as unknown[]).some(v => v === value)) errors.push(`${path}: not in enum`);
+  if (s.type !== undefined) {
+    const t = s.type as string;
+    const ok =
+      (t === "object" && typeof value === "object" && value !== null && !Array.isArray(value)) ||
+      (t === "array" && Array.isArray(value)) ||
+      (t === "string" && typeof value === "string") ||
+      (t === "boolean" && typeof value === "boolean") ||
+      (t === "integer" && typeof value === "number" && Number.isInteger(value));
+    if (!ok) { errors.push(`${path}: expected ${t}`); return errors; }
+  }
+  if (typeof value === "number") {
+    if (s.minimum !== undefined && value < (s.minimum as number)) errors.push(`${path}: below minimum`);
+    if (s.maximum !== undefined && value > (s.maximum as number)) errors.push(`${path}: above maximum`);
+  }
+  if (typeof value === "string") {
+    if (s.minLength !== undefined && value.length < (s.minLength as number)) errors.push(`${path}: too short`);
+    if (s.maxLength !== undefined && value.length > (s.maxLength as number)) errors.push(`${path}: too long`);
+    if (s.pattern !== undefined && !new RegExp(s.pattern as string).test(value)) errors.push(`${path}: pattern`);
+  }
+  if (Array.isArray(value) && s.items !== undefined) value.forEach((v, i) => errors.push(...validate(s.items, v, `${path}[${i}]`)));
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    const props = (s.properties ?? {}) as Record<string, unknown>;
+    const record = value as Record<string, unknown>;
+    if (s.required !== undefined) for (const key of s.required as string[]) if (record[key] === undefined) errors.push(`${path}.${key}: required`);
+    if (s.additionalProperties === false) for (const key of Object.keys(record)) if (props[key] === undefined) errors.push(`${path}.${key}: additional property`);
+    for (const [key, sub] of Object.entries(props)) if (record[key] !== undefined) errors.push(...validate(sub, record[key], `${path}.${key}`));
+  }
+  return errors;
+}
+
+describe("S5 chat contract (frozen §3.5 shapes)", () => {
+  it("freezes pairing and op/liveId WS payloads, including zero resume cursor", () => {
+    expect(validate(CHAT_CONTRACT_SCHEMAS.ws, { op: "subscribe", id: "chat", topic: "livechat", liveId: "live-1", lastSeq: 0 })).toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.ws, { op: "subscribe", id: "chat", topic: "livechat", liveStreamId: "live-1" })).not.toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.devicePairing, { pairingCode: "ABCD-2345", qrPayload: "{}", expiresAt: "2026-10-08T00:00:00Z" })).toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.sendBody, { text: "hi", targets: [] })).not.toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.moderateBody, { action: "timeout" })).not.toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.moderateBody, { action: "timeout", durationSeconds: 600 })).toEqual([]);
+  });
+
+  it("the schema examples satisfy the TypeScript types and the schema", () => {
+    const message: ChatMessage = CHAT_CONTRACT_EXAMPLES.chatMessage;
+    expect(isValidChatMessage(message)).toBe(true);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.chatMessage, CHAT_CONTRACT_EXAMPLES.chatMessage)).toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.delivery, CHAT_CONTRACT_EXAMPLES.delivery)).toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.capability, CHAT_CONTRACT_EXAMPLES.capability)).toEqual([]);
+    expect(validate(CHAT_CONTRACT_SCHEMAS.chatHubFrame, {
+      kind: "chat", liveStreamId: "live-1", channelId: "ch-1", seq: 1, message: CHAT_CONTRACT_EXAMPLES.chatMessage,
+    })).toEqual([]);
+  });
+
+  it("the message schema rejects unknown fields, bad seq and bad source", () => {
+    const base = CHAT_CONTRACT_EXAMPLES.chatMessage;
+    expect(validate(CHAT_MESSAGE_SCHEMA, { ...base, extra: true })).toEqual([expect.stringContaining("extra")]);
+    expect(validate(CHAT_MESSAGE_SCHEMA, { ...base, seq: 0 })).toEqual([expect.stringContaining("seq")]);
+    expect(validate(CHAT_MESSAGE_SCHEMA, { ...base, source: "rumour" })).toEqual([expect.stringContaining("source")]);
+    expect(validate(CHAT_MESSAGE_SCHEMA, { ...base, author: { handle: "x" } })).toEqual([expect.stringContaining("color")]);
+  });
+
+  it("delivery only allows the four statuses; capability states include the paused reasons", () => {
+    expect(validate(CHAT_CONTRACT_SCHEMAS.delivery, { ...CHAT_CONTRACT_EXAMPLES.delivery, status: "flapped" })).not.toEqual([]);
+    for (const state of ["ok", "paused:quota", "paused:rate", "degraded"]) {
+      expect(validate(CHAT_CONTRACT_SCHEMAS.capability, { ...CHAT_CONTRACT_EXAMPLES.capability, state })).toEqual([]);
+    }
+  });
+
+  it("a hub frame carries kind chat and a channel-scoped seq", () => {
+    const frame = { kind: "chat", liveStreamId: "live-1", channelId: "ch-1", seq: 3, message: CHAT_CONTRACT_EXAMPLES.chatMessage };
+    expect(validate(CHAT_HUB_FRAME_SCHEMA, frame)).toEqual([]);
+    expect(validate(CHAT_HUB_FRAME_SCHEMA, { ...frame, kind: "state" })).toEqual([expect.stringContaining("kind")]);
+  });
+
+  it("author colour is a stable function of provider:handle, never identity-fused", () => {
+    expect(authorColor("twitch", "viewer")).toBe(authorColor("twitch", "viewer"));
+    expect(authorColor("twitch", "viewer")).not.toBe(authorColor("youtube", "viewer"));
+    expect(authorColor("twitch", "viewer")).toMatch(/^hsl\(\d+ 70% 62%\)$/);
+    expect(authorColor("twitch", "viewer")).toMatch(/^hsl\([0-5]\d |hsl\([1-9]\d\d /);
+  });
+
+  it("isValidChatMessage rejects a non-integer seq and a missing author", () => {
+    const base = CHAT_CONTRACT_EXAMPLES.chatMessage;
+    expect(isValidChatMessage({ ...base, seq: 1.5 })).toBe(false);
+    expect(isValidChatMessage({ ...base, author: { handle: "" , color: "hsl(1 70% 62%)" } })).toBe(false);
+    expect(isValidChatMessage({ ...base, author: undefined })).toBe(false);
+  });
+});
diff --git a/packages/core/src/chat-contract.ts b/packages/core/src/chat-contract.ts
new file mode 100644
index 0000000..a3b11e3
--- /dev/null
+++ b/packages/core/src/chat-contract.ts
@@ -0,0 +1,302 @@
+/**
+ * S5 chat-unification contract (streaming-architecture.md §3.5).
+ *
+ * This module is the FROZEN wire contract between the Tactical Media Broadcast Hub chat hub,
+ * the web Control Room and the Opticast client. Both ends implement these
+ * shapes; changing them is a version bump, not a drive-by edit. Handwritten
+ * JSON Schema lives in `chat-contract.schema.ts` (validated against the types
+ * in `chat-contract.test.ts`) so clients can validate a transcript without a
+ * code-generation step and without a new dependency.
+ */
+
+/** Topic names multiplexed on the single /realtime socket. */
+export type LiveChatTopic = "livechat" | "channel";
+
+/** WS frame operations (§3.5 wire). Nest control ops reuse the gateway's. */
+export type LiveChatFrameOp =
+  | "auth"
+  | "ready"
+  | "close"
+  | "subscribe"
+  | "ack"
+  | "nack"
+  | "msg"
+  | "resync"
+  | "unsubscribe"
+  | "ping"
+  | "pong";
+
+/** `msg.type` values on the livechat topic. */
+export type LiveChatEventType =
+  | "chat.message"
+  | "chat.moderated"
+  | "chat.delivery"
+  | "chat.gap"
+  | "stream.state"
+  | "capability";
+
+/**
+ * Platforms the hub normalizes today (§3.2 table). These are open string
+ * unions, not a provider registry: the hub resolves adapters by connector id
+ * and the wire stays open so a new platform needs no contract change.
+ */
+export type LiveChatProvider = (string & {});
+
+/** Message provenance. `system` covers gap markers and hub notices. */
+export type LiveChatSource = "live-chat" | "social-reply" | "system";
+
+export interface LiveChatAuthor {
+  /** Provider login/handle, never empty. */
+  handle: string;
+  displayName?: string;
+  avatarUrl?: string;
+  badges?: string[];
+  /** Hash of `provider:handle` (§3.5 identity rule); a CSS colour. */
+  color: string;
+}
+
+/** Normalized chat message on the wire. Dates are ISO strings. */
+export interface ChatMessage {
+  /** Hub-assigned per-live monotonic ordering. Authoritative for cursors. */
+  seq: number;
+  id: string;
+  liveStreamId: string;
+  connectionId: string;
+  provider: string;
+  providerMessageId: string;
+  author: LiveChatAuthor;
+  text: string;
+  sentAt: string;
+  receivedAt: string;
+  isModerated: boolean;
+  replyTo?: string;
+  source: LiveChatSource;
+}
+
+/** Per-target send outcome; one row per (message, target). */
+export interface Delivery {
+  connectionId: string;
+  provider: string;
+  status: "queued" | "sent" | "failed" | "unsupported";
+  error?: string;
+}
+
+export interface LiveChatCapability {
+  connectionId: string;
+  provider: string;
+  read: boolean;
+  reply: boolean;
+  moderate: boolean;
+  state: "ok" | "paused:quota" | "paused:rate" | "degraded";
+  reason?: string;
+}
+
+export interface LiveSummary {
+  liveStreamId: string;
+  connectionId: string;
+  provider: string;
+  title: string;
+  state: "created" | "waiting" | "live" | "ended";
+}
+
+/** Chat message envelope pushed on the hub topic (WS `msg` payload). */
+export interface ChatMessageFrame {
+  kind: "chat";
+  liveStreamId: string;
+  channelId: string;
+  /** Same value as the message's `seq`; resume cursors use it. */
+  seq: number;
+  message: ChatMessage;
+}
+
+export interface ChatModeratedFrame {
+  kind: "chat";
+  liveStreamId: string;
+  channelId: string;
+  seq: number;
+  action: "delete" | "timeout" | "ban";
+  targetMessageId: string;
+  targetHandle?: string;
+}
+
+export interface ChatDeliveryFrame {
+  kind: "chat";
+  liveStreamId: string;
+  channelId: string;
+  seq: number;
+  messageId: string;
+  delivery: Delivery[];
+}
+
+/** Emitted when a provider gap is accepted (e.g. a Twitch WS drop). */
+export interface ChatGapFrame {
+  kind: "chat";
+  liveStreamId: string;
+  channelId: string;
+  seq: number;
+  provider: string;
+  reason: string;
+}
+
+export type ChatHubFrame = ChatMessageFrame | ChatModeratedFrame | ChatDeliveryFrame | ChatGapFrame;
+
+// ---------------------------------------------------------------------------
+// WS frames (both ends implement; §3.5 wire table)
+// ---------------------------------------------------------------------------
+
+export interface WsAuthFrame {
+  op: "auth";
+  /** Bearer token (session or device). Never in the URL. */
+  token: string;
+}
+
+export type WsSubscribeFrame = {
+  op: "subscribe";
+  id: string;
+  /** Resume cursor; absent means latest only. Zero requests all retained frames. */
+  lastSeq?: number;
+} & ({ topic: "livechat"; liveId: string } | { topic: "channel"; channelId: string });
+
+export interface WsAckFrame {
+  op: "ack";
+  id: string;
+  fromSeq: number;
+}
+
+export interface WsNackFrame {
+  op: "nack";
+  id: string;
+  reason: string;
+}
+
+export interface WsMsgFrame<T = ChatHubFrame> {
+  op: "msg";
+  topic: LiveChatTopic;
+  seq: number;
+  type: LiveChatEventType;
+  payload: T;
+}
+
+export interface WsResyncFrame {
+  op: "resync";
+  topic: LiveChatTopic;
+}
+
+export interface WsUnsubscribeFrame {
+  op: "unsubscribe";
+  id: string;
+}
+
+export interface WsPingFrame {
+  op: "ping";
+}
+
+export interface WsPongFrame {
+  op: "pong";
+}
+
+export interface WsReadyFrame { op: "ready" }
+export interface WsCloseFrame { op: "close"; reason: string }
+
+export type LiveChatWsFrame =
+  | WsReadyFrame
+  | WsCloseFrame
+  | WsAuthFrame
+  | WsSubscribeFrame
+  | WsAckFrame
+  | WsNackFrame
+  | WsMsgFrame
+  | WsResyncFrame
+  | WsUnsubscribeFrame
+  | WsPingFrame
+  | WsPongFrame;
+
+// ---------------------------------------------------------------------------
+// REST request bodies (§3.5 endpoints; workspace from session/device token)
+// ---------------------------------------------------------------------------
+
+export interface SendChatMessageBody {
+  /** 1..500 characters. */
+  text: string;
+  targets: "all" | string[];
+  replyTo?: string;
+}
+
+export interface ModerateChatBody {
+  action: "delete" | "timeout" | "ban";
+  /** 1..1209600, required for timeout. */
+  durationSeconds?: number;
+}
+
+/** Issuance has an empty body; workspace and user come from the session. */
+export type DevicePairingRequest = Record<string, never>;
+
+export interface DevicePairingResponse {
+  pairingCode: string;
+  qrPayload: string;
+  expiresAt: string;
+}
+
+export interface DeviceRedeemBody {
+  pairingCode: string;
+  deviceName: string;
+}
+
+export interface DeviceRedeemResponse {
+  deviceToken: string;
+  workspaceId: string;
+}
+
+/** Device token claims, mirrored from the `devices` row. */
+export interface DeviceTokenPayload {
+  deviceId: string;
+  workspaceId: string;
+  userId: string;
+  scopes: string[];
+  epoch: number;
+  issuedAt: number;
+  expiresAt: number;
+}
+
+export const DEVICE_SCOPES = ["livechat.view", "livechat.send", "livechat.moderate", "stream.view"] as const;
+export type DeviceScope = (typeof DEVICE_SCOPES)[number];
+
+/** Deterministic author colour: hash of `provider:handle` (§3.5 identity). */
+export function authorColor(provider: string, handle: string): string {
+  let hash = 0x811c9dc5;
+  const key = `${provider}:${handle}`;
+  for (let i = 0; i < key.length; i += 1) {
+    hash ^= key.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  const hue = ((hash >>> 0) % 360 + 360) % 360;
+  return `hsl(${hue} 70% 62%)`;
+}
+
+/** Validate a transcript payload against the frozen message shape. */
+export function isValidChatMessage(value: unknown): value is ChatMessage {
+  if (typeof value !== "object" || value === null) return false;
+  const m = value as Record<string, unknown>;
+  return (
+    typeof m.seq === "number" &&
+    Number.isSafeInteger(m.seq) &&
+    m.seq > 0 &&
+    typeof m.id === "string" &&
+    typeof m.liveStreamId === "string" &&
+    typeof m.connectionId === "string" &&
+    typeof m.provider === "string" &&
+    typeof m.providerMessageId === "string" &&
+    typeof m.text === "string" &&
+    typeof m.sentAt === "string" &&
+    typeof m.receivedAt === "string" &&
+    typeof m.isModerated === "boolean" &&
+    typeof m.source === "string" &&
+    (m.source === "live-chat" || m.source === "social-reply" || m.source === "system") &&
+    typeof m.author === "object" &&
+    m.author !== null &&
+    typeof (m.author as Record<string, unknown>).handle === "string" &&
+    String((m.author as Record<string, unknown>).handle).length > 0 &&
+    typeof (m.author as Record<string, unknown>).color === "string" &&
+    (m.replyTo === undefined || typeof m.replyTo === "string")
+  );
+}
diff --git a/packages/core/src/connection.ts b/packages/core/src/connection.ts
new file mode 100644
index 0000000..f9237d4
--- /dev/null
+++ b/packages/core/src/connection.ts
@@ -0,0 +1,51 @@
+import type { ConnectorCapabilities } from "./capabilities.js";
+
+/**
+ * Credential references are opaque handles into the vault (WP2).
+ * Raw tokens never appear in these types by design.
+ */
+export interface CredentialRef {
+  readonly kind: "credential-ref";
+  readonly id: string;
+}
+
+export type ProviderId = string;
+
+export interface Channel {
+  id: string;
+  workspaceId: string;
+  provider: ProviderId;
+  displayName: string;
+  createdAt: Date;
+}
+
+export interface ConnectorConnection {
+  id: string;
+  workspaceId: string;
+  provider: ProviderId;
+  channelId: string;
+  credentialId: CredentialRef;
+  /** Manifest-declared field values, e.g. instanceUrl for federated platforms. */
+  fields: Record<string, string>;
+  createdAt: Date;
+}
+
+export interface NormalizedIdentity {
+  provider: ProviderId;
+  remoteId: string;
+  handle: string;
+  displayName?: string;
+  avatarUrl?: string;
+}
+
+/** Channel on a remote video platform; account ≠ channel (federated platforms). */
+export interface RemoteVideoChannel {
+  id: string;
+  provider: ProviderId;
+  instanceUrl: string;
+  remoteChannelId: string;
+  handle: string;
+  displayName?: string;
+  avatarUrl?: string;
+  capabilities: ConnectorCapabilities;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
new file mode 100644
index 0000000..3bcbfbb
--- /dev/null
+++ b/packages/core/src/index.ts
@@ -0,0 +1,27 @@
+/**
+ * Normalized domain types shared by every workspace app. Connector packages
+ * never leak provider names into this package — enforced by the root lint rule.
+ */
+
+export interface HealthState {
+  status: "up" | "down";
+}
+
+export * from "./capabilities.js";
+export * from "./chat-contract.js";
+export * from "./chat-contract.schema.js";
+export * from "./connection.js";
+export * from "./messaging.js";
+export * from "./publishing.js";
+export * from "./shared-files.js";
+export * from "./social.js";
+export * from "./stream-columns.js";
+export * from "./vc.js";
+export * from "./video.js";
+export * from "./workspace.js";
+
+// publishing.ts retains the legacy VideoAsset declaration for connector
+// compatibility. Prefer the first-class video-domain declaration here.
+export type { VideoAsset } from "./video.js";
+
+export * from "./publishing-execution.js";
diff --git a/packages/core/src/messaging.ts b/packages/core/src/messaging.ts
new file mode 100644
index 0000000..e939343
--- /dev/null
+++ b/packages/core/src/messaging.ts
@@ -0,0 +1,47 @@
+/** Transport-agnostic list page — shared by every paginated surface. */
+export interface Page<T, C = string> {
+  items: T[];
+  nextCursor?: C;
+}
+
+export interface RemoteMedia {
+  remoteId: string;
+  url?: string;
+  mimeType: string;
+  width?: number;
+  height?: number;
+}
+
+/** Result of resolving a live source for program input (WP6 go-live slice). */
+export interface LiveSourceResolution {
+  /** Absolute HLS playback URL, or null when the source is not live. */
+  playbackHlsUrl: string | null;
+  live: boolean;
+}
+
+export interface StreamPlaybackSource {
+  remoteId: string;
+  /** Absolute playback URL (HLS manifest, embed page, etc.). */
+  url: string;
+  kind: "hls" | "dash" | "embed";
+  protocol: "https" | "rtmp" | "rtmps" | "srt";
+}
+
+export interface DirectMessage {
+  id: string;
+  provider: string;
+  conversationRemoteId: string;
+  fromHandle: string;
+  toHandle: string;
+  text: string;
+  sentAt: Date;
+}
+
+export interface NormalizedWebhookEvent {
+  provider: string;
+  eventType: string;
+  /** Connection or channel the event belongs to, when resolvable. */
+  connectionKey?: string;
+  payload: Record<string, unknown>;
+  receivedAt: Date;
+}
diff --git a/packages/core/src/publishing-execution.ts b/packages/core/src/publishing-execution.ts
new file mode 100644
index 0000000..ae7e397
--- /dev/null
+++ b/packages/core/src/publishing-execution.ts
@@ -0,0 +1,7 @@
+export function publishingIdempotencyKey(parts: { workspaceId: string; draftId: string; attemptNo: string | bigint | number }): string {
+  if (!/^[A-Za-z0-9-]+$/.test(parts.workspaceId) || !/^[A-Za-z0-9-]+$/.test(parts.draftId)) throw new RangeError("invalid attempt identity");
+  if (typeof parts.attemptNo === "number" && !Number.isSafeInteger(parts.attemptNo)) throw new RangeError("unsafe attempt number");
+  const attempt = String(parts.attemptNo);
+  if (!/^[1-9][0-9]*$/.test(attempt)) throw new RangeError("attemptNo must be a positive decimal integer");
+  return `wp3:${parts.workspaceId}:${parts.draftId}:a${attempt}:publish`;
+}
diff --git a/packages/core/src/publishing.ts b/packages/core/src/publishing.ts
new file mode 100644
index 0000000..993a595
--- /dev/null
+++ b/packages/core/src/publishing.ts
@@ -0,0 +1,109 @@
+export type Visibility =
+  | "public"
+  | "unlisted"
+  | "private"
+  | "followers"
+  | "provider_default";
+
+export type FormatIntent =
+  | "short_form"
+  | "long_form"
+  | "story"
+  | "feed_video"
+  | "provider_default";
+
+export interface MediaAsset {
+  id: string;
+  workspaceId: string;
+  storageKey: string;
+  mimeType: string;
+  sizeBytes: number;
+  width?: number;
+  height?: number;
+  createdAt: Date;
+}
+
+export interface NormalizedPost {
+  text: string;
+  mediaAssetIds: string[];
+  visibility: Visibility;
+  scheduledAt?: Date;
+  providerMetadata: Record<string, unknown>;
+}
+
+export interface Draft {
+  id: string;
+  workspaceId: string;
+  authorId: string;
+  post: NormalizedPost;
+  targets: PostTarget[];
+  state: "editing" | "in_review" | "approved" | "rejected" | "scheduled" | "published";
+  reviewerId?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface PostTarget {
+  channelId: string;
+  connectionId: string;
+}
+
+export interface Publication {
+  id: string;
+  workspaceId: string;
+  draftId: string;
+  connectionId: string;
+  remoteId: string;
+  remoteUrl?: string;
+  publishedAt: Date;
+  providerMetadata: Record<string, unknown>;
+}
+
+export interface ScheduledPublication {
+  id: string;
+  workspaceId: string;
+  draftId: string;
+  publishAt: Date;
+  targets: PostTarget[];
+  idempotencyKey: string;
+  state: "pending" | "in_flight" | "done" | "failed";
+}
+
+export interface VideoAsset {
+  id: string;
+  workspaceId: string;
+  storageKey: string;
+  mimeType: string;
+  sizeBytes: number;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  frameRate?: number;
+  codec?: string;
+  audioCodec?: string;
+}
+
+export interface NormalizedVideoPublication {
+  videoAssetId: string;
+  title?: string;
+  description?: string;
+  tags?: string[];
+  thumbnailAssetId?: string;
+  visibility: Visibility;
+  formatIntent: FormatIntent;
+  scheduledAt?: Date;
+  providerMetadata: Record<string, unknown>;
+}
+
+export type VideoProcessingState =
+  | "uploading"
+  | "processing"
+  | "ready"
+  | "failed";
+
+export interface VideoProcessingStatus {
+  remoteId: string;
+  state: VideoProcessingState;
+  progressPercent?: number;
+  error?: string;
+}
diff --git a/packages/core/src/shared-files.test.ts b/packages/core/src/shared-files.test.ts
new file mode 100644
index 0000000..e7ea246
--- /dev/null
+++ b/packages/core/src/shared-files.test.ts
@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { attachmentArchiveKey, canArchiveAttachment, type GroupFileMapping, type MatrixAttachmentCandidate } from "./shared-files.js";
+
+const mapping: GroupFileMapping = {
+  workspaceId: "workspace", groupId: "group", roomId: "!archive:example.org",
+  spaceId: "space", folderId: "folder", archivePolicy: "unencrypted-archive",
+  retention: { mode: "keep", legalHold: false },
+};
+const event: MatrixAttachmentCandidate = {
+  roomId: mapping.roomId, eventId: "$event", senderId: "@sender:example.org",
+  eventType: "m.room.message", msgtype: "m.file", roomEncryption: "unencrypted",
+  encryptedFile: false, redacted: false, mxcUri: "mxc://example.org/media",
+};
+
+describe("group file archive policy", () => {
+  it("accepts only attachments in an explicitly mapped unencrypted archive room", () => {
+    for (const msgtype of ["m.file", "m.image", "m.audio", "m.video"]) {
+      expect(canArchiveAttachment(mapping, { ...event, msgtype })).toBe(true);
+    }
+    expect(canArchiveAttachment({ ...mapping, archivePolicy: "disabled" }, event)).toBe(false);
+    expect(canArchiveAttachment(mapping, { ...event, roomId: "!other:example.org" })).toBe(false);
+  });
+
+  it("fails closed on encryption, unknown state, redactions and non-attachment messages", () => {
+    for (const patch of [
+      { roomEncryption: "encrypted" as const }, { roomEncryption: "unknown" as const },
+      { encryptedFile: true }, { redacted: true }, { eventType: "m.room.encrypted" },
+      { msgtype: "m.text" }, { mxcUri: "https://attacker.example/file" }, { mxcUri: "mxc://example.org/" },
+    ]) expect(canArchiveAttachment(mapping, { ...event, ...patch })).toBe(false);
+  });
+
+  it("replays use the same identity without conflating tenants or rooms", () => {
+    expect(attachmentArchiveKey("w", "r", "e")).toBe(attachmentArchiveKey("w", "r", "e"));
+    expect(attachmentArchiveKey("w2", "r", "e")).not.toBe(attachmentArchiveKey("w", "r", "e"));
+    expect(attachmentArchiveKey("a:b", "c", "e")).not.toBe(attachmentArchiveKey("a", "b:c", "e"));
+  });
+});
diff --git a/packages/core/src/shared-files.ts b/packages/core/src/shared-files.ts
new file mode 100644
index 0000000..1875918
--- /dev/null
+++ b/packages/core/src/shared-files.ts
@@ -0,0 +1,109 @@
+/** Shared file/index contracts. Payloads are remote; these records contain metadata only. */
+/** A share expiry never deletes a file. UTC ISO-8601 for timed retention. */
+export type FileRetention = { legalHold: boolean } & (
+  | { mode: "keep"; expiresAt?: never }
+  | { mode: "until"; expiresAt: string }
+);
+
+export interface GroupFileMapping {
+  workspaceId: string;
+  groupId: string;
+  /** Immutable Matrix room ID, never an alias or display name. */
+  roomId: string;
+  spaceId: string;
+  folderId: string;
+  archivePolicy: "disabled" | "unencrypted-archive";
+  retention: FileRetention;
+}
+
+export type SharedFileOrigin =
+  | { kind: "matrix"; mxcUri: string }
+  | { kind: "bridge"; mxcUri: string; providerId: string; remoteEventId?: string }
+  | { kind: "upload" }
+  | { kind: "pad-export"; padId: string; revision: string };
+
+export interface GroupFile {
+  id: string;
+  workspaceId: string;
+  groupId: string;
+  roomId: string;
+  senderId: string;
+  /** Null for a direct upload/export until a link is posted in the room. */
+  eventId: string | null;
+  origin: SharedFileOrigin;
+  name: string;
+  mimeType: string;
+  sizeBytes: number;
+  /** SHA-256 of verified payload bytes, lowercase hex; never an S3 ETag. */
+  checksum: { algorithm: "sha256"; value: string };
+  createdAt: string;
+  indexedAt: string;
+  file: { spaceId: string; resourceId: string; version: string };
+  /** Authenticated library link by default; never a persisted presigned R2 URL. */
+  shareLink: { url: string; access: "members" | "public"; expiresAt: string | null };
+  retention: FileRetention;
+  status: "available" | "revoked" | "expired";
+}
+
+export interface MatrixAttachmentCandidate {
+  roomId: string;
+  eventId: string;
+  senderId: string;
+  eventType: string;
+  msgtype: string;
+  /** Unknown state must fail closed, including on initial sync. */
+  roomEncryption: "unencrypted" | "encrypted" | "unknown";
+  encryptedFile: boolean;
+  redacted: boolean;
+  mxcUri: string;
+}
+
+/** Eligibility only; the adapter must also check membership/ACL, quotas and actual bytes. */
+export function canArchiveAttachment(
+  mapping: GroupFileMapping,
+  event: MatrixAttachmentCandidate,
+): boolean {
+  return mapping.archivePolicy === "unencrypted-archive"
+    && mapping.roomId === event.roomId
+    && event.roomEncryption === "unencrypted"
+    && !event.encryptedFile
+    && !event.redacted
+    && event.eventType === "m.room.message"
+    && ["m.file", "m.image", "m.audio", "m.video"].includes(event.msgtype)
+    && /^mxc:\/\/[^/\s]+\/[^/\s?#]+$/.test(event.mxcUri);
+}
+
+/** Collision-free replay identity; DB uniqueness is scoped to workspace/room/event. */
+export function attachmentArchiveKey(workspaceId: string, roomId: string, eventId: string): string {
+  return JSON.stringify([workspaceId, roomId, eventId]);
+}
+
+/** Future adapter boundary, not a running bot or public API. Commit before advancing sync. */
+export interface HubArchivePort {
+  archive(mapping: GroupFileMapping, event: MatrixAttachmentCandidate): Promise<GroupFile>;
+  revoke(workspaceId: string, roomId: string, eventId: string): Promise<void>;
+}
+
+export interface CollaborativeDocument {
+  fileId: string;
+  mimeType: "application/vnd.oasis.opendocument.text";
+  editor: "wopi";
+  /** Authenticated launch URL; WOPI access tokens are short-lived and not indexed. */
+  launchUrl: string;
+}
+
+/** Etherpad/HedgeDoc-compatible link/export seam. No pad text or revisions in Hub DB. */
+export interface SharedPad {
+  id: string;
+  workspaceId: string;
+  groupId: string;
+  roomId: string;
+  service: "etherpad-compatible" | "hedgedoc-compatible";
+  url: string;
+  payloadStore: "r2";
+  retention: FileRetention;
+}
+
+export interface PadExportPort {
+  exportRevision(pad: SharedPad, revision: string): Promise<GroupFile>;
+}
diff --git a/packages/core/src/social.ts b/packages/core/src/social.ts
new file mode 100644
index 0000000..e0d0945
--- /dev/null
+++ b/packages/core/src/social.ts
@@ -0,0 +1,89 @@
+import type { ProviderId } from "./connection.js";
+
+export interface FeedItem {
+  id: string;
+  provider: ProviderId;
+  remoteId: string;
+  authorHandle: string;
+  text: string;
+  mediaUrls: string[];
+  createdAt: Date;
+  metrics: Record<string, number>;
+}
+
+export interface Feed {
+  id: string;
+  workspaceId: string;
+  connectionId: string;
+  kind: "home" | "mentions" | "search" | "list";
+  query?: string;
+}
+
+export interface Conversation {
+  id: string;
+  workspaceId: string;
+  connectionId: string;
+  participantHandles: string[];
+  lastMessageAt: Date;
+  unreadCount: number;
+  assignedUserId?: string;
+}
+
+export interface Comment {
+  id: string;
+  provider: ProviderId;
+  remoteId: string;
+  onRemoteId: string;
+  authorHandle: string;
+  text: string;
+  createdAt: Date;
+}
+
+export interface Reaction {
+  id: string;
+  provider: ProviderId;
+  onRemoteId: string;
+  kind: string;
+  count: number;
+}
+
+export interface Metric {
+  id: string;
+  workspaceId: string;
+  subjectType: "publication" | "channel" | "livestream";
+  subjectId: string;
+  capturedAt: Date;
+  values: Record<string, number>;
+}
+
+export interface AnalyticsSnapshot {
+  subjectId: string;
+  windowStart: Date;
+  windowEnd: Date;
+  series: readonly Metric[];
+}
+
+export interface AuditLogEntry {
+  id: string;
+  workspaceId: string;
+  actorUserId: string;
+  actorRole: string;
+  action: string;
+  targetType: string;
+  targetId: string;
+  diff: Record<string, unknown> | null;
+  ip?: string;
+  sessionId?: string;
+  at: Date;
+  prevHash?: string;
+  hash: string;
+}
+
+export interface WebhookEvent {
+  id: string;
+  workspaceId: string;
+  provider: ProviderId;
+  eventType: string;
+  payload: Record<string, unknown>;
+  receivedAt: Date;
+}
diff --git a/packages/core/src/stream-columns.test.ts b/packages/core/src/stream-columns.test.ts
new file mode 100644
index 0000000..a4be8cf
--- /dev/null
+++ b/packages/core/src/stream-columns.test.ts
@@ -0,0 +1,225 @@
+import { describe, expect, it } from "vitest";
+import {
+  ACCOUNTS_MAX,
+  clampIntervalMs,
+  clampPosition,
+  clampTitle,
+  DEFAULT_INTERVAL_MS,
+  defaultIntervalMs,
+  isKeywordLike,
+  parseRefreshPolicyClamped,
+  parseStreamColumnSpec,
+  QUERY_MAX,
+  STREAM_COLUMN_TITLE_MAX,
+  StreamColumnsValidationError,
+} from "./stream-columns.js";
+
+const rejects = (fn: () => unknown): void => {
+  expect(fn).toThrow(StreamColumnsValidationError);
+};
+
+describe("column type dispatch", () => {
+  it("covers exactly the four persisted types", () => {
+    expect(
+      parseStreamColumnSpec("platform_feed", { connectionId: "c1", kinds: ["home"] }),
+    ).toEqual({ connectionId: "c1", kinds: ["home"] });
+    expect(
+      parseStreamColumnSpec("saved_search", { query: "product", platforms: ["bluesky"] }),
+    ).toEqual({ query: "product", platforms: ["bluesky"], matchMode: "any" });
+    expect(
+      parseStreamColumnSpec("keyword", { query: "acampada26", platforms: ["bluesky", "mastodon"] }),
+    ).toEqual({ query: "acampada26", platforms: ["bluesky", "mastodon"], matchMode: "any" });
+    expect(
+      parseStreamColumnSpec("account_list", {
+        accounts: [{ provider: "mastodon", handle: "@user@mastodon.social" }],
+      }),
+    ).toEqual({ accounts: [{ provider: "mastodon", handle: "@user@mastodon.social" }] });
+  });
+
+  it("treats saved_search as keyword-shaped (shared engine, §1.1)", () => {
+    const good = { query: "t", platforms: ["bluesky"] };
+    expect(parseStreamColumnSpec("saved_search", good)).toEqual(
+      parseStreamColumnSpec("keyword", good),
+    );
+    rejects(() => parseStreamColumnSpec("saved_search", { platforms: ["bluesky"] }));
+  });
+
+  it("isKeywordLike groups the shared keyword engine", () => {
+    expect(isKeywordLike("keyword")).toBe(true);
+    expect(isKeywordLike("saved_search")).toBe(true);
+    expect(isKeywordLike("platform_feed")).toBe(false);
+    expect(isKeywordLike("account_list")).toBe(false);
+  });
+});
+
+describe("platform_feed spec", () => {
+  it("defaults kinds to [\"home\"] when omitted or empty is rejected", () => {
+    expect(parseStreamColumnSpec("platform_feed", { connectionId: "c1" }))
+      .toEqual({ connectionId: "c1", kinds: ["home"] });
+    rejects(() => parseStreamColumnSpec("platform_feed", { connectionId: "c1", kinds: [] }));
+  });
+
+  it("accepts home+mentions in any order, deduped", () => {
+    expect(parseStreamColumnSpec("platform_feed", { connectionId: "c1", kinds: ["mentions", "home", "mentions"] }))
+      .toEqual({ connectionId: "c1", kinds: ["mentions", "home"] });
+  });
+
+  it("rejects bad kinds and connection ids", () => {
+    rejects(() => parseStreamColumnSpec("platform_feed", { connectionId: "c1", kinds: ["home", "list"] }));
+    rejects(() => parseStreamColumnSpec("platform_feed", { connectionId: "c1", kinds: "home" }));
+    rejects(() => parseStreamColumnSpec("platform_feed", { connectionId: "", kinds: ["home"] }));
+    rejects(() => parseStreamColumnSpec("platform_feed", { connectionId: 42, kinds: ["home"] }));
+    rejects(() => parseStreamColumnSpec("platform_feed", {}));
+    rejects(() => parseStreamColumnSpec("platform_feed", null));
+    rejects(() => parseStreamColumnSpec("platform_feed", "c1"));
+    rejects(() => parseStreamColumnSpec("platform_feed", []));
+  });
+});
+
+describe("keyword / saved_search spec", () => {
+  it("trims the query and rejects empty-after-trim", () => {
+    expect(parseStreamColumnSpec("keyword", { query: "  acampada26  ", platforms: ["bluesky"] }).query)
+      .toBe("acampada26");
+    rejects(() => parseStreamColumnSpec("keyword", { query: "   ", platforms: ["bluesky"] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "", platforms: ["bluesky"] }));
+    rejects(() => parseStreamColumnSpec("keyword", { platforms: ["bluesky"] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: 7, platforms: ["bluesky"] }));
+  });
+
+  it("enforces the 1..200 query window and control-char ban", () => {
+    const edge = "x".repeat(QUERY_MAX);
+    expect(parseStreamColumnSpec("keyword", { query: ` ${edge} `, platforms: ["bluesky"] }).query)
+      .toBe(edge); // exactly 200 after trim passes
+    rejects(() => parseStreamColumnSpec("keyword", { query: `${edge}x`, platforms: ["bluesky"] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "a\u0000b", platforms: ["bluesky"] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "a\nb", platforms: ["bluesky"] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "a\u007fb", platforms: ["bluesky"] }));
+  });
+
+  it("dedupes platforms and rejects empty/invalid lists", () => {
+    expect(parseStreamColumnSpec("keyword", { query: "q", platforms: ["bluesky", "bluesky", "youtube"] }).platforms)
+      .toEqual(["bluesky", "youtube"]);
+    rejects(() => parseStreamColumnSpec("keyword", { query: "q", platforms: [] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "q" }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "q", platforms: ["bluesky", ""] }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "q", platforms: [42] }));
+  });
+
+  it("allows only the reserved matchMode \"any\"", () => {
+    expect(parseStreamColumnSpec("keyword", { query: "q", platforms: ["bluesky"], matchMode: "any" }).matchMode)
+      .toBe("any");
+    rejects(() => parseStreamColumnSpec("keyword", { query: "q", platforms: ["bluesky"], matchMode: "all" }));
+    rejects(() => parseStreamColumnSpec("keyword", { query: "q", platforms: ["bluesky"], matchMode: null }));
+  });
+});
+
+describe("account_list spec", () => {
+  it("trims handles and accepts the documented shapes", () => {
+    expect(
+      parseStreamColumnSpec("account_list", {
+        accounts: [
+          { provider: "mastodon", handle: " @user@mastodon.social " },
+          { provider: "bluesky", handle: "@user.bsky.social" },
+          { provider: "youtube", handle: "UCxxxxxxxxxxxxxxxxxxxxxx" },
+        ],
+      }).accounts,
+    ).toEqual([
+      { provider: "mastodon", handle: "@user@mastodon.social" },
+      { provider: "bluesky", handle: "@user.bsky.social" },
+      { provider: "youtube", handle: "UCxxxxxxxxxxxxxxxxxxxxxx" },
+    ]);
+  });
+
+  it("enforces the 1..50 window", () => {
+    const account = { provider: "mastodon", handle: "@user" };
+    expect(parseStreamColumnSpec("account_list", { accounts: [account] }).accounts).toHaveLength(1);
+    expect(
+      parseStreamColumnSpec("account_list", { accounts: Array.from({ length: ACCOUNTS_MAX }, () => account) }).accounts,
+    ).toHaveLength(ACCOUNTS_MAX);
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: [] }));
+    rejects(() =>
+      parseStreamColumnSpec("account_list", {
+        accounts: Array.from({ length: ACCOUNTS_MAX + 1 }, () => account),
+      }),
+    );
+  });
+
+  it("rejects malformed entries", () => {
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: [{ provider: "mastodon" }] }));
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: [{ handle: "@user" }] }));
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: [{ provider: "", handle: "@u" }] }));
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: [{ provider: "mastodon", handle: "   " }] }));
+    rejects(() =>
+      parseStreamColumnSpec("account_list", { accounts: [{ provider: "mastodon", handle: "a\u0000b" }] }),
+    );
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: ["@user"] }));
+    rejects(() => parseStreamColumnSpec("account_list", { accounts: {} }));
+  });
+});
+
+describe("refresh_policy", () => {
+  it("defaults to {}", () => {
+    expect(parseRefreshPolicyClamped()).toEqual({});
+    expect(parseRefreshPolicyClamped({})).toEqual({});
+    expect(parseRefreshPolicyClamped(undefined)).toEqual({});
+    expect(parseRefreshPolicyClamped(null)).toEqual({});
+  });
+
+  it("keeps valid interval/paused values", () => {
+    expect(parseRefreshPolicyClamped({ intervalMs: 300_000, paused: true }))
+      .toEqual({ intervalMs: 300_000, paused: true });
+    expect(parseRefreshPolicyClamped({ paused: false })).toEqual({ paused: false });
+  });
+
+  it("clamps intervalMs into 60_000..3_600_000", () => {
+    expect(parseRefreshPolicyClamped({ intervalMs: 0 }).intervalMs).toBe(60_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: -5_000 }).intervalMs).toBe(60_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: 59_999 }).intervalMs).toBe(60_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: 10 }).intervalMs).toBe(60_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: 3_600_000 }).intervalMs).toBe(3_600_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: 10_000_000 }).intervalMs).toBe(3_600_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: 90_500 }).intervalMs).toBe(90_500);
+    expect(parseRefreshPolicyClamped({ intervalMs: 60_000.4 }).intervalMs).toBe(60_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: Number.NaN }).intervalMs).toBe(60_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: Number.POSITIVE_INFINITY }).intervalMs).toBe(3_600_000);
+    expect(parseRefreshPolicyClamped({ intervalMs: Number.NEGATIVE_INFINITY }).intervalMs).toBe(60_000);
+  });
+
+  it("rejects malformed policies", () => {
+    rejects(() => parseRefreshPolicyClamped({ intervalMs: "60000" }));
+    rejects(() => parseRefreshPolicyClamped({ paused: "yes" }));
+    rejects(() => parseRefreshPolicyClamped([1, 2]));
+    rejects(() => parseRefreshPolicyClamped("paused"));
+  });
+
+  it("exposes the per-type default cadences", () => {
+    expect(DEFAULT_INTERVAL_MS).toEqual({
+      platform_feed: 60_000,
+      keyword: 120_000,
+      account_list: 180_000,
+      saved_search: 300_000,
+    });
+    for (const type of ["platform_feed", "keyword", "account_list", "saved_search"] as const) {
+      expect(defaultIntervalMs(type)).toBe(DEFAULT_INTERVAL_MS[type]);
+      expect(defaultIntervalMs(type)).toBeGreaterThanOrEqual(clampIntervalMs(60_000));
+    }
+  });
+});
+
+describe("shared clamps", () => {
+  it("clampTitle trims and caps at 80 chars (mirrors the DB CHECK)", () => {
+    expect(clampTitle("  Movement voices  ")).toBe("Movement voices");
+    expect(clampTitle("x".repeat(STREAM_COLUMN_TITLE_MAX))).toHaveLength(STREAM_COLUMN_TITLE_MAX);
+    expect(clampTitle(` ${"y".repeat(STREAM_COLUMN_TITLE_MAX + 20)} `)).toHaveLength(STREAM_COLUMN_TITLE_MAX);
+    expect(clampTitle("").length).toBe(0);
+  });
+
+  it("clampPosition yields finite non-negative integers", () => {
+    expect(clampPosition(0)).toBe(0);
+    expect(clampPosition(7.9)).toBe(8);
+    expect(clampPosition(-3)).toBe(0);
+    expect(clampPosition(Number.NaN)).toBe(0);
+    expect(clampPosition(Number.POSITIVE_INFINITY)).toBe(2_147_483_647);
+    expect(clampPosition(2_147_483_648)).toBe(2_147_483_647);
+  });
+});
diff --git a/packages/core/src/stream-columns.ts b/packages/core/src/stream-columns.ts
new file mode 100644
index 0000000..e16b585
--- /dev/null
+++ b/packages/core/src/stream-columns.ts
@@ -0,0 +1,304 @@
+/**
+ * Streams columns (WP3 §1.2): typed `spec` per column type + clamped
+ * `refresh_policy`. Invalid specs are rejected before insert (the API maps
+ * StreamColumnsValidationError → 422) and never stored; clamps are applied,
+ * not errors — intervalMs floors to 60 s / caps at 1 h, titles trim+cap at 80
+ * chars, positions stay sane dense ranks.
+ *
+ * Dependency-free by house rule (see chat-contract.schema.ts): plain parse
+ * functions, no zod. The four persisted types and their shapes follow design
+ * §1.1/§1.2; `saved_search` shares the keyword engine, it only differs in the
+ * column `type` label.
+ */
+import type { ProviderId } from "./connection.js";
+
+export type StreamColumnType = "platform_feed" | "keyword" | "account_list" | "saved_search";
+
+export const STREAM_COLUMN_TYPES: readonly StreamColumnType[] = [
+  "platform_feed",
+  "keyword",
+  "account_list",
+  "saved_search",
+] as const;
+
+export type PlatformFeedKind = "home" | "mentions";
+
+/** `{ connectionId, kinds }` — kinds defaults to ["home"] (design §1.2). */
+export interface PlatformFeedSpec {
+  connectionId: string;
+  kinds: PlatformFeedKind[];
+}
+
+/** Shared by `keyword` and `saved_search` (§1.1: saved_search is keyword). */
+export interface KeywordSpec {
+  /** 1..200 chars after trimming; no NUL/control chars. */
+  query: string;
+  /** Provider ids, e.g. ["bluesky","mastodon","youtube"]; deduped. */
+  platforms: ProviderId[];
+  /** Reserved; v1 = single term set, no boolean ops. */
+  matchMode: "any";
+}
+
+export interface AccountListEntry {
+  provider: ProviderId;
+  /** Free text: "@user@instance.social" | "@user" | "UC…" (YT channel id). */
+  handle: string;
+}
+
+/** 1..50 entries (design §1.2). */
+export interface AccountListSpec {
+  accounts: AccountListEntry[];
+}
+
+export type StreamColumnSpec = PlatformFeedSpec | KeywordSpec | AccountListSpec;
+
+/** `{ intervalMs?, paused? }` — clamped server-side (design §1.2). */
+export interface RefreshPolicy {
+  /** 60_000..3_600_000 after clamping. */
+  intervalMs?: number;
+  paused?: boolean;
+}
+
+export const QUERY_MAX = 200;
+export const ACCOUNTS_MAX = 50;
+export const PLATFORMS_MAX = 200;
+/** Title cap: matches the stream_columns.title CHECK in migration 021. */
+export const STREAM_COLUMN_TITLE_MAX = 80;
+export const STREAM_COLUMN_POSITION_DEFAULT = 0;
+const POSITION_MAX = 2_147_483_647; // integer column
+
+const INTERVAL_FLOOR = 60_000;
+const INTERVAL_CEIL = 3_600_000;
+
+/** Default cadence per column type (design §1.2). */
+export const DEFAULT_INTERVAL_MS: Record<StreamColumnType, number> = {
+  platform_feed: 60_000,
+  keyword: 120_000,
+  account_list: 180_000,
+  saved_search: 300_000,
+};
+
+/** API layer maps this → 422; never stored on failure. */
+export class StreamColumnsValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StreamColumnsValidationError";
+  }
+}
+
+function fail(message: string): never {
+  throw new StreamColumnsValidationError(message);
+}
+
+function asObject(value: unknown, what: string): Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return fail(`${what} must be a JSON object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function isControlCharFree(value: string): boolean {
+  return !/[\u0000-\u001f\u007f]/.test(value);
+}
+
+function providerId(value: unknown, what: string): ProviderId {
+  if (typeof value !== "string" || value.length === 0 || value.length > 64) {
+    return fail(`${what} must be a 1..64-char provider id`);
+  }
+  if (!isControlCharFree(value)) return fail(`${what} must not contain control characters`);
+  return value;
+}
+
+// ---------------------------------------------------------------------------
+// spec: platform_feed
+// ---------------------------------------------------------------------------
+
+function parsePlatformFeedSpec(value: unknown): PlatformFeedSpec {
+  const spec = asObject(value, "platform_feed spec");
+  if (typeof spec["connectionId"] !== "string" || spec["connectionId"].length === 0) {
+    fail("platform_feed: connectionId must be a non-empty string");
+  }
+  if (spec["connectionId"].length > 200) {
+    fail("platform_feed: connectionId exceeds 200 chars");
+  }
+  const rawKinds = spec["kinds"];
+  const kinds: PlatformFeedKind[] =
+    rawKinds === undefined ? ["home"] : parseKinds(rawKinds);
+  return { connectionId: spec["connectionId"], kinds };
+}
+
+function parseKinds(value: unknown): PlatformFeedKind[] {
+  if (!Array.isArray(value)) {
+    fail("platform_feed: kinds must be a non-empty array of \"home\"|\"mentions\"");
+  }
+  const kinds: PlatformFeedKind[] = [];
+  for (const kind of value) {
+    if (kind !== "home" && kind !== "mentions") {
+      fail("platform_feed: kinds may contain only \"home\"|\"mentions\"");
+    }
+    if (!kinds.includes(kind)) kinds.push(kind);
+  }
+  if (kinds.length === 0) {
+    fail("platform_feed: kinds must be a non-empty array of \"home\"|\"mentions\"");
+  }
+  return kinds;
+}
+
+// ---------------------------------------------------------------------------
+// spec: keyword / saved_search — one engine, two labels (design §1.1)
+// ---------------------------------------------------------------------------
+
+function parseKeywordSpec(value: unknown): KeywordSpec {
+  const spec = asObject(value, "keyword spec");
+  const rawQuery = spec["query"];
+  if (typeof rawQuery !== "string") fail("keyword: query must be a string");
+  const query = rawQuery.trim();
+  if (query.length < 1) fail("keyword: query must be 1..200 chars after trimming");
+  if (query.length > QUERY_MAX) fail(`keyword: query exceeds ${QUERY_MAX} chars after trimming`);
+  if (!isControlCharFree(query)) {
+    fail("keyword: query must not contain NUL/control characters");
+  }
+  const platforms = parsePlatforms(spec["platforms"]);
+  const matchMode = spec["matchMode"];
+  if (matchMode !== undefined && matchMode !== "any") {
+    fail("keyword: matchMode must be \"any\" (no boolean operators in v1)");
+  }
+  return { query, platforms, matchMode: "any" };
+}
+
+function parsePlatforms(value: unknown): ProviderId[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > PLATFORMS_MAX) {
+    fail(`keyword: platforms must be an array of 1..${PLATFORMS_MAX} provider ids`);
+  }
+  const platforms: ProviderId[] = [];
+  for (const platform of value) {
+    const id = providerId(platform, "keyword: platform");
+    if (!platforms.includes(id)) platforms.push(id); // dedupe silently
+  }
+  return platforms;
+}
+
+// ---------------------------------------------------------------------------
+// spec: account_list
+// ---------------------------------------------------------------------------
+
+function parseAccountListSpec(value: unknown): AccountListSpec {
+  const spec = asObject(value, "account_list spec");
+  const rawAccounts = spec["accounts"];
+  if (!Array.isArray(rawAccounts) || rawAccounts.length < 1 || rawAccounts.length > ACCOUNTS_MAX) {
+    fail(`account_list: accounts must be an array of 1..${ACCOUNTS_MAX} entries`);
+  }
+  const accounts: AccountListEntry[] = [];
+  for (const entry of rawAccounts) {
+    const record = asObject(entry, "account_list: account");
+    const provider = providerId(record["provider"], "account_list: provider");
+    const handle = record["handle"];
+    if (typeof handle !== "string") fail("account_list: handle must be a string");
+    const trimmed = handle.trim();
+    if (trimmed.length < 1 || trimmed.length > 200) {
+      fail("account_list: handle must be 1..200 chars after trimming");
+    }
+    if (!isControlCharFree(trimmed)) {
+      fail("account_list: handle must not contain NUL/control characters");
+    }
+    accounts.push({ provider, handle: trimmed });
+  }
+  return { accounts };
+}
+
+// ---------------------------------------------------------------------------
+// refresh_policy
+// ---------------------------------------------------------------------------
+
+function parseRefreshPolicyObject(value: unknown): RefreshPolicy {
+  const result: RefreshPolicy = {};
+  if (value === undefined || value === null) return result; // column default '{}'
+  const policy = asObject(value, "refresh_policy");
+  if (policy["intervalMs"] !== undefined) {
+    const intervalMs = policy["intervalMs"];
+    if (typeof intervalMs !== "number") {
+      fail("refresh_policy: intervalMs must be a number");
+    }
+    result.intervalMs = clampIntervalMs(intervalMs); // non-finite -> floor
+  }
+  if (policy["paused"] !== undefined) {
+    if (typeof policy["paused"] !== "boolean") {
+      fail("refresh_policy: paused must be a boolean");
+    }
+    result.paused = policy["paused"];
+  }
+  return result;
+}
+
+/** Clamp to the design §1.2 window 60_000..3_600_000 (rounded, finite). */
+export function clampIntervalMs(intervalMs: number): number {
+  if (Number.isNaN(intervalMs)) return INTERVAL_FLOOR;
+  return Math.min(Math.max(Math.round(intervalMs), INTERVAL_FLOOR), INTERVAL_CEIL);
+}
+
+/** Effective cadence when the user set none (design §1.2 defaults). */
+export function defaultIntervalMs(type: StreamColumnType): number {
+  return DEFAULT_INTERVAL_MS[type];
+}
+
+// ---------------------------------------------------------------------------
+// Public entry points
+// ---------------------------------------------------------------------------
+
+/** Maps a column type to its exact persisted spec shape (design §1.2). */
+export type SpecForType<T extends StreamColumnType> =
+  T extends "platform_feed" ? PlatformFeedSpec
+  : T extends "account_list" ? AccountListSpec
+  : KeywordSpec; // keyword + saved_search share the keyword engine (§1.1)
+
+/**
+ * Validate + clamp a `spec` for a column type. Throws
+ * StreamColumnsValidationError (→ 422 at the API boundary); returns the
+ * canonical clamped form to persist as JSONB, typed per column type.
+ */
+export function parseStreamColumnSpec<T extends StreamColumnType>(
+  type: T,
+  value: unknown,
+): SpecForType<T> {
+  switch (type) {
+    case "platform_feed":
+      return parsePlatformFeedSpec(value) as SpecForType<T>;
+    case "keyword":
+    case "saved_search":
+      return parseKeywordSpec(value) as SpecForType<T>;
+    case "account_list":
+      return parseAccountListSpec(value) as SpecForType<T>;
+  }
+}
+
+/**
+ * Validate + clamp `refresh_policy` (default `{}`). intervalMs clamps to
+ * 60_000..3_600_000. The budget-derived floor ("never below the
+ * per-connection budget interval") is applied by the scheduler on top of
+ * this; this layer enforces only the global clamp window.
+ */
+export function parseRefreshPolicyClamped(value: unknown = {}): RefreshPolicy {
+  return parseRefreshPolicyObject(value);
+}
+
+// ---------------------------------------------------------------------------
+// Small shared clamps
+// ---------------------------------------------------------------------------
+
+export function isKeywordLike(type: StreamColumnType): type is "keyword" | "saved_search" {
+  return type === "keyword" || type === "saved_search";
+}
+
+/** Trim + cap at 80 chars so a persist can never trip the DB CHECK. */
+export function clampTitle(title: string): string {
+  const trimmed = title.trim();
+  return trimmed.length > STREAM_COLUMN_TITLE_MAX
+    ? trimmed.slice(0, STREAM_COLUMN_TITLE_MAX)
+    : trimmed;
+}
+
+/** Dense-rank positions: finite, non-negative integers. */
+export function clampPosition(position: number): number {
+  if (Number.isNaN(position)) return STREAM_COLUMN_POSITION_DEFAULT;
+  return Math.min(Math.max(Math.round(position), STREAM_COLUMN_POSITION_DEFAULT), POSITION_MAX);
+}
diff --git a/packages/core/src/vc.ts b/packages/core/src/vc.ts
new file mode 100644
index 0000000..0e68375
--- /dev/null
+++ b/packages/core/src/vc.ts
@@ -0,0 +1,266 @@
+import type { CredentialRef } from "./connection.js";
+
+/** Virtual Channel / Auto Director domain (Level 2 — models land in WP1, engines in WP9–WP13). */
+
+export type VirtualChannelMode = "automatic" | "manual" | "hybrid";
+
+export type SwitchPolicyName =
+  | "highest_priority"
+  | "oldest_live"
+  | "newest_live"
+  | "round_robin"
+  | "operator_required"
+  | "picture_in_picture"
+  | "two_up"
+  | "split_screen"
+  | "grid";
+
+export interface SwitchPolicy {
+  name: SwitchPolicyName;
+  /** LIVE confirmation successes required (default 2). */
+  liveConfirmations: number;
+  /** OFFLINE failures required (default 3). */
+  offlineConfirmations: number;
+  /** No-media seconds before OFFLINE (default 10). */
+  noMediaSeconds: number;
+  /** Minimum ms a selected source is held before switching away. */
+  minHoldMs: number;
+  /** Cooldown ms between program switches. */
+  switchCooldownMs: number;
+}
+
+export interface VirtualChannel {
+  id: string;
+  workspaceId: string;
+  name: string;
+  mode: VirtualChannelMode;
+  outputProfileId: string;
+  fallbackSceneId?: string;
+  switchPolicy: SwitchPolicy;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export type LiveSourceStateType =
+  | "OFFLINE"
+  | "UNKNOWN"
+  | "PROBING"
+  | "STARTING"
+  | "LIVE"
+  | "UNSTABLE"
+  | "ENDING"
+  | "ERROR";
+
+export interface VirtualChannelSource {
+  id: string;
+  virtualChannelId: string;
+  provider: string;
+  connectionId?: string;
+  channelId?: string;
+  externalUrl?: string;
+  priority: number;
+  enabled: boolean;
+  autoSelect: boolean;
+  label?: string;
+  metadata: Record<string, unknown>;
+}
+
+export interface LiveSourceState {
+  sourceId: string;
+  state: LiveSourceStateType;
+  detectedAt?: Date;
+  liveSince?: Date;
+  lastHealthyAt?: Date;
+  streamUrl?: string;
+  latencyMs?: number;
+  metadata: Record<string, unknown>;
+}
+
+export interface SourceMonitorState {
+  sourceId: string;
+  current: LiveSourceState;
+  history: readonly LiveSourceState[];
+}
+
+export type SceneLayout =
+  | "single"
+  | "pip"
+  | "two_up"
+  | "split_horizontal"
+  | "split_vertical"
+  | "grid"
+  | "custom";
+
+export type CropMode = "contain" | "cover" | "crop";
+export type SlotAudio = "off" | "on" | "primary";
+
+export interface SceneSlot {
+  sourceId?: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  zIndex: number;
+  cropMode: CropMode;
+  audio: SlotAudio;
+}
+
+export interface ProductionScene {
+  id: string;
+  virtualChannelId: string;
+  name: string;
+  layout: SceneLayout;
+  slots: SceneSlot[];
+  metadata: Record<string, unknown>;
+}
+
+export interface ProductionBus {
+  previewSceneId?: string;
+  programSceneId: string;
+}
+
+export interface DirectorCondition {
+  field: "live_source_count" | "max_priority" | "source_state";
+  op: ">=" | "<=" | "==" | ">";
+  value: number | string;
+}
+
+export interface DirectorAction {
+  layout: SceneLayout;
+  /** Source selection hint: "top_priority" | "all_live" | "oldest_live" | explicit sourceIds. */
+  selection: "top_priority" | "all_live" | "oldest_live" | "explicit";
+  sourceIds?: string[];
+}
+
+export interface AutoDirectorRule {
+  id: string;
+  virtualChannelId: string;
+  priority: number;
+  condition: DirectorCondition;
+  action: DirectorAction;
+}
+
+export type MediaWorkerState =
+  | "STOPPED"
+  | "STARTING"
+  | "RUNNING"
+  | "DEGRADED"
+  | "RESTARTING"
+  | "FAILED";
+
+export interface MediaWorker {
+  id: string;
+  virtualChannelId: string;
+  host: string;
+  state: MediaWorkerState;
+  desiredState: MediaWorkerState;
+  lastHeartbeatAt?: Date;
+}
+
+export interface OutputProfile {
+  id: string;
+  name: string;
+  width: number;
+  height: number;
+  fps: number;
+  videoCodec: string;
+  videoBitrate: number;
+  audioCodec: string;
+  audioBitrate: number;
+  sampleRate: number;
+}
+
+/**
+ * Platform-side live target owned by the live domain (WP6, proposal §4.4).
+ * Owns the provider, the ingest endpoint URL and the vaulted ingest credential
+ * reference — and never references media outputs (aggregate boundary vs
+ * StreamOutput): the inbound FK runs StreamOutput -> destination only.
+ * `ingestCredential` is an opaque vault reference; raw stream keys never
+ * appear in this type by design.
+ */
+export interface LiveStreamDestination {
+  id: string;
+  workspaceId: string;
+  label: string;
+  provider: string;
+  /** Ingest endpoint (rtmp/rtmps/srt push URL). */
+  endpointUrl: string;
+  /** Vault reference to the ingest credential (stream key); absent for keyless targets. */
+  ingestCredential?: CredentialRef;
+  /** Derived, explicitly-stale platform state; runtime truth is the monitor. */
+  lastPlatformState: "unknown" | "created" | "waiting" | "live" | "ended";
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/** Exactly one target: a destination id, or the output's own generic credential handle. */
+export type StreamOutputTarget =
+  | { kind: "destination"; destinationId: string }
+  | { kind: "handle"; credentialHandleId: string };
+
+export interface StreamOutput {
+  id: string;
+  virtualChannelId: string;
+  connectorId: string;
+  connectionId?: string;
+  /** Mutually exclusive with `credentialHandleId`; use `target` for the closed union. */
+  destinationId?: string;
+  /** Mutually exclusive with `destinationId`; an opaque vault handle, never a secret. */
+  credentialHandleId?: string;
+  enabled: boolean;
+}
+
+export function streamOutputTarget(output: Pick<StreamOutput, "destinationId" | "credentialHandleId">): StreamOutputTarget | null {
+  if (output.destinationId !== undefined && output.credentialHandleId !== undefined) {
+    throw new Error("StreamOutput cannot reference both a destination and its own credential handle");
+  }
+  if (output.destinationId !== undefined) return { kind: "destination", destinationId: output.destinationId };
+  if (output.credentialHandleId !== undefined) return { kind: "handle", credentialHandleId: output.credentialHandleId };
+  return null;
+}
+
+export interface LiveStream {
+  id: string;
+  provider: string;
+  connectionId: string;
+  remoteId: string;
+  title: string;
+  state: "created" | "waiting" | "live" | "ended";
+  startedAt?: Date;
+  endedAt?: Date;
+  streamKeyRef?: { readonly kind: "credential-ref"; readonly id: string };
+  rtmpUrl?: string;
+  playbackUrls: string[];
+}
+
+export interface LiveChatMessage {
+  id: string;
+  provider: string;
+  liveStreamId: string;
+  authorHandle: string;
+  text: string;
+  sentAt: Date;
+  isModerated: boolean;
+}
+
+export interface LiveChatParticipant {
+  handle: string;
+  role: "viewer" | "moderator" | "owner" | "bot";
+}
+
+/** Anti-flapping defaults (proposal §5.2 / reducer hysteresis). */
+export const DEFAULT_SWITCH_POLICY: SwitchPolicy = {
+  name: "highest_priority",
+  liveConfirmations: 2,
+  offlineConfirmations: 3,
+  noMediaSeconds: 10,
+  minHoldMs: 2_000,
+  switchCooldownMs: 10_000,
+};
+
+/** TAKE holds per its release mode; LOCK holds until released, expired or revoked. */
+export type DirectorOverrideKind = "take" | "lock";
+/** WP10 manual override release modes (`timed` = expiresAt, default 5 min). */
+export type DirectorOverrideRelease = "until_released" | "timed" | "until_source_offline" | "until_next_event";
+export type DirectorOverrideReleaseReason = "AUTHZ_REVOKED" | "OVERRIDE_EXPIRED" | "SOURCE_OFFLINE" | "NEXT_EVENT";
+export type DirectorMode = "AUTO" | "MANUAL" | "LOCKED" | "FALLBACK";
diff --git a/packages/core/src/video.ts b/packages/core/src/video.ts
new file mode 100644
index 0000000..d4003cf
--- /dev/null
+++ b/packages/core/src/video.ts
@@ -0,0 +1,42 @@
+export interface VideoAsset {
+  id: string;
+  workspaceId: string;
+  storageKey: string;
+  mimeType: string;
+  sizeBytes: number;
+  width?: number;
+  height?: number;
+  durationMs?: number;
+  frameRate?: number;
+  codec?: string;
+  audioCodec?: string;
+  thumbnailKey?: string;
+}
+
+export type VideoProcessingJobState =
+  | "queued"
+  | "probing"
+  | "transcoding"
+  | "complete"
+  | "failed";
+
+export interface VideoProcessingJob {
+  id: string;
+  workspaceId: string;
+  videoAssetId: string;
+  state: VideoProcessingJobState;
+  progressPercent?: number;
+  outputKey?: string;
+  error?: string;
+}
+
+export interface VideoLibraryEntry {
+  videoAsset: VideoAsset;
+  processingState: VideoProcessingJobState;
+  publications: Array<{
+    connectionId: string;
+    remoteId: string;
+    platform: string;
+    publishedAt: Date;
+  }>;
+}
diff --git a/packages/core/src/workspace.ts b/packages/core/src/workspace.ts
new file mode 100644
index 0000000..361fc3b
--- /dev/null
+++ b/packages/core/src/workspace.ts
@@ -0,0 +1,82 @@
+/** Identity & RBAC primitives. Roles are bundles of permission strings. */
+
+export const PERMISSIONS = [
+  "workspace.view",
+  "workspace.settings",
+  "workspace.members.manage",
+  "connection.view",
+  "connection.manage",
+  "credential.manage",
+  "draft.view",
+  "draft.create",
+  "draft.edit",
+  "approval.request",
+  "approval.grant",
+  "publication.publish",
+  "publication.schedule",
+  "publication.delete",
+  "media.view",
+  "media.manage",
+  "inbox.view",
+  "inbox.reply",
+  "stream.view",
+  "analytics.view",
+  "audit.view",
+  "virtualchannel.view",
+  "virtualchannel.create",
+  "virtualchannel.edit",
+  "director.view",
+  "director.take",
+  "director.override_auto",
+  "director.change_layout",
+  "director.lock_program",
+  "streamsource.manage",
+  "streamoutput.manage",
+  "livestream.view",
+  "livestream.manage",
+  "livechat.view",
+  "livechat.send",
+  "livechat.moderate",
+] as const;
+
+export type Permission = (typeof PERMISSIONS)[number];
+
+export type RoleName =
+  | "Owner"
+  | "Admin"
+  | "Publisher"
+  | "Editor"
+  | "Approver"
+  | "Analyst"
+  | "Moderator"
+  | "VideoPublisher"
+  | "StreamOperator"
+  | "BroadcastOperator";
+
+export interface Role {
+  name: RoleName | string;
+  permissions: readonly Permission[];
+}
+
+export interface User {
+  id: string;
+  externalId: string;
+  displayName: string;
+  email: string;
+  createdAt: Date;
+}
+
+export interface Workspace {
+  id: string;
+  name: string;
+  slug: string;
+  createdAt: Date;
+}
+
+export interface Membership {
+  id: string;
+  workspaceId: string;
+  userId: string;
+  role: RoleName;
+  createdAt: Date;
+}
diff --git a/packages/core/tsconfig.json b/packages/core/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/core/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/egress/README.md b/packages/egress/README.md
new file mode 100644
index 0000000..f76919c
--- /dev/null
+++ b/packages/egress/README.md
@@ -0,0 +1,131 @@
+# @tactical-media-broadcast-hub/egress
+
+Shared HTTP(S) egress policy and PostgreSQL host budgets for WP7 callers. This slice
+only adds the package; API and media-worker endpoint validators are migrated later.
+
+```ts
+import { Pool } from "pg";
+import { createEgressClient, EgressError } from "@tactical-media-broadcast-hub/egress";
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL });
+const { egressFetch, policy } = createEgressClient({ pool });
+const response = await egressFetch("https://instance.example/api/v1/videos", {}, {
+  hostClass: "monitor",
+  pinnedOrigin: true,
+});
+```
+
+The caller owns/closes the pool. `egressFetch(url, init, {pool, hostClass, ...config})`
+is also exported for one-off calls. `createEgressClient` reuses configuration and
+returns `{egressFetch, policy, budgets}`. No global pool, application migration or
+in-process budget is created. Requests use Node HTTP(S), bypass proxy environment
+variables, and open a fresh connection for each hop. There is no hidden retry.
+
+## Policy and requests
+
+`validateUrl(url, options)` and `policy.validateUrl(url)` check syntax, literals and
+ports without DNS or database access. `await policy.validate(url)` returns
+`{url, pinnedAddress, family, hostKey}` after resolving once, rejecting every
+non-public answer (including mixed public/private answers), and choosing one
+address. The request lookup returns only this IP. The original hostname remains
+in Host and TLS certificate verification/SNI. A failed address is not replaced
+by an unvalidated address.
+
+HTTP port 80 and HTTPS port 443 are allowed by default. Operator configuration can
+set per-scheme allowlists, e.g. `ports: {"https:": [443, 8443]}`. Credentials in
+URLs, localhost names, whitespace/control characters and backslashes are rejected.
+Query strings are supported; fragments are stripped. Both local blocklists are
+covered, including metadata/link-local, CGNAT, reserved/documentation/benchmark,
+multicast, IPv4-mapped IPv6 and IPv6 transition ranges. Legacy IPv4-compatible,
+site-local and local-use NAT64 ranges are also denied.
+
+301/302/303/307/308 redirects get fresh validation, DNS pins and budget consumption
+per hop. Cycles and more than five redirects fail. Fetch `redirect: "manual"`
+returns the redirect without following; `"error"` rejects it. Cross-origin
+redirects strip Authorization, Proxy-Authorization and cookies; redirects that
+would replay a body across origins are rejected. Use `pinnedOrigin: true` for
+secret-bearing requests and discovery/JWKS fetches: every off-origin redirect is
+rejected before DNS or connection, including a different scheme/port. A URL value
+for `pinnedOrigin` also checks the initial request against that origin.
+
+Responses are buffered into a standard `Response` with final `url` and
+`redirected`. Defaults: 15-second total deadline (DNS, DB, redirects and body),
+8 MiB request/response limits, five redirects. Configure `timeoutMs`,
+`maxRequestBytes`, `maxResponseBytes`, `maxRedirects`; caller abort signals are
+honored. The transport requests identity encoding and rejects upstream compressed
+bodies rather than returning incorrectly decoded bytes. It does not maintain a
+cookie jar. No application-specific authorization is inferred from `hostClass`.
+
+`EgressError.code` distinguishes `DENIED_PRIVATE_ADDRESS`, `SCHEME_DENIED`,
+`PORT_DENIED`, `DNS_FAILED`, `BUDGET_EXHAUSTED`, `REDIRECT_LOOP`, `ORIGIN_DENIED`,
+`TIMEOUT`, `ABORTED`, size limits and invalid input/configuration. Budget errors
+include `retryAfterMs`; messages omit URLs and upstream exception strings.
+
+## Migration and shared buckets
+
+The application migration owner runs `migrations/001_host_budgets.sql` inside a
+transaction, recording **`@tactical-media-broadcast-hub/egress/001_host_budgets.sql`** in the
+existing `schema_migrations(name, applied_at)` ledger in the same transaction.
+Use a namespaced ledger key to avoid colliding with the API's `001_tenants.sql`.
+The SQL is exported via `@tactical-media-broadcast-hub/egress/migrations/001_host_budgets.sql`.
+It neither creates nor writes a separate migration ledger. Grant the runtime
+pool role SELECT/INSERT/UPDATE on `host_budgets` as part of application deployment.
+This is infrastructure state, so no workspace column or RLS policy is installed.
+
+Keys are IDNA/punycode lowercase `host:effective-port` (IPv6 bracketed); trailing
+DNS dots are stripped. All callers, replicas and host classes draw from the same
+row for a key. Default capacity is 3, continuous refill is 10 tokens per fixed
+10-second interval. `hostClasses` configures initial capacity/refill for new hosts,
+e.g. `{monitor: {capacity: 3, refillPerInterval: 10}}`. The first initializer wins;
+later callers cannot enlarge or reset an existing bucket. Administrative changes
+to existing rows must be applied explicitly in the database.
+
+Initialization, row locking, refill and conditional UPDATE/debit occur in one
+transaction. Time is sampled from PostgreSQL after acquiring the lock, so worker
+clock skew and lock waits cannot overfill the bucket. The optional `now` callback
+is a test clock; omit it in production.
+
+429, Retry-After (seconds or HTTP date), and X-RateLimit-Remaining=0 park tokens at
+zero using a future `updated_at`. X-RateLimit-Reset accepts Unix seconds,
+milliseconds, or small delta-second values. Missing/invalid 429 hints default to
+ten seconds. Parking deadlines never shorten due to concurrent responses; refill
+starts at the deadline and the next token becomes available after its refill
+time. Remaining/Limit hints only tighten tokens/capacity/rate; absent a longer
+reset window, Limit is conservatively treated as tokens per ten seconds. Hints
+never increase local limits. Parking is applied at response headers, even if the
+body later fails its size limit. Callers decide when to retry budget errors.
+
+## HLS
+
+`await validateMasterPlaylist(text, playlistUrl, policy)` requires a master
+playlist and returns validated/pinned child endpoints, including variant lines,
+renditions, iframe variants, keys/maps and other URI-bearing attributes.
+`await rewriteSegmentUris(text, playlistUrl, policy)` accepts master/media
+playlists, validates their base and every child, and returns absolute URLs.
+Relative, root-relative, protocol-relative and absolute references are supported.
+Quoted commas, other attribute values, comments and LF/CRLF style are preserved.
+Content-steering SERVER-URI is validated too. Malformed/unquoted/duplicate URI
+attributes and unexpanded HLS variables are rejected.
+
+Rewritten URLs must still be fetched through `egressFetch`, which validates and
+pins at connection time. These helpers do not fetch playlists or hand remote
+URLs to media processes. Relay-local IDs and RTMP/SRT mediation belong to later
+integration work.
+
+## Verification
+
+From this package, with Node 22+ and pnpm available:
+
+```sh
+pnpm install --filter @tactical-media-broadcast-hub/egress --lockfile=false --ignore-scripts
+pnpm exec tsc --noEmit
+pnpm exec vitest run
+```
+
+Database tests use a unique temporary schema and drop it afterward. Set
+`EGRESS_TEST_DATABASE_URL` to a PostgreSQL 15+ database whose test role can create
+schemas; the default is the repository Compose development database at
+`postgres://superposter:superposter_dev@127.0.0.1:5433/superposter`.
+No production tables or application migrations are touched. Tests cover the
+address matrix, DNS pinning/rebinding, redirect policy, PostgreSQL concurrency,
+fake-clock refill, Retry-After/rate-limit parking, request caps and HLS rewriting.
diff --git a/packages/egress/migrations/001_host_budgets.sql b/packages/egress/migrations/001_host_budgets.sql
new file mode 100644
index 0000000..3d1139e
--- /dev/null
+++ b/packages/egress/migrations/001_host_budgets.sql
@@ -0,0 +1,16 @@
+-- Infrastructure state shared by all egress callers; deliberately not tenant/RLS scoped.
+-- Run in an owner transaction and record @tactical-media-broadcast-hub/egress/001_host_budgets.sql
+-- in the application's schema_migrations(name, applied_at). This package never migrates at runtime.
+SET LOCAL lock_timeout = '5s';
+
+CREATE TABLE host_budgets (
+  host text PRIMARY KEY CHECK (host <> '' AND host = lower(host)),
+  capacity double precision NOT NULL CHECK (capacity >= 1 AND capacity < 'Infinity'::double precision),
+  -- Tokens per fixed 10-second interval (fractional tokens support continuous refill).
+  refill_per_interval double precision NOT NULL CHECK (refill_per_interval > 0 AND refill_per_interval < 'Infinity'::double precision),
+  tokens double precision NOT NULL CHECK (tokens >= 0 AND tokens <= capacity),
+  -- A future timestamp parks the bucket: no refill/debit until this deadline.
+  updated_at timestamptz NOT NULL DEFAULT clock_timestamp() CHECK (isfinite(updated_at))
+);
+
+COMMENT ON TABLE host_budgets IS 'Infrastructure egress budgets; one IDNA lowercase host:effective-port key across callers and host classes. Retain while host is in use.';
diff --git a/packages/egress/package.json b/packages/egress/package.json
new file mode 100644
index 0000000..81a0f86
--- /dev/null
+++ b/packages/egress/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/egress",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": "./dist/index.js", "./migrations/*": "./migrations/*" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": { "pg": "^8.23.1" },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/pg": "^8.23.1",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/egress/src/budget.d.ts b/packages/egress/src/budget.d.ts
new file mode 100644
index 0000000..817a997
--- /dev/null
+++ b/packages/egress/src/budget.d.ts
@@ -0,0 +1,23 @@
+import type { Pool } from "pg";
+export declare const REFILL_INTERVAL_MS = 10000;
+export interface HostBudget {
+    capacity: number;
+    refillPerInterval: number;
+}
+export declare const DEFAULT_HOST_BUDGET: Readonly<HostBudget>;
+export interface HostBudgetOptions {
+    pool: Pick<Pool, "connect">;
+    hostClasses?: Readonly<Record<string, HostBudget>>;
+    /** Test clock only. Production uses the DB clock sampled after acquiring the row lock. */
+    now?: () => Date;
+}
+export declare function retryAfterDeadline(headers: Headers, now: number): number | undefined;
+export declare class HostBudgets {
+    private readonly options;
+    constructor(options: HostBudgetOptions);
+    private configuration;
+    private locked;
+    consume(host: string, hostClass: string): Promise<void>;
+    /** Header hints can only tighten a shared budget; parking is monotone under concurrent responses. */
+    observe(host: string, hostClass: string, status: number, headers: Headers): Promise<void>;
+}
diff --git a/packages/egress/src/budget.js b/packages/egress/src/budget.js
new file mode 100644
index 0000000..8c08179
--- /dev/null
+++ b/packages/egress/src/budget.js
@@ -0,0 +1,99 @@
+import { EgressError } from "./errors.js";
+export const REFILL_INTERVAL_MS = 10_000;
+export const DEFAULT_HOST_BUDGET = Object.freeze({ capacity: 3, refillPerInterval: 10 });
+function numericHeader(headers, name) {
+    const raw = headers.get(name);
+    if (raw === null || !/^\d+(?:\.\d+)?$/.test(raw.trim()))
+        return undefined;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+export function retryAfterDeadline(headers, now) {
+    const value = headers.get("retry-after");
+    if (value === null)
+        return undefined;
+    if (/^\d+(?:\.\d+)?$/.test(value.trim())) {
+        const deadline = now + Number(value) * 1000;
+        return Number.isFinite(deadline) && deadline <= 8.64e15 ? deadline : undefined;
+    }
+    const deadline = Date.parse(value);
+    return Number.isFinite(deadline) ? Math.max(now, deadline) : undefined;
+}
+export class HostBudgets {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    configuration(hostClass) {
+        const config = this.options.hostClasses?.[hostClass] ?? DEFAULT_HOST_BUDGET;
+        if (!Number.isFinite(config.capacity) || config.capacity < 1 || !Number.isFinite(config.refillPerInterval) || config.refillPerInterval <= 0) {
+            throw new EgressError("INVALID_CONFIGURATION", "Invalid host budget");
+        }
+        return config;
+    }
+    async locked(host, hostClass, action) {
+        const config = this.configuration(hostClass);
+        const client = await this.options.pool.connect().catch(() => { throw new EgressError("BUDGET_UNAVAILABLE", "Budget database is unavailable"); });
+        try {
+            await client.query("BEGIN");
+            // Existing rows remain authoritative: another caller/class cannot reset or enlarge a bucket.
+            await client.query(`INSERT INTO host_budgets(host, capacity, refill_per_interval, tokens, updated_at)
+        VALUES ($1, $2, $3, $2, COALESCE($4::timestamptz, clock_timestamp())) ON CONFLICT (host) DO NOTHING`, [host, config.capacity, config.refillPerInterval, this.options.now?.() ?? null]);
+            const row = (await client.query("SELECT capacity, refill_per_interval, tokens, updated_at FROM host_budgets WHERE host = $1 FOR UPDATE", [host])).rows[0];
+            // Keep microseconds in SQL parameters. pg's Date parser truncates them and can make
+            // a freshly inserted bucket appear parked if both queries finish in one millisecond.
+            const timestamp = this.options.now?.() ?? (await client.query("SELECT clock_timestamp()::text AS now")).rows[0].now;
+            const now = typeof timestamp === "string" ? new Date(timestamp) : timestamp;
+            const result = await action(client, row, now, timestamp);
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (error) {
+            await client.query("ROLLBACK").catch(() => undefined);
+            throw error instanceof EgressError ? error : new EgressError("BUDGET_UNAVAILABLE", "Budget transaction failed");
+        }
+        finally {
+            client.release();
+        }
+    }
+    async consume(host, hostClass) {
+        const retryAfterMs = await this.locked(host, hostClass, async (client, row, now, timestamp) => {
+            const result = await client.query(`UPDATE host_budgets
+        SET tokens = LEAST(capacity, tokens + GREATEST(0, EXTRACT(EPOCH FROM ($2::timestamptz - updated_at))) * refill_per_interval / 10) - 1,
+            updated_at = $2
+        WHERE host = $1 AND updated_at <= $2
+          AND LEAST(capacity, tokens + GREATEST(0, EXTRACT(EPOCH FROM ($2::timestamptz - updated_at))) * refill_per_interval / 10) >= 1
+        RETURNING tokens`, [host, timestamp]);
+            if (result.rowCount)
+                return undefined;
+            const elapsed = Math.max(0, now.getTime() - row.updated_at.getTime());
+            return Math.ceil(Math.max(0, row.updated_at.getTime() - now.getTime()) + Math.max(0, (1 - row.tokens) * REFILL_INTERVAL_MS / row.refill_per_interval - elapsed));
+        });
+        if (retryAfterMs !== undefined)
+            throw new EgressError("BUDGET_EXHAUSTED", "Host budget is exhausted", retryAfterMs);
+    }
+    /** Header hints can only tighten a shared budget; parking is monotone under concurrent responses. */
+    async observe(host, hostClass, status, headers) {
+        const remaining = numericHeader(headers, "x-ratelimit-remaining");
+        const limit = numericHeader(headers, "x-ratelimit-limit");
+        if (status !== 429 && !headers.has("retry-after") && remaining === undefined && limit === undefined)
+            return;
+        await this.locked(host, hostClass, async (client, row, now, timestamp) => {
+            const time = now.getTime();
+            const reset = numericHeader(headers, "x-ratelimit-reset");
+            const proposedReset = reset === undefined ? undefined : reset >= 1e12 ? reset : reset >= 1e9 ? reset * 1000 : time + reset * 1000;
+            const resetAt = proposedReset !== undefined && proposedReset <= 8.64e15 ? proposedReset : undefined;
+            const retryAt = retryAfterDeadline(headers, time);
+            const exhausted = status === 429 || remaining === 0 || retryAt !== undefined;
+            const capacity = Math.min(row.capacity, limit !== undefined && limit >= 1 ? limit : row.capacity);
+            // When no window is supplied, conservatively interpret Limit per our fixed 10-second interval.
+            const refill = limit !== undefined && limit >= 1 ? Math.min(row.refill_per_interval, limit * REFILL_INTERVAL_MS / Math.max(REFILL_INTERVAL_MS, (resetAt ?? time) - time)) : row.refill_per_interval;
+            const deadline = exhausted ? Math.max(time, retryAt ?? 0, resetAt ?? 0, retryAt === undefined && resetAt === undefined ? time + REFILL_INTERVAL_MS : 0) : time;
+            await client.query(`UPDATE host_budgets SET capacity = $2,
+        tokens = CASE WHEN $6::boolean THEN 0 ELSE LEAST($2, $3,
+          tokens + GREATEST(0, EXTRACT(EPOCH FROM ($7::timestamptz - updated_at))) * refill_per_interval / 10) END,
+        updated_at = GREATEST(updated_at, $4::timestamptz), refill_per_interval = $5 WHERE host = $1`, [host, capacity, remaining ?? capacity, exhausted ? new Date(Math.max(row.updated_at.getTime(), deadline)) : timestamp, refill, exhausted, timestamp]);
+        });
+    }
+}
+//# sourceMappingURL=budget.js.map
\ No newline at end of file
diff --git a/packages/egress/src/budget.js.map b/packages/egress/src/budget.js.map
new file mode 100644
index 0000000..aff192d
--- /dev/null
+++ b/packages/egress/src/budget.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["budget.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE1C,MAAM,CAAC,MAAM,kBAAkB,GAAG,MAAM,CAAC;AAEzC,MAAM,CAAC,MAAM,mBAAmB,GAAyB,MAAM,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,iBAAiB,EAAE,EAAE,EAAE,CAAC,CAAC;AAS/G,SAAS,aAAa,CAAC,OAAgB,EAAE,IAAY;IACnD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,GAAG,KAAK,IAAI,IAAI,CAAC,iBAAiB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;AACpD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,GAAW;IAC9D,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,SAAS,CAAC;IACrC,IAAI,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;QACzC,MAAM,QAAQ,GAAG,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QAC5C,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACjF,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IACnC,OAAO,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzE,CAAC;AAED,MAAM,OAAO,WAAW;IACO;IAA7B,YAA6B,OAA0B;QAA1B,YAAO,GAAP,OAAO,CAAmB;IAAG,CAAC;IACnD,aAAa,CAAC,SAAiB;QACrC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,SAAS,CAAC,IAAI,mBAAmB,CAAC;QAC5E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,MAAM,CAAC,iBAAiB,IAAI,CAAC,EAAE,CAAC;YAC5I,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,qBAAqB,CAAC,CAAC;QACxE,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,MAAM,CAAI,IAAY,EAAE,SAAiB,EAAE,MAA+F;QACtJ,MAAM,MAAM,GAAG,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;QAC7C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,MAAM,IAAI,WAAW,CAAC,oBAAoB,EAAE,gCAAgC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACjJ,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5B,6FAA6F;YAC7F,MAAM,MAAM,CAAC,KAAK,CAAC;4GACmF,EACtG,CAAC,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,iBAAiB,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,IAAI,CAAC,CAAC,CAAC;YACjF,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,KAAK,CAAY,uGAAuG,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC;YACtK,oFAAoF;YACpF,qFAAqF;YACrF,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,MAAM,MAAM,CAAC,KAAK,CAAkB,uCAAuC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAE,CAAC,GAAG,CAAC;YACtI,MAAM,GAAG,GAAG,OAAO,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC5E,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,CAAC,CAAC;YACzD,MAAM,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YAC7B,OAAO,MAAM,CAAC;QAChB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACtD,MAAM,KAAK,YAAY,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,oBAAoB,EAAE,2BAA2B,CAAC,CAAC;QAClH,CAAC;gBAAS,CAAC;YAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,SAAiB;QAC3C,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE;YAC5F,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAAC;;;;;yBAKf,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC;YACxC,IAAI,MAAM,CAAC,QAAQ;gBAAE,OAAO,SAAS,CAAC;YACtC,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,CAAC,CAAC;YACtE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,kBAAkB,GAAG,GAAG,CAAC,mBAAmB,GAAG,OAAO,CAAC,CAAC,CAAC;QACnK,CAAC,CAAC,CAAC;QACH,IAAI,YAAY,KAAK,SAAS;YAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,0BAA0B,EAAE,YAAY,CAAC,CAAC;IACtH,CAAC;IAED,qGAAqG;IACrG,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,SAAiB,EAAE,MAAc,EAAE,OAAgB;QAC7E,MAAM,SAAS,GAAG,aAAa,CAAC,OAAO,EAAE,uBAAuB,CAAC,CAAC;QAClE,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;QAC1D,IAAI,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,IAAI,SAAS,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS;YAAE,OAAO;QAC5G,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,SAAS,EAAE,EAAE;YACvE,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;YAC3B,MAAM,KAAK,GAAG,aAAa,CAAC,OAAO,EAAE,mBAAmB,CAAC,CAAC;YAC1D,MAAM,aAAa,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,GAAG,IAAI,CAAC;YAClI,MAAM,OAAO,GAAG,aAAa,KAAK,SAAS,IAAI,aAAa,IAAI,OAAO,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC;YACpG,MAAM,OAAO,GAAG,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;YAClD,MAAM,SAAS,GAAG,MAAM,KAAK,GAAG,IAAI,SAAS,KAAK,CAAC,IAAI,OAAO,KAAK,SAAS,CAAC;YAC7E,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YAClG,+FAA+F;YAC/F,MAAM,MAAM,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,mBAAmB,EACjF,KAAK,GAAG,kBAAkB,GAAG,IAAI,CAAC,GAAG,CAAC,kBAAkB,EAAE,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,mBAAmB,CAAC;YACjH,MAAM,QAAQ,GAAG,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,CAAC,EAAE,OAAO,IAAI,CAAC,EACpE,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;YACzF,MAAM,MAAM,CAAC,KAAK,CAAC;;;qGAG4E,EAC/F,CAAC,IAAI,EAAE,QAAQ,EAAE,SAAS,IAAI,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,CAAC,CAAC,CAAC;QACzJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}
\ No newline at end of file
diff --git a/packages/egress/src/budget.test.ts b/packages/egress/src/budget.test.ts
new file mode 100644
index 0000000..bfe5b9c
--- /dev/null
+++ b/packages/egress/src/budget.test.ts
@@ -0,0 +1,71 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { HostBudgets } from "./budget.js";
+import { testDatabase } from "./test-db.js";
+
+describe("PostgreSQL host budgets", () => {
+  const pool = testDatabase();
+  afterEach(() => { vi.useRealTimers(); });
+  function clock() {
+    vi.useFakeTimers({ toFake: ["Date"] });
+    vi.setSystemTime(new Date("2026-01-01T00:00:00Z"));
+    return () => new Date();
+  }
+  it("parallel callers share one atomic capacity even on first initialization", async () => {
+    const now = clock();
+    const callers = Array.from({ length: 16 }, () => new HostBudgets({ pool, now }));
+    const results = await Promise.allSettled(Array.from({ length: 80 }, (_, index) => callers[index % callers.length]!.consume("example.com:443", "monitor")));
+    expect(results.filter((r) => r.status === "fulfilled")).toHaveLength(3);
+    for (const result of results) if (result.status === "rejected") expect(result.reason).toMatchObject({ code: "BUDGET_EXHAUSTED", retryAfterMs: 1000 });
+    expect((await pool.query("SELECT tokens FROM host_budgets")).rows[0].tokens).toBe(0);
+  });
+  it("refills fractional tokens, caps idle refill, and tolerates a backwards clock", async () => {
+    const now = clock();
+    const bucket = new HostBudgets({ pool, now });
+    for (let i = 0; i < 3; i++) await bucket.consume("example.com:443", "monitor");
+    vi.setSystemTime(Date.now() + 999);
+    await expect(bucket.consume("example.com:443", "monitor")).rejects.toMatchObject({ code: "BUDGET_EXHAUSTED", retryAfterMs: 1 });
+    vi.setSystemTime(Date.now() + 1);
+    await bucket.consume("example.com:443", "monitor");
+    vi.setSystemTime(Date.now() + 60_000);
+    for (let i = 0; i < 3; i++) await bucket.consume("example.com:443", "monitor");
+    await expect(bucket.consume("example.com:443", "monitor")).rejects.toMatchObject({ code: "BUDGET_EXHAUSTED" });
+    vi.setSystemTime(Date.now() - 5000);
+    await expect(bucket.consume("example.com:443", "monitor")).rejects.toMatchObject({ code: "BUDGET_EXHAUSTED", retryAfterMs: 6000 });
+  });
+  it.each(["seconds", "date"])("parks on Retry-After (%s) without a concurrent response shortening the deadline", async (kind) => {
+    const now = clock();
+    const bucket = new HostBudgets({ pool, now });
+    const retry = kind === "seconds" ? "5" : new Date(Date.now() + 5000).toUTCString();
+    await bucket.consume("example.com:443", "monitor");
+    await bucket.observe("example.com:443", "monitor", 429, new Headers({ "Retry-After": retry }));
+    await bucket.observe("example.com:443", "monitor", 429, new Headers({ "Retry-After": "1" }));
+    await bucket.observe("example.com:443", "monitor", 200, new Headers({ "X-RateLimit-Remaining": "100" }));
+    vi.setSystemTime(Date.now() + 5000);
+    await expect(bucket.consume("example.com:443", "monitor")).rejects.toMatchObject({ retryAfterMs: 1000 });
+    vi.setSystemTime(Date.now() + 1000);
+    await bucket.consume("example.com:443", "monitor");
+  });
+  it("honors reset/remaining/limit and defaults missing 429 hints to ten seconds", async () => {
+    const now = clock();
+    const bucket = new HostBudgets({ pool, now });
+    await bucket.consume("example.com:443", "monitor");
+    await bucket.observe("example.com:443", "monitor", 200, new Headers({ "X-RateLimit-Remaining": "0", "X-RateLimit-Reset": String((Date.now() + 7000) / 1000), "X-RateLimit-Limit": "2" }));
+    await expect(bucket.consume("example.com:443", "monitor")).rejects.toMatchObject({ retryAfterMs: 12000 });
+    expect((await pool.query("SELECT capacity, tokens, refill_per_interval FROM host_budgets")).rows[0]).toMatchObject({ capacity: 2, tokens: 0, refill_per_interval: 2 });
+    await bucket.observe("other.com:443", "monitor", 429, new Headers({ "Retry-After": "invalid" }));
+    await expect(bucket.consume("other.com:443", "monitor")).rejects.toMatchObject({ retryAfterMs: 11000 });
+  });
+  it("uses DB time by default, isolates ports/hosts and prevents class-based resets", async () => {
+    const bucket = new HostBudgets({ pool, hostClasses: { large: { capacity: 100, refillPerInterval: 100 } } });
+    await bucket.consume("example.com:443", "monitor");
+    await bucket.consume("example.com:443", "large");
+    await bucket.consume("example.com:80", "large");
+    const rows = (await pool.query("SELECT host, capacity FROM host_budgets ORDER BY host")).rows;
+    expect(rows).toEqual([{ host: "example.com:443", capacity: 3 }, { host: "example.com:80", capacity: 100 }]);
+  });
+  it("never mistakes newly created buckets for parked buckets with the DB microsecond clock", async () => {
+    const bucket = new HostBudgets({ pool });
+    for (let i = 0; i < 40; i++) await bucket.consume(`fresh-${i}.example:443`, "monitor");
+    expect((await pool.query("SELECT count(*)::int AS count FROM host_budgets WHERE tokens >= 2 AND tokens <= 3")).rows[0].count).toBe(40);
+  });
+});
diff --git a/packages/egress/src/budget.ts b/packages/egress/src/budget.ts
new file mode 100644
index 0000000..44df446
--- /dev/null
+++ b/packages/egress/src/budget.ts
@@ -0,0 +1,106 @@
+import type { Pool, PoolClient } from "pg";
+import { EgressError } from "./errors.js";
+
+export const REFILL_INTERVAL_MS = 10_000;
+export interface HostBudget { capacity: number; refillPerInterval: number }
+export const DEFAULT_HOST_BUDGET: Readonly<HostBudget> = Object.freeze({ capacity: 3, refillPerInterval: 10 });
+export interface HostBudgetOptions {
+  pool: Pick<Pool, "connect">;
+  hostClasses?: Readonly<Record<string, HostBudget>>;
+  /** Test clock only. Production uses the DB clock sampled after acquiring the row lock. */
+  now?: () => Date;
+}
+interface BudgetRow { capacity: number; refill_per_interval: number; tokens: number; updated_at: Date }
+
+function numericHeader(headers: Headers, name: string): number | undefined {
+  const raw = headers.get(name);
+  if (raw === null || !/^\d+(?:\.\d+)?$/.test(raw.trim())) return undefined;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : undefined;
+}
+
+export function retryAfterDeadline(headers: Headers, now: number): number | undefined {
+  const value = headers.get("retry-after");
+  if (value === null) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(value.trim())) {
+    const deadline = now + Number(value) * 1000;
+    return Number.isFinite(deadline) && deadline <= 8.64e15 ? deadline : undefined;
+  }
+  const deadline = Date.parse(value);
+  return Number.isFinite(deadline) ? Math.max(now, deadline) : undefined;
+}
+
+export class HostBudgets {
+  constructor(private readonly options: HostBudgetOptions) {}
+  private configuration(hostClass: string): HostBudget {
+    const config = this.options.hostClasses?.[hostClass] ?? DEFAULT_HOST_BUDGET;
+    if (!Number.isFinite(config.capacity) || config.capacity < 1 || !Number.isFinite(config.refillPerInterval) || config.refillPerInterval <= 0) {
+      throw new EgressError("INVALID_CONFIGURATION", "Invalid host budget");
+    }
+    return config;
+  }
+
+  private async locked<T>(host: string, hostClass: string, action: (client: PoolClient, row: BudgetRow, now: Date, timestamp: Date | string) => Promise<T>): Promise<T> {
+    const config = this.configuration(hostClass);
+    const client = await this.options.pool.connect().catch(() => { throw new EgressError("BUDGET_UNAVAILABLE", "Budget database is unavailable"); });
+    try {
+      await client.query("BEGIN");
+      // Existing rows remain authoritative: another caller/class cannot reset or enlarge a bucket.
+      await client.query(`INSERT INTO host_budgets(host, capacity, refill_per_interval, tokens, updated_at)
+        VALUES ($1, $2, $3, $2, COALESCE($4::timestamptz, clock_timestamp())) ON CONFLICT (host) DO NOTHING`,
+      [host, config.capacity, config.refillPerInterval, this.options.now?.() ?? null]);
+      const row = (await client.query<BudgetRow>("SELECT capacity, refill_per_interval, tokens, updated_at FROM host_budgets WHERE host = $1 FOR UPDATE", [host])).rows[0]!;
+      // Keep microseconds in SQL parameters. pg's Date parser truncates them and can make
+      // a freshly inserted bucket appear parked if both queries finish in one millisecond.
+      const timestamp = this.options.now?.() ?? (await client.query<{ now: string }>("SELECT clock_timestamp()::text AS now")).rows[0]!.now;
+      const now = typeof timestamp === "string" ? new Date(timestamp) : timestamp;
+      const result = await action(client, row, now, timestamp);
+      await client.query("COMMIT");
+      return result;
+    } catch (error) {
+      await client.query("ROLLBACK").catch(() => undefined);
+      throw error instanceof EgressError ? error : new EgressError("BUDGET_UNAVAILABLE", "Budget transaction failed");
+    } finally { client.release(); }
+  }
+
+  async consume(host: string, hostClass: string): Promise<void> {
+    const retryAfterMs = await this.locked(host, hostClass, async (client, row, now, timestamp) => {
+      const result = await client.query(`UPDATE host_budgets
+        SET tokens = LEAST(capacity, tokens + GREATEST(0, EXTRACT(EPOCH FROM ($2::timestamptz - updated_at))) * refill_per_interval / 10) - 1,
+            updated_at = $2
+        WHERE host = $1 AND updated_at <= $2
+          AND LEAST(capacity, tokens + GREATEST(0, EXTRACT(EPOCH FROM ($2::timestamptz - updated_at))) * refill_per_interval / 10) >= 1
+        RETURNING tokens`, [host, timestamp]);
+      if (result.rowCount) return undefined;
+      const elapsed = Math.max(0, now.getTime() - row.updated_at.getTime());
+      return Math.ceil(Math.max(0, row.updated_at.getTime() - now.getTime()) + Math.max(0, (1 - row.tokens) * REFILL_INTERVAL_MS / row.refill_per_interval - elapsed));
+    });
+    if (retryAfterMs !== undefined) throw new EgressError("BUDGET_EXHAUSTED", "Host budget is exhausted", retryAfterMs);
+  }
+
+  /** Header hints can only tighten a shared budget; parking is monotone under concurrent responses. */
+  async observe(host: string, hostClass: string, status: number, headers: Headers): Promise<void> {
+    const remaining = numericHeader(headers, "x-ratelimit-remaining");
+    const limit = numericHeader(headers, "x-ratelimit-limit");
+    if (status !== 429 && !headers.has("retry-after") && remaining === undefined && limit === undefined) return;
+    await this.locked(host, hostClass, async (client, row, now, timestamp) => {
+      const time = now.getTime();
+      const reset = numericHeader(headers, "x-ratelimit-reset");
+      const proposedReset = reset === undefined ? undefined : reset >= 1e12 ? reset : reset >= 1e9 ? reset * 1000 : time + reset * 1000;
+      const resetAt = proposedReset !== undefined && proposedReset <= 8.64e15 ? proposedReset : undefined;
+      const retryAt = retryAfterDeadline(headers, time);
+      const exhausted = status === 429 || remaining === 0 || retryAt !== undefined;
+      const capacity = Math.min(row.capacity, limit !== undefined && limit >= 1 ? limit : row.capacity);
+      // When no window is supplied, conservatively interpret Limit per our fixed 10-second interval.
+      const refill = limit !== undefined && limit >= 1 ? Math.min(row.refill_per_interval,
+        limit * REFILL_INTERVAL_MS / Math.max(REFILL_INTERVAL_MS, (resetAt ?? time) - time)) : row.refill_per_interval;
+      const deadline = exhausted ? Math.max(time, retryAt ?? 0, resetAt ?? 0,
+        retryAt === undefined && resetAt === undefined ? time + REFILL_INTERVAL_MS : 0) : time;
+      await client.query(`UPDATE host_budgets SET capacity = $2,
+        tokens = CASE WHEN $6::boolean THEN 0 ELSE LEAST($2, $3,
+          tokens + GREATEST(0, EXTRACT(EPOCH FROM ($7::timestamptz - updated_at))) * refill_per_interval / 10) END,
+        updated_at = GREATEST(updated_at, $4::timestamptz), refill_per_interval = $5 WHERE host = $1`,
+      [host, capacity, remaining ?? capacity, exhausted ? new Date(Math.max(row.updated_at.getTime(), deadline)) : timestamp, refill, exhausted, timestamp]);
+    });
+  }
+}
diff --git a/packages/egress/src/client.d.ts b/packages/egress/src/client.d.ts
new file mode 100644
index 0000000..4c56494
--- /dev/null
+++ b/packages/egress/src/client.d.ts
@@ -0,0 +1,20 @@
+import { HostBudgets, type HostBudgetOptions } from "./budget.js";
+import { EgressPolicy, type EgressPolicyOptions } from "./policy.js";
+export interface EgressClientOptions extends HostBudgetOptions, EgressPolicyOptions {
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    maxRequestBytes?: number;
+    maxRedirects?: number;
+}
+export interface EgressRequestOptions {
+    hostClass: string;
+    /** true pins to the initial origin; a URL string explicitly pins to that origin. */
+    pinnedOrigin?: boolean | string | URL;
+}
+export declare function createEgressClient(options: EgressClientOptions): {
+    egressFetch: (raw: string | URL, init: RequestInit | undefined, context: EgressRequestOptions) => Promise<Response>;
+    policy: EgressPolicy;
+    budgets: HostBudgets;
+};
+/** Stateless convenience form. Reuse createEgressClient when pool/config are fixed. */
+export declare function egressFetch(url: string | URL, init: RequestInit | undefined, options: EgressClientOptions & EgressRequestOptions): Promise<Response>;
diff --git a/packages/egress/src/client.js b/packages/egress/src/client.js
new file mode 100644
index 0000000..a4a0b0a
--- /dev/null
+++ b/packages/egress/src/client.js
@@ -0,0 +1,142 @@
+import { HostBudgets } from "./budget.js";
+import { EgressError } from "./errors.js";
+import { EgressPolicy } from "./policy.js";
+import { requestPinned } from "./transport.js";
+const redirectStatuses = new Set([301, 302, 303, 307, 308]);
+export function createEgressClient(options) {
+    const policy = new EgressPolicy(options);
+    const budgets = new HostBudgets(options);
+    const timeoutMs = options.timeoutMs ?? 15_000;
+    const maxResponseBytes = options.maxResponseBytes ?? 8 * 1024 * 1024;
+    const maxRequestBytes = options.maxRequestBytes ?? 8 * 1024 * 1024;
+    const maxRedirects = options.maxRedirects ?? 5;
+    if (![timeoutMs, maxResponseBytes, maxRequestBytes].every((value) => Number.isSafeInteger(value) && value > 0) || !Number.isSafeInteger(maxRedirects) || maxRedirects < 0) {
+        throw new EgressError("INVALID_CONFIGURATION", "Invalid request limits");
+    }
+    async function egressFetch(raw, init = {}, context) {
+        const controller = new AbortController();
+        const abort = () => controller.abort(new EgressError("ABORTED", "Request aborted"));
+        init.signal?.addEventListener("abort", abort, { once: true });
+        if (init.signal?.aborted)
+            abort();
+        const timer = setTimeout(() => controller.abort(new EgressError("TIMEOUT", "Egress deadline exceeded")), timeoutMs);
+        const check = () => { if (controller.signal.aborted)
+            throw controller.signal.reason; };
+        let abortListener;
+        const cancelled = new Promise((_resolve, reject) => {
+            abortListener = () => reject(controller.signal.reason);
+            controller.signal.addEventListener("abort", abortListener, { once: true });
+            if (controller.signal.aborted)
+                abortListener();
+        });
+        const run = async () => {
+            check();
+            let url = policy.validateUrl(raw);
+            const pinnedOrigin = context.pinnedOrigin === true ? url.origin : context.pinnedOrigin ? policy.validateUrl(context.pinnedOrigin).origin : undefined;
+            if (pinnedOrigin && url.origin !== pinnedOrigin)
+                throw new EgressError("ORIGIN_DENIED", "Request is outside the pinned origin");
+            // Request provides fetch method/header/body normalization; the transport owns connection options.
+            let normalized;
+            try {
+                normalized = new Request(url, init);
+            }
+            catch {
+                throw new EgressError("INVALID_REQUEST", "Invalid fetch request initialization");
+            }
+            let method = normalized.method;
+            const headers = new Headers(normalized.headers);
+            let body;
+            if (normalized.body) {
+                const reader = normalized.body.getReader();
+                const cancelBody = () => { void reader.cancel().catch(() => undefined); };
+                controller.signal.addEventListener("abort", cancelBody, { once: true });
+                const chunks = [];
+                let size = 0;
+                try {
+                    for (;;) {
+                        check();
+                        const { value, done } = await reader.read();
+                        if (done)
+                            break;
+                        size += value.length;
+                        if (size > maxRequestBytes)
+                            throw new EgressError("REQUEST_TOO_LARGE", "Request exceeds size limit");
+                        chunks.push(Buffer.from(value));
+                    }
+                    body = Buffer.concat(chunks);
+                }
+                finally {
+                    controller.signal.removeEventListener("abort", cancelBody);
+                    void reader.cancel().catch(() => undefined);
+                }
+            }
+            const visited = new Set();
+            for (let hop = 0;; hop++) {
+                check();
+                if (visited.has(url.href))
+                    throw new EgressError("REDIRECT_LOOP", "Redirect cycle detected");
+                visited.add(url.href);
+                const endpoint = await policy.validate(url);
+                check();
+                await budgets.consume(endpoint.hostKey, context.hostClass);
+                check();
+                const wire = await requestPinned(endpoint, method, headers, body, controller.signal, maxResponseBytes, (status, responseHeaders) => budgets.observe(endpoint.hostKey, context.hostClass, status, responseHeaders));
+                check();
+                const location = wire.headers.get("location");
+                if (!redirectStatuses.has(wire.status) || !location || init.redirect === "manual") {
+                    const response = new Response(method === "HEAD" || [204, 205, 304].includes(wire.status) ? null : new Uint8Array(wire.body), { status: wire.status, statusText: wire.statusText, headers: wire.headers });
+                    Object.defineProperties(response, { url: { value: url.href }, redirected: { value: hop > 0 } });
+                    return response;
+                }
+                if (init.redirect === "error" || hop >= maxRedirects)
+                    throw new EgressError("REDIRECT_LOOP", "Redirect limit exceeded");
+                if (/[\s\\\u0000-\u001f\u007f]/u.test(location))
+                    throw new EgressError("INVALID_URL", "Malformed redirect target");
+                let target;
+                try {
+                    target = policy.validateUrl(new URL(location, url));
+                }
+                catch (error) {
+                    if (error instanceof EgressError)
+                        throw error;
+                    throw new EgressError("INVALID_URL", "Invalid redirect target");
+                }
+                if (pinnedOrigin && target.origin !== pinnedOrigin)
+                    throw new EgressError("ORIGIN_DENIED", "Redirect is outside the pinned origin");
+                if (target.origin !== url.origin) {
+                    for (const name of ["authorization", "proxy-authorization", "cookie", "cookie2"])
+                        headers.delete(name);
+                    // A body can contain secrets just as headers can; refuse to replay it off-origin.
+                    if (body && (wire.status === 307 || wire.status === 308 || method !== "POST" && wire.status !== 303)) {
+                        throw new EgressError("ORIGIN_DENIED", "Request body cannot be redirected off-origin");
+                    }
+                }
+                if (wire.status === 303 && method !== "HEAD" || (wire.status === 301 || wire.status === 302) && method === "POST") {
+                    method = "GET";
+                    body = undefined;
+                    for (const name of ["content-type", "content-length", "content-encoding", "content-language", "content-location"])
+                        headers.delete(name);
+                }
+                url = target;
+            }
+        };
+        try {
+            return await Promise.race([run(), cancelled]);
+        }
+        catch (error) {
+            throw error instanceof EgressError ? error : new EgressError("NETWORK_ERROR", "Egress request failed");
+        }
+        finally {
+            clearTimeout(timer);
+            init.signal?.removeEventListener("abort", abort);
+            if (abortListener)
+                controller.signal.removeEventListener("abort", abortListener);
+        }
+    }
+    return { egressFetch, policy, budgets };
+}
+/** Stateless convenience form. Reuse createEgressClient when pool/config are fixed. */
+export function egressFetch(url, init = {}, options) {
+    return createEgressClient(options).egressFetch(url, init, options);
+}
+//# sourceMappingURL=client.js.map
\ No newline at end of file
diff --git a/packages/egress/src/client.js.map b/packages/egress/src/client.js.map
new file mode 100644
index 0000000..ef13e70
--- /dev/null
+++ b/packages/egress/src/client.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAA0B,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAA4B,MAAM,aAAa,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAa/C,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE5D,MAAM,UAAU,kBAAkB,CAAC,OAA4B;IAC7D,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,OAAO,GAAG,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,CAAC;IAC9C,MAAM,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACrE,MAAM,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IACnE,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,CAAC;IAC/C,IAAI,CAAC,CAAC,SAAS,EAAE,gBAAgB,EAAE,eAAe,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC1K,MAAM,IAAI,WAAW,CAAC,uBAAuB,EAAE,wBAAwB,CAAC,CAAC;IAC3E,CAAC;IAED,KAAK,UAAU,WAAW,CAAC,GAAiB,EAAE,OAAoB,EAAE,EAAE,OAA6B;QACjG,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACpF,IAAI,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9D,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;YAAE,KAAK,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,IAAI,WAAW,CAAC,SAAS,EAAE,0BAA0B,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;QACpH,MAAM,KAAK,GAAG,GAAG,EAAE,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;YAAE,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACvF,IAAI,aAAuC,CAAC;QAC5C,MAAM,SAAS,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;YACxD,aAAa,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACvD,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC3E,IAAI,UAAU,CAAC,MAAM,CAAC,OAAO;gBAAE,aAAa,EAAE,CAAC;QACjD,CAAC,CAAC,CAAC;QACH,MAAM,GAAG,GAAG,KAAK,IAAI,EAAE;YACrB,KAAK,EAAE,CAAC;YACR,IAAI,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAClC,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,KAAK,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YACrJ,IAAI,YAAY,IAAI,GAAG,CAAC,MAAM,KAAK,YAAY;gBAAE,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,sCAAsC,CAAC,CAAC;YAChI,kGAAkG;YAClG,IAAI,UAAmB,CAAC;YACxB,IAAI,CAAC;gBAAC,UAAU,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YAAC,CAAC;YAC5C,MAAM,CAAC;gBAAC,MAAM,IAAI,WAAW,CAAC,iBAAiB,EAAE,sCAAsC,CAAC,CAAC;YAAC,CAAC;YAC3F,IAAI,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;YAC/B,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;YAChD,IAAI,IAAwB,CAAC;YAC7B,IAAI,UAAU,CAAC,IAAI,EAAE,CAAC;gBACpB,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;gBAC3C,MAAM,UAAU,GAAG,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;gBAC1E,UAAU,CAAC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;gBACxE,MAAM,MAAM,GAAa,EAAE,CAAC;gBAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;gBACb,IAAI,CAAC;oBACH,SAAS,CAAC;wBACR,KAAK,EAAE,CAAC;wBACR,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;wBAC5C,IAAI,IAAI;4BAAE,MAAM;wBAChB,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;wBACrB,IAAI,IAAI,GAAG,eAAe;4BAAE,MAAM,IAAI,WAAW,CAAC,mBAAmB,EAAE,4BAA4B,CAAC,CAAC;wBACrG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;oBAClC,CAAC;oBACD,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBAC/B,CAAC;wBAAS,CAAC;oBACT,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;oBAC3D,KAAK,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;gBAC9C,CAAC;YACH,CAAC;YACD,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;YAClC,KAAK,IAAI,GAAG,GAAG,CAAC,GAAI,GAAG,EAAE,EAAE,CAAC;gBAC1B,KAAK,EAAE,CAAC;gBACR,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC;oBAAE,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAAC;gBAC7F,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;gBACtB,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;gBAC5C,KAAK,EAAE,CAAC;gBACR,MAAM,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC;gBAC3D,KAAK,EAAE,CAAC;gBACR,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,CAAC,MAAM,EAAE,gBAAgB,EACnG,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,CAAC;gBAC9G,KAAK,EAAE,CAAC;gBACR,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;gBAC9C,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;oBAClF,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EACzH,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;oBAC/E,MAAM,CAAC,gBAAgB,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,EAAE,KAAK,EAAE,GAAG,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;oBAChG,OAAO,QAAQ,CAAC;gBAClB,CAAC;gBACD,IAAI,IAAI,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,IAAI,YAAY;oBAAE,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAAC;gBACxH,IAAI,4BAA4B,CAAC,IAAI,CAAC,QAAQ,CAAC;oBAAE,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,2BAA2B,CAAC,CAAC;gBACnH,IAAI,MAAW,CAAC;gBAChB,IAAI,CAAC;oBAAC,MAAM,GAAG,MAAM,CAAC,WAAW,CAAC,IAAI,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC;gBAAC,CAAC;gBAC5D,OAAO,KAAK,EAAE,CAAC;oBAAC,IAAI,KAAK,YAAY,WAAW;wBAAE,MAAM,KAAK,CAAC;oBAAC,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,yBAAyB,CAAC,CAAC;gBAAC,CAAC;gBACjI,IAAI,YAAY,IAAI,MAAM,CAAC,MAAM,KAAK,YAAY;oBAAE,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,uCAAuC,CAAC,CAAC;gBACpI,IAAI,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,MAAM,EAAE,CAAC;oBACjC,KAAK,MAAM,IAAI,IAAI,CAAC,eAAe,EAAE,qBAAqB,EAAE,QAAQ,EAAE,SAAS,CAAC;wBAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;oBACvG,kFAAkF;oBAClF,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,MAAM,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,EAAE,CAAC;wBACrG,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,8CAA8C,CAAC,CAAC;oBACzF,CAAC;gBACH,CAAC;gBACD,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,GAAG,IAAI,IAAI,CAAC,MAAM,KAAK,GAAG,CAAC,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;oBAClH,MAAM,GAAG,KAAK,CAAC;oBAAC,IAAI,GAAG,SAAS,CAAC;oBACjC,KAAK,MAAM,IAAI,IAAI,CAAC,cAAc,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,kBAAkB,CAAC;wBAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBAC1I,CAAC;gBACD,GAAG,GAAG,MAAM,CAAC;YACf,CAAC;QACH,CAAC,CAAC;QACF,IAAI,CAAC;YAAC,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,SAAS,CAAC,CAAC,CAAC;QAAC,CAAC;QACtD,OAAO,KAAK,EAAE,CAAC;YAAC,MAAM,KAAK,YAAY,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,uBAAuB,CAAC,CAAC;QAAC,CAAC;gBACjH,CAAC;YACP,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;YACjD,IAAI,aAAa;gBAAE,UAAU,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AAC1C,CAAC;AAED,uFAAuF;AACvF,MAAM,UAAU,WAAW,CAAC,GAAiB,EAAE,OAAoB,EAAE,EAAE,OAAmD;IACxH,OAAO,kBAAkB,CAAC,OAAO,CAAC,CAAC,WAAW,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AACrE,CAAC"}
\ No newline at end of file
diff --git a/packages/egress/src/client.test.ts b/packages/egress/src/client.test.ts
new file mode 100644
index 0000000..0ccc2f9
--- /dev/null
+++ b/packages/egress/src/client.test.ts
@@ -0,0 +1,150 @@
+import { EventEmitter } from "node:events";
+import http, { type ClientRequest, type IncomingMessage, type RequestOptions } from "node:http";
+import https from "node:https";
+import { PassThrough } from "node:stream";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createEgressClient } from "./client.js";
+import { testDatabase } from "./test-db.js";
+
+interface Fixture { status?: number; headers?: Record<string, string>; body?: string; hang?: boolean }
+interface Call { url: URL; options: RequestOptions; pin?: string; body?: Buffer }
+function mockWire(fixtures: Fixture[]) {
+  const calls: Call[] = [];
+  const implementation = ((url: URL, options: RequestOptions, callback: (response: IncomingMessage) => void) => {
+    const fixture = fixtures.shift();
+    if (!fixture) throw new Error("Unexpected connection");
+    const call: Call = { url, options };
+    calls.push(call);
+    const request = new EventEmitter() as ClientRequest;
+    request.destroy = () => { request.emit("close"); return request; };
+    request.end = ((body?: Buffer) => {
+      call.body = body;
+      const lookup = options.lookup as (host: string, options: object, cb: (error: Error | null, address: string) => void) => void;
+      lookup(url.hostname, {}, (_error, address) => { call.pin = address; });
+      if (!fixture.hang) queueMicrotask(() => {
+        const stream = new PassThrough();
+        const incoming = stream as unknown as IncomingMessage;
+        incoming.statusCode = fixture.status ?? 200;
+        incoming.statusMessage = "OK";
+        incoming.rawHeaders = Object.entries(fixture.headers ?? {}).flat();
+        callback(incoming);
+        stream.end(fixture.body ?? "ok");
+      });
+      return request;
+    }) as ClientRequest["end"];
+    return request;
+  }) as typeof http.request;
+  vi.spyOn(http, "request").mockImplementation(implementation);
+  vi.spyOn(https, "request").mockImplementation(implementation as typeof https.request);
+  return calls;
+}
+
+describe("validated, pinned, budgeted fetch", () => {
+  const pool = testDatabase();
+  afterEach(() => { vi.restoreAllMocks(); });
+  const publicResolver = async () => [{ address: "8.8.8.8", family: 4 }];
+  it("connects to the pinned answer once, retaining TLS hostname and overriding Host spoofing", async () => {
+    const calls = mockWire([{ body: "pinned" }]);
+    const resolver = vi.fn().mockResolvedValueOnce([{ address: "8.8.8.8", family: 4 }]).mockResolvedValueOnce([{ address: "127.0.0.1", family: 4 }]);
+    const client = createEgressClient({ pool, resolver });
+    const response = await client.egressFetch("https://example.com/asset", { headers: { Host: "internal.local" } }, { hostClass: "monitor" });
+    expect(await response.text()).toBe("pinned");
+    expect(response.url).toBe("https://example.com/asset");
+    expect(resolver).toHaveBeenCalledTimes(1);
+    expect(calls[0]!.pin).toBe("8.8.8.8");
+    expect(calls[0]!.url.hostname).toBe("example.com");
+    expect(calls[0]!.options.agent).toBe(false);
+    expect(calls[0]!.options.headers).toMatchObject({ host: "example.com" });
+  });
+  it.each(["http://127.0.0.1/secret", "https://[::1]/secret", "https://internal.example/secret"])("denies redirect to %s before making the second connection", async (location) => {
+    const calls = mockWire([{ status: 302, headers: { location } }]);
+    const resolver = vi.fn(async (host: string) => [{ address: host === "internal.example" ? "10.0.0.1" : "8.8.8.8", family: 4 }]);
+    const client = createEgressClient({ pool, resolver });
+    await expect(client.egressFetch("https://example.com/start", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+    expect(calls).toHaveLength(1);
+  });
+  it("resolves and pins again at each redirect hop, detecting same-host DNS rebinding", async () => {
+    const calls = mockWire([{ status: 302, headers: { location: "/next" } }]);
+    const resolver = vi.fn().mockResolvedValueOnce([{ address: "8.8.8.8", family: 4 }]).mockResolvedValueOnce([{ address: "127.0.0.1", family: 4 }]);
+    await expect(createEgressClient({ pool, resolver }).egressFetch("https://example.com/start", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+    expect(resolver).toHaveBeenCalledTimes(2);
+    expect(calls).toHaveLength(1);
+  });
+  it.each([302, 307, 308])("pinned-origin rejects an off-origin %s without forwarding auth or body", async (status) => {
+    const calls = mockWire([{ status, headers: { location: "https://sink.example/token" } }]);
+    const resolver = vi.fn(publicResolver);
+    await expect(createEgressClient({ pool, resolver }).egressFetch("https://example.com/token",
+      { method: "POST", body: "secret", headers: { authorization: "Bearer secret" } }, { hostClass: "monitor", pinnedOrigin: true })).rejects.toMatchObject({ code: "ORIGIN_DENIED" });
+    expect(calls).toHaveLength(1);
+    expect(resolver).toHaveBeenCalledTimes(1);
+  });
+  it("strips sensitive headers on public cross-origin redirects and normalizes POST to GET", async () => {
+    const calls = mockWire([{ status: 302, headers: { location: "//cdn.example/next" } }, { body: "done" }]);
+    const response = await createEgressClient({ pool, resolver: publicResolver }).egressFetch("https://example.com/start",
+      { method: "POST", body: "form", headers: { authorization: "secret", cookie: "session=secret", "content-type": "text/plain" } }, { hostClass: "monitor" });
+    expect(await response.text()).toBe("done");
+    expect(response.redirected).toBe(true);
+    expect(calls[1]!.options.method).toBe("GET");
+    expect(calls[1]!.body).toBeUndefined();
+    expect(calls[1]!.options.headers).not.toHaveProperty("authorization");
+    expect(calls[1]!.options.headers).not.toHaveProperty("cookie");
+    expect(calls[1]!.options.headers).not.toHaveProperty("content-type");
+  });
+  it("follows same-origin 307 without changing method/body", async () => {
+    const calls = mockWire([{ status: 307, headers: { location: "/next" } }, {}]);
+    await createEgressClient({ pool, resolver: publicResolver }).egressFetch("https://example.com/start", { method: "POST", body: "payload" }, { hostClass: "monitor", pinnedOrigin: true });
+    expect(calls[1]!.options.method).toBe("POST");
+    expect(calls[1]!.body?.toString()).toBe("payload");
+  });
+  it("bounds cycles and redirect depth; manual returns without following", async () => {
+    let calls = mockWire([{ status: 302, headers: { location: "/start" } }]);
+    await expect(createEgressClient({ pool, resolver: publicResolver }).egressFetch("https://example.com/start", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "REDIRECT_LOOP" });
+    expect(calls).toHaveLength(1);
+    calls = mockWire([{ status: 302, headers: { location: "/next" } }]);
+    await expect(createEgressClient({ pool, resolver: publicResolver, maxRedirects: 0 }).egressFetch("https://other.example/start", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "REDIRECT_LOOP" });
+    calls = mockWire([{ status: 302, headers: { location: "http://127.0.0.1/" } }]);
+    const response = await createEgressClient({ pool, resolver: publicResolver }).egressFetch("https://manual.example/start", { redirect: "manual" }, { hostClass: "monitor" });
+    expect(response.status).toBe(302);
+    expect(calls).toHaveLength(1);
+  });
+  it("parks on 429 before another caller can connect", async () => {
+    const calls = mockWire([{ status: 429, headers: { "retry-after": "10" } }]);
+    const client = createEgressClient({ pool, resolver: publicResolver });
+    expect((await client.egressFetch("https://example.com/start", {}, { hostClass: "monitor" })).status).toBe(429);
+    await expect(client.egressFetch("https://example.com/next", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "BUDGET_EXHAUSTED" });
+    expect(calls).toHaveLength(1);
+  });
+  it.each<Record<string, string>>([{}, { "content-length": "100" }])("enforces response caps for streamed and declared lengths: %j", async (headers) => {
+    mockWire([{ headers, body: "12345" }]);
+    await expect(createEgressClient({ pool, resolver: publicResolver, maxResponseBytes: 4 }).egressFetch("https://example.com", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "RESPONSE_TOO_LARGE" });
+  });
+  it("caps request bodies before acquiring a token or connecting", async () => {
+    const calls = mockWire([]);
+    await expect(createEgressClient({ pool, resolver: publicResolver, maxRequestBytes: 4 }).egressFetch("https://example.com", { method: "POST", body: "12345" }, { hostClass: "monitor" })).rejects.toMatchObject({ code: "REQUEST_TOO_LARGE" });
+    expect(calls).toHaveLength(0);
+    expect((await pool.query("SELECT * FROM host_budgets")).rows).toHaveLength(0);
+  });
+  it("returns HEAD metadata without applying a body cap to Content-Length", async () => {
+    mockWire([{ headers: { "content-length": "100000", "content-encoding": "gzip" }, body: "" }]);
+    const response = await createEgressClient({ pool, resolver: publicResolver, maxResponseBytes: 4 }).egressFetch("https://example.com", { method: "HEAD" }, { hostClass: "monitor" });
+    expect(response.headers.get("content-length")).toBe("100000");
+    expect(await response.text()).toBe("");
+  });
+  it("rejects whitespace in redirect targets instead of normalizing it away", async () => {
+    const calls = mockWire([{ status: 302, headers: { location: "https://next.example/a b" } }]);
+    await expect(createEgressClient({ pool, resolver: publicResolver }).egressFetch("https://example.com", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "INVALID_URL" });
+    expect(calls).toHaveLength(1);
+  });
+  it("times out a stalled DNS resolution and a stalled connection", async () => {
+    const stalled = () => new Promise<never>(() => undefined);
+    await expect(createEgressClient({ pool, resolver: stalled, timeoutMs: 30 }).egressFetch("https://example.com", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "TIMEOUT" });
+    mockWire([{ hang: true }]);
+    await expect(createEgressClient({ pool, resolver: publicResolver, timeoutMs: 100 }).egressFetch("https://example.com", {}, { hostClass: "monitor" })).rejects.toMatchObject({ code: "TIMEOUT" });
+  });
+  it("honors an already-aborted signal without DNS, debit, or network", async () => {
+    const controller = new AbortController(); controller.abort();
+    const resolver = vi.fn(publicResolver);
+    await expect(createEgressClient({ pool, resolver }).egressFetch("https://example.com", { signal: controller.signal }, { hostClass: "monitor" })).rejects.toMatchObject({ code: "ABORTED" });
+    expect(resolver).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/egress/src/client.ts b/packages/egress/src/client.ts
new file mode 100644
index 0000000..c4a9e41
--- /dev/null
+++ b/packages/egress/src/client.ts
@@ -0,0 +1,129 @@
+import { HostBudgets, type HostBudgetOptions } from "./budget.js";
+import { EgressError } from "./errors.js";
+import { EgressPolicy, type EgressPolicyOptions } from "./policy.js";
+import { requestPinned } from "./transport.js";
+
+export interface EgressClientOptions extends HostBudgetOptions, EgressPolicyOptions {
+  timeoutMs?: number;
+  maxResponseBytes?: number;
+  maxRequestBytes?: number;
+  maxRedirects?: number;
+}
+export interface EgressRequestOptions {
+  hostClass: string;
+  /** true pins to the initial origin; a URL string explicitly pins to that origin. */
+  pinnedOrigin?: boolean | string | URL;
+}
+const redirectStatuses = new Set([301, 302, 303, 307, 308]);
+
+export function createEgressClient(options: EgressClientOptions) {
+  const policy = new EgressPolicy(options);
+  const budgets = new HostBudgets(options);
+  const timeoutMs = options.timeoutMs ?? 15_000;
+  const maxResponseBytes = options.maxResponseBytes ?? 8 * 1024 * 1024;
+  const maxRequestBytes = options.maxRequestBytes ?? 8 * 1024 * 1024;
+  const maxRedirects = options.maxRedirects ?? 5;
+  if (![timeoutMs, maxResponseBytes, maxRequestBytes].every((value) => Number.isSafeInteger(value) && value > 0) || !Number.isSafeInteger(maxRedirects) || maxRedirects < 0) {
+    throw new EgressError("INVALID_CONFIGURATION", "Invalid request limits");
+  }
+
+  async function egressFetch(raw: string | URL, init: RequestInit = {}, context: EgressRequestOptions): Promise<Response> {
+    const controller = new AbortController();
+    const abort = () => controller.abort(new EgressError("ABORTED", "Request aborted"));
+    init.signal?.addEventListener("abort", abort, { once: true });
+    if (init.signal?.aborted) abort();
+    const timer = setTimeout(() => controller.abort(new EgressError("TIMEOUT", "Egress deadline exceeded")), timeoutMs);
+    const check = () => { if (controller.signal.aborted) throw controller.signal.reason; };
+    let abortListener: (() => void) | undefined;
+    const cancelled = new Promise<never>((_resolve, reject) => {
+      abortListener = () => reject(controller.signal.reason);
+      controller.signal.addEventListener("abort", abortListener, { once: true });
+      if (controller.signal.aborted) abortListener();
+    });
+    const run = async () => {
+      check();
+      let url = policy.validateUrl(raw);
+      const pinnedOrigin = context.pinnedOrigin === true ? url.origin : context.pinnedOrigin ? policy.validateUrl(context.pinnedOrigin).origin : undefined;
+      if (pinnedOrigin && url.origin !== pinnedOrigin) throw new EgressError("ORIGIN_DENIED", "Request is outside the pinned origin");
+      // Request provides fetch method/header/body normalization; the transport owns connection options.
+      let normalized: Request;
+      try { normalized = new Request(url, init); }
+      catch { throw new EgressError("INVALID_REQUEST", "Invalid fetch request initialization"); }
+      let method = normalized.method;
+      const headers = new Headers(normalized.headers);
+      let body: Buffer | undefined;
+      if (normalized.body) {
+        const reader = normalized.body.getReader();
+        const cancelBody = () => { void reader.cancel().catch(() => undefined); };
+        controller.signal.addEventListener("abort", cancelBody, { once: true });
+        const chunks: Buffer[] = [];
+        let size = 0;
+        try {
+          for (;;) {
+            check();
+            const { value, done } = await reader.read();
+            if (done) break;
+            size += value.length;
+            if (size > maxRequestBytes) throw new EgressError("REQUEST_TOO_LARGE", "Request exceeds size limit");
+            chunks.push(Buffer.from(value));
+          }
+          body = Buffer.concat(chunks);
+        } finally {
+          controller.signal.removeEventListener("abort", cancelBody);
+          void reader.cancel().catch(() => undefined);
+        }
+      }
+      const visited = new Set<string>();
+      for (let hop = 0; ; hop++) {
+        check();
+        if (visited.has(url.href)) throw new EgressError("REDIRECT_LOOP", "Redirect cycle detected");
+        visited.add(url.href);
+        const endpoint = await policy.validate(url);
+        check();
+        await budgets.consume(endpoint.hostKey, context.hostClass);
+        check();
+        const wire = await requestPinned(endpoint, method, headers, body, controller.signal, maxResponseBytes,
+          (status, responseHeaders) => budgets.observe(endpoint.hostKey, context.hostClass, status, responseHeaders));
+        check();
+        const location = wire.headers.get("location");
+        if (!redirectStatuses.has(wire.status) || !location || init.redirect === "manual") {
+          const response = new Response(method === "HEAD" || [204, 205, 304].includes(wire.status) ? null : new Uint8Array(wire.body),
+            { status: wire.status, statusText: wire.statusText, headers: wire.headers });
+          Object.defineProperties(response, { url: { value: url.href }, redirected: { value: hop > 0 } });
+          return response;
+        }
+        if (init.redirect === "error" || hop >= maxRedirects) throw new EgressError("REDIRECT_LOOP", "Redirect limit exceeded");
+        if (/[\s\\\u0000-\u001f\u007f]/u.test(location)) throw new EgressError("INVALID_URL", "Malformed redirect target");
+        let target: URL;
+        try { target = policy.validateUrl(new URL(location, url)); }
+        catch (error) { if (error instanceof EgressError) throw error; throw new EgressError("INVALID_URL", "Invalid redirect target"); }
+        if (pinnedOrigin && target.origin !== pinnedOrigin) throw new EgressError("ORIGIN_DENIED", "Redirect is outside the pinned origin");
+        if (target.origin !== url.origin) {
+          for (const name of ["authorization", "proxy-authorization", "cookie", "cookie2"]) headers.delete(name);
+          // A body can contain secrets just as headers can; refuse to replay it off-origin.
+          if (body && (wire.status === 307 || wire.status === 308 || method !== "POST" && wire.status !== 303)) {
+            throw new EgressError("ORIGIN_DENIED", "Request body cannot be redirected off-origin");
+          }
+        }
+        if (wire.status === 303 && method !== "HEAD" || (wire.status === 301 || wire.status === 302) && method === "POST") {
+          method = "GET"; body = undefined;
+          for (const name of ["content-type", "content-length", "content-encoding", "content-language", "content-location"]) headers.delete(name);
+        }
+        url = target;
+      }
+    };
+    try { return await Promise.race([run(), cancelled]); }
+    catch (error) { throw error instanceof EgressError ? error : new EgressError("NETWORK_ERROR", "Egress request failed"); }
+    finally {
+      clearTimeout(timer);
+      init.signal?.removeEventListener("abort", abort);
+      if (abortListener) controller.signal.removeEventListener("abort", abortListener);
+    }
+  }
+  return { egressFetch, policy, budgets };
+}
+
+/** Stateless convenience form. Reuse createEgressClient when pool/config are fixed. */
+export function egressFetch(url: string | URL, init: RequestInit = {}, options: EgressClientOptions & EgressRequestOptions): Promise<Response> {
+  return createEgressClient(options).egressFetch(url, init, options);
+}
diff --git a/packages/egress/src/errors.d.ts b/packages/egress/src/errors.d.ts
new file mode 100644
index 0000000..0586c03
--- /dev/null
+++ b/packages/egress/src/errors.d.ts
@@ -0,0 +1,7 @@
+export type EgressErrorCode = "INVALID_URL" | "SCHEME_DENIED" | "PORT_DENIED" | "DENIED_PRIVATE_ADDRESS" | "DNS_FAILED" | "BUDGET_EXHAUSTED" | "REDIRECT_LOOP" | "ORIGIN_DENIED" | "TIMEOUT" | "ABORTED" | "RESPONSE_TOO_LARGE" | "REQUEST_TOO_LARGE" | "NETWORK_ERROR" | "INVALID_PLAYLIST" | "INVALID_CONFIGURATION" | "INVALID_REQUEST" | "BUDGET_UNAVAILABLE";
+/** Messages intentionally omit URLs, credentials and upstream error strings. */
+export declare class EgressError extends Error {
+    readonly code: EgressErrorCode;
+    readonly retryAfterMs?: number | undefined;
+    constructor(code: EgressErrorCode, message: string, retryAfterMs?: number | undefined);
+}
diff --git a/packages/egress/src/errors.js b/packages/egress/src/errors.js
new file mode 100644
index 0000000..ee5cb23
--- /dev/null
+++ b/packages/egress/src/errors.js
@@ -0,0 +1,12 @@
+/** Messages intentionally omit URLs, credentials and upstream error strings. */
+export class EgressError extends Error {
+    code;
+    retryAfterMs;
+    constructor(code, message, retryAfterMs) {
+        super(message);
+        this.code = code;
+        this.retryAfterMs = retryAfterMs;
+        this.name = "EgressError";
+    }
+}
+//# sourceMappingURL=errors.js.map
\ No newline at end of file
diff --git a/packages/egress/src/errors.js.map b/packages/egress/src/errors.js.map
new file mode 100644
index 0000000..8d66ba2
--- /dev/null
+++ b/packages/egress/src/errors.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["errors.ts"],"names":[],"mappings":"AAMA,gFAAgF;AAChF,MAAM,OAAO,WAAY,SAAQ,KAAK;IACR;IAAwD;IAApF,YAA4B,IAAqB,EAAE,OAAe,EAAkB,YAAqB;QACvG,KAAK,CAAC,OAAO,CAAC,CAAC;QADW,SAAI,GAAJ,IAAI,CAAiB;QAAmC,iBAAY,GAAZ,YAAY,CAAS;QAEvG,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF"}
\ No newline at end of file
diff --git a/packages/egress/src/errors.ts b/packages/egress/src/errors.ts
new file mode 100644
index 0000000..5fdd0a5
--- /dev/null
+++ b/packages/egress/src/errors.ts
@@ -0,0 +1,13 @@
+export type EgressErrorCode =
+  | "INVALID_URL" | "SCHEME_DENIED" | "PORT_DENIED" | "DENIED_PRIVATE_ADDRESS"
+  | "DNS_FAILED" | "BUDGET_EXHAUSTED" | "REDIRECT_LOOP" | "ORIGIN_DENIED"
+  | "TIMEOUT" | "ABORTED" | "RESPONSE_TOO_LARGE" | "REQUEST_TOO_LARGE"
+  | "NETWORK_ERROR" | "INVALID_PLAYLIST" | "INVALID_CONFIGURATION" | "INVALID_REQUEST" | "BUDGET_UNAVAILABLE";
+
+/** Messages intentionally omit URLs, credentials and upstream error strings. */
+export class EgressError extends Error {
+  constructor(public readonly code: EgressErrorCode, message: string, public readonly retryAfterMs?: number) {
+    super(message);
+    this.name = "EgressError";
+  }
+}
diff --git a/packages/egress/src/hls.d.ts b/packages/egress/src/hls.d.ts
new file mode 100644
index 0000000..334e397
--- /dev/null
+++ b/packages/egress/src/hls.d.ts
@@ -0,0 +1,5 @@
+import { EgressPolicy, type ValidatedEndpoint } from "./policy.js";
+/** Validates master variants and URI-bearing tags (renditions, keys, maps, etc.) with DNS pinning. */
+export declare function validateMasterPlaylist(playlist: string, base: string | URL, policy?: EgressPolicy): Promise<ValidatedEndpoint[]>;
+/** Produces absolute, validated child URLs, preserving comments, attributes and newline style. */
+export declare function rewriteSegmentUris(playlist: string, base: string | URL, policy?: EgressPolicy): Promise<string>;
diff --git a/packages/egress/src/hls.js b/packages/egress/src/hls.js
new file mode 100644
index 0000000..6e89249
--- /dev/null
+++ b/packages/egress/src/hls.js
@@ -0,0 +1,124 @@
+import { EgressError } from "./errors.js";
+import { EgressPolicy } from "./policy.js";
+/** Parse attribute boundaries rather than finding URI= inside other quoted values. */
+function attributeUris(attributes, offset) {
+    const uris = [];
+    if (!/^\s*[A-Z0-9-]+\s*=/.test(attributes))
+        return uris;
+    let cursor = 0;
+    const seen = new Set();
+    while (cursor < attributes.length) {
+        const key = /^\s*([A-Z0-9-]+)\s*=\s*/.exec(attributes.slice(cursor));
+        if (!key)
+            throw new EgressError("INVALID_PLAYLIST", "Malformed HLS attributes");
+        cursor += key[0].length;
+        const quoted = attributes[cursor] === '"';
+        const start = cursor + (quoted ? 1 : 0);
+        const end = quoted ? attributes.indexOf('"', start) : attributes.indexOf(",", start);
+        const valueEnd = end < 0 && !quoted ? attributes.length : end;
+        if (valueEnd < 0)
+            throw new EgressError("INVALID_PLAYLIST", "Unterminated HLS attribute");
+        if (key[1] === "URI" || key[1] === "SERVER-URI") {
+            if (!quoted || start === valueEnd || seen.has(key[1]))
+                throw new EgressError("INVALID_PLAYLIST", "Invalid HLS URI attribute");
+            seen.add(key[1]);
+            uris.push({ start: offset + start, end: offset + valueEnd, value: attributes.slice(start, valueEnd) });
+        }
+        cursor = valueEnd + (quoted ? 1 : 0);
+        while (/\s/.test(attributes[cursor] ?? "") && cursor < attributes.length)
+            cursor++;
+        if (cursor === attributes.length)
+            break;
+        if (attributes[cursor] !== "," || cursor + 1 === attributes.length)
+            throw new EgressError("INVALID_PLAYLIST", "Invalid HLS attribute suffix");
+        cursor++;
+    }
+    return uris;
+}
+function playlistUris(playlist) {
+    if (!/^#EXTM3U(?:\r?\n|$)/.test(playlist) || playlist.includes("\u0000"))
+        throw new EgressError("INVALID_PLAYLIST", "Missing HLS header");
+    const uris = [];
+    let offset = 0;
+    let awaitingVariant = false;
+    let variants = 0;
+    let media = false;
+    for (const line of playlist.split(/(?<=\n)/)) {
+        const text = line.replace(/\r?\n$/, "").trim();
+        if (text && !text.startsWith("#")) {
+            const start = offset + line.indexOf(text);
+            uris.push({ start, end: start + text.length, value: text });
+            if (awaitingVariant) {
+                variants++;
+                awaitingVariant = false;
+            }
+        }
+        else if (text.startsWith("#EXT")) {
+            if (text.startsWith("#EXTINF:"))
+                media = true;
+            if (text.startsWith("#EXT-X-STREAM-INF:")) {
+                if (awaitingVariant)
+                    throw new EgressError("INVALID_PLAYLIST", "Variant URI is missing");
+                awaitingVariant = true;
+            }
+            const colon = line.indexOf(":");
+            if (colon >= 0) {
+                const attributes = line.slice(colon + 1).replace(/\r?\n$/, "");
+                const attributesFound = attributeUris(attributes, offset + colon + 1);
+                uris.push(...attributesFound);
+                if (text.startsWith("#EXT-X-I-FRAME-STREAM-INF:")) {
+                    if (!attributesFound.length)
+                        throw new EgressError("INVALID_PLAYLIST", "I-frame URI is missing");
+                    variants++;
+                }
+            }
+        }
+        offset += line.length;
+    }
+    if (awaitingVariant)
+        throw new EgressError("INVALID_PLAYLIST", "Variant URI is missing");
+    return { uris, master: variants > 0 && !media };
+}
+async function resolveUris(uris, base, policy) {
+    const baseUrl = (await policy.validate(base)).url;
+    const endpoints = [];
+    // Sequential validation bounds DNS work even for large playlists; shared URI pins within this parse.
+    const cache = new Map();
+    for (const occurrence of uris) {
+        if (!occurrence.value || occurrence.value.includes("{$") || /[\s\\\u0000-\u001f\u007f]/u.test(occurrence.value))
+            throw new EgressError("INVALID_PLAYLIST", "Invalid or unexpanded HLS URI");
+        let absolute;
+        try {
+            absolute = new URL(occurrence.value, baseUrl);
+        }
+        catch {
+            throw new EgressError("INVALID_PLAYLIST", "Invalid HLS URI");
+        }
+        let endpoint = cache.get(absolute.href);
+        if (!endpoint) {
+            endpoint = await policy.validate(absolute);
+            cache.set(absolute.href, endpoint);
+        }
+        endpoints.push(endpoint);
+    }
+    return endpoints;
+}
+/** Validates master variants and URI-bearing tags (renditions, keys, maps, etc.) with DNS pinning. */
+export async function validateMasterPlaylist(playlist, base, policy = new EgressPolicy()) {
+    const { uris, master } = playlistUris(playlist);
+    if (!master)
+        throw new EgressError("INVALID_PLAYLIST", "Expected an HLS master playlist");
+    return resolveUris(uris, base, policy);
+}
+/** Produces absolute, validated child URLs, preserving comments, attributes and newline style. */
+export async function rewriteSegmentUris(playlist, base, policy = new EgressPolicy()) {
+    const { uris } = playlistUris(playlist);
+    const endpoints = await resolveUris(uris, base, policy);
+    let rewritten = playlist;
+    for (let index = uris.length - 1; index >= 0; index--) {
+        const uri = uris[index];
+        rewritten = rewritten.slice(0, uri.start) + endpoints[index].url.href + rewritten.slice(uri.end);
+    }
+    return rewritten;
+}
+//# sourceMappingURL=hls.js.map
\ No newline at end of file
diff --git a/packages/egress/src/hls.js.map b/packages/egress/src/hls.js.map
new file mode 100644
index 0000000..f4135ee
--- /dev/null
+++ b/packages/egress/src/hls.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"hls.js","sourceRoot":"","sources":["hls.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,YAAY,EAA0B,MAAM,aAAa,CAAC;AAInE,sFAAsF;AACtF,SAAS,aAAa,CAAC,UAAkB,EAAE,MAAc;IACvD,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACxD,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,MAAM,GAAG,UAAU,CAAC,MAAM,EAAE,CAAC;QAClC,MAAM,GAAG,GAAG,yBAAyB,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC;QACrE,IAAI,CAAC,GAAG;YAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,0BAA0B,CAAC,CAAC;QAChF,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;QACxB,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC;QAC1C,MAAM,KAAK,GAAG,MAAM,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,GAAG,GAAG,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QACrF,MAAM,QAAQ,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9D,IAAI,QAAQ,GAAG,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,4BAA4B,CAAC,CAAC;QAC1F,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,KAAK,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,YAAY,EAAE,CAAC;YAChD,IAAI,CAAC,MAAM,IAAI,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,2BAA2B,CAAC,CAAC;YAC9H,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;YACjB,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,GAAG,KAAK,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,EAAE,KAAK,EAAE,UAAU,CAAC,KAAK,CAAC,KAAK,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC;QACzG,CAAC;QACD,MAAM,GAAG,QAAQ,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,IAAI,MAAM,GAAG,UAAU,CAAC,MAAM;YAAE,MAAM,EAAE,CAAC;QACnF,IAAI,MAAM,KAAK,UAAU,CAAC,MAAM;YAAE,MAAM;QACxC,IAAI,UAAU,CAAC,MAAM,CAAC,KAAK,GAAG,IAAI,MAAM,GAAG,CAAC,KAAK,UAAU,CAAC,MAAM;YAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,8BAA8B,CAAC,CAAC;QAC9I,MAAM,EAAE,CAAC;IACX,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,QAAgB;IACpC,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,oBAAoB,CAAC,CAAC;IAC1I,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,IAAI,eAAe,GAAG,KAAK,CAAC;IAC5B,IAAI,QAAQ,GAAG,CAAC,CAAC;IACjB,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC;QAC7C,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC/C,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YAC5D,IAAI,eAAe,EAAE,CAAC;gBAAC,QAAQ,EAAE,CAAC;gBAAC,eAAe,GAAG,KAAK,CAAC;YAAC,CAAC;QAC/D,CAAC;aAAM,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;YACnC,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC;gBAAE,KAAK,GAAG,IAAI,CAAC;YAC9C,IAAI,IAAI,CAAC,UAAU,CAAC,oBAAoB,CAAC,EAAE,CAAC;gBAC1C,IAAI,eAAe;oBAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,wBAAwB,CAAC,CAAC;gBACzF,eAAe,GAAG,IAAI,CAAC;YACzB,CAAC;YACD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YAChC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBACf,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;gBAC/D,MAAM,eAAe,GAAG,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,KAAK,GAAG,CAAC,CAAC,CAAC;gBACtE,IAAI,CAAC,IAAI,CAAC,GAAG,eAAe,CAAC,CAAC;gBAC9B,IAAI,IAAI,CAAC,UAAU,CAAC,4BAA4B,CAAC,EAAE,CAAC;oBAClD,IAAI,CAAC,eAAe,CAAC,MAAM;wBAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,wBAAwB,CAAC,CAAC;oBACjG,QAAQ,EAAE,CAAC;gBACb,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,IAAI,IAAI,CAAC,MAAM,CAAC;IACxB,CAAC;IACD,IAAI,eAAe;QAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,wBAAwB,CAAC,CAAC;IACzF,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,WAAW,CAAC,IAAqB,EAAE,IAAkB,EAAE,MAAoB;IACxF,MAAM,OAAO,GAAG,CAAC,MAAM,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;IAClD,MAAM,SAAS,GAAwB,EAAE,CAAC;IAC1C,qGAAqG;IACrG,MAAM,KAAK,GAAG,IAAI,GAAG,EAA6B,CAAC;IACnD,KAAK,MAAM,UAAU,IAAI,IAAI,EAAE,CAAC;QAC9B,IAAI,CAAC,UAAU,CAAC,KAAK,IAAI,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,4BAA4B,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;YAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,+BAA+B,CAAC,CAAC;QAC5L,IAAI,QAAa,CAAC;QAClB,IAAI,CAAC;YAAC,QAAQ,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC;YAAC,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,iBAAiB,CAAC,CAAC;QAAC,CAAC;QAC9H,IAAI,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACxC,IAAI,CAAC,QAAQ,EAAE,CAAC;YAAC,QAAQ,GAAG,MAAM,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;YAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAAC,CAAC;QAClG,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC3B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,sGAAsG;AACtG,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,QAAgB,EAAE,IAAkB,EAAE,MAAM,GAAG,IAAI,YAAY,EAAE;IAC5G,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,WAAW,CAAC,kBAAkB,EAAE,iCAAiC,CAAC,CAAC;IAC1F,OAAO,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACzC,CAAC;AAED,kGAAkG;AAClG,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,QAAgB,EAAE,IAAkB,EAAE,MAAM,GAAG,IAAI,YAAY,EAAE;IACxG,MAAM,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,QAAQ,CAAC,CAAC;IACxC,MAAM,SAAS,GAAG,MAAM,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;IACxD,IAAI,SAAS,GAAG,QAAQ,CAAC;IACzB,KAAK,IAAI,KAAK,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC;QACtD,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAE,CAAC;QACzB,SAAS,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACpG,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
\ No newline at end of file
diff --git a/packages/egress/src/hls.test.ts b/packages/egress/src/hls.test.ts
new file mode 100644
index 0000000..b8c9082
--- /dev/null
+++ b/packages/egress/src/hls.test.ts
@@ -0,0 +1,41 @@
+import { describe, expect, it } from "vitest";
+import { rewriteSegmentUris, validateMasterPlaylist } from "./hls.js";
+import { EgressPolicy } from "./policy.js";
+
+const policy = new EgressPolicy({ resolver: async (host) => [{ address: host === "private.example" ? "10.1.2.3" : "8.8.8.8", family: 4 }] });
+const base = "https://media.example/live/master.m3u8?signature=abc";
+describe("HLS child policy and URI rewriting", () => {
+  it("rewrites relative, root-relative, absolute and protocol-relative segments with CRLF preserved", async () => {
+    const source = '#EXTM3U\r\n# comment\r\n#EXTINF:10,\r\nsegment.ts?token=1\r\n../other.ts\r\n/root.ts\r\nhttps://cdn.example/a.ts\r\n//cdn.example/b.ts\r\n';
+    expect(await rewriteSegmentUris(source, base, policy)).toBe('#EXTM3U\r\n# comment\r\n#EXTINF:10,\r\nhttps://media.example/live/segment.ts?token=1\r\nhttps://media.example/other.ts\r\nhttps://media.example/root.ts\r\nhttps://cdn.example/a.ts\r\nhttps://cdn.example/b.ts\r\n');
+  });
+  it("rewrites variant, rendition, map, encryption-key, part and iframe URIs including commas", async () => {
+    const source = '#EXTM3U\n#EXT-X-MEDIA:TYPE=AUDIO,URI="audio/list.m3u8",NAME="Audio"\n#EXT-X-STREAM-INF:BANDWIDTH=1234,CODECS="avc1,mp4a"\nvideo/list.m3u8\n#EXT-X-I-FRAME-STREAM-INF:BANDWIDTH=12,URI="//cdn.example/iframe.m3u8"\n#EXT-X-MAP:URI="init.mp4"\n#EXT-X-KEY:METHOD=AES-128,URI="keys/key?k=1,2"\n#EXT-X-PART:DURATION=0.1,URI="part.m4s"\n';
+    const endpoints = await validateMasterPlaylist(source, base, policy);
+    expect(endpoints).toHaveLength(6);
+    expect(endpoints.every((endpoint) => endpoint.pinnedAddress === "8.8.8.8")).toBe(true);
+    const rewritten = await rewriteSegmentUris(source, base, policy);
+    expect(rewritten).toContain('URI="https://media.example/live/keys/key?k=1,2"');
+    expect(rewritten).toContain('CODECS="avc1,mp4a"\nhttps://media.example/live/video/list.m3u8');
+    expect(rewritten).toContain('URI="https://cdn.example/iframe.m3u8"');
+  });
+  it.each(["http://127.0.0.1/segment", "https://[::1]/segment", "//private.example/segment", "file:///tmp/segment", "https://media.example:80/segment"])("rejects unsafe child %s", async (uri) => {
+    await expect(rewriteSegmentUris(`#EXTM3U\n${uri}\n`, base, policy)).rejects.toThrow();
+    await expect(validateMasterPlaylist(`#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=1\n${uri}\n`, base, policy)).rejects.toThrow();
+    await expect(rewriteSegmentUris(`#EXTM3U\n#EXT-X-KEY:METHOD=AES-128,URI="${uri}"\n`, base, policy)).rejects.toThrow();
+  });
+  it.each(["not HLS", "#EXTM3U\n#EXT-X-STREAM-INF:BANDWIDTH=1\n", '#EXTM3U\n#EXT-X-MAP:URI=unquoted\n', '#EXTM3U\n#EXT-X-MAP:URI="{$var}/init.mp4"\n', '#EXTM3U\n#EXT-X-MAP:URI="a",URI="b"\n'])("rejects malformed or unexpanded playlist %s", async (playlist) => {
+    await expect(rewriteSegmentUris(playlist, base, policy)).rejects.toMatchObject({ code: "INVALID_PLAYLIST" });
+  });
+  it("requires a master and validates the base even when no children exist", async () => {
+    await expect(validateMasterPlaylist("#EXTM3U\n#EXTINF:2,\nseg.ts\n", base, policy)).rejects.toMatchObject({ code: "INVALID_PLAYLIST" });
+    await expect(rewriteSegmentUris("#EXTM3U\n", "https://private.example/master.m3u8", policy)).rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+  });
+  it("preserves URI-looking text inside quoted names and validates content steering URIs", async () => {
+    const source = '#EXTM3U\n#EXT-X-MEDIA:NAME="name,URI=ordinary text",URI="audio.m3u8"\n#EXT-X-CONTENT-STEERING:SERVER-URI="../steering.json",PATHWAY-ID="main"\n';
+    const rewritten = await rewriteSegmentUris(source, base, policy);
+    expect(rewritten).toContain('NAME="name,URI=ordinary text",URI="https://media.example/live/audio.m3u8"');
+    expect(rewritten).toContain('SERVER-URI="https://media.example/steering.json"');
+    await expect(rewriteSegmentUris('#EXTM3U\n#EXT-X-CONTENT-STEERING:SERVER-URI="//private.example/steer"\n', base, policy)).rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+  });
+});
diff --git a/packages/egress/src/hls.ts b/packages/egress/src/hls.ts
new file mode 100644
index 0000000..7df565e
--- /dev/null
+++ b/packages/egress/src/hls.ts
@@ -0,0 +1,104 @@
+import { EgressError } from "./errors.js";
+import { EgressPolicy, type ValidatedEndpoint } from "./policy.js";
+
+interface UriOccurrence { start: number; end: number; value: string }
+
+/** Parse attribute boundaries rather than finding URI= inside other quoted values. */
+function attributeUris(attributes: string, offset: number): UriOccurrence[] {
+  const uris: UriOccurrence[] = [];
+  if (!/^\s*[A-Z0-9-]+\s*=/.test(attributes)) return uris;
+  let cursor = 0;
+  const seen = new Set<string>();
+  while (cursor < attributes.length) {
+    const key = /^\s*([A-Z0-9-]+)\s*=\s*/.exec(attributes.slice(cursor));
+    if (!key) throw new EgressError("INVALID_PLAYLIST", "Malformed HLS attributes");
+    cursor += key[0].length;
+    const quoted = attributes[cursor] === '"';
+    const start = cursor + (quoted ? 1 : 0);
+    const end = quoted ? attributes.indexOf('"', start) : attributes.indexOf(",", start);
+    const valueEnd = end < 0 && !quoted ? attributes.length : end;
+    if (valueEnd < 0) throw new EgressError("INVALID_PLAYLIST", "Unterminated HLS attribute");
+    if (key[1] === "URI" || key[1] === "SERVER-URI") {
+      if (!quoted || start === valueEnd || seen.has(key[1])) throw new EgressError("INVALID_PLAYLIST", "Invalid HLS URI attribute");
+      seen.add(key[1]);
+      uris.push({ start: offset + start, end: offset + valueEnd, value: attributes.slice(start, valueEnd) });
+    }
+    cursor = valueEnd + (quoted ? 1 : 0);
+    while (/\s/.test(attributes[cursor] ?? "") && cursor < attributes.length) cursor++;
+    if (cursor === attributes.length) break;
+    if (attributes[cursor] !== "," || cursor + 1 === attributes.length) throw new EgressError("INVALID_PLAYLIST", "Invalid HLS attribute suffix");
+    cursor++;
+  }
+  return uris;
+}
+
+function playlistUris(playlist: string): { uris: UriOccurrence[]; master: boolean } {
+  if (!/^#EXTM3U(?:\r?\n|$)/.test(playlist) || playlist.includes("\u0000")) throw new EgressError("INVALID_PLAYLIST", "Missing HLS header");
+  const uris: UriOccurrence[] = [];
+  let offset = 0;
+  let awaitingVariant = false;
+  let variants = 0;
+  let media = false;
+  for (const line of playlist.split(/(?<=\n)/)) {
+    const text = line.replace(/\r?\n$/, "").trim();
+    if (text && !text.startsWith("#")) {
+      const start = offset + line.indexOf(text);
+      uris.push({ start, end: start + text.length, value: text });
+      if (awaitingVariant) { variants++; awaitingVariant = false; }
+    } else if (text.startsWith("#EXT")) {
+      if (text.startsWith("#EXTINF:")) media = true;
+      if (text.startsWith("#EXT-X-STREAM-INF:")) {
+        if (awaitingVariant) throw new EgressError("INVALID_PLAYLIST", "Variant URI is missing");
+        awaitingVariant = true;
+      }
+      const colon = line.indexOf(":");
+      if (colon >= 0) {
+        const attributes = line.slice(colon + 1).replace(/\r?\n$/, "");
+        const attributesFound = attributeUris(attributes, offset + colon + 1);
+        uris.push(...attributesFound);
+        if (text.startsWith("#EXT-X-I-FRAME-STREAM-INF:")) {
+          if (!attributesFound.length) throw new EgressError("INVALID_PLAYLIST", "I-frame URI is missing");
+          variants++;
+        }
+      }
+    }
+    offset += line.length;
+  }
+  if (awaitingVariant) throw new EgressError("INVALID_PLAYLIST", "Variant URI is missing");
+  return { uris, master: variants > 0 && !media };
+}
+
+async function resolveUris(uris: UriOccurrence[], base: string | URL, policy: EgressPolicy): Promise<ValidatedEndpoint[]> {
+  const baseUrl = (await policy.validate(base)).url;
+  const endpoints: ValidatedEndpoint[] = [];
+  // Sequential validation bounds DNS work even for large playlists; shared URI pins within this parse.
+  const cache = new Map<string, ValidatedEndpoint>();
+  for (const occurrence of uris) {
+    if (!occurrence.value || occurrence.value.includes("{$") || /[\s\\\u0000-\u001f\u007f]/u.test(occurrence.value)) throw new EgressError("INVALID_PLAYLIST", "Invalid or unexpanded HLS URI");
+    let absolute: URL;
+    try { absolute = new URL(occurrence.value, baseUrl); } catch { throw new EgressError("INVALID_PLAYLIST", "Invalid HLS URI"); }
+    let endpoint = cache.get(absolute.href);
+    if (!endpoint) { endpoint = await policy.validate(absolute); cache.set(absolute.href, endpoint); }
+    endpoints.push(endpoint);
+  }
+  return endpoints;
+}
+
+/** Validates master variants and URI-bearing tags (renditions, keys, maps, etc.) with DNS pinning. */
+export async function validateMasterPlaylist(playlist: string, base: string | URL, policy = new EgressPolicy()): Promise<ValidatedEndpoint[]> {
+  const { uris, master } = playlistUris(playlist);
+  if (!master) throw new EgressError("INVALID_PLAYLIST", "Expected an HLS master playlist");
+  return resolveUris(uris, base, policy);
+}
+
+/** Produces absolute, validated child URLs, preserving comments, attributes and newline style. */
+export async function rewriteSegmentUris(playlist: string, base: string | URL, policy = new EgressPolicy()): Promise<string> {
+  const { uris } = playlistUris(playlist);
+  const endpoints = await resolveUris(uris, base, policy);
+  let rewritten = playlist;
+  for (let index = uris.length - 1; index >= 0; index--) {
+    const uri = uris[index]!;
+    rewritten = rewritten.slice(0, uri.start) + endpoints[index]!.url.href + rewritten.slice(uri.end);
+  }
+  return rewritten;
+}
diff --git a/packages/egress/src/index.d.ts b/packages/egress/src/index.d.ts
new file mode 100644
index 0000000..549d012
--- /dev/null
+++ b/packages/egress/src/index.d.ts
@@ -0,0 +1,5 @@
+export { EgressError, type EgressErrorCode } from "./errors.js";
+export { EgressPolicy, assertPublicAddress, validateUrl, hostBudgetKey, type EgressPolicyOptions, type ValidatedEndpoint, type Resolver, type ResolvedAddress } from "./policy.js";
+export { HostBudgets, DEFAULT_HOST_BUDGET, REFILL_INTERVAL_MS, retryAfterDeadline, type HostBudget, type HostBudgetOptions } from "./budget.js";
+export { createEgressClient, egressFetch, type EgressClientOptions, type EgressRequestOptions } from "./client.js";
+export { validateMasterPlaylist, rewriteSegmentUris } from "./hls.js";
diff --git a/packages/egress/src/index.js b/packages/egress/src/index.js
new file mode 100644
index 0000000..f25d9c4
--- /dev/null
+++ b/packages/egress/src/index.js
@@ -0,0 +1,6 @@
+export { EgressError } from "./errors.js";
+export { EgressPolicy, assertPublicAddress, validateUrl, hostBudgetKey } from "./policy.js";
+export { HostBudgets, DEFAULT_HOST_BUDGET, REFILL_INTERVAL_MS, retryAfterDeadline } from "./budget.js";
+export { createEgressClient, egressFetch } from "./client.js";
+export { validateMasterPlaylist, rewriteSegmentUris } from "./hls.js";
+//# sourceMappingURL=index.js.map
\ No newline at end of file
diff --git a/packages/egress/src/index.js.map b/packages/egress/src/index.js.map
new file mode 100644
index 0000000..c864519
--- /dev/null
+++ b/packages/egress/src/index.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAwB,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,WAAW,EAAE,aAAa,EAAyF,MAAM,aAAa,CAAC;AACnL,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,kBAAkB,EAA2C,MAAM,aAAa,CAAC;AAChJ,OAAO,EAAE,kBAAkB,EAAE,WAAW,EAAuD,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,sBAAsB,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC"}
\ No newline at end of file
diff --git a/packages/egress/src/index.ts b/packages/egress/src/index.ts
new file mode 100644
index 0000000..549d012
--- /dev/null
+++ b/packages/egress/src/index.ts
@@ -0,0 +1,5 @@
+export { EgressError, type EgressErrorCode } from "./errors.js";
+export { EgressPolicy, assertPublicAddress, validateUrl, hostBudgetKey, type EgressPolicyOptions, type ValidatedEndpoint, type Resolver, type ResolvedAddress } from "./policy.js";
+export { HostBudgets, DEFAULT_HOST_BUDGET, REFILL_INTERVAL_MS, retryAfterDeadline, type HostBudget, type HostBudgetOptions } from "./budget.js";
+export { createEgressClient, egressFetch, type EgressClientOptions, type EgressRequestOptions } from "./client.js";
+export { validateMasterPlaylist, rewriteSegmentUris } from "./hls.js";
diff --git a/packages/egress/src/policy.d.ts b/packages/egress/src/policy.d.ts
new file mode 100644
index 0000000..9db3fd0
--- /dev/null
+++ b/packages/egress/src/policy.d.ts
@@ -0,0 +1,26 @@
+export interface ResolvedAddress {
+    address: string;
+    family: number;
+}
+export type Resolver = (hostname: string) => Promise<readonly ResolvedAddress[]>;
+export interface EgressPolicyOptions {
+    /** Operator-controlled allowlists; defaults to HTTP 80 and HTTPS 443 only. */
+    ports?: Partial<Record<"http:" | "https:", readonly number[]>>;
+    resolver?: Resolver;
+}
+export interface ValidatedEndpoint {
+    url: URL;
+    pinnedAddress: string;
+    family: 4 | 6;
+    hostKey: string;
+}
+export declare function assertPublicAddress(address: string): void;
+export declare function hostBudgetKey(url: URL): string;
+/** Pure syntactic/literal policy check; no DNS or budget is consumed. */
+export declare function validateUrl(raw: string | URL, options?: EgressPolicyOptions): URL;
+export declare class EgressPolicy {
+    private readonly options;
+    constructor(options?: EgressPolicyOptions);
+    validateUrl(raw: string | URL): URL;
+    validate(raw: string | URL): Promise<ValidatedEndpoint>;
+}
diff --git a/packages/egress/src/policy.js b/packages/egress/src/policy.js
new file mode 100644
index 0000000..b9cc1ff
--- /dev/null
+++ b/packages/egress/src/policy.js
@@ -0,0 +1,93 @@
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import { domainToASCII } from "node:url";
+import { EgressError } from "./errors.js";
+const blocked = new BlockList();
+for (const [subnet, prefix] of [
+    ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+    ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
+    ["192.0.2.0", 24], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24],
+    ["224.0.0.0", 4], ["240.0.0.0", 4],
+])
+    blocked.addSubnet(subnet, prefix, "ipv4");
+for (const [subnet, prefix] of [
+    ["::", 96], ["::1", 128], ["fc00::", 7], ["fe80::", 10], ["fec0::", 10],
+    ["ff00::", 8], ["2001::", 32], ["2001:db8::", 32], ["2002::", 16],
+    ["64:ff9b::", 96], ["64:ff9b:1::", 48],
+])
+    blocked.addSubnet(subnet, prefix, "ipv6");
+// Keep this separate: Node also maps native IPv4 into this range internally.
+const mapped = new BlockList();
+mapped.addSubnet("::ffff:0:0", 96, "ipv6");
+export function assertPublicAddress(address) {
+    const normalized = address.replace(/^\[|\]$/g, "").toLowerCase();
+    const family = isIP(normalized);
+    if (!family)
+        throw new EgressError("DNS_FAILED", "Invalid resolved address");
+    if (normalized.includes("%") || family === 6 && mapped.check(normalized, "ipv6") || blocked.check(normalized, family === 4 ? "ipv4" : "ipv6")) {
+        throw new EgressError("DENIED_PRIVATE_ADDRESS", "Non-public addresses are denied");
+    }
+}
+export function hostBudgetKey(url) {
+    const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+    const canonical = isIP(host) ? host : domainToASCII(host);
+    return `${isIP(canonical) === 6 ? `[${canonical}]` : canonical}:${url.port || (url.protocol === "https:" ? "443" : "80")}`;
+}
+/** Pure syntactic/literal policy check; no DNS or budget is consumed. */
+export function validateUrl(raw, options = {}) {
+    const text = String(raw);
+    if (/[\s\\\u0000-\u001f\u007f]/u.test(text))
+        throw new EgressError("INVALID_URL", "Malformed URL");
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new EgressError("INVALID_URL", "Malformed URL");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        throw new EgressError("SCHEME_DENIED", "Only HTTP and HTTPS are allowed");
+    if (!url.hostname || url.username || url.password)
+        throw new EgressError("INVALID_URL", "URL credentials are denied");
+    const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+    if (!(options.ports?.[url.protocol] ?? (url.protocol === "https:" ? [443] : [80])).includes(port)) {
+        throw new EgressError("PORT_DENIED", "Port is not allowed for this scheme");
+    }
+    const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+    if (host === "localhost" || host.endsWith(".localhost"))
+        throw new EgressError("DENIED_PRIVATE_ADDRESS", "Localhost is denied");
+    if (isIP(host))
+        assertPublicAddress(host);
+    else
+        url.hostname = domainToASCII(host);
+    url.hash = "";
+    return url;
+}
+export class EgressPolicy {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    validateUrl(raw) { return validateUrl(raw, this.options); }
+    async validate(raw) {
+        const url = this.validateUrl(raw);
+        const host = url.hostname.replace(/^\[|\]$/g, "");
+        let addresses;
+        try {
+            addresses = isIP(host) ? [{ address: host, family: isIP(host) }] : await (this.options.resolver ?? ((name) => lookup(name, { all: true, verbatim: true })))(host);
+        }
+        catch (error) {
+            if (error instanceof EgressError)
+                throw error;
+            throw new EgressError("DNS_FAILED", "Hostname resolution failed");
+        }
+        if (!addresses.length)
+            throw new EgressError("DNS_FAILED", "No resolved addresses");
+        // Mixed public/private answers are denied, rather than relying on answer order.
+        for (const entry of addresses)
+            assertPublicAddress(entry.address);
+        const pinnedAddress = addresses[0].address.replace(/^\[|\]$/g, "").toLowerCase();
+        return { url, pinnedAddress, family: isIP(pinnedAddress), hostKey: hostBudgetKey(url) };
+    }
+}
+//# sourceMappingURL=policy.js.map
\ No newline at end of file
diff --git a/packages/egress/src/policy.js.map b/packages/egress/src/policy.js.map
new file mode 100644
index 0000000..f2ec7f0
--- /dev/null
+++ b/packages/egress/src/policy.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["policy.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAgB1C,MAAM,OAAO,GAAG,IAAI,SAAS,EAAE,CAAC;AAChC,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI;IAC7B,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;IACrE,CAAC,aAAa,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC;IAC/E,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,cAAc,EAAE,EAAE,CAAC,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC;IAChF,CAAC,WAAW,EAAE,CAAC,CAAC,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC;CAC1B;IAAE,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACtD,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI;IAC7B,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;IACvE,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,EAAE,CAAC,YAAY,EAAE,EAAE,CAAC,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC;IACjE,CAAC,WAAW,EAAE,EAAE,CAAC,EAAE,CAAC,aAAa,EAAE,EAAE,CAAC;CAC9B;IAAE,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AACtD,6EAA6E;AAC7E,MAAM,MAAM,GAAG,IAAI,SAAS,EAAE,CAAC;AAC/B,MAAM,CAAC,SAAS,CAAC,YAAY,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;AAE3C,MAAM,UAAU,mBAAmB,CAAC,OAAe;IACjD,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACjE,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;IAChC,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,0BAA0B,CAAC,CAAC;IAC7E,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,CAAC,IAAI,OAAO,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC;QAC9I,MAAM,IAAI,WAAW,CAAC,wBAAwB,EAAE,iCAAiC,CAAC,CAAC;IACrF,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,GAAQ;IACpC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACnF,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1D,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,SAAS,IAAI,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC;AAC7H,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAC,GAAiB,EAAE,UAA+B,EAAE;IAC9E,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IACzB,IAAI,4BAA4B,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IACnG,IAAI,GAAQ,CAAC;IACb,IAAI,CAAC;QAAC,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,CAAC;IAAC,CAAC;IAAC,MAAM,CAAC;QAAC,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAAC,CAAC;IAC7F,IAAI,GAAG,CAAC,QAAQ,KAAK,OAAO,IAAI,GAAG,CAAC,QAAQ,KAAK,QAAQ;QAAE,MAAM,IAAI,WAAW,CAAC,eAAe,EAAE,iCAAiC,CAAC,CAAC;IACrI,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ,IAAI,GAAG,CAAC,QAAQ;QAAE,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,4BAA4B,CAAC,CAAC;IACtH,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACxE,IAAI,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QAClG,MAAM,IAAI,WAAW,CAAC,aAAa,EAAE,qCAAqC,CAAC,CAAC;IAC9E,CAAC;IACD,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;IACnF,IAAI,IAAI,KAAK,WAAW,IAAI,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,MAAM,IAAI,WAAW,CAAC,wBAAwB,EAAE,qBAAqB,CAAC,CAAC;IAChI,IAAI,IAAI,CAAC,IAAI,CAAC;QAAE,mBAAmB,CAAC,IAAI,CAAC,CAAC;;QACrC,GAAG,CAAC,QAAQ,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACxC,GAAG,CAAC,IAAI,GAAG,EAAE,CAAC;IACd,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,UAA+B,EAAE;QAAjC,YAAO,GAAP,OAAO,CAA0B;IAAG,CAAC;IAClE,WAAW,CAAC,GAAiB,IAAS,OAAO,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IAC9E,KAAK,CAAC,QAAQ,CAAC,GAAiB;QAC9B,MAAM,GAAG,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAClC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAClD,IAAI,SAAqC,CAAC;QAC1C,IAAI,CAAC;YACH,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MACjE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7F,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,WAAW;gBAAE,MAAM,KAAK,CAAC;YAC9C,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,4BAA4B,CAAC,CAAC;QACpE,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,MAAM;YAAE,MAAM,IAAI,WAAW,CAAC,YAAY,EAAE,uBAAuB,CAAC,CAAC;QACpF,gFAAgF;QAChF,KAAK,MAAM,KAAK,IAAI,SAAS;YAAE,mBAAmB,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClE,MAAM,aAAa,GAAG,SAAS,CAAC,CAAC,CAAE,CAAC,OAAO,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC;QAClF,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,aAAa,CAAU,EAAE,OAAO,EAAE,aAAa,CAAC,GAAG,CAAC,EAAE,CAAC;IACnG,CAAC;CACF"}
\ No newline at end of file
diff --git a/packages/egress/src/policy.test.ts b/packages/egress/src/policy.test.ts
new file mode 100644
index 0000000..01eef1b
--- /dev/null
+++ b/packages/egress/src/policy.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it, vi } from "vitest";
+import { assertPublicAddress, EgressPolicy, hostBudgetKey, validateUrl } from "./policy.js";
+
+describe("unified public-address policy", () => {
+  it.each([
+    "0.0.0.0", "0.1.2.3", "10.0.0.1", "100.64.0.1", "100.127.255.255", "127.0.0.1", "127.255.1.1",
+    "169.254.169.254", "169.254.1.1", "172.16.0.1", "172.31.255.255", "192.0.0.1", "192.168.1.1",
+    "192.0.2.1", "198.18.0.1", "198.19.255.255", "198.51.100.1", "203.0.113.1", "224.0.0.1", "239.1.2.3",
+    "240.0.0.1", "255.255.255.255", "::", "::1", "[::1]", "fc00::1", "fdff::1", "fe80::1", "fec0::1", "ff02::1",
+    "2001::1", "2001:db8::1", "2002:0808:0808::1", "64:ff9b::808:808", "64:ff9b:1::1",
+    "::ffff:127.0.0.1", "::ffff:8.8.8.8", "0:0:0:0:0:ffff:0808:0808", "::8.8.8.8",
+  ])("denies %s", (address) => { expect(() => assertPublicAddress(address)).toThrowError(expect.objectContaining({ code: "DENIED_PRIVATE_ADDRESS" })); });
+  it.each(["8.8.8.8", "1.1.1.1", "100.63.255.255", "100.128.0.1", "172.15.0.1", "172.32.0.1", "192.169.0.1", "2606:4700:4700::1111", "2001:4860:4860::8888"])("allows %s", (address) => { expect(() => assertPublicAddress(address)).not.toThrow(); });
+  it.each(["http://2130706433", "http://0177.0.0.1", "http://0x7f000001", "http://127.1", "http://[::ffff:0808:0808]", "http://LOCALHOST.", "http://foo.localhost"])("normalizes then denies %s", (url) => { expect(() => validateUrl(url)).toThrowError(expect.objectContaining({ code: "DENIED_PRIVATE_ADDRESS" })); });
+  it.each(["file:///etc/passwd", "ftp://example.com", "rtmp://example.com", "concat:foo"])("denies scheme %s", (url) => { expect(() => validateUrl(url)).toThrowError(expect.objectContaining({ code: "SCHEME_DENIED" })); });
+  it.each(["https://user:secret@example.com", " https://example.com", "https://example.com\n", "https:\\example.com", "-https://example.com"])("denies malformed input %s", (url) => { expect(() => validateUrl(url)).toThrow(); });
+  it("has per-scheme port allowlists and stable IDNA/effective-port keys", () => {
+    expect(() => validateUrl("https://example.com:80")).toThrowError(expect.objectContaining({ code: "PORT_DENIED" }));
+    expect(() => validateUrl("http://example.com:443")).toThrowError(expect.objectContaining({ code: "PORT_DENIED" }));
+    expect(validateUrl("https://example.com:8443", { ports: { "https:": [443, 8443] } }).port).toBe("8443");
+    expect(hostBudgetKey(validateUrl("https://BÜCHER.Example.:443/a"))).toBe("xn--bcher-kva.example:443");
+    expect(hostBudgetKey(validateUrl("http://[2606:4700:4700::1111]"))).toBe("[2606:4700:4700::1111]:80");
+  });
+  it("pins one validated answer and rejects mixed or invalid DNS results", async () => {
+    const resolver = vi.fn().mockResolvedValueOnce([{ address: "8.8.8.8", family: 4 }]).mockResolvedValueOnce([{ address: "127.0.0.1", family: 4 }]);
+    const policy = new EgressPolicy({ resolver });
+    expect((await policy.validate("https://example.com")).pinnedAddress).toBe("8.8.8.8");
+    expect(resolver).toHaveBeenCalledTimes(1);
+    await expect(policy.validate("https://example.com")).rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+    await expect(new EgressPolicy({ resolver: async () => [{ address: "8.8.8.8", family: 4 }, { address: "10.0.0.1", family: 4 }] }).validate("https://example.com")).rejects.toMatchObject({ code: "DENIED_PRIVATE_ADDRESS" });
+    for (const answer of [[], [{ address: "bogus", family: 4 }]]) {
+      await expect(new EgressPolicy({ resolver: async () => answer }).validate("https://example.com")).rejects.toMatchObject({ code: "DNS_FAILED" });
+    }
+  });
+});
diff --git a/packages/egress/src/policy.ts b/packages/egress/src/policy.ts
new file mode 100644
index 0000000..ef713af
--- /dev/null
+++ b/packages/egress/src/policy.ts
@@ -0,0 +1,91 @@
+import { lookup } from "node:dns/promises";
+import { BlockList, isIP } from "node:net";
+import { domainToASCII } from "node:url";
+import { EgressError } from "./errors.js";
+
+export interface ResolvedAddress { address: string; family: number }
+export type Resolver = (hostname: string) => Promise<readonly ResolvedAddress[]>;
+export interface EgressPolicyOptions {
+  /** Operator-controlled allowlists; defaults to HTTP 80 and HTTPS 443 only. */
+  ports?: Partial<Record<"http:" | "https:", readonly number[]>>;
+  resolver?: Resolver;
+}
+export interface ValidatedEndpoint {
+  url: URL;
+  pinnedAddress: string;
+  family: 4 | 6;
+  hostKey: string;
+}
+
+const blocked = new BlockList();
+for (const [subnet, prefix] of [
+  ["0.0.0.0", 8], ["10.0.0.0", 8], ["100.64.0.0", 10], ["127.0.0.0", 8],
+  ["169.254.0.0", 16], ["172.16.0.0", 12], ["192.0.0.0", 24], ["192.168.0.0", 16],
+  ["192.0.2.0", 24], ["198.18.0.0", 15], ["198.51.100.0", 24], ["203.0.113.0", 24],
+  ["224.0.0.0", 4], ["240.0.0.0", 4],
+] as const) blocked.addSubnet(subnet, prefix, "ipv4");
+for (const [subnet, prefix] of [
+  ["::", 96], ["::1", 128], ["fc00::", 7], ["fe80::", 10], ["fec0::", 10],
+  ["ff00::", 8], ["2001::", 32], ["2001:db8::", 32], ["2002::", 16],
+  ["64:ff9b::", 96], ["64:ff9b:1::", 48],
+] as const) blocked.addSubnet(subnet, prefix, "ipv6");
+// Keep this separate: Node also maps native IPv4 into this range internally.
+const mapped = new BlockList();
+mapped.addSubnet("::ffff:0:0", 96, "ipv6");
+
+export function assertPublicAddress(address: string): void {
+  const normalized = address.replace(/^\[|\]$/g, "").toLowerCase();
+  const family = isIP(normalized);
+  if (!family) throw new EgressError("DNS_FAILED", "Invalid resolved address");
+  if (normalized.includes("%") || family === 6 && mapped.check(normalized, "ipv6") || blocked.check(normalized, family === 4 ? "ipv4" : "ipv6")) {
+    throw new EgressError("DENIED_PRIVATE_ADDRESS", "Non-public addresses are denied");
+  }
+}
+
+export function hostBudgetKey(url: URL): string {
+  const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+  const canonical = isIP(host) ? host : domainToASCII(host);
+  return `${isIP(canonical) === 6 ? `[${canonical}]` : canonical}:${url.port || (url.protocol === "https:" ? "443" : "80")}`;
+}
+
+/** Pure syntactic/literal policy check; no DNS or budget is consumed. */
+export function validateUrl(raw: string | URL, options: EgressPolicyOptions = {}): URL {
+  const text = String(raw);
+  if (/[\s\\\u0000-\u001f\u007f]/u.test(text)) throw new EgressError("INVALID_URL", "Malformed URL");
+  let url: URL;
+  try { url = new URL(text); } catch { throw new EgressError("INVALID_URL", "Malformed URL"); }
+  if (url.protocol !== "http:" && url.protocol !== "https:") throw new EgressError("SCHEME_DENIED", "Only HTTP and HTTPS are allowed");
+  if (!url.hostname || url.username || url.password) throw new EgressError("INVALID_URL", "URL credentials are denied");
+  const port = Number(url.port || (url.protocol === "https:" ? 443 : 80));
+  if (!(options.ports?.[url.protocol] ?? (url.protocol === "https:" ? [443] : [80])).includes(port)) {
+    throw new EgressError("PORT_DENIED", "Port is not allowed for this scheme");
+  }
+  const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+  if (host === "localhost" || host.endsWith(".localhost")) throw new EgressError("DENIED_PRIVATE_ADDRESS", "Localhost is denied");
+  if (isIP(host)) assertPublicAddress(host);
+  else url.hostname = domainToASCII(host);
+  url.hash = "";
+  return url;
+}
+
+export class EgressPolicy {
+  constructor(private readonly options: EgressPolicyOptions = {}) {}
+  validateUrl(raw: string | URL): URL { return validateUrl(raw, this.options); }
+  async validate(raw: string | URL): Promise<ValidatedEndpoint> {
+    const url = this.validateUrl(raw);
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    let addresses: readonly ResolvedAddress[];
+    try {
+      addresses = isIP(host) ? [{ address: host, family: isIP(host) }] : await
+        (this.options.resolver ?? ((name) => lookup(name, { all: true, verbatim: true })))(host);
+    } catch (error) {
+      if (error instanceof EgressError) throw error;
+      throw new EgressError("DNS_FAILED", "Hostname resolution failed");
+    }
+    if (!addresses.length) throw new EgressError("DNS_FAILED", "No resolved addresses");
+    // Mixed public/private answers are denied, rather than relying on answer order.
+    for (const entry of addresses) assertPublicAddress(entry.address);
+    const pinnedAddress = addresses[0]!.address.replace(/^\[|\]$/g, "").toLowerCase();
+    return { url, pinnedAddress, family: isIP(pinnedAddress) as 4 | 6, hostKey: hostBudgetKey(url) };
+  }
+}
diff --git a/packages/egress/src/test-db.ts b/packages/egress/src/test-db.ts
new file mode 100644
index 0000000..d6bc633
--- /dev/null
+++ b/packages/egress/src/test-db.ts
@@ -0,0 +1,28 @@
+import { randomUUID } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { Pool } from "pg";
+import { afterAll, beforeAll, beforeEach } from "vitest";
+
+/** Dedicated schema per suite; never runs application migrations or modifies application rows. */
+export function testDatabase(): Pool {
+  const connectionString = process.env.EGRESS_TEST_DATABASE_URL ?? "postgres://superposter:superposter_dev@127.0.0.1:5433/superposter";
+  const schema = `egress_test_${randomUUID().replaceAll("-", "")}`;
+  const owner = new Pool({ connectionString });
+  const pool = new Pool({ connectionString, options: `-c search_path=${schema}`, max: 24 });
+  beforeAll(async () => {
+    await owner.query(`CREATE SCHEMA ${schema}`);
+    const client = await pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query(await readFile(new URL("../migrations/001_host_budgets.sql", import.meta.url), "utf8"));
+      await client.query("COMMIT");
+    } finally { client.release(); }
+  });
+  beforeEach(async () => { await pool.query("TRUNCATE host_budgets"); });
+  afterAll(async () => {
+    await pool.end();
+    await owner.query(`DROP SCHEMA IF EXISTS ${schema} CASCADE`);
+    await owner.end();
+  });
+  return pool;
+}
diff --git a/packages/egress/src/transport.d.ts b/packages/egress/src/transport.d.ts
new file mode 100644
index 0000000..9b68ce4
--- /dev/null
+++ b/packages/egress/src/transport.d.ts
@@ -0,0 +1,9 @@
+import type { ValidatedEndpoint } from "./policy.js";
+export interface WireResponse {
+    status: number;
+    statusText: string;
+    headers: Headers;
+    body: Buffer;
+}
+/** A fresh socket for every hop: no proxy, second DNS lookup, or unvalidated pooled connection. */
+export declare function requestPinned(endpoint: ValidatedEndpoint, method: string, headers: Headers, body: Buffer | undefined, signal: AbortSignal, maxResponseBytes: number, onHeaders: (status: number, headers: Headers) => Promise<void>): Promise<WireResponse>;
diff --git a/packages/egress/src/transport.js b/packages/egress/src/transport.js
new file mode 100644
index 0000000..d52d70a
--- /dev/null
+++ b/packages/egress/src/transport.js
@@ -0,0 +1,86 @@
+import http from "node:http";
+import https from "node:https";
+import { EgressError } from "./errors.js";
+/** A fresh socket for every hop: no proxy, second DNS lookup, or unvalidated pooled connection. */
+export function requestPinned(endpoint, method, headers, body, signal, maxResponseBytes, onHeaders) {
+    return new Promise((resolve, reject) => {
+        const requestHeaders = Object.fromEntries(headers.entries());
+        requestHeaders.host = endpoint.url.host;
+        requestHeaders["accept-encoding"] = "identity";
+        delete requestHeaders["content-length"];
+        delete requestHeaders["transfer-encoding"];
+        delete requestHeaders.connection;
+        if (body)
+            requestHeaders["content-length"] = String(body.length);
+        let response;
+        let settled = false;
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            reject(error);
+            response?.destroy();
+            request.destroy();
+        };
+        const request = (endpoint.url.protocol === "https:" ? https : http).request(endpoint.url, {
+            method, headers: requestHeaders, agent: false, family: endpoint.family,
+            // Keep URL hostname for TLS verification/SNI and Host, but return only the vetted IP.
+            lookup: (_hostname, options, callback) => {
+                if (options.all)
+                    callback(null, [{ address: endpoint.pinnedAddress, family: endpoint.family }]);
+                else
+                    callback(null, endpoint.pinnedAddress, endpoint.family);
+            },
+        }, (incoming) => {
+            response = incoming;
+            const responseHeaders = new Headers();
+            for (let i = 0; i < incoming.rawHeaders.length; i += 2)
+                responseHeaders.append(incoming.rawHeaders[i], incoming.rawHeaders[i + 1]);
+            incoming.on("error", () => fail(new EgressError("NETWORK_ERROR", "Response stream failed")));
+            incoming.on("aborted", () => fail(new EgressError("NETWORK_ERROR", "Response stream aborted")));
+            void (async () => {
+                const status = incoming.statusCode ?? 502;
+                await onHeaders(status, responseHeaders);
+                if (settled)
+                    return;
+                const hasBody = method !== "HEAD" && ![204, 205, 304].includes(status);
+                const length = Number(responseHeaders.get("content-length"));
+                if (hasBody && Number.isFinite(length) && length > maxResponseBytes) {
+                    fail(new EgressError("RESPONSE_TOO_LARGE", "Response exceeds size limit"));
+                    return;
+                }
+                // Identity encoding makes both the size cap and returned byte representation explicit.
+                const encoding = responseHeaders.get("content-encoding");
+                if (hasBody && encoding && encoding.toLowerCase() !== "identity") {
+                    fail(new EgressError("NETWORK_ERROR", "Upstream ignored identity encoding"));
+                    return;
+                }
+                const chunks = [];
+                let size = 0;
+                incoming.on("data", (chunk) => {
+                    size += chunk.length;
+                    if (size > maxResponseBytes)
+                        fail(new EgressError("RESPONSE_TOO_LARGE", "Response exceeds size limit"));
+                    else
+                        chunks.push(chunk);
+                });
+                incoming.on("end", () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    resolve({ status, statusText: incoming.statusMessage ?? "", headers: responseHeaders, body: Buffer.concat(chunks) });
+                });
+            })().catch((error) => fail(error instanceof EgressError ? error : new EgressError("NETWORK_ERROR", "Response processing failed")));
+        });
+        const aborted = () => fail(signal.reason instanceof EgressError ? signal.reason : new EgressError("ABORTED", "Request aborted"));
+        signal.addEventListener("abort", aborted, { once: true });
+        request.on("close", () => signal.removeEventListener("abort", aborted));
+        request.on("error", () => fail(new EgressError("NETWORK_ERROR", "Connection failed")));
+        if (signal.aborted) {
+            aborted();
+            return;
+        }
+        request.end(body);
+    });
+}
+//# sourceMappingURL=transport.js.map
\ No newline at end of file
diff --git a/packages/egress/src/transport.js.map b/packages/egress/src/transport.js.map
new file mode 100644
index 0000000..7d61ba7
--- /dev/null
+++ b/packages/egress/src/transport.js.map
@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["transport.ts"],"names":[],"mappings":"AAAA,OAAO,IAA8B,MAAM,WAAW,CAAC;AACvD,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAK1C,mGAAmG;AACnG,MAAM,UAAU,aAAa,CAAC,QAA2B,EAAE,MAAc,EAAE,OAAgB,EAAE,IAAwB,EACnH,MAAmB,EAAE,gBAAwB,EAC7C,SAA8D;IAC9D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,cAAc,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;QAC7D,cAAc,CAAC,IAAI,GAAG,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC;QACxC,cAAc,CAAC,iBAAiB,CAAC,GAAG,UAAU,CAAC;QAC/C,OAAO,cAAc,CAAC,gBAAgB,CAAC,CAAC;QACxC,OAAO,cAAc,CAAC,mBAAmB,CAAC,CAAC;QAC3C,OAAO,cAAc,CAAC,UAAU,CAAC;QACjC,IAAI,IAAI;YAAE,cAAc,CAAC,gBAAgB,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACjE,IAAI,QAAqC,CAAC;QAC1C,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,IAAI,GAAG,CAAC,KAAkB,EAAE,EAAE;YAClC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,MAAM,CAAC,KAAK,CAAC,CAAC;YACd,QAAQ,EAAE,OAAO,EAAE,CAAC;YACpB,OAAO,CAAC,OAAO,EAAE,CAAC;QACpB,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,EAAE;YACxF,MAAM,EAAE,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM;YACtE,sFAAsF;YACtF,MAAM,EAAE,CAAC,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE;gBACvC,IAAI,OAAO,CAAC,GAAG;oBAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;;oBAC3F,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,aAAa,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;YAC/D,CAAC;SACF,EAAE,CAAC,QAAQ,EAAE,EAAE;YACd,QAAQ,GAAG,QAAQ,CAAC;YACpB,MAAM,eAAe,GAAG,IAAI,OAAO,EAAE,CAAC;YACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC;gBAAE,eAAe,CAAC,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAE,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAE,CAAC,CAAC;YACrI,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,wBAAwB,CAAC,CAAC,CAAC,CAAC;YAC7F,QAAQ,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,yBAAyB,CAAC,CAAC,CAAC,CAAC;YAChG,KAAK,CAAC,KAAK,IAAI,EAAE;gBACf,MAAM,MAAM,GAAG,QAAQ,CAAC,UAAU,IAAI,GAAG,CAAC;gBAC1C,MAAM,SAAS,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;gBACzC,IAAI,OAAO;oBAAE,OAAO;gBACpB,MAAM,OAAO,GAAG,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACvE,MAAM,MAAM,GAAG,MAAM,CAAC,eAAe,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC;gBAC7D,IAAI,OAAO,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,GAAG,gBAAgB,EAAE,CAAC;oBACpE,IAAI,CAAC,IAAI,WAAW,CAAC,oBAAoB,EAAE,6BAA6B,CAAC,CAAC,CAAC;oBAAC,OAAO;gBACrF,CAAC;gBACD,uFAAuF;gBACvF,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;gBACzD,IAAI,OAAO,IAAI,QAAQ,IAAI,QAAQ,CAAC,WAAW,EAAE,KAAK,UAAU,EAAE,CAAC;oBACjE,IAAI,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,oCAAoC,CAAC,CAAC,CAAC;oBAAC,OAAO;gBACvF,CAAC;gBACD,MAAM,MAAM,GAAa,EAAE,CAAC;gBAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;gBACb,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;oBACpC,IAAI,IAAI,KAAK,CAAC,MAAM,CAAC;oBACrB,IAAI,IAAI,GAAG,gBAAgB;wBAAE,IAAI,CAAC,IAAI,WAAW,CAAC,oBAAoB,EAAE,6BAA6B,CAAC,CAAC,CAAC;;wBACnG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC1B,CAAC,CAAC,CAAC;gBACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;oBACtB,IAAI,OAAO;wBAAE,OAAO;oBACpB,OAAO,GAAG,IAAI,CAAC;oBACf,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,CAAC,aAAa,IAAI,EAAE,EAAE,OAAO,EAAE,eAAe,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;gBACvH,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,YAAY,WAAW,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,4BAA4B,CAAC,CAAC,CAAC,CAAC;QAC9I,CAAC,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,YAAY,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC,SAAS,EAAE,iBAAiB,CAAC,CAAC,CAAC;QACjI,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1D,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC;QACxE,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,eAAe,EAAE,mBAAmB,CAAC,CAAC,CAAC,CAAC;QACvF,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAAC,OAAO,EAAE,CAAC;YAAC,OAAO;QAAC,CAAC;QAC1C,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC,CAAC;AACL,CAAC"}
\ No newline at end of file
diff --git a/packages/egress/src/transport.ts b/packages/egress/src/transport.ts
new file mode 100644
index 0000000..32621f3
--- /dev/null
+++ b/packages/egress/src/transport.ts
@@ -0,0 +1,77 @@
+import http, { type IncomingMessage } from "node:http";
+import https from "node:https";
+import { EgressError } from "./errors.js";
+import type { ValidatedEndpoint } from "./policy.js";
+
+export interface WireResponse { status: number; statusText: string; headers: Headers; body: Buffer }
+
+/** A fresh socket for every hop: no proxy, second DNS lookup, or unvalidated pooled connection. */
+export function requestPinned(endpoint: ValidatedEndpoint, method: string, headers: Headers, body: Buffer | undefined,
+  signal: AbortSignal, maxResponseBytes: number,
+  onHeaders: (status: number, headers: Headers) => Promise<void>): Promise<WireResponse> {
+  return new Promise((resolve, reject) => {
+    const requestHeaders = Object.fromEntries(headers.entries());
+    requestHeaders.host = endpoint.url.host;
+    requestHeaders["accept-encoding"] = "identity";
+    delete requestHeaders["content-length"];
+    delete requestHeaders["transfer-encoding"];
+    delete requestHeaders.connection;
+    if (body) requestHeaders["content-length"] = String(body.length);
+    let response: IncomingMessage | undefined;
+    let settled = false;
+    const fail = (error: EgressError) => {
+      if (settled) return;
+      settled = true;
+      reject(error);
+      response?.destroy();
+      request.destroy();
+    };
+    const request = (endpoint.url.protocol === "https:" ? https : http).request(endpoint.url, {
+      method, headers: requestHeaders, agent: false, family: endpoint.family,
+      // Keep URL hostname for TLS verification/SNI and Host, but return only the vetted IP.
+      lookup: (_hostname, options, callback) => {
+        if (options.all) callback(null, [{ address: endpoint.pinnedAddress, family: endpoint.family }]);
+        else callback(null, endpoint.pinnedAddress, endpoint.family);
+      },
+    }, (incoming) => {
+      response = incoming;
+      const responseHeaders = new Headers();
+      for (let i = 0; i < incoming.rawHeaders.length; i += 2) responseHeaders.append(incoming.rawHeaders[i]!, incoming.rawHeaders[i + 1]!);
+      incoming.on("error", () => fail(new EgressError("NETWORK_ERROR", "Response stream failed")));
+      incoming.on("aborted", () => fail(new EgressError("NETWORK_ERROR", "Response stream aborted")));
+      void (async () => {
+        const status = incoming.statusCode ?? 502;
+        await onHeaders(status, responseHeaders);
+        if (settled) return;
+        const hasBody = method !== "HEAD" && ![204, 205, 304].includes(status);
+        const length = Number(responseHeaders.get("content-length"));
+        if (hasBody && Number.isFinite(length) && length > maxResponseBytes) {
+          fail(new EgressError("RESPONSE_TOO_LARGE", "Response exceeds size limit")); return;
+        }
+        // Identity encoding makes both the size cap and returned byte representation explicit.
+        const encoding = responseHeaders.get("content-encoding");
+        if (hasBody && encoding && encoding.toLowerCase() !== "identity") {
+          fail(new EgressError("NETWORK_ERROR", "Upstream ignored identity encoding")); return;
+        }
+        const chunks: Buffer[] = [];
+        let size = 0;
+        incoming.on("data", (chunk: Buffer) => {
+          size += chunk.length;
+          if (size > maxResponseBytes) fail(new EgressError("RESPONSE_TOO_LARGE", "Response exceeds size limit"));
+          else chunks.push(chunk);
+        });
+        incoming.on("end", () => {
+          if (settled) return;
+          settled = true;
+          resolve({ status, statusText: incoming.statusMessage ?? "", headers: responseHeaders, body: Buffer.concat(chunks) });
+        });
+      })().catch((error: unknown) => fail(error instanceof EgressError ? error : new EgressError("NETWORK_ERROR", "Response processing failed")));
+    });
+    const aborted = () => fail(signal.reason instanceof EgressError ? signal.reason : new EgressError("ABORTED", "Request aborted"));
+    signal.addEventListener("abort", aborted, { once: true });
+    request.on("close", () => signal.removeEventListener("abort", aborted));
+    request.on("error", () => fail(new EgressError("NETWORK_ERROR", "Connection failed")));
+    if (signal.aborted) { aborted(); return; }
+    request.end(body);
+  });
+}
diff --git a/packages/egress/tsconfig.json b/packages/egress/tsconfig.json
new file mode 100644
index 0000000..972facb
--- /dev/null
+++ b/packages/egress/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src" },
+  "include": ["src"]
+}
diff --git a/packages/media-sandbox/README.md b/packages/media-sandbox/README.md
new file mode 100644
index 0000000..091c939
--- /dev/null
+++ b/packages/media-sandbox/README.md
@@ -0,0 +1,38 @@
+# @tactical-media-broadcast-hub/media-sandbox
+
+WP4/WP9 Linux runtime for untrusted uploaded media and the worker's existing typed FFmpeg graph builders. Commands contain argv arrays, never shell text. Uploads use a server-minted UUID or SHA-256 id and appear as `file:/upload/<id>`; the resolver's host path and original filename do not enter media argv. The runtime copies only that regular file, with `O_NOFOLLOW` and a size cap, into private staging. Client filenames are metadata only. Do not expose the server asset resolver or the supervisor argv adapter as a client API.
+
+Build with `pnpm --dir packages/media-sandbox build`, typecheck with `pnpm --dir packages/media-sandbox typecheck`, and test with `pnpm --dir packages/media-sandbox test`. A C compiler and Linux headers are required. The native launcher is generated at `dist/media-confine`. Build this package before starting the media-worker; its supervisor resolves the built CommonJS entry without a worker manifest or lockfile change. The worker still typechecks independently before that build.
+
+## Runtime profile
+
+The launcher joins the job's cgroup **before** executing `unshare`, so mapping helpers and all media descendants inherit its limits. `unshare --user --map-auto --map-user=0 --setgroups=allow --mount --net --pid --fork --kill-child` requires subordinate UID/GID ranges and working `newuidmap`/`newgidmap`. Mapping the caller UID to namespace root separately preserves `setgroups=allow` for the subordinate GID mapping; `--map-root-user` would force setgroups denial and prevent dropping inherited groups. Namespace root sets up the filesystem, drops the capability bounding set, supplementary groups, and all effective/permitted/inheritable capabilities, then switches to a distinct nonzero mapped UID/GID for each concurrently active child. UID leases use atomic private directories under `/tmp/media-sandbox-uids-<worker-uid>` so concurrent worker processes sharing a subordinate range also use distinct host UIDs. Leases are released after job teardown; after a worker crash, stale lease directories deliberately remain reserved and can be removed once its children are confirmed gone. A single-UID user namespace is deliberately insufficient. No privileged/root fallback exists.
+
+The mount namespace binds a dedicated minimal rootfs read-only (`nosuid,nodev`), the single upload directory read-only (`noexec`), and the channel/job scratch directory writable (`noexec`). It adds a private 16 MiB tmpfs, read-only procfs exposing only the job PID namespace, and `/dev/null`. It never binds host `/`, `/etc`, a full upload bucket, home, vault/DB paths, Docker sockets or other jobs. Nested mounts in the supplied rootfs are rejected. Caller-supplied scratch must have a worker-owned 0700 parent; the scratch directory is writable to the mapped UID. The supervisor generates scratch names from a workspace/channel hash and prepares existing generated output directories through directory descriptors, without following symlinks.
+
+`native/confine.c` contains the architecture-checked seccomp BPF profile (x86-64 and aarch64). It rejects the x32 ABI, new sockets/connect/bind/sendmsg, mount/chroot/namespace creation or joining, ptrace/process-memory access, keyrings, module loading, BPF/perf, file-handle access, userfaultfd and io_uring. It rejects namespace flags in `clone` and returns ENOSYS for `clone3` to allow ordinary thread fallback. Ordinary FFmpeg decoding syscalls remain allowed. `no-new-privileges` and zero capabilities prevent privilege regain. The empty network namespace has no DNS resolver or route; inherited relay pipes remain usable.
+
+The dedicated delegated cgroup v2 subtree must have `cpu`, `memory`, and `pids` controllers enabled by the operator. Each job gets `cpu.max`, `memory.max`, `memory.swap.max=0`, `memory.oom.group=1`, and `pids.max`. File size uses `RLIMIT_FSIZE`, CPU execution has an `RLIMIT_CPU` ceiling, and a supervisor wall timer uses `cgroup.kill` plus the job process group. Core dumps are disabled. Failures and termination clean only the job's cgroup and staging. CPU/time/file size are per process where implemented by rlimits; memory/pids/CPU quota and wall termination cover descendants. A scratch filesystem quota is still appropriate if an operator needs a total disk-byte cap in addition to the per-file cap.
+
+Probe inputs have `-protocol_whitelist file` and a forced demuxer from `DEMUXERS`. HLS, DASH, concat, SDP and other remote manifests are excluded. Probe JSON is restricted to selected stream/format fields, capped at 256 KiB, and validated for shape, types, bounds, allowed string syntax, unique stream indexes and at most 64 streams. Parse failures never echo input. Tags, filenames and arbitrary metadata do not reach the result. Probe stderr is drained and logged only as a fixed suppression message. Commands are frozen and runtime-branded; fabricated argv objects cannot be spawned.
+
+## Worker integration and deployment
+
+`apps/media-worker/src/supervisor/sandbox.ts` uses an AsyncLocalStorage context around a channel's start/stop/reconfigure. It installs one Node spawn adapter; only FFmpeg/ffprobe calls in that context are mediated. Other spawns retain their original behavior. Existing relay/compositor/playlist/preview FFmpeg children retain their stdio descriptors and ManagedProcess API. The package's supervisor adapter validates existing typed argv, forces input demuxers and per-input protocol whitelists, translates minted overlay/scratch paths, rejects IO filters and remote URLs, and never accepts arbitrary FFmpeg switches. Current worker jobs have no ffprobe call; upload probes must use the package's typed `probe(assetId, demuxer, options)` wrapper. A freeform ffprobe spawn in the supervisor is rejected.
+
+`MEDIA_SANDBOX=off` is the local default. `MEDIA_SANDBOX=on`, or `NODE_ENV=production` with no flag, enables confinement. Production explicitly setting `off` is rejected at supervisor construction. Enabled operation requires:
+
+- `MEDIA_SANDBOX_ROOTFS`: an operator-owned, immutable, dedicated FFmpeg runtime rootfs. Include `/usr/bin/ffmpeg`, `/usr/bin/ffprobe` and only their required runtime libraries, plus real empty directories `/upload`, `/scratch`, `/tmp`, `/proc`, `/dev` and a regular empty `/dev/null` mount target. No symlink mount targets or nested mounts. Pin the FFmpeg/ffprobe version and image digest in the deployment image and keep that version under CVE watch; this package does not silently use a host installation in production.
+- `MEDIA_SANDBOX_CGROUP_ROOT`: the empty worker-delegated cgroup subtree (do not delegate the host cgroup root).
+- Working subordinate UID/GID mappings, mount/net/PID namespaces, seccomp, and cgroup v2 including `cgroup.kill`.
+- Optional `MEDIA_SCRATCH_DIR` (same setting as existing production jobs) and `MEDIA_SANDBOX_WALL_TIME_MS` (channel default 24 hours; package/upload default 120 seconds).
+
+All children receive fixed PATH/LANG/HOME only. The supervisor replaces the public stderr stream with fixed suppression messages before `spawnManaged` attaches a logger; a passthrough caller redactor cannot leak attacker-controlled stderr or partial secret strings. Native failures also use fixed messages. The media supervisor keeps existing restart/version logic.
+
+This boundary covers FFmpeg/ffprobe children. Existing native frame-gate/source-bus and egress relay processes are outside this integration; their isolation requires their respective runtime wiring. Relay transport remains fd-only, with external routing confined by the existing endpoint-validation/egress layer.
+
+## Security tests
+
+Vitest covers minted-path construction, protocol/demuxer rejection, frozen command branding, limit validation, probe schema/output overflow, and the real native seccomp/no-new-privileges profile without namespaces. Capability-dependent tests execute a statically compiled adversarial media child inside the full runtime: host/vault/DB/sibling-file denial, read-only root, different UIDs, network denial, memory/time/pids/file-size bounds with a surviving sibling, capped/invalid probe output, and planted stream-key/OAuth-token/SRT-passphrase canaries against wrapper and final child `/proc` metadata, stderr and captured output. The full capability check executes the actual native confinement, including UID dropping and seccomp; unsupported hosts skip with a fixed explanatory message.
+
+Worker tests drive a freshly signed command through the real supervisor into `spawnManaged`, inspect `/proc/<pid>/cmdline` and `environ`, force a real FFmpeg error, and scan captured stderr and every supervisor log line. The local canary runs on ordinary hosts; the enabled canary requires the full rootless runtime and skips explicitly when unavailable. Existing production argv compatibility and fail-closed configuration behavior are also checked.
diff --git a/packages/media-sandbox/native/confine.c b/packages/media-sandbox/native/confine.c
new file mode 100644
index 0000000..bc83a5b
--- /dev/null
+++ b/packages/media-sandbox/native/confine.c
@@ -0,0 +1,124 @@
+#define _GNU_SOURCE
+#include <errno.h>
+#include <fcntl.h>
+#include <grp.h>
+#include <linux/audit.h>
+#include <linux/capability.h>
+#include <linux/filter.h>
+#include <linux/seccomp.h>
+#include <stddef.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/mount.h>
+#include <sys/prctl.h>
+#include <sys/resource.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/syscall.h>
+#include <unistd.h>
+
+/* All errors are fixed text: never echo argv, paths, environment or media bytes. */
+static void fail(void) { fputs("media sandbox confinement failed\n", stderr); exit(125); }
+static void check(int result) { if (result < 0) fail(); }
+static unsigned long number(const char *s) {
+  char *end; errno = 0; unsigned long n = strtoul(s, &end, 10);
+  if (errno || !*s || *end) fail();
+  return n;
+}
+static void limit(int resource, unsigned long value) {
+  struct rlimit r = { value, value }; check(setrlimit(resource, &r));
+}
+static void target(char *out, size_t size, const char *root, const char *name) {
+  if (snprintf(out, size, "%s%s", root, name) >= (int)size) fail();
+}
+static void filter(void) {
+#if defined(__x86_64__)
+#define ARCH AUDIT_ARCH_X86_64
+#elif defined(__aarch64__)
+#define ARCH AUDIT_ARCH_AARCH64
+#else
+#error Unsupported seccomp architecture
+#endif
+#define DENY(n) BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, __NR_##n, 0, 1), BPF_STMT(BPF_RET|BPF_K, SECCOMP_RET_ERRNO|EPERM)
+  struct sock_filter rules[] = {
+    BPF_STMT(BPF_LD|BPF_W|BPF_ABS, offsetof(struct seccomp_data, arch)),
+    BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, ARCH, 1, 0),
+    BPF_STMT(BPF_RET|BPF_K, SECCOMP_RET_KILL_PROCESS),
+    BPF_STMT(BPF_LD|BPF_W|BPF_ABS, offsetof(struct seccomp_data, nr)),
+    /* Reject the x32 ABI as well as unknown syscall-number namespaces. */
+    BPF_JUMP(BPF_JMP|BPF_JGE|BPF_K, 0x40000000, 0, 1),
+    BPF_STMT(BPF_RET|BPF_K, SECCOMP_RET_KILL_PROCESS),
+    DENY(socket), DENY(socketpair), DENY(connect), DENY(bind), DENY(listen),
+    DENY(accept), DENY(accept4), DENY(sendto), DENY(sendmsg), DENY(sendmmsg),
+    DENY(mount), DENY(umount2), DENY(pivot_root), DENY(chroot), DENY(unshare), DENY(setns),
+    DENY(ptrace), DENY(process_vm_readv), DENY(process_vm_writev),
+    DENY(bpf), DENY(perf_event_open), DENY(keyctl), DENY(add_key), DENY(request_key),
+    DENY(reboot), DENY(kexec_load), DENY(init_module), DENY(finit_module), DENY(delete_module),
+    DENY(open_by_handle_at), DENY(name_to_handle_at), DENY(userfaultfd),
+    DENY(io_uring_setup), DENY(io_uring_enter), DENY(io_uring_register),
+    /* FFmpeg needs threads, never new namespaces. clone3 falls back to clone. */
+    BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, __NR_clone3, 0, 1),
+    BPF_STMT(BPF_RET|BPF_K, SECCOMP_RET_ERRNO|ENOSYS),
+    BPF_JUMP(BPF_JMP|BPF_JEQ|BPF_K, __NR_clone, 0, 3),
+    BPF_STMT(BPF_LD|BPF_W|BPF_ABS, offsetof(struct seccomp_data, args[0])),
+    BPF_JUMP(BPF_JMP|BPF_JSET|BPF_K, 0x7e020000, 0, 1),
+    BPF_STMT(BPF_RET|BPF_K, SECCOMP_RET_ERRNO|EPERM),
+    BPF_STMT(BPF_RET|BPF_K, SECCOMP_RET_ALLOW)
+  };
+  struct sock_fprog p = { sizeof(rules)/sizeof(rules[0]), rules };
+  check(prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0));
+  check(prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, &p));
+}
+int main(int argc, char **argv) {
+  if (argc == 2 && !strcmp(argv[1], "--seccomp-check")) {
+    filter();
+    if (socket(AF_INET, SOCK_STREAM, 0) != -1 || errno != EPERM) fail();
+    if (syscall(SYS_unshare, 0) != -1 || errno != EPERM) fail();
+    if (syscall(SYS_clone3, NULL, 0) != -1 || errno != ENOSYS) fail();
+    if (prctl(PR_GET_NO_NEW_PRIVS, 0, 0, 0, 0) != 1 || getpid() <= 0) fail();
+    return 0;
+  }
+  /* Join before unshare forks: every descendant inherits the bounded cgroup. */
+  if (argc > 4 && !strcmp(argv[1], "--join")) {
+    int fd = open(argv[2], O_WRONLY|O_CLOEXEC|O_NOFOLLOW); check(fd);
+    char pid[32]; int n = snprintf(pid, sizeof(pid), "%ld", (long)getpid());
+    if (write(fd, pid, n) != n) fail();
+    check(close(fd)); execv(argv[3], &argv[3]); fail();
+  }
+  /* root staging, trusted rootfs, upload staging, scratch, uid, size, CPU seconds, executable, argv */
+  if (argc < 10 || strcmp(argv[1], "--confine")) fail();
+  const char *root = argv[2]; unsigned long uid = number(argv[6]);
+  if (uid < 1000 || uid > 60000) fail();
+  check(mount(NULL, "/", NULL, MS_REC|MS_PRIVATE, NULL));
+  check(mount(argv[3], root, NULL, MS_BIND|MS_REC, NULL));
+  check(mount(NULL, root, NULL, MS_BIND|MS_REMOUNT|MS_RDONLY|MS_NOSUID|MS_NODEV, NULL));
+  char path[4096];
+  target(path, sizeof(path), root, "/upload");
+  check(mount(argv[4], path, NULL, MS_BIND, NULL));
+  check(mount(NULL, path, NULL, MS_BIND|MS_REMOUNT|MS_RDONLY|MS_NOSUID|MS_NODEV|MS_NOEXEC, NULL));
+  target(path, sizeof(path), root, "/scratch");
+  check(mount(argv[5], path, NULL, MS_BIND, NULL));
+  check(mount(NULL, path, NULL, MS_BIND|MS_REMOUNT|MS_NOSUID|MS_NODEV|MS_NOEXEC, NULL));
+  target(path, sizeof(path), root, "/tmp");
+  check(mount("tmpfs", path, "tmpfs", MS_NOSUID|MS_NODEV|MS_NOEXEC, "size=16m,mode=1777"));
+  target(path, sizeof(path), root, "/proc");
+  check(mount("proc", path, "proc", MS_NOSUID|MS_NODEV|MS_NOEXEC|MS_RDONLY, NULL));
+  target(path, sizeof(path), root, "/dev/null");
+  check(mount("/dev/null", path, NULL, MS_BIND, NULL));
+  check(mount(NULL, path, NULL, MS_BIND|MS_REMOUNT|MS_NOSUID|MS_NOEXEC, NULL));
+  check(chdir(root)); check(chroot(".")); check(chdir("/scratch"));
+  limit(RLIMIT_CORE, 0); limit(RLIMIT_FSIZE, number(argv[7])); limit(RLIMIT_CPU, number(argv[8]));
+  limit(RLIMIT_NOFILE, 1024);
+  /* Subordinate GID mapping keeps setgroups allowed; remove all inherited groups. */
+  int groups = getgroups(0, NULL); check(groups);
+  if (groups > 0) check(setgroups(0, NULL));
+  for (int c = 0; c <= CAP_LAST_CAP; c++) check(prctl(PR_CAPBSET_DROP, c, 0, 0, 0));
+  check(setresgid(uid, uid, uid)); check(setresuid(uid, uid, uid));
+  struct __user_cap_header_struct h = { _LINUX_CAPABILITY_VERSION_3, 0 };
+  struct __user_cap_data_struct d[2] = {{0}, {0}};
+  check(syscall(SYS_capset, &h, d)); check(prctl(PR_SET_DUMPABLE, 0));
+  filter();
+  if (!strcmp(argv[9], "--check")) return 0;
+  execv(argv[9], &argv[9]); fail();
+}
diff --git a/packages/media-sandbox/native/test-child.c b/packages/media-sandbox/native/test-child.c
new file mode 100644
index 0000000..9c616a4
--- /dev/null
+++ b/packages/media-sandbox/native/test-child.c
@@ -0,0 +1,77 @@
+/* Adversarial test payload, compiled statically into the disposable test rootfs. */
+#define _GNU_SOURCE
+#include <arpa/inet.h>
+#include <errno.h>
+#include <fcntl.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/prctl.h>
+#include <sys/socket.h>
+#include <sys/stat.h>
+#include <sys/wait.h>
+#include <unistd.h>
+extern char **environ;
+static void copy(const char *path) {
+  FILE *f = fopen(path, "r"); if (!f) exit(9);
+  int c; while ((c = fgetc(f)) != EOF) putchar(c ? c : '\n'); fclose(f);
+}
+int main(int argc, char **argv) {
+  const char *input = NULL;
+  for (int i = 1; i + 1 < argc; i++) if (!strcmp(argv[i], "-i")) input = argv[i + 1];
+  if (!input || strncmp(input, "file:", 5)) {
+    /* Pipe-only supervisor canary: stay alive to inspect /proc, then force a failure. */
+    fputs("forced authentication/connection failure\n", stderr); fflush(stderr); sleep(2); return 7;
+  }
+  FILE *f = fopen(input + 5, "r"); if (!f) return 8;
+  char action[64], path[4096] = {0};
+  if (!fgets(action, sizeof(action), f)) return 8;
+  action[strcspn(action, "\n")] = 0;
+  if (fgets(path, sizeof(path), f)) path[strcspn(path, "\n")] = 0;
+  fclose(f);
+  if (!strcmp(action, "isolation")) {
+    if (!getuid() || prctl(PR_GET_NO_NEW_PRIVS, 0, 0, 0, 0) != 1) return 10;
+    if (!access(path, R_OK) || !access("/etc/passwd", R_OK) || !access("/var/run/docker.sock", R_OK)) return 11;
+    int fd = open("/root-write", O_WRONLY|O_CREAT, 0600); if (fd >= 0) return 12;
+    fd = open("/scratch/result", O_WRONLY|O_CREAT, 0600); if (fd < 0) return 13; close(fd);
+    if (!access("/upload/unmounted", R_OK)) return 14;
+    printf("isolated uid=%u\n", getuid()); return 0;
+  }
+  if (!strcmp(action, "network")) {
+    for (int n = 0; n < 3; n++) {
+      int fd = socket(AF_INET, SOCK_STREAM, 0);
+      if (fd >= 0) {
+        const char *ips[] = {"127.0.0.1", "10.0.0.1", "169.254.169.254"};
+        struct sockaddr_in addr = { .sin_family = AF_INET, .sin_port = htons(80) };
+        inet_pton(AF_INET, ips[n], &addr.sin_addr);
+        if (!connect(fd, (struct sockaddr *)&addr, sizeof(addr))) return 15;
+        close(fd);
+      } else if (errno != EPERM) return 16;
+    }
+    puts("network denied"); return 0;
+  }
+  if (!strcmp(action, "memory")) {
+    puts("ready"); fflush(stdout);
+    for (;;) { char *p = malloc(1024*1024); if (!p) return 17; memset(p, 1, 1024*1024); asm volatile("" : : "r"(p) : "memory"); }
+  }
+  if (!strcmp(action, "pids")) {
+    int count = 0; pid_t child;
+    while ((child = fork()) >= 0) { if (!child) { sleep(10); return 0; } if (++count > 100) return 18; }
+    puts("pids denied"); fflush(stdout);
+    int ok = errno == EAGAIN; return ok ? 0 : 19;
+  }
+  if (!strcmp(action, "sleep")) { puts("ready"); fflush(stdout); sleep(20); return 0; }
+  if (!strcmp(action, "size")) {
+    f = fopen("/scratch/large", "w"); if (!f) return 20;
+    for (;;) { char b[4096] = {0}; if (fwrite(b, 1, sizeof(b), f) != sizeof(b)) return 21; fflush(f); }
+  }
+  if (!strcmp(action, "metadata")) {
+    copy("/proc/self/cmdline"); copy("/proc/self/environ");
+    /* Host canaries must not be visible to the child. */
+    for (char **e = environ; *e; e++) if (strstr(*e, "CANARY")) return 22;
+    fputs("forced authentication/connection failure\n", stderr); sleep(2); return 7;
+  }
+  if (!strcmp(action, "probe-good")) { puts("{\"format\":{\"format_name\":\"wav\",\"duration\":\"1.0\",\"size\":\"10\"},\"streams\":[{\"index\":0,\"codec_type\":\"audio\",\"codec_name\":\"pcm_s16le\",\"sample_rate\":\"48000\",\"channels\":2}]}"); return 0; }
+  if (!strcmp(action, "probe-big")) { for (int i = 0; i < 500000; i++) putchar('x'); return 0; }
+  puts("{\"format\":{},\"streams\":[],\"unexpected\":\"untrusted metadata\"}"); return 0;
+}
diff --git a/packages/media-sandbox/node_modules b/packages/media-sandbox/node_modules
new file mode 120000
index 0000000..0c0127b
--- /dev/null
+++ b/packages/media-sandbox/node_modules
@@ -0,0 +1 @@
+../egress/node_modules
\ No newline at end of file
diff --git a/packages/media-sandbox/package.json b/packages/media-sandbox/package.json
new file mode 100644
index 0000000..d7595ed
--- /dev/null
+++ b/packages/media-sandbox/package.json
@@ -0,0 +1,15 @@
+{
+  "name": "@tactical-media-broadcast-hub/media-sandbox",
+  "private": true,
+  "version": "0.1.0",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": "./dist/index.js" },
+  "scripts": {
+    "build": "sh scripts/build-helper.sh && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "sh scripts/build-helper.sh && vitest run"
+  },
+  "devDependencies": { "@types/node": "^22.20.5", "typescript": "^5.5.4", "vitest": "^2.0.5" }
+}
diff --git a/packages/media-sandbox/scripts/build-helper.sh b/packages/media-sandbox/scripts/build-helper.sh
new file mode 100644
index 0000000..deaed66
--- /dev/null
+++ b/packages/media-sandbox/scripts/build-helper.sh
@@ -0,0 +1,5 @@
+#!/bin/sh
+set -eu
+cd "$(dirname "$0")/.."
+mkdir -p dist
+${CC:-cc} -std=c11 -O2 -Wall -Wextra -Werror -fstack-protector-strong -D_FORTIFY_SOURCE=2 -Wl,-z,relro,-z,now native/confine.c -o dist/media-confine
diff --git a/packages/media-sandbox/src/command.test.ts b/packages/media-sandbox/src/command.test.ts
new file mode 100644
index 0000000..609352a
--- /dev/null
+++ b/packages/media-sandbox/src/command.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { assertMediaCommand, MediaCommandBuilder, type Demuxer } from "./command";
+import { DEFAULT_LIMITS, limitsWith, sandboxEnabled, sandboxEnvironment } from "./profile";
+import { validateProbe } from "./probe";
+const id = "b".repeat(64); const builder = new MediaCommandBuilder();
+describe("argv-only media commands", () => {
+  it("uses minted ids and fixed sandbox paths for probe and transcode", () => {
+    const probe = builder.probe(id, "mov");
+    expect(probe.argv).toContain(`file:/upload/${id}`);
+    expect(probe.argv.slice(probe.argv.indexOf("-protocol_whitelist"), probe.argv.indexOf("-protocol_whitelist") + 4)).toEqual(["-protocol_whitelist", "file", "-f", "mov"]);
+    expect(builder.transcode(id, "mov", id, { width: 1280, height: 720 }).argv.at(-1)).toBe(`file:/scratch/${id}.mp4`);
+    expect(Object.isFrozen(probe.argv)).toBe(true);
+    expect(() => assertMediaCommand({ binary: "ffmpeg", argv: [] })).toThrow(/builder/i);
+  });
+  it.each(["filename.mp4", "../escape", "file:/etc/passwd", "concat:a|b", "https://example.com", "rtmp://example.com/key", "a;id", "a\u0000b"])("rejects paths/protocols as asset id: %s", value => {
+    expect(() => builder.probe(value, "mov")).toThrow(/asset/);
+  });
+  it.each(["concat", "hls", "dash", "lavfi", "sdp", "http", "file"])("rejects non-allowlisted demuxer %s", format => {
+    expect(() => builder.probe(id, format as Demuxer)).toThrow(/demuxer/);
+  });
+  it.each([0, 1, 3, 4098, NaN, Infinity])("rejects dimensions %s", width => {
+    expect(() => builder.transcode(id, "mov", id, { width, height: 720 })).toThrow();
+  });
+  it("confines existing supervisor pipes and forces a demuxer on legacy remuxes", () => {
+    expect(builder.supervisor("ffmpeg", ["-i", "pipe:0", "-c", "copy", "-f", "mpegts", "pipe:1"], "/job").argv).toEqual(["-f", "mpegts", "-protocol_whitelist", "pipe", "-i", "pipe:0", "-c", "copy", "-f", "mpegts", "pipe:1"]);
+  });
+  it.each(["file:/etc/passwd", "concat:a|b", "https://example.org", "tcp://127.0.0.1:80"])("rejects a remote manifest endpoint %s", input => {
+    expect(() => builder.supervisor("ffmpeg", ["-f", "mpegts", "-i", input], "/job")).toThrow();
+  });
+  it("rejects IO filters and arbitrary options; permits minted overlay ids", () => {
+    expect(() => builder.supervisor("ffmpeg", ["-vf", "movie=/etc/passwd"], "/job")).toThrow();
+    expect(() => builder.supervisor("ffmpeg", ["-report"], "/job")).toThrow();
+    expect(builder.supervisor("ffmpeg", ["-i", `file:/job/${id}.png`, "-f", "null", "-"], "/job").argv).toContain("png_pipe");
+    expect(() => builder.supervisor("ffmpeg", ["-i", "file:/job/user-name.png"], "/job")).toThrow();
+  });
+});
+it("local defaults off, production defaults on and cannot opt out", () => {
+  expect(sandboxEnabled({})).toBe(false);
+  expect(sandboxEnabled({ MEDIA_SANDBOX: "on" })).toBe(true);
+  expect(sandboxEnabled({ NODE_ENV: "production" })).toBe(true);
+  expect(() => sandboxEnabled({ NODE_ENV: "production", MEDIA_SANDBOX: "off" })).toThrow(/requires/);
+  expect(() => sandboxEnabled({ MEDIA_SANDBOX: "maybe" })).toThrow();
+  expect(sandboxEnvironment()).toEqual({ PATH: "/usr/bin:/bin", LANG: "C", HOME: "/tmp" });
+});
+it("validates every CPU/memory/pids/time/size limit", () => {
+  for (const key of Object.keys(DEFAULT_LIMITS)) expect(() => limitsWith({ [key]: 0 })).toThrow();
+  expect(() => limitsWith({ cpuPeriodUs: 1 })).toThrow();
+});
+it("validates bounded probe schema without untrusted tags or arbitrary strings", () => {
+  expect(validateProbe({ format: { format_name: "mov,mp4", duration: "1.3" }, streams: [{ index: 0, codec_type: "video", width: 1920, height: 1080 }] }).streams).toHaveLength(1);
+  for (const invalid of [null, {}, { format: {}, streams: [], tags: {} }, { format: { format_name: "secret-token" }, streams: [] },
+    { format: {}, streams: [{ index: 0, codec_type: "video", width: -1 }] }, { format: {}, streams: Array(65).fill({ index: 0, codec_type: "audio" }) },
+    { format: {}, streams: [{ index: 0, codec_type: "audio" }, { index: 0, codec_type: "audio" }] }]) {
+    expect(() => validateProbe(invalid)).toThrow(/invalid probe/);
+  }
+});
diff --git a/packages/media-sandbox/src/command.ts b/packages/media-sandbox/src/command.ts
new file mode 100644
index 0000000..e5c01e4
--- /dev/null
+++ b/packages/media-sandbox/src/command.ts
@@ -0,0 +1,110 @@
+export const DEMUXERS = ["mov", "matroska", "mpegts", "wav", "mp3", "ogg", "flac", "image2", "png_pipe", "jpeg_pipe", "rawvideo", "s16le"] as const;
+export type Demuxer = typeof DEMUXERS[number];
+export interface MediaCommand { readonly binary: "ffmpeg" | "ffprobe"; readonly argv: readonly string[] }
+const issued = new WeakSet<object>();
+function command(binary: MediaCommand["binary"], argv: string[]): MediaCommand {
+  const result = Object.freeze({ binary, argv: Object.freeze(argv) }); issued.add(result); return result;
+}
+export function assertMediaCommand(value: MediaCommand): void {
+  if (!issued.has(value)) throw new Error("MediaCommandBuilder command required");
+}
+export function assertAssetId(id: string): void {
+  if (!/^(?:[0-9a-f]{64}|[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})$/.test(id)) throw new Error("invalid server asset id");
+}
+function demuxer(value: string): void {
+  if (!(DEMUXERS as readonly string[]).includes(value)) throw new Error("demuxer denied");
+}
+export function assetPath(id: string): string { assertAssetId(id); return `file:/upload/${id}`; }
+
+
+const FILTERS = new Set(["scale", "pad", "setsar", "crop", "color", "split", "null", "overlay", "xstack", "format", "anullsrc", "aformat", "volume", "amix", "asplit", "noise", "fps", "aresample", "asetpts", "setpts"]);
+function validateFilters(text: string): void {
+  if (text.length > 65536 || /(?:movie|amovie|subtitles|drawtext|zmq|azmq)\s*=|https?:|file:|concat:/i.test(text)) throw new Error("filter IO denied");
+  let quote = false, escaped = false, start = 0;
+  const validate = (part: string): void => {
+    const name = /^(?:\[[a-zA-Z0-9_:]+\])*([a-z][a-z0-9_]*)(?:=|\[|$)/.exec(part)?.[1];
+    if (!name || !FILTERS.has(name)) throw new Error("filter IO denied");
+  };
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    if (escaped) { escaped = false; continue; }
+    if (c === "\\") { escaped = true; continue; }
+    if (c === "'") quote = !quote;
+    if (!quote && (c === "," || c === ";")) { validate(text.slice(start, i)); start = i + 1; }
+  }
+  if (quote || escaped) throw new Error("filter IO denied");
+  validate(text.slice(start));
+}
+
+/** No original filename, arbitrary URL, shell string or extra-arguments escape hatch. */
+export class MediaCommandBuilder {
+  probe(assetId: string, format: Demuxer): MediaCommand {
+    demuxer(format);
+    return command("ffprobe", ["-hide_banner", "-v", "error", "-protocol_whitelist", "file", "-f", format,
+      "-show_entries", "format=duration,size,format_name:stream=index,codec_type,codec_name,width,height,sample_rate,channels",
+      "-of", "json", "-i", assetPath(assetId)]);
+  }
+  transcode(assetId: string, format: Demuxer, outputId: string, dimensions: { width: number; height: number }): MediaCommand {
+    demuxer(format); assertAssetId(outputId);
+    for (const v of [dimensions.width, dimensions.height]) {
+      if (!Number.isSafeInteger(v) || v < 2 || v > 4096 || v % 2) throw new Error("invalid dimensions");
+    }
+    return command("ffmpeg", ["-hide_banner", "-nostdin", "-loglevel", "error", "-threads", "2", "-filter_threads", "1",
+      "-protocol_whitelist", "file", "-f", format, "-i", assetPath(assetId), "-vf", `scale=${dimensions.width}:${dimensions.height}`,
+      "-c:v", "libx264", "-preset", "veryfast", "-c:a", "aac", "-f", "mp4", "-y", `file:/scratch/${outputId}.mp4`]);
+  }
+
+  /** Adapter ONLY for argv from the worker's existing typed graph builders. */
+  supervisor(binary: MediaCommand["binary"], args: readonly string[], scratch: string): MediaCommand {
+    if (binary !== "ffmpeg") throw new Error("use the typed probe wrapper");
+    const flags = new Set(["-hide_banner", "-nostdin", "-re", "-y", "-an", "-vn", "-shortest"]);
+    const values = new Set(["-loglevel", "-threads", "-threads:v", "-filter_threads", "-filter_complex_threads", "-thread_queue_size", "-probesize", "-analyzeduration",
+      "-f", "-pix_fmt", "-s", "-framerate", "-ar", "-ac", "-fflags", "-i", "-vf", "-af", "-filter_complex", "-map", "-t", "-c", "-c:v", "-c:a",
+      "-preset", "-tune", "-profile:v", "-level:v", "-b:v", "-b:a", "-maxrate", "-bufsize", "-g", "-keyint_min", "-sc_threshold",
+      "-fps_mode", "-flush_packets", "-flags:v", "-flags:a", "-frames:v", "-q:v", "-progress", "-output_ts_offset", "-muxdelay", "-muxpreload",
+      "-loop", "-mpegts_flags", "-hls_time", "-hls_list_size", "-hls_segment_type", "-hls_fmp4_init_filename", "-hls_flags", "-hls_segment_filename", "-protocol_whitelist"]);
+    const argv: string[] = []; let format: string | undefined;
+    const mapPath = (value: string): string => {
+      const raw = value.startsWith("file:") ? value.slice(5) : value;
+      if (!raw.startsWith(`${scratch}/`) || raw.split("/").includes("..")) throw new Error("media path denied");
+      const suffix = raw.slice(scratch.length);
+      if (!/^\/[A-Za-z0-9_./%\-]+$/.test(suffix)) throw new Error("media path denied");
+      return `file:/scratch${suffix}`;
+    };
+    for (let i = 0; i < args.length; i++) {
+      const key = args[i]!;
+      if (flags.has(key)) { argv.push(key); continue; }
+      if (!key.startsWith("-") || key === "-") {
+        if (key === "-" && format === "null") argv.push("pipe:1");
+        else if (format === "tee" && /^\[f=(?:rawvideo|s16le):onfail=ignore\]pipe:\d{1,3}\|\[f=null\]-$/.test(key)) argv.push(key);
+        else argv.push(/^pipe:\d{1,3}$/.test(key) ? key : mapPath(key));
+        format = undefined; continue;
+      }
+      if (!values.has(key)) throw new Error("media option denied");
+      let value = args[++i];
+      if (value === undefined || /[\u0000-\u001f\u007f]/.test(value)) throw new Error("media option denied");
+      if (key === "-protocol_whitelist") continue; // Replaced per input below.
+      if (key === "-f") format = value;
+      if (["-vf", "-af", "-filter_complex"].includes(key)) validateFilters(value);
+      if (key === "-i") {
+        if (/^pipe:\d{1,3}$/.test(value)) {
+          if (!format) { format = "mpegts"; argv.push("-f", format); } demuxer(format);
+          argv.push("-protocol_whitelist", "pipe");
+        } else if (format === "lavfi") {
+          if (!/^(?:testsrc2|smptehdbars|mandelbrot|rgbtestsrc|sine|color|anullsrc)=/.test(value) || /[\/;]|(?:movie|http|file|concat):/i.test(value)) throw new Error("synthetic input denied");
+          argv.push("-protocol_whitelist", "file");
+        } else {
+          const path = mapPath(value);
+          if (!/\/[0-9a-f]{64}\.png$/.test(path)) throw new Error("asset input denied");
+          argv.push("-protocol_whitelist", "file", "-f", "png_pipe"); value = path;
+        }
+        format = undefined;
+      } else if (key === "-hls_segment_filename") { argv.push(key, mapPath(value)); continue; }
+      else if (key === "-progress" && !/^pipe:\d{1,3}$/.test(value)) throw new Error("progress endpoint denied");
+      else if (key === "-hls_fmp4_init_filename" && value !== "init.mp4") throw new Error("init filename denied");
+      else if (!["-i", "-vf", "-af", "-filter_complex", "-framerate"].includes(key) && /(?:https?|rtmp|srt|tcp|udp|file|concat):|\//i.test(value)) throw new Error("media protocol denied");
+      argv.push(key, value);
+    }
+    return command(binary, argv);
+  }
+}
diff --git a/packages/media-sandbox/src/index.ts b/packages/media-sandbox/src/index.ts
new file mode 100644
index 0000000..e02bdce
--- /dev/null
+++ b/packages/media-sandbox/src/index.ts
@@ -0,0 +1,4 @@
+export * from "./command";
+export * from "./profile";
+export * from "./runtime";
+export * from "./probe";
diff --git a/packages/media-sandbox/src/probe.ts b/packages/media-sandbox/src/probe.ts
new file mode 100644
index 0000000..aae9605
--- /dev/null
+++ b/packages/media-sandbox/src/probe.ts
@@ -0,0 +1,58 @@
+import { MediaCommandBuilder, type Demuxer } from "./command";
+import { spawnSandbox, type SandboxChild, type SandboxOptions } from "./runtime";
+export interface ProbeResult {
+  format: { format_name?: string; duration?: string; size?: string };
+  streams: Array<{ index: number; codec_type: "video" | "audio" | "subtitle" | "data" | "attachment"; codec_name?: string; width?: number; height?: number; sample_rate?: string; channels?: number }>;
+}
+const fail = (): never => { throw new Error("invalid probe output"); };
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) fail();
+  return value as Record<string, unknown>;
+}
+function keys(value: Record<string, unknown>, allowed: string[]): void {
+  if (Object.keys(value).some(key => !allowed.includes(key))) fail();
+}
+export function validateProbe(value: unknown): ProbeResult {
+  const root = record(value); keys(root, ["format", "streams"]);
+  const format = record(root.format); keys(format, ["format_name", "duration", "size"]);
+  for (const [k, v] of Object.entries(format)) {
+    if (typeof v !== "string" || v.length > 128 || !(k === "format_name" ? /^[a-z0-9_,]+$/ : /^\d+(?:\.\d+)?$/).test(v)) fail();
+    if (k !== "format_name" && !Number.isFinite(Number(v))) fail();
+  }
+  if (!Array.isArray(root.streams) || root.streams.length > 64) fail();
+  const indices = new Set<number>();
+  for (const raw of root.streams as unknown[]) {
+    const stream = record(raw); keys(stream, ["index", "codec_type", "codec_name", "width", "height", "sample_rate", "channels"]);
+    if (!Number.isSafeInteger(stream.index) || Number(stream.index) < 0 || indices.has(Number(stream.index))) fail();
+    indices.add(Number(stream.index));
+    if (!["video", "audio", "subtitle", "data", "attachment"].includes(String(stream.codec_type))) fail();
+    for (const k of ["width", "height", "channels"]) {
+      if (stream[k] !== undefined && (!Number.isSafeInteger(stream[k]) || Number(stream[k]) <= 0 || Number(stream[k]) > (k === "channels" ? 64 : 16384))) fail();
+    }
+    if (stream.codec_name !== undefined && (typeof stream.codec_name !== "string" || !/^[a-z0-9_]{1,128}$/.test(stream.codec_name))) fail();
+    if (stream.sample_rate !== undefined && (typeof stream.sample_rate !== "string" || !/^\d{1,7}$/.test(stream.sample_rate) || Number(stream.sample_rate) > 768000)) fail();
+  }
+  return value as ProbeResult;
+}
+/** Exported collector allows testing hostile/oversized output using a real child. */
+export async function collectProbe(job: SandboxChild, maxBytes = 256 * 1024, onLog: (line: string) => void = () => undefined): Promise<ProbeResult> {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 1024 * 1024) { job.kill(); throw new Error("invalid probe output cap"); }
+  let size = 0; let oversized = false; const chunks: Buffer[] = [];
+  job.child.stdout?.on("data", (chunk: Buffer) => {
+    size += chunk.length;
+    if (size > maxBytes) { oversized = true; job.kill(); return; }
+    chunks.push(chunk);
+  });
+  job.child.stderr?.on("data", () => onLog("media probe stderr suppressed"));
+  let spawnFailed = false; job.child.once("error", () => { spawnFailed = true; });
+  const result = await job.exited;
+  if (oversized) throw new Error("probe output limit exceeded");
+  if (spawnFailed || result.code !== 0) throw new Error("media probe failed");
+  let parsed: unknown;
+  try { parsed = JSON.parse(Buffer.concat(chunks).toString("utf8")); } catch { return fail(); }
+  return validateProbe(parsed);
+}
+export function probe(assetId: string, format: Demuxer, options: SandboxOptions, onLog?: (line: string) => void): Promise<ProbeResult> {
+  if (!options.asset || options.asset.id !== assetId) throw new Error("probe asset mapping required");
+  return collectProbe(spawnSandbox(new MediaCommandBuilder().probe(assetId, format), options, { stdio: ["ignore", "pipe", "pipe"] }), undefined, onLog);
+}
diff --git a/packages/media-sandbox/src/profile.ts b/packages/media-sandbox/src/profile.ts
new file mode 100644
index 0000000..9656f8c
--- /dev/null
+++ b/packages/media-sandbox/src/profile.ts
@@ -0,0 +1,25 @@
+export interface SandboxLimits {
+  cpuQuotaUs: number;
+  cpuPeriodUs: number;
+  memoryBytes: number;
+  pids: number;
+  wallTimeMs: number;
+  fileSizeBytes: number;
+}
+export const DEFAULT_LIMITS: Readonly<SandboxLimits> = Object.freeze({
+  cpuQuotaUs: 200_000, cpuPeriodUs: 100_000, memoryBytes: 512 * 1024 * 1024,
+  pids: 64, wallTimeMs: 120_000, fileSizeBytes: 1024 * 1024 * 1024,
+});
+export function limitsWith(overrides: Partial<SandboxLimits> = {}): SandboxLimits {
+  const result = { ...DEFAULT_LIMITS, ...overrides };
+  for (const v of Object.values(result)) if (!Number.isSafeInteger(v) || v <= 0) throw new Error("invalid sandbox limit");
+  if (result.cpuPeriodUs < 1000 || result.cpuPeriodUs > 1_000_000 || result.pids < 4) throw new Error("invalid sandbox limit");
+  return result;
+}
+export function sandboxEnabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  if (env.MEDIA_SANDBOX !== undefined && env.MEDIA_SANDBOX !== "on" && env.MEDIA_SANDBOX !== "off") throw new Error("MEDIA_SANDBOX must be on or off");
+  if (env.NODE_ENV === "production" && env.MEDIA_SANDBOX === "off") throw new Error("production requires media sandbox");
+  return env.MEDIA_SANDBOX === "on" || env.NODE_ENV === "production";
+}
+/** PATH is fixed; no inherited keys, tokens, proxy settings, loader options or config. */
+export function sandboxEnvironment(): NodeJS.ProcessEnv { return { PATH: "/usr/bin:/bin", LANG: "C", HOME: "/tmp" }; }
diff --git a/packages/media-sandbox/src/runtime.test.ts b/packages/media-sandbox/src/runtime.test.ts
new file mode 100644
index 0000000..ea02d15
--- /dev/null
+++ b/packages/media-sandbox/src/runtime.test.ts
@@ -0,0 +1,103 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterAll, describe, expect, it } from "vitest";
+import { MediaCommandBuilder } from "./command";
+import { collectProbe } from "./probe";
+import { sandboxEnvironment } from "./profile";
+import { helperPath, sandboxCapability, spawnSandbox, type SandboxChild, type SandboxOptions } from "./runtime";
+const work = mkdtempSync(join(tmpdir(), "media-security-tests-"));
+const rootfs = join(work, "rootfs");
+for (const dir of ["upload", "scratch", "tmp", "proc", "dev", "usr/bin"]) mkdirSync(join(rootfs, dir), { recursive: true });
+writeFileSync(join(rootfs, "dev/null"), "");
+const built = spawnSync("cc", ["-static", "-O0", "-Wall", "-Wextra", "-Werror", resolve(__dirname, "../native/test-child.c"), "-o", join(rootfs, "usr/bin/ffprobe")]);
+if (built.status === 0) spawnSync("cp", [join(rootfs, "usr/bin/ffprobe"), join(rootfs, "usr/bin/ffmpeg")]);
+const options = { rootfs, cgroupRoot: process.env.MEDIA_SANDBOX_CGROUP_ROOT ?? "/sys/fs/cgroup" };
+const capability = built.status === 0 ? sandboxCapability(options) : { available: false, reason: "static C test fixture compiler unavailable" };
+if (!capability.available) console.warn(`SKIP sandbox integration and sandbox canaries: ${capability.reason}`);
+afterAll(() => rmSync(work, { recursive: true, force: true }));
+const builder = new MediaCommandBuilder(); let sequence = 0;
+function job(action: string, limits?: SandboxOptions["limits"]): SandboxChild {
+  const id = (++sequence).toString(16).padStart(64, "0"); const file = join(work, id);
+  writeFileSync(file, action);
+  return spawnSandbox(builder.probe(id, "wav"), { ...options, limits, asset: { id, resolve: () => file } }, { stdio: ["ignore", "pipe", "pipe"] });
+}
+async function output(child: SandboxChild): Promise<{ code: number | null; signal: NodeJS.Signals | null; stdout: string; stderr: string }> {
+  let stdout = "", stderr = "";
+  child.child.stdout?.on("data", chunk => { stdout += String(chunk); });
+  child.child.stderr?.on("data", chunk => { stderr += String(chunk); });
+  return { ...await child.exited, stdout, stderr };
+}
+function ready(child: SandboxChild): Promise<void> {
+  return new Promise((done, reject) => { child.child.stdout!.once("data", () => done()); child.child.once("exit", () => reject(new Error("sandbox failed before ready"))); });
+}
+
+describe.skipIf(!capability.available)("rootless sandbox confinement", () => {
+  it("cannot read host/vault/DB/other-job files; root is read-only and scratch works; UIDs differ", async () => {
+    const secret = join(work, "vault-db-sibling-secret"); writeFileSync(secret, "private");
+    const first = await output(job(`isolation\n${secret}\n`));
+    const second = await output(job(`isolation\n${secret}\n`));
+    expect(first.code, first.stderr).toBe(0); expect(second.code, second.stderr).toBe(0);
+    expect(first.stdout).toContain("isolated uid="); expect(first.stdout).not.toEqual(second.stdout);
+  });
+  it("blocks socket creation, DNS, loopback, internal CIDRs and metadata", async () => {
+    const result = await output(job("network\n")); expect(result.code, result.stderr).toBe(0); expect(result.stdout).toContain("network denied");
+  });
+  it("kills memory/time offenders without affecting a sibling", async () => {
+    const sibling = job("sleep\n", { wallTimeMs: 30_000 });
+    try {
+      await ready(sibling);
+      const memory = await output(job("memory\n", { memoryBytes: 16 * 1024 * 1024, wallTimeMs: 5000 }));
+      expect(memory.stdout).toContain("ready"); expect(memory.signal).toBe("SIGKILL");
+      expect(sibling.child.exitCode).toBeNull(); expect(sibling.child.signalCode).toBeNull();
+      const timed = await output(job("sleep\n", { wallTimeMs: 1000 })); expect(timed.stdout).toContain("ready"); expect(timed.signal).toBe("SIGKILL");
+      expect(sibling.child.exitCode).toBeNull(); expect(sibling.child.signalCode).toBeNull();
+    } finally { sibling.kill(); await sibling.exited; }
+  }, 15_000);
+  it("enforces pids and file-size caps without affecting siblings", async () => {
+    const sibling = job("sleep\n", { wallTimeMs: 30_000 });
+    try {
+      await ready(sibling);
+      const pids = await output(job("pids\n", { pids: 12 })); expect(pids.code, pids.stderr).toBe(0); expect(pids.stdout).toContain("pids denied");
+      const size = await output(job("size\n", { fileSizeBytes: 8192 })); expect(size.code).not.toBe(0);
+      expect(sibling.child.exitCode).toBeNull(); expect(sibling.child.signalCode).toBeNull();
+    } finally { sibling.kill(); await sibling.exited; }
+  }, 15_000);
+  it("caps and validates hostile probe output", async () => {
+    expect((await collectProbe(job("probe-good\n"))).streams).toHaveLength(1);
+    await expect(collectProbe(job("probe-big\n"), 4096)).rejects.toThrow(/limit exceeded/);
+    await expect(collectProbe(job("probe-invalid\n"))).rejects.toThrow(/invalid probe/);
+  });
+  it("canary key/token/passphrase stay absent from every process cmdline/environ and captured output/log", async () => {
+    const canaries = ["stream-key-canary-95c70", "oauth-token-canary-d7921", "srt-passphrase-canary-f1f12"];
+    const names = ["CANARY_STREAM_KEY", "CANARY_OAUTH_TOKEN", "CANARY_SRT_PASSPHRASE"];
+    const before = names.map(name => process.env[name]); names.forEach((name, i) => { process.env[name] = canaries[i]; });
+    try {
+      const child = job("metadata\n");
+      const captured = output(child);
+      // The host-visible wrapper stays alive while the child inspects its final /proc metadata itself.
+      await new Promise(done => setTimeout(done, 100));
+      const metadata = [readFileSync(`/proc/${child.child.pid}/cmdline`), readFileSync(`/proc/${child.child.pid}/environ`)];
+      const result = await captured;
+      expect(result.code).toBe(7);
+      expect(result.stdout).toContain("PATH=/usr/bin:/bin");
+      expect(result.stderr).toContain("forced authentication/connection failure");
+      for (const canary of canaries) for (const text of [...metadata.map(v => v.toString()), result.stdout, result.stderr]) expect(text).not.toContain(canary);
+    } finally { names.forEach((name, i) => { if (before[i] === undefined) delete process.env[name]; else process.env[name] = before[i]; }); }
+  });
+});
+it("probe collector caps output and never logs hostile stderr, even without sandbox capability", async () => {
+  const canary = "stream-key-canary-oversized"; const logs: string[] = [];
+  const child = spawn(process.execPath, ["-e", 'process.stdin.once("data",b=>{process.stderr.write(b);process.stdout.write("x".repeat(50000))})'], { env: sandboxEnvironment(), stdio: ["pipe", "pipe", "pipe"] });
+  const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(done => child.once("close", (code, signal) => done({ code, signal })));
+  const collected = collectProbe({ child, exited, kill: () => { child.kill("SIGKILL"); } }, 4096, line => logs.push(line));
+  child.stdin!.end(canary);
+  await expect(collected).rejects.toThrow(/limit exceeded/);
+  expect(logs.length).toBeGreaterThan(0); expect(logs.join("\n")).not.toContain(canary);
+});
+
+it("installs the real seccomp profile and no-new-privileges without needing userns", () => {
+  const result = spawnSync(helperPath(), ["--seccomp-check"], { env: sandboxEnvironment(), timeout: 5000 });
+  expect(result.status, String(result.stderr)).toBe(0);
+});
diff --git a/packages/media-sandbox/src/runtime.ts b/packages/media-sandbox/src/runtime.ts
new file mode 100644
index 0000000..f2976c0
--- /dev/null
+++ b/packages/media-sandbox/src/runtime.ts
@@ -0,0 +1,172 @@
+import { spawn, spawnSync, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { constants, closeSync, fstatSync, openSync, readSync, writeSync, chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, rmdirSync, statfsSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { assertAssetId, assertMediaCommand, type MediaCommand } from "./command";
+import { limitsWith, sandboxEnvironment, type SandboxLimits } from "./profile";
+
+export interface SandboxOptions {
+  /** Dedicated, operator-built minimal FFmpeg rootfs; never the host /. */
+  rootfs: string;
+  /** Empty cgroup v2 subtree delegated to this worker with cpu/memory/pids enabled. */
+  cgroupRoot: string;
+  helperPath?: string;
+  scratchDir?: string;
+  limits?: Partial<SandboxLimits>;
+  /** Server asset resolver; called only after validating the minted id. */
+  asset?: { id: string; resolve(id: string): string };
+}
+export class SandboxUnavailable extends Error { constructor() { super("media sandbox unavailable: requires mapped unprivileged UID/userns, mount/net/pid namespaces, trusted rootfs and delegated cgroup v2"); this.name = "SandboxUnavailable"; } }
+export interface SandboxChild {
+  child: ChildProcess;
+  exited: Promise<{ code: number | null; signal: NodeJS.Signals | null }>;
+  kill(signal?: NodeJS.Signals): void;
+}
+const activeUids = new Set<number>(); let nextUid = 1000;
+const uidLeases = join(tmpdir(), `media-sandbox-uids-${process.getuid?.() ?? "unsupported"}`);
+function uid(): number {
+  try { mkdirSync(uidLeases, { mode: 0o700 }); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw new SandboxUnavailable(); }
+  const stat = lstatSync(uidLeases);
+  if (!stat.isDirectory() || stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) !== 0) throw new SandboxUnavailable();
+  for (let n = 0; n <= 59000; n++) {
+    const v = nextUid; nextUid = nextUid >= 60000 ? 1000 : nextUid + 1;
+    if (activeUids.has(v)) continue;
+    try { mkdirSync(join(uidLeases, String(v)), { mode: 0o700 }); }
+    catch (error) { if ((error as NodeJS.ErrnoException).code === "EEXIST") continue; throw new SandboxUnavailable(); }
+    activeUids.add(v); return v;
+  }
+  throw new SandboxUnavailable();
+}
+function releaseUid(value: number): void {
+  try { rmdirSync(join(uidLeases, String(value))); } catch { /* stale leases remain reserved rather than risk UID reuse */ }
+  activeUids.delete(value);
+}
+export function helperPath(): string { return resolve(__dirname, "../dist/media-confine"); }
+function checkedRootfs(path: string): string {
+  const root = realpathSync(path);
+  if (root === "/" || root === "/usr" || root === "/etc") throw new SandboxUnavailable();
+  for (const dir of ["upload", "scratch", "tmp", "proc", "dev"]) {
+    if (!lstatSync(join(root, dir)).isDirectory() || lstatSync(join(root, dir)).isSymbolicLink()) throw new SandboxUnavailable();
+  }
+  if (!lstatSync(join(root, "dev/null")).isFile()) throw new SandboxUnavailable();
+  // A recursive bind with writable nested mounts would undermine the read-only root.
+  if (readFileSync("/proc/self/mountinfo", "utf8").split("\n").some(line => {
+    const mount = line.split(" ")[4]?.replace(/\\040/g, " "); return mount?.startsWith(`${root}/`);
+  })) throw new SandboxUnavailable();
+  return root;
+}
+function createCgroup(root: string, limits: SandboxLimits): string {
+  const base = realpathSync(root);
+  if (statfsSync(base).type !== 0x63677270 || !existsSync(join(base, "cgroup.controllers"))) throw new SandboxUnavailable();
+  const path = join(base, `media-${randomUUID()}`);
+  mkdirSync(path);
+  try {
+    writeFileSync(join(path, "cpu.max"), `${limits.cpuQuotaUs} ${limits.cpuPeriodUs}`);
+    writeFileSync(join(path, "memory.max"), String(limits.memoryBytes));
+    writeFileSync(join(path, "memory.swap.max"), "0");
+    writeFileSync(join(path, "memory.oom.group"), "1");
+    writeFileSync(join(path, "pids.max"), String(limits.pids));
+    if (!existsSync(join(path, "cgroup.kill"))) throw new SandboxUnavailable();
+    return path;
+  } catch { rmdirSync(path); throw new SandboxUnavailable(); }
+}
+function confinementArgs(helper: string, group: string, root: string, rootfs: string, uploads: string, scratch: string, jobUid: number, limits: SandboxLimits, executable: string, argv: readonly string[]): string[] {
+  return ["--join", join(group, "cgroup.procs"), "/usr/bin/unshare", "--user", "--map-auto", "--map-user=0", "--setgroups=allow", "--mount", "--net", "--pid", "--fork", "--kill-child",
+    helper, "--confine", root, rootfs, uploads, scratch, String(jobUid), String(limits.fileSizeBytes), String(Math.ceil(limits.wallTimeMs / 1000)), executable, ...argv];
+}
+export function sandboxCapability(options: SandboxOptions): { available: boolean; reason?: string } {
+  let group: string | undefined; let work: string | undefined; let detail = ""; let jobUid: number | undefined;
+  try {
+    jobUid = uid();
+    const rootfs = checkedRootfs(options.rootfs); const limits = limitsWith(options.limits);
+    const helper = options.helperPath ?? helperPath();
+    if (!existsSync(helper)) throw new SandboxUnavailable();
+    work = mkdtempSync(join(tmpdir(), "media-sandbox-check-"));
+    const root = join(work, "root"), uploads = join(work, "uploads"), scratch = join(work, "scratch");
+    for (const dir of [root, uploads, scratch]) mkdirSync(dir);
+    chmodSync(scratch, 0o777);
+    group = createCgroup(options.cgroupRoot, limits);
+    const result = spawnSync(helper, confinementArgs(helper, group, root, rootfs, uploads, scratch, jobUid, limits, "--check", []), { env: sandboxEnvironment(), timeout: 5000 });
+    if (result.status !== 0) {
+      if (String(result.stderr).includes("newuidmap")) detail = " (UID mapping helper failed)";
+      throw new SandboxUnavailable();
+    }
+    return { available: true };
+  } catch { return { available: false, reason: new SandboxUnavailable().message + detail }; }
+  finally {
+    if (group) { try { writeFileSync(join(group, "cgroup.kill"), "1"); rmdirSync(group); } catch { /* timed-out setup */ } }
+    if (work) rmSync(work, { recursive: true, force: true }); if (jobUid !== undefined) releaseUid(jobUid);
+  }
+}
+
+/** Synchronous construction keeps existing spawnManaged lifecycle/stdio semantics. */
+export function spawnSandbox(command: MediaCommand, options: SandboxOptions, spawnOptions: SpawnOptions = {}, spawner: typeof spawn = spawn): SandboxChild {
+  assertMediaCommand(command);
+  const limits = limitsWith(options.limits); const jobUid = uid();
+  let work: string | undefined; let group: string | undefined;
+  try {
+    const rootfs = checkedRootfs(options.rootfs);
+    work = mkdtempSync(join(tmpdir(), "media-sandbox-")); chmodSync(work, 0o700);
+    const root = join(work, "root"); const uploads = join(work, "uploads"); const scratch = options.scratchDir ? realpathSync(options.scratchDir) : join(work, "scratch");
+    mkdirSync(root); mkdirSync(uploads, { mode: 0o755 });
+    if (!options.scratchDir) { mkdirSync(scratch); chmodSync(scratch, 0o777); }
+    else {
+      const parent = lstatSync(dirname(scratch));
+      if (scratch === "/" || !lstatSync(scratch).isDirectory() || parent.uid !== process.getuid?.() || (parent.mode & 0o077) !== 0) throw new SandboxUnavailable();
+    }
+    if (options.asset) {
+      assertAssetId(options.asset.id);
+      const source = options.asset.resolve(options.asset.id);
+      const input = openSync(source, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+      let dest: number | undefined;
+      try {
+        const stat = fstatSync(input);
+        if (!stat.isFile() || stat.size > limits.fileSizeBytes) throw new Error("upload denied");
+        const path = join(uploads, options.asset.id);
+        dest = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+        const buffer = Buffer.alloc(64 * 1024); let total = 0; let count: number;
+        while ((count = readSync(input, buffer, 0, buffer.length, null)) > 0) {
+          total += count; if (total > limits.fileSizeBytes) throw new Error("upload denied");
+          let written = 0;
+          while (written < count) written += writeSync(dest, buffer, written, count - written);
+        }
+        chmodSync(path, 0o444);
+      } finally { closeSync(input); if (dest !== undefined) closeSync(dest); }
+    }
+    group = createCgroup(options.cgroupRoot, limits);
+    const helper = options.helperPath ?? helperPath();
+    const args = confinementArgs(helper, group, root, rootfs, uploads, scratch, jobUid, limits, `/usr/bin/${command.binary}`, command.argv);
+    const child = spawner(helper, args, { ...spawnOptions, cwd: undefined, shell: false, detached: true, env: sandboxEnvironment() });
+    const groupPath = group; const workPath = work;
+    const kill = (signal: NodeJS.Signals = "SIGKILL"): void => {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      if (signal === "SIGKILL") { try { writeFileSync(join(groupPath, "cgroup.kill"), "1"); } catch { /* group may already be empty */ } }
+      if (child.pid) { try { process.kill(-child.pid, signal); } catch { /* already exited */ } }
+    };
+    const timer = setTimeout(() => kill(), limits.wallTimeMs); timer.unref();
+    let cleaned = false;
+    const cleanup = (): void => {
+      if (cleaned) return; cleaned = true; clearTimeout(timer);
+      try { writeFileSync(join(groupPath, "cgroup.kill"), "1"); } catch { /* startup failure */ }
+      try { rmdirSync(groupPath); } catch { /* transient kernel teardown; no siblings touched */ }
+      rmSync(workPath, { force: true, recursive: true }); releaseUid(jobUid);
+    };
+    const exited = new Promise<{ code: number | null; signal: NodeJS.Signals | null }>(resolveExit => {
+      child.once("close", (code, signal) => { cleanup(); resolveExit({ code, signal }); });
+    });
+    child.once("error", () => { if (!child.pid) cleanup(); });
+    // Existing ManagedProcess.kill must also kill the wrapper's whole job.
+    const nativeKill = child.kill.bind(child);
+    child.kill = (signal?: NodeJS.Signals | number) => {
+      if (typeof signal === "number") return nativeKill(signal);
+      kill(signal ?? "SIGTERM"); return true;
+    };
+    return { child, exited, kill };
+  } catch (error) {
+    if (group) { try { rmdirSync(group); } catch { /* no child launched */ } }
+    if (work) rmSync(work, { force: true, recursive: true }); releaseUid(jobUid);
+    if (error instanceof Error && error.message === "upload denied") throw error;
+    throw new SandboxUnavailable();
+  }
+}
diff --git a/packages/media-sandbox/tsconfig.json b/packages/media-sandbox/tsconfig.json
new file mode 100644
index 0000000..c942ef3
--- /dev/null
+++ b/packages/media-sandbox/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "outDir": "dist", "rootDir": "src", "module": "CommonJS", "moduleResolution": "node" },
+  "include": ["src"]
+}
diff --git a/packages/publishing-execution/README.md b/packages/publishing-execution/README.md
new file mode 100644
index 0000000..2cbdc61
--- /dev/null
+++ b/packages/publishing-execution/README.md
@@ -0,0 +1,25 @@
+# Publishing execution
+
+The API and scheduler share this built PostgreSQL repository. Callers own the
+`pg.Pool` and its lifecycle. `scheduleAttempt` and `cancelAttempt` run inside the
+API's existing tenant transaction; other methods establish their own RLS-bound
+transaction. Mutation order is workspace, draft, schedule, attempt, audit.
+
+A business attempt gets a positive decimal attempt number and one provider key.
+Transport retries, Temporal replay and lease recovery retain that key.
+`retryLater` requires proof that the attempt has no unresolved delivery:
+429/refusal of the current request cannot disprove an earlier ambiguous send.
+Use `retryDeduplicated` for that case; it retains dispatch evidence and the
+original dedupe deadline. Both settlements are owner/epoch/expiry fenced.
+Unknown work cannot get a new key or send automatically.
+
+The SDK around-send hook holds `withDispatchGate` across the bounded request,
+after rate-limiter waits. Provider evidence is appended separately before
+finalization, including evidence from stale owners. A current owner can finalize
+a receipt after authorization changes; the audit records those changes. Receipt
+recovery uses a separate workflow ID and never needs another provider send.
+
+Runtime boot never executes owner DDL. Apply migrations through the API's offline
+`migrate` CLI with an explicit `SUPER_DATABASE_URL`; API writes and scheduler
+startup require completed 019, FORCE RLS, valid indexes and the `sp_app` role.
+018 is retained unchanged because local evidence records its application.
diff --git a/packages/publishing-execution/package.json b/packages/publishing-execution/package.json
new file mode 100644
index 0000000..65f0447
--- /dev/null
+++ b/packages/publishing-execution/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@tactical-media-broadcast-hub/publishing-execution",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@tactical-media-broadcast-hub/core": "workspace:*",
+    "pg": "^8.23.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5",
+    "@types/pg": "^8.23.1"
+  }
+}
diff --git a/packages/publishing-execution/src/approval.test.ts b/packages/publishing-execution/src/approval.test.ts
new file mode 100644
index 0000000..61c9c43
--- /dev/null
+++ b/packages/publishing-execution/src/approval.test.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from "vitest";
+import { publishingIdempotencyKey } from "@tactical-media-broadcast-hub/core";
+import { canonicalPostHash } from "./approval.js";
+describe("approval and attempt identity", () => {
+  it("sorts nested keys, excludes execution metadata, and preserves target and array order", () => {
+    const post = { text: "hi", mediaAssetIds: ["a", "b"], providerMetadata: { connectionId: "target", nested: { z: 2, a: 1 } } };
+    const reordered = { providerMetadata: { nested: { a: 1, z: 2 }, connectionId: "target", draftId: "injected", idempotencyKey: "key" }, mediaAssetIds: ["a", "b"], text: "hi" };
+    expect(canonicalPostHash(post)).toBe(canonicalPostHash(reordered));
+    expect(canonicalPostHash(post)).not.toBe(canonicalPostHash({ ...post, mediaAssetIds: ["b", "a"] }));
+    expect(canonicalPostHash(post)).not.toBe(canonicalPostHash({ ...post, providerMetadata: { ...post.providerMetadata, connectionId: "other" } }));
+  });
+  it("uses decimal bigint attempts without precision loss", () => {
+    expect(publishingIdempotencyKey({ workspaceId: "ws", draftId: "draft", attemptNo: "9007199254740993" })).toBe("wp3:ws:draft:a9007199254740993:publish");
+    expect(() => publishingIdempotencyKey({ workspaceId: "ws", draftId: "draft", attemptNo: Number.MAX_SAFE_INTEGER + 1 })).toThrow();
+    for (const attemptNo of ["0", "01", "-1", "1.1"]) expect(() => publishingIdempotencyKey({ workspaceId: "ws", draftId: "draft", attemptNo })).toThrow();
+  });
+});
diff --git a/packages/publishing-execution/src/approval.ts b/packages/publishing-execution/src/approval.ts
new file mode 100644
index 0000000..760ecd1
--- /dev/null
+++ b/packages/publishing-execution/src/approval.ts
@@ -0,0 +1,13 @@
+import { createHash } from "node:crypto";
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([key, item]) => [key, canonical(item)]));
+  return value;
+}
+/** The target lives in providerMetadata.connectionId; execution keys are excluded. */
+export function canonicalPostHash<T extends { providerMetadata: Record<string, unknown> }>(post: T): string {
+  const metadata = { ...post.providerMetadata };
+  delete metadata.idempotencyKey;
+  delete metadata.draftId;
+  return createHash("sha256").update(JSON.stringify(canonical({ ...post, providerMetadata: metadata }))).digest("hex");
+}
diff --git a/packages/publishing-execution/src/index.ts b/packages/publishing-execution/src/index.ts
new file mode 100644
index 0000000..991e4a4
--- /dev/null
+++ b/packages/publishing-execution/src/index.ts
@@ -0,0 +1,3 @@
+export * from "./publishing.repository.js";
+export * from "./approval.js";
+export * from "./schema.js";
diff --git a/packages/publishing-execution/src/publishing.repository.ts b/packages/publishing-execution/src/publishing.repository.ts
new file mode 100644
index 0000000..36f42b4
--- /dev/null
+++ b/packages/publishing-execution/src/publishing.repository.ts
@@ -0,0 +1,1219 @@
+import { publishingIdempotencyKey } from "@tactical-media-broadcast-hub/core";
+import { canonicalPostHash } from "./approval.js";
+import type { Pool, PoolClient } from "pg";
+
+/**
+ * WP3 execution spine: the tenant-scoped claim / dispatch-gate / receipt /
+ * finalization repository behind the scheduler's publish activity (plan §4).
+ *
+ * PostgreSQL owns the fences. Every method enters the tenant through the same
+ * transaction-local `set_config('app.workspace_id', …, true)` as withTenant,
+ * so RLS binds as sp_app. Mutations lock in one order — workspace row, draft,
+ * schedule, attempt, then the audit chain — matching team/group/credential
+ * mutations, which take the workspace row FOR UPDATE before domain rows.
+ *
+ * Bigint columns cross this boundary as decimal strings (pg's int8 default).
+ */
+
+export const PUBLISH_ERROR_CODES = [
+  "AUTHZ_REVOKED",
+  "CREDENTIAL_CHANGED",
+  "SUPERSEDED",
+  "CANCELLED",
+  "PUBLISH_OUTCOME_UNKNOWN",
+  "RETRY_EXHAUSTED",
+  "EXECUTION_FENCE_MISSING",
+  "LEGACY_AUTHORIZATION_MISSING",
+] as const;
+export type PublishErrorCode = (typeof PUBLISH_ERROR_CODES)[number] | (string & {});
+
+/** Roles that may use every connection without group sharing (groups.service WORKSPACE_WIDE_ROLES). */
+const WORKSPACE_WIDE_ROLES = ["Owner", "Admin"];
+const DEFAULT_LEASE_SECONDS = 90;
+export const MAX_DISPATCHES = 5;
+const SCHEDULER_ROLE = "sp_scheduler";
+
+/** Identity of one business attempt as carried by the workflow input. */
+export interface AttemptRef {
+  workspaceId: string;
+  scheduleId: string;
+  generation: string;
+  idempotencyKey: string;
+}
+
+/** Proof of current ownership; every journal write CASes owner_token + claim_epoch. */
+export interface Lease {
+  workspaceId: string;
+  attemptId: string;
+  scheduleId: string;
+  draftId: string;
+  idempotencyKey: string;
+  generation: string;
+  ownerToken: string;
+  claimEpoch: string;
+  leaseUntil: Date;
+}
+
+export interface ExecutionPost {
+  text: string;
+  mediaAssetIds: string[];
+  visibility: string;
+  providerMetadata: Record<string, unknown>;
+}
+
+export interface ClaimedJob {
+  lease: Lease;
+  attemptNo: string;
+  retryCount: number;
+  firstDispatchStartedAt?: Date;
+  providerRetryDeadline?: Date;
+  post: ExecutionPost;
+  connection: { id: string; provider: string; channelId: string; fields: Record<string, unknown>; createdAt: Date };
+  credential: { id: string; generation: string };
+  /** A previous owner stamped a dispatch whose outcome is not settled. */
+  priorDispatch: { startedAt: Date; count: number; providerRetryDeadline?: Date } | undefined;
+}
+
+export interface StoredPublication {
+  id: string;
+  workspaceId: string;
+  draftId: string;
+  connectionId: string;
+  idempotencyKey: string;
+  remoteId: string;
+  remoteUrl?: string;
+  publishedAt: Date;
+  providerMetadata: Record<string, unknown>;
+}
+
+export interface StoredReceipt {
+  id: string;
+  workspaceId: string;
+  attemptId: string;
+  remoteId: string;
+  remoteUrl?: string;
+  publishedAt?: Date;
+  providerMetadata: Record<string, unknown>;
+  receivedAt: Date;
+}
+
+export interface RemoteResult {
+  remoteId: string;
+  remoteUrl?: string;
+  publishedAt?: Date;
+  /** Caller-sanitized, allowlisted provider metadata (never tokens or raw bodies). */
+  providerMetadata?: Record<string, unknown>;
+}
+
+export type ClaimOutcome =
+  | { kind: "claimed"; job: ClaimedJob }
+  | { kind: "finalize"; job: ClaimedJob; receipt: StoredReceipt }
+  | { kind: "done"; publication: StoredPublication }
+  | { kind: "wait"; until: Date; reason: "not_due" | "busy" }
+  | { kind: "paused"; code: PublishErrorCode }
+  | { kind: "superseded"; code: PublishErrorCode }
+  | { kind: "failed"; code: PublishErrorCode }
+  | { kind: "unknown"; code: PublishErrorCode };
+
+export type GateOutcome<T> =
+  | { kind: "sent"; value: T }
+  | { kind: "finalize" }
+  | { kind: "lost" }
+  | { kind: "paused"; code: PublishErrorCode }
+  | { kind: "superseded"; code: PublishErrorCode }
+  | { kind: "failed"; code: PublishErrorCode }
+  | { kind: "unknown"; code: PublishErrorCode };
+
+export type FinalizeOutcome = { kind: "done"; publication: StoredPublication } | { kind: "stale" };
+export type SettleOutcome = { kind: "settled"; until?: Date } | { kind: "stale" };
+
+export interface ScheduleAttemptInput {
+  workspaceId: string;
+  draftId: string;
+  connectionId: string;
+  scheduledByUserId: string;
+  requiredPermission: "publication.schedule" | "publication.publish";
+  publishAt: Date;
+  expectedPrevious?: { state: "failed" | "needs_reauthorization"; generation: string };
+  timezone?: string;
+  localPublishAt?: string;
+  tzdataVersion?: string;
+}
+
+export interface ScheduledAttempt {
+  scheduleId: string;
+  attemptId: string;
+  attemptNo: string;
+  generation: string;
+  idempotencyKey: string;
+}
+
+export interface DueWork {
+  evidenceOnly: boolean;
+  workspaceId: string;
+  scheduleId: string;
+  idempotencyKey: string;
+  generation: string;
+  publishAt: Date;
+}
+
+/** Conflicting or missing evidence: operator-visible, never auto-repaired. */
+export class PublishingIntegrityError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message);
+    this.name = "PublishingIntegrityError";
+  }
+}
+
+/** A scheduling command that the current draft/schedule/credential state refuses. */
+export class PublishingStateError extends Error {
+  constructor(readonly code: string, message: string) {
+    super(message);
+    this.name = "PublishingStateError";
+  }
+}
+
+/** `wp3:<workspaceUUID>:<draftUUID>:a<attemptNo>:publish` — reused verbatim by every replay. */
+export function publishIdempotencyKey(workspaceId: string, draftId: string, attemptNo: string): string {
+  return publishingIdempotencyKey({ workspaceId, draftId, attemptNo });
+}
+
+type Row = Record<string, unknown>;
+
+interface Locked {
+  epoch: string;
+  connection: Row;
+  draft: Row;
+  schedule: Row;
+  attempt: Row;
+}
+
+export interface PublishingRepositoryOptions {
+  leaseSeconds?: number;
+}
+
+export class PublishingExecutionRepository {
+  private readonly leaseSeconds: number;
+
+  constructor(
+    private readonly pool: Pool,
+    options: PublishingRepositoryOptions = {},
+  ) {
+    this.leaseSeconds = options.leaseSeconds ?? DEFAULT_LEASE_SECONDS;
+  }
+
+  // -------------------------------------------------------------------------
+  // Discovery (SECURITY DEFINER, identifiers only)
+  // -------------------------------------------------------------------------
+
+  async listDue(limit = 100): Promise<DueWork[]> {
+    const res = await this.pool.query("SELECT * FROM publishing_due_schedules($1)", [limit]);
+    return (res.rows as Row[]).map((r) => ({
+      evidenceOnly: r.evidence_only === true,
+      workspaceId: String(r.workspace_id),
+      scheduleId: String(r.schedule_id),
+      idempotencyKey: String(r.idempotency_key),
+      generation: String(r.generation),
+      publishAt: new Date(String(r.publish_at)),
+    }));
+  }
+
+  async resolveWorkspace(idempotencyKey: string): Promise<string | undefined> {
+    const res = await this.pool.query("SELECT publishing_schedule_workspace($1) AS workspace_id", [idempotencyKey]);
+    const id = (res.rows[0] as Row | undefined)?.workspace_id;
+    return id === null || id === undefined ? undefined : String(id);
+  }
+
+  async findPublication(workspaceId: string, idempotencyKey: string): Promise<StoredPublication | undefined> {
+    return this.inTenant(workspaceId, async (client) => {
+      const res = await client.query("SELECT * FROM publications WHERE idempotency_key = $1", [idempotencyKey]);
+      const row = res.rows[0] as Row | undefined;
+      return row === undefined ? undefined : publicationFromRow(row);
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Scheduling: a new business attempt (called inside the service's tenant tx)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Creates or re-arms the draft's single schedule row for a NEW business
+   * attempt: allocates attempt_no from the locked draft counter, snapshots
+   * principal / approval proof / exact credential generation, bumps the
+   * schedule generation (voiding every older workflow) and journals a ready
+   * attempt. Must run in a tenant transaction for `input.workspaceId`.
+   */
+  async scheduleAttempt(client: PoolClient, input: ScheduleAttemptInput): Promise<ScheduledAttempt> {
+    const epoch = await lockWorkspace(client, input.workspaceId);
+    const draftRes = await client.query("SELECT * FROM drafts WHERE id = $1 FOR UPDATE", [input.draftId]);
+    const draft = draftRes.rows[0] as Row | undefined;
+    if (draft === undefined) throw new PublishingStateError("DRAFT_NOT_FOUND", "draft not found");
+    if (
+      draft.state !== "approved" ||
+      draft.approved_revision === null ||
+      String(draft.approved_revision) !== String(draft.revision) ||
+      draft.approved_hash === null ||
+      draft.reviewer_user_id === null
+    ) {
+      throw new PublishingStateError("DRAFT_NOT_APPROVED", "draft has no current approval");
+    }
+
+    const approvedPost = draft.post as ExecutionPost;
+    if (approvedPost.mediaAssetIds.length > 0 || "mediaIds" in approvedPost.providerMetadata) throw new PublishingStateError("UNSUPPORTED_MEDIA", "publishing currently supports text only");
+    if (approvedPost.providerMetadata.connectionId !== input.connectionId || canonicalPostHash(approvedPost) !== draft.approved_hash) {
+      throw new PublishingStateError("APPROVAL_MISMATCH", "approved content or target does not match");
+    }
+
+    const existingRes = await client.query("SELECT * FROM scheduled_publications WHERE draft_id = $1 FOR UPDATE", [
+      input.draftId,
+    ]);
+    const existing = existingRes.rows[0] as Row | undefined;
+    if (input.expectedPrevious && (!existing || existing.state !== input.expectedPrevious.state || String(existing.generation) !== input.expectedPrevious.generation)) throw new PublishingStateError("SCHEDULE_CHANGED", "schedule state or generation changed");
+    if (existing !== undefined && ["pending", "in_flight", "done"].includes(String(existing.state))) {
+      if (existing.state === "pending" && String(existing.connection_id) === input.connectionId && toDate(existing.publish_at).getTime() === input.publishAt.getTime() && String(existing.scheduled_by_user_id) === input.scheduledByUserId && existing.required_permission === input.requiredPermission && String(existing.post_hash) === String(draft.approved_hash)) {
+        const prior = await client.query("SELECT id FROM publishing_attempts WHERE idempotency_key = $1", [existing.idempotency_key]);
+        if (prior.rows[0]) return { scheduleId: String(existing.id), attemptId: String(prior.rows[0].id), attemptNo: String(existing.attempt_no), generation: String(existing.generation), idempotencyKey: String(existing.idempotency_key) };
+      }
+      throw new PublishingStateError("SCHEDULE_ACTIVE", `schedule is ${String(existing.state)}`);
+    }
+    if (existing !== undefined) {
+      const unsettled = await client.query(
+        `SELECT 1 FROM publishing_attempts
+          WHERE schedule_id = $1
+            AND (status IN ('in_progress', 'unknown') OR (status = 'failed' AND error_code = 'PUBLISH_OUTCOME_UNKNOWN') OR EXISTS (SELECT 1 FROM publishing_receipts r WHERE r.attempt_id = publishing_attempts.id AND r.workspace_id = publishing_attempts.workspace_id))`,
+        [existing.id],
+      );
+      if ((unsettled.rowCount ?? 0) > 0) {
+        throw new PublishingStateError("PUBLISH_OUTCOME_UNKNOWN", "a previous attempt has an unsettled outcome");
+      }
+    }
+
+    const credRes = await client.query(
+      `SELECT cr.id, cr.generation FROM connections c
+        JOIN credentials cr ON cr.connection_id = c.id AND cr.kind = 'connector-oauth' AND cr.revoked_at IS NULL
+       WHERE c.id = $1 AND c.disconnected_at IS NULL`,
+      [input.connectionId],
+    );
+    const credential = credRes.rows[0] as Row | undefined;
+    if (credential === undefined) throw new PublishingStateError("CREDENTIAL_CHANGED", "connection has no active credential");
+
+    const authz = await authorize(client, {
+      workspaceId: input.workspaceId,
+      principal: input.scheduledByUserId,
+      permission: input.requiredPermission,
+      reviewer: String(draft.reviewer_user_id),
+      connectionId: input.connectionId,
+      credentialId: String(credential.id),
+      credentialGeneration: String(credential.generation),
+    });
+    if (authz !== undefined) throw new PublishingStateError(authz, "scheduling principal is not authorized");
+
+    const counter = await client.query(
+      "UPDATE drafts SET publication_attempt = publication_attempt + 1 WHERE id = $1 RETURNING publication_attempt",
+      [input.draftId],
+    );
+    const attemptNo = String((counter.rows[0] as Row).publication_attempt);
+    const key = publishIdempotencyKey(input.workspaceId, input.draftId, attemptNo);
+    const fence = [
+      input.connectionId,
+      input.publishAt,
+      key,
+      input.scheduledByUserId,
+      input.requiredPermission,
+      epoch,
+      String(draft.approved_revision),
+      String(draft.approved_hash),
+      String(credential.id),
+      String(credential.generation),
+      attemptNo,
+      input.timezone ?? "UTC",
+      input.localPublishAt ?? null,
+      input.tzdataVersion ?? null,
+    ];
+
+    let schedule: Row;
+    if (existing === undefined) {
+      const ins = await client.query(
+        `INSERT INTO scheduled_publications
+           (workspace_id, draft_id, connection_id, publish_at, idempotency_key, scheduled_by_user_id,
+            required_permission, authorized_epoch, approved_revision, post_hash, credential_id,
+            credential_generation, attempt_no, timezone, local_publish_at, tzdata_version,
+            generation, execution_version, state, next_attempt_at)
+         VALUES ($15, $16, $1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, 1, 1, 'pending', $2)
+         RETURNING id, generation`,
+        [...fence, input.workspaceId, input.draftId],
+      );
+      schedule = ins.rows[0] as Row;
+    } else {
+      const upd = await client.query(
+        `UPDATE scheduled_publications SET
+           connection_id = $1, publish_at = $2, idempotency_key = $3, scheduled_by_user_id = $4,
+           required_permission = $5, authorized_epoch = $6, approved_revision = $7, post_hash = $8,
+           credential_id = $9, credential_generation = $10, attempt_no = $11, timezone = $12,
+           local_publish_at = $13, tzdata_version = $14, generation = generation + 1,
+           execution_version = 1, state = 'pending', next_attempt_at = $2, retry_count = 0,
+           error = NULL, error_code = NULL
+         WHERE id = $15
+         RETURNING id, generation`,
+        [...fence, existing.id],
+      );
+      schedule = upd.rows[0] as Row;
+    }
+
+    const attempt = await client.query(
+      `INSERT INTO publishing_attempts
+         (workspace_id, schedule_id, draft_id, connection_id, attempt_no, idempotency_key,
+          schedule_generation, post_snapshot, post_hash, scheduled_by_user_id, required_permission,
+          approved_revision, reviewer_user_id, credential_id, credential_generation, authorized_epoch)
+       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11, $12, $13, $14, $15, $16)
+       RETURNING id`,
+      [
+        input.workspaceId,
+        schedule.id,
+        input.draftId,
+        input.connectionId,
+        attemptNo,
+        key,
+        schedule.generation,
+        draft.post,
+        draft.approved_hash,
+        input.scheduledByUserId,
+        input.requiredPermission,
+        draft.approved_revision,
+        draft.reviewer_user_id,
+        credential.id,
+        credential.generation,
+        epoch,
+      ],
+    );
+    return {
+      scheduleId: String(schedule.id),
+      attemptId: String((attempt.rows[0] as Row).id),
+      attemptNo,
+      generation: String(schedule.generation),
+      idempotencyKey: key,
+    };
+  }
+
+  /** Cancellation retains journal and evidence; only undispatched intent can be cancelled. */
+  async cancelAttempt(client: PoolClient, workspaceId: string, draftId: string): Promise<void> {
+    await lockWorkspace(client, workspaceId);
+    await client.query("SELECT id FROM drafts WHERE id = $1 FOR UPDATE", [draftId]);
+    const schedules = await client.query("SELECT * FROM scheduled_publications WHERE draft_id = $1 FOR UPDATE", [draftId]);
+    const schedule = schedules.rows[0] as Row | undefined;
+    if (!schedule) throw new PublishingStateError("SCHEDULE_NOT_FOUND", "schedule not found");
+    const attempts = await client.query("SELECT * FROM publishing_attempts WHERE schedule_id = $1 ORDER BY attempt_no FOR UPDATE", [schedule.id]);
+    if ((attempts.rows as Row[]).some((a) => a.status === "unknown" || (a.dispatch_started_at !== null && a.status !== "completed" && a.status !== "failed"))) throw new PublishingStateError("PUBLISH_OUTCOME_UNKNOWN", "dispatch is unsettled");
+    if (!["pending", "in_flight", "needs_reauthorization", "cancelled"].includes(String(schedule.state))) throw new PublishingStateError("SCHEDULE_ACTIVE", "schedule cannot be cancelled");
+    await client.query("UPDATE publishing_attempts SET status = 'abandoned', owner_token = NULL, lease_until = NULL, error_code = 'CANCELLED' WHERE schedule_id = $1 AND status IN ('ready', 'in_progress')", [schedule.id]);
+    await client.query("UPDATE scheduled_publications SET state = 'cancelled', generation = generation + 1, error_code = 'CANCELLED' WHERE id = $1 AND state <> 'cancelled'", [schedule.id]);
+  }
+
+  // -------------------------------------------------------------------------
+  // Claim
+  // -------------------------------------------------------------------------
+
+  /**
+   * Atomic claim under workspace FOR UPDATE + draft/schedule/attempt row locks.
+   * A live owner yields `wait`; an expired lease is recoverable by exactly one
+   * claimer (owner_token change advances claim_epoch in the DB). Existing
+   * evidence short-circuits to `done` / `finalize` — never a second send.
+   */
+  async claim(ref: AttemptRef): Promise<ClaimOutcome> {
+    return this.inTenant(ref.workspaceId, async (client) => {
+      const epoch = await lockWorkspace(client, ref.workspaceId);
+      const pub = await client.query("SELECT * FROM publications WHERE idempotency_key = $1", [ref.idempotencyKey]);
+      if (pub.rows[0] !== undefined) return { kind: "done", publication: publicationFromRow(pub.rows[0] as Row) };
+
+      const locked = await lockAttemptByKey(client, ref.idempotencyKey, epoch);
+      if (locked === undefined) return { kind: "failed", code: "EXECUTION_FENCE_MISSING" };
+      const { draft, schedule, attempt } = locked;
+      if (String(schedule.id) !== ref.scheduleId) return { kind: "failed", code: "EXECUTION_FENCE_MISSING" };
+
+      const now = await dbNow(client);
+      const status = String(attempt.status);
+      if (status === "completed") {
+        throw new PublishingIntegrityError("PUBLICATION_MISSING", `attempt ${String(attempt.id)} completed without a publication`);
+      }
+
+      // Durable evidence wins over every other fence: finalize, never resend.
+      const receipt = await readReceipt(client, String(attempt.id));
+      if (receipt !== undefined) {
+        if (status === "abandoned") {
+          throw new PublishingIntegrityError("RECEIPT_ON_ABANDONED_ATTEMPT", `attempt ${String(attempt.id)} is abandoned but has a receipt`);
+        }
+        if (status === "in_progress" && toDate(attempt.lease_until) > now) {
+          return { kind: "wait", until: toDate(attempt.lease_until), reason: "busy" };
+        }
+        const lease = await this.takeOwnership(client, locked, epoch);
+        return { kind: "finalize", job: jobFromLocked(locked, lease), receipt };
+      }
+
+      // A ref whose generation disagrees with its own key's attempt is not
+      // this attempt's workflow: refuse it without touching the real attempt.
+      if (String(attempt.schedule_generation) !== ref.generation) return { kind: "superseded", code: "SUPERSEDED" };
+      if (
+        String(schedule.generation) !== String(attempt.schedule_generation) ||
+        String(schedule.idempotency_key) !== String(attempt.idempotency_key)
+      ) {
+        return supersede(client, locked, "SUPERSEDED");
+      }
+      if (Number(schedule.execution_version) !== 1) return { kind: "failed", code: "EXECUTION_FENCE_MISSING" };
+
+      switch (status) {
+        case "abandoned":
+          return { kind: "superseded", code: String(attempt.error_code ?? "SUPERSEDED") };
+        case "failed":
+          return { kind: "failed", code: String(attempt.error_code ?? schedule.error_code ?? "FAILED") };
+        case "unknown":
+          return { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" };
+        case "ready": {
+          const scheduleState = String(schedule.state);
+          if (scheduleState === "cancelled") return supersede(client, locked, "CANCELLED");
+          if (scheduleState === "needs_reauthorization") return { kind: "paused", code: String(schedule.error_code) };
+          if (scheduleState !== "pending") return { kind: "failed", code: String(schedule.error_code ?? "FAILED") };
+          const dueAt = maxDate(toDate(schedule.next_attempt_at), toDate(schedule.publish_at));
+          if (dueAt > now) return { kind: "wait", until: dueAt, reason: "not_due" };
+          if (draft.state !== "approved") return supersede(client, locked, "SUPERSEDED");
+          break;
+        }
+        case "in_progress": {
+          if (toDate(attempt.lease_until) > now) {
+            return { kind: "wait", until: toDate(attempt.lease_until), reason: "busy" };
+          }
+          // Recovery: only this exact in-flight schedule's scheduled draft.
+          if (schedule.state !== "in_flight" || draft.state !== "scheduled") {
+            throw new PublishingIntegrityError("RECOVERY_STATE", `attempt ${String(attempt.id)} in progress outside an in-flight schedule`);
+          }
+          break;
+        }
+        default:
+          throw new PublishingIntegrityError("ATTEMPT_STATUS", `unexpected attempt status ${status}`);
+      }
+
+      if (!contentFenceHolds(draft, attempt)) return supersede(client, locked, "SUPERSEDED");
+
+      const denied = await authorize(client, authzInput(attempt));
+      if (denied !== undefined) {
+        if (attempt.dispatch_started_at !== null) {
+          await settleUnknown(client, locked, "PUBLISH_OUTCOME_UNKNOWN");
+          return { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" };
+        }
+        await pause(client, locked, denied);
+        return { kind: "paused", code: denied };
+      }
+
+      const lease = await this.takeOwnership(client, locked, epoch);
+      return { kind: "claimed", job: jobFromLocked(locked, lease) };
+    });
+  }
+
+  /** Renews a live lease; false once the lease expired or ownership moved on. */
+  async heartbeat(lease: Lease): Promise<boolean> {
+    return this.inTenant(lease.workspaceId, async (client) => {
+      const res = await client.query(
+        `UPDATE publishing_attempts SET lease_until = now() + make_interval(secs => $4::double precision)
+          WHERE id = $1 AND owner_token = $2 AND claim_epoch = $3
+            AND status = 'in_progress' AND lease_until > now()
+          RETURNING lease_until`,
+        [lease.attemptId, lease.ownerToken, lease.claimEpoch, this.leaseSeconds],
+      );
+      const row = res.rows[0] as Row | undefined;
+      if (row === undefined) return false;
+      lease.leaseUntil = toDate(row.lease_until);
+      return true;
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Dispatch gate
+  // -------------------------------------------------------------------------
+
+  /**
+   * Holds the workspace row FOR SHARE in a dedicated READ COMMITTED tenant
+   * transaction across `send`, so any approval/authz/credential mutation
+   * (which takes workspace FOR UPDATE first) either committed before the
+   * fence re-read — and blocks the send — or serializes after it. The dispatch
+   * stamp commits in a separate short transaction (owner/claim_epoch CAS,
+   * dispatch_count < MAX) so receipts and heartbeats never wait on the gate.
+   *
+   * `allowRedispatch` with `dedupeWindowMs` is the connector's declared
+   * token-dedupe policy (e.g. verified Mastodon origins). Without it an
+   * unsettled earlier dispatch becomes PUBLISH_OUTCOME_UNKNOWN, never a resend.
+   */
+  async withDispatchGate<T>(
+    lease: Lease,
+    policy: { allowRedispatch?: boolean; dedupeWindowMs?: number },
+    send: () => Promise<T>,
+  ): Promise<GateOutcome<T>> {
+    const client = await this.pool.connect();
+    let open = false;
+    const end = async (sql: "COMMIT" | "ROLLBACK"): Promise<void> => {
+      if (!open) return;
+      open = false;
+      await client.query(sql).catch(() => undefined);
+    };
+    try {
+      await client.query("BEGIN ISOLATION LEVEL READ COMMITTED");
+      open = true;
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [lease.workspaceId]);
+      await client.query("SELECT 1 FROM workspaces WHERE id = $1 FOR SHARE", [lease.workspaceId]);
+
+      const attemptRes = await client.query(
+        `SELECT a.*, clock_timestamp() AS db_now FROM publishing_attempts a WHERE a.id = $1`,
+        [lease.attemptId],
+      );
+      const attempt = attemptRes.rows[0] as Row | undefined;
+      if (
+        attempt === undefined ||
+        attempt.status !== "in_progress" ||
+        attempt.owner_token !== lease.ownerToken ||
+        String(attempt.claim_epoch) !== lease.claimEpoch ||
+        toDate(attempt.lease_until) <= toDate(attempt.db_now)
+      ) {
+        await end("ROLLBACK");
+        return { kind: "lost" };
+      }
+      if ((await readReceipt(client, lease.attemptId)) !== undefined) {
+        await end("ROLLBACK");
+        return { kind: "finalize" };
+      }
+
+      const scheduleRes = await client.query("SELECT * FROM scheduled_publications WHERE id = $1", [attempt.schedule_id]);
+      const draftRes = await client.query("SELECT * FROM drafts WHERE id = $1", [attempt.draft_id]);
+      const schedule = scheduleRes.rows[0] as Row;
+      const draft = draftRes.rows[0] as Row;
+      const fenced =
+        schedule.state === "in_flight" &&
+        String(schedule.generation) === String(attempt.schedule_generation) &&
+        String(schedule.idempotency_key) === String(attempt.idempotency_key) &&
+        contentFenceHolds(draft, attempt);
+      const denied = fenced ? await authorize(client, authzInput(attempt)) : undefined;
+      const priorDispatch = attempt.dispatch_started_at !== null;
+      const redispatchAllowed =
+        policy.allowRedispatch === true &&
+        attempt.provider_retry_deadline !== null &&
+        toDate(attempt.provider_retry_deadline) > toDate(attempt.db_now);
+      const exhausted = Number(attempt.dispatch_count) >= MAX_DISPATCHES;
+
+      if (!fenced || denied !== undefined || (priorDispatch && !redispatchAllowed) || exhausted) {
+        await end("ROLLBACK");
+        if (priorDispatch) {
+          const settled = await this.settle(lease, (c, l) => settleUnknown(c, l, "PUBLISH_OUTCOME_UNKNOWN"));
+          return settled.kind === "stale" ? { kind: "lost" } : { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" };
+        }
+        if (!fenced) {
+          const settled = await this.settle(lease, (c, l) => supersede(c, l, "SUPERSEDED").then(() => undefined));
+          return settled.kind === "stale" ? { kind: "lost" } : { kind: "superseded", code: "SUPERSEDED" };
+        }
+        if (denied !== undefined) {
+          const settled = await this.settle(lease, (c, l) => pause(c, l, denied));
+          return settled.kind === "stale" ? { kind: "lost" } : { kind: "paused", code: denied };
+        }
+        const settled = await this.settle(lease, (c, l) => settleFailed(c, l, "RETRY_EXHAUSTED"));
+        return settled.kind === "stale" ? { kind: "lost" } : { kind: "failed", code: "RETRY_EXHAUSTED" };
+      }
+
+      const windowSeconds = Math.max(0, (policy.dedupeWindowMs ?? 0) / 1000);
+      const stamped = await this.pool.connect().then(async (stampClient) => {
+        try {
+          await stampClient.query("BEGIN");
+          await stampClient.query("SELECT set_config('app.workspace_id', $1, true)", [lease.workspaceId]);
+          const res = await stampClient.query(
+            `UPDATE publishing_attempts SET
+               dispatch_started_at = clock_timestamp(),
+               first_dispatch_started_at = COALESCE(first_dispatch_started_at, clock_timestamp()),
+               dispatch_count = dispatch_count + 1,
+               provider_retry_deadline = COALESCE(provider_retry_deadline,
+                 CASE WHEN $4::double precision > 0 THEN clock_timestamp() + make_interval(secs => $4::double precision) END)
+             WHERE id = $1 AND owner_token = $2 AND claim_epoch = $3 AND status = 'in_progress'
+               AND dispatch_count < ${MAX_DISPATCHES} AND lease_until > clock_timestamp()`,
+            [lease.attemptId, lease.ownerToken, lease.claimEpoch, windowSeconds],
+          );
+          await stampClient.query("COMMIT");
+          return (res.rowCount ?? 0) === 1;
+        } catch (err) {
+          await stampClient.query("ROLLBACK").catch(() => undefined);
+          throw err;
+        } finally {
+          stampClient.release();
+        }
+      });
+      if (!stamped) {
+        await end("ROLLBACK");
+        return { kind: "lost" };
+      }
+      try {
+        return { kind: "sent", value: await send() };
+      } finally {
+        await end("COMMIT");
+      }
+    } finally {
+      await end("ROLLBACK");
+      client.release();
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Receipt + finalization
+  // -------------------------------------------------------------------------
+
+  /**
+   * Append-only provider evidence in its own transaction. Any (even deposed)
+   * owner may record matching evidence; a different remote id for the same
+   * attempt is an integrity failure, never an overwrite.
+   */
+  async recordReceipt(
+    ref: { workspaceId: string; attemptId: string },
+    remote: RemoteResult,
+  ): Promise<{ receipt: StoredReceipt; inserted: boolean }> {
+    const remoteId = remote.remoteId.trim();
+    if (remoteId === "" || remoteId.length > 512) {
+      throw new PublishingIntegrityError("RECEIPT_SHAPE", "provider returned an invalid remote id");
+    }
+    const metadata = remote.providerMetadata ?? {};
+    if (typeof metadata !== "object" || metadata === null || Array.isArray(metadata)) {
+      throw new PublishingIntegrityError("RECEIPT_SHAPE", "provider metadata must be an object");
+    }
+    return this.inTenant(ref.workspaceId, async (client) => {
+      const attempt = await client.query("SELECT dispatch_count FROM publishing_attempts WHERE id = $1", [ref.attemptId]);
+      const row = attempt.rows[0] as Row | undefined;
+      if (row === undefined) throw new PublishingIntegrityError("ATTEMPT_MISSING", "receipt for an unknown attempt");
+      if (Number(row.dispatch_count) === 0) {
+        throw new PublishingIntegrityError("RECEIPT_WITHOUT_DISPATCH", "receipt for an attempt that was never dispatched");
+      }
+      const ins = await client.query(
+        `INSERT INTO publishing_receipts (workspace_id, attempt_id, remote_id, remote_url, published_at, provider_metadata)
+         VALUES ($1, $2, $3, $4, $5, $6)
+         ON CONFLICT (workspace_id, attempt_id) DO NOTHING
+         RETURNING *`,
+        [ref.workspaceId, ref.attemptId, remoteId, remote.remoteUrl ?? null, remote.publishedAt ?? null, metadata],
+      );
+      if (ins.rows[0] !== undefined) return { receipt: receiptFromRow(ins.rows[0] as Row), inserted: true };
+      const existing = await readReceipt(client, ref.attemptId);
+      if (existing === undefined) throw new PublishingIntegrityError("RECEIPT_MISSING", "receipt conflict without a row");
+      if (existing.remoteId !== remoteId) {
+        throw new PublishingIntegrityError("RECEIPT_CONFLICT", `attempt ${ref.attemptId} already has different remote evidence`);
+      }
+      return { receipt: existing, inserted: false };
+    });
+  }
+
+  /**
+   * Current owner turns the receipt into exactly one canonical Publication:
+   * CAS owner/epoch, same generation/key, insert ON CONFLICT(key) then verify
+   * identity, mark done/completed/published, append audit last. A deposed
+   * owner gets `stale` and must not report success; its receipt stays for
+   * the new owner.
+   */
+  async finalize(lease: Lease): Promise<FinalizeOutcome> {
+    return this.inTenant(lease.workspaceId, async (client) => {
+      const epoch = await lockWorkspace(client, lease.workspaceId);
+      const locked = await lockAttemptByKey(client, lease.idempotencyKey, epoch);
+      if (locked === undefined || !ownsLease(locked.attempt, lease)) return { kind: "stale" };
+      const { draft, schedule, attempt } = locked;
+      if (
+        String(schedule.generation) !== String(attempt.schedule_generation) ||
+        String(schedule.idempotency_key) !== String(attempt.idempotency_key) ||
+        String(draft.revision) !== String(attempt.approved_revision) ||
+        canonicalPostHash(draft.post as ExecutionPost) !== attempt.post_hash ||
+        canonicalPostHash(attempt.post_snapshot as ExecutionPost) !== attempt.post_hash
+      ) {
+        throw new PublishingIntegrityError("FINALIZE_FENCE", `attempt ${lease.attemptId} fences changed while dispatched`);
+      }
+      const receipt = await readReceipt(client, lease.attemptId);
+      if (receipt === undefined) throw new PublishingIntegrityError("RECEIPT_MISSING", "finalize without a durable receipt");
+
+      await client.query(
+        `INSERT INTO publications
+           (workspace_id, draft_id, connection_id, idempotency_key, remote_id, remote_url, published_at, provider_metadata)
+         VALUES ($1, $2, $3, $4, $5, $6, COALESCE($7::timestamptz, $8::timestamptz), $9)
+         ON CONFLICT (idempotency_key) DO NOTHING`,
+        [
+          lease.workspaceId,
+          attempt.draft_id,
+          attempt.connection_id,
+          attempt.idempotency_key,
+          receipt.remoteId,
+          receipt.remoteUrl ?? null,
+          receipt.publishedAt ?? null,
+          receipt.receivedAt,
+          receipt.providerMetadata,
+        ],
+      );
+      const pubRes = await client.query("SELECT * FROM publications WHERE idempotency_key = $1", [attempt.idempotency_key]);
+      const publication = publicationFromRow(pubRes.rows[0] as Row);
+      if (
+        publication.remoteId !== receipt.remoteId ||
+        publication.draftId !== String(attempt.draft_id) ||
+        publication.connectionId !== String(attempt.connection_id)
+      ) {
+        throw new PublishingIntegrityError("PUBLICATION_CONFLICT", `publication for ${String(attempt.idempotency_key)} disagrees with its receipt`);
+      }
+
+      await client.query(
+        `UPDATE publishing_attempts SET status = 'completed', owner_token = NULL, lease_until = NULL, error_code = NULL
+          WHERE id = $1`,
+        [attempt.id],
+      );
+      await client.query(
+        "UPDATE scheduled_publications SET state = 'done', error = NULL, error_code = NULL WHERE id = $1",
+        [schedule.id],
+      );
+      await client.query(
+        "UPDATE drafts SET state = 'published', updated_at = now() WHERE id = $1 AND state IN ('scheduled', 'approved')",
+        [draft.id],
+      );
+      const authorizationChanged = await authorize(client, authzInput(attempt));
+      await audit(client, lease.workspaceId, "publication.published", "publication", publication.id, {
+        ...(authorizationChanged ? { authorizationChanged } : {}),
+        draftId: String(draft.id),
+        attemptNo: String(attempt.attempt_no),
+        remoteId: publication.remoteId,
+      });
+      return { kind: "done", publication };
+    });
+  }
+
+  // -------------------------------------------------------------------------
+  // Settlements (owner-CAS'd)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Definite provider non-delivery (e.g. 429 with retry_after): same attempt
+   * and key, dispatch marker cleared, schedule pending at `notBefore`.
+   */
+  async retryLater(lease: Lease, code: string, notBefore: Date): Promise<SettleOutcome> {
+    return this.retry(lease, code, notBefore, false);
+  }
+
+  /** Ambiguous deduplicated retry retains the original evidence and deadline. */
+  async retryDeduplicated(lease: Lease, code: string, notBefore: Date): Promise<SettleOutcome> {
+    return this.retry(lease, code, notBefore, true);
+  }
+
+  async pauseForReauthorization(lease: Lease, code = "CREDENTIAL_REJECTED"): Promise<SettleOutcome> {
+    return this.settle(lease, (client, locked) => pause(client, locked, code));
+  }
+
+  private async retry(lease: Lease, code: string, notBefore: Date, ambiguous: boolean): Promise<SettleOutcome> {
+    return this.settle(lease, async (client, locked) => {
+      if (Number(locked.attempt.dispatch_count) >= MAX_DISPATCHES || Number(locked.schedule.retry_count) >= MAX_DISPATCHES - 1) {
+        if (ambiguous) await settleUnknown(client, locked, "PUBLISH_OUTCOME_UNKNOWN");
+        else await settleFailed(client, locked, "RETRY_EXHAUSTED");
+        return undefined;
+      }
+      await client.query(
+        `UPDATE publishing_attempts SET status = 'ready', owner_token = NULL, lease_until = NULL,
+                dispatch_started_at = CASE WHEN $3::boolean THEN dispatch_started_at ELSE NULL END, error_code = $2
+          WHERE id = $1`,
+        [locked.attempt.id, code, ambiguous],
+      );
+      const res = await client.query(
+        `UPDATE scheduled_publications SET state = 'pending', next_attempt_at = GREATEST($2::timestamptz, now()),
+                retry_count = retry_count + 1, error_code = $3
+          WHERE id = $1 RETURNING next_attempt_at`,
+        [locked.schedule.id, notBefore, code],
+      );
+      await client.query("UPDATE drafts SET state = 'approved', updated_at = now() WHERE id = $1 AND state = 'scheduled'", [
+        locked.draft.id,
+      ]);
+      return toDate((res.rows[0] as Row).next_attempt_at);
+    });
+  }
+
+  /** Permanent provider rejection or exhausted safe retries (known no-send). */
+  async fail(lease: Lease, code: string): Promise<SettleOutcome> {
+    return this.settle(lease, (client, locked) => settleFailed(client, locked, code));
+  }
+
+  /** Send may have happened and cannot be reconciled: lock, never resend. */
+  async markUnknown(lease: Lease, evidence?: { remoteId: string; scheduledAt: string }): Promise<SettleOutcome> {
+    return this.settle(lease, async (client, locked) => {
+      if (evidence) await audit(client, lease.workspaceId, "publication.unexpected_remote_schedule", "draft", lease.draftId, { remoteId: evidence.remoteId.slice(0, 512), scheduledAt: evidence.scheduledAt });
+      await settleUnknown(client, locked, "PUBLISH_OUTCOME_UNKNOWN");
+    });
+  }
+
+  private async settle(
+    lease: Lease,
+    fn: (client: PoolClient, locked: Locked) => Promise<Date | undefined | void>,
+  ): Promise<SettleOutcome> {
+    return this.inTenant(lease.workspaceId, async (client) => {
+      const epoch = await lockWorkspace(client, lease.workspaceId);
+      const locked = await lockAttemptByKey(client, lease.idempotencyKey, epoch);
+      if (locked === undefined || !ownsLease(locked.attempt, lease)) return { kind: "stale" } as const;
+      const until = await fn(client, locked);
+      return until instanceof Date ? { kind: "settled", until } : { kind: "settled" };
+    });
+  }
+
+  private async takeOwnership(client: PoolClient, locked: Locked, epoch: string): Promise<Lease> {
+    const { attempt, schedule, draft } = locked;
+    const res = await client.query(
+      `UPDATE publishing_attempts SET status = 'in_progress', owner_token = gen_random_uuid(),
+              lease_until = now() + make_interval(secs => $3::double precision), authorized_epoch = $4, error_code = NULL
+        WHERE id = $1 AND claim_epoch = $2
+        RETURNING owner_token, claim_epoch, lease_until`,
+      [attempt.id, attempt.claim_epoch, this.leaseSeconds, epoch],
+    );
+    const row = res.rows[0] as Row | undefined;
+    if (row === undefined) throw new PublishingIntegrityError("CLAIM_CAS", "claim lost its compare-and-set under row lock");
+    await client.query(
+      "UPDATE scheduled_publications SET state = 'in_flight', authorized_epoch = $2, error = NULL, error_code = NULL WHERE id = $1",
+      [schedule.id, epoch],
+    );
+    await client.query("UPDATE drafts SET state = 'scheduled', updated_at = now() WHERE id = $1 AND state = 'approved'", [
+      draft.id,
+    ]);
+    return {
+      workspaceId: String(attempt.workspace_id),
+      attemptId: String(attempt.id),
+      scheduleId: String(schedule.id),
+      draftId: String(draft.id),
+      idempotencyKey: String(attempt.idempotency_key),
+      generation: String(attempt.schedule_generation),
+      ownerToken: String(row.owner_token),
+      claimEpoch: String(row.claim_epoch),
+      leaseUntil: toDate(row.lease_until),
+    };
+  }
+
+  private async inTenant<T>(workspaceId: string, fn: (client: PoolClient) => Promise<T>): Promise<T> {
+    const client = await this.pool.connect();
+    try {
+      await client.query("BEGIN");
+      await client.query("SELECT set_config('app.workspace_id', $1, true)", [workspaceId]);
+      const result = await fn(client);
+      await client.query("COMMIT");
+      return result;
+    } catch (err) {
+      await client.query("ROLLBACK").catch(() => undefined);
+      throw err;
+    } finally {
+      client.release();
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tenant-transaction helpers (caller holds the tenant context)
+// ---------------------------------------------------------------------------
+
+async function lockWorkspace(client: PoolClient, workspaceId: string): Promise<string> {
+  const res = await client.query("SELECT authz_epoch FROM workspaces WHERE id = $1 FOR UPDATE", [workspaceId]);
+  const row = res.rows[0] as Row | undefined;
+  if (row === undefined) throw new PublishingIntegrityError("WORKSPACE_MISSING", "workspace not found");
+  return String(row.authz_epoch);
+}
+
+/** Locks draft -> schedule -> attempt for one key (workspace already locked). */
+async function lockAttemptByKey(client: PoolClient, idempotencyKey: string, epoch: string): Promise<Locked | undefined> {
+  const ids = await client.query("SELECT id, schedule_id, draft_id FROM publishing_attempts WHERE idempotency_key = $1", [
+    idempotencyKey,
+  ]);
+  const ref = ids.rows[0] as Row | undefined;
+  if (ref === undefined) return undefined;
+  const draft = (await client.query("SELECT * FROM drafts WHERE id = $1 FOR UPDATE", [ref.draft_id])).rows[0] as Row;
+  const schedule = (await client.query("SELECT * FROM scheduled_publications WHERE id = $1 FOR UPDATE", [ref.schedule_id]))
+    .rows[0] as Row;
+  const attempt = (await client.query("SELECT *, clock_timestamp() AS db_now FROM publishing_attempts WHERE id = $1 FOR UPDATE", [ref.id])).rows[0] as Row;
+  const connection = (
+    await client.query("SELECT id, provider, channel_id, fields, created_at FROM connections WHERE id = $1", [
+      attempt.connection_id,
+    ])
+  ).rows[0] as Row;
+  return { epoch, connection, draft, schedule, attempt };
+}
+
+function ownsLease(attempt: Row, lease: Lease): boolean {
+  return (
+    attempt.status === "in_progress" &&
+    attempt.owner_token === lease.ownerToken &&
+    String(attempt.claim_epoch) === lease.claimEpoch &&
+    toDate(attempt.lease_until) > toDate(attempt.db_now)
+  );
+}
+
+function contentFenceHolds(draft: Row, attempt: Row): boolean {
+  return (
+    String(draft.revision) === String(attempt.approved_revision) &&
+    String(draft.approved_revision) === String(attempt.approved_revision) &&
+    draft.approved_hash === attempt.post_hash &&
+    canonicalPostHash(draft.post as ExecutionPost) === attempt.post_hash &&
+    canonicalPostHash(attempt.post_snapshot as ExecutionPost) === attempt.post_hash &&
+    draft.reviewer_user_id === attempt.reviewer_user_id &&
+    String(draft.id) === String(attempt.draft_id)
+  );
+}
+
+interface AuthzInput {
+  workspaceId: string;
+  principal: string;
+  permission: string;
+  reviewer: string;
+  connectionId: string;
+  credentialId: string;
+  credentialGeneration: string;
+}
+
+function authzInput(attempt: Row): AuthzInput {
+  return {
+    workspaceId: String(attempt.workspace_id),
+    principal: String(attempt.scheduled_by_user_id),
+    permission: String(attempt.required_permission),
+    reviewer: String(attempt.reviewer_user_id),
+    connectionId: String(attempt.connection_id),
+    credentialId: String(attempt.credential_id),
+    credentialGeneration: String(attempt.credential_generation),
+  };
+}
+
+/**
+ * Re-reads every live authorization input: the recorded principal's active
+ * membership + role permission + connection access (userCanUseConnection),
+ * the approver's live approval.grant, the connection (not a tombstone) and
+ * the exact credential row/generation, unrevoked. Never a stored role.
+ */
+async function authorize(client: PoolClient, input: AuthzInput): Promise<PublishErrorCode | undefined> {
+  const res = await client.query(
+    `SELECT
+       EXISTS (
+         SELECT 1 FROM memberships m
+           JOIN role_permissions rp ON rp.role = m.role AND rp.permission = $3
+          WHERE m.workspace_id = $1 AND m.user_id = $2 AND m.status = 'active'
+            AND (m.role = ANY($8::text[])
+                 OR EXISTS (SELECT 1 FROM group_connections gc
+                              JOIN group_members gm ON gm.group_id = gc.group_id
+                             WHERE gc.connection_id = $5 AND gm.user_id = m.user_id))
+       ) AS principal_ok,
+       EXISTS (
+         SELECT 1 FROM memberships m
+           JOIN role_permissions rp ON rp.role = m.role AND rp.permission = 'approval.grant'
+          WHERE m.workspace_id = $1 AND m.user_id = $4 AND m.status = 'active'
+       ) AS approver_ok,
+       EXISTS (
+         SELECT 1 FROM connections c
+           JOIN credentials cr ON cr.connection_id = c.id
+          WHERE c.id = $5 AND c.disconnected_at IS NULL
+            AND cr.id = $6 AND cr.kind = 'connector-oauth' AND cr.generation = $7 AND cr.revoked_at IS NULL
+       ) AS credential_ok`,
+    [
+      input.workspaceId,
+      input.principal,
+      input.permission,
+      input.reviewer,
+      input.connectionId,
+      input.credentialId,
+      input.credentialGeneration,
+      WORKSPACE_WIDE_ROLES,
+    ],
+  );
+  const row = res.rows[0] as { principal_ok: boolean; approver_ok: boolean; credential_ok: boolean };
+  if (!row.credential_ok) return "CREDENTIAL_CHANGED";
+  if (!row.principal_ok || !row.approver_ok) return "AUTHZ_REVOKED";
+  return undefined;
+}
+
+/** Durable pause: the attempt is closed; resume is a new explicit attempt. */
+async function pause(client: PoolClient, locked: Locked, code: PublishErrorCode): Promise<void> {
+  await client.query(
+    "UPDATE publishing_attempts SET status = 'abandoned', owner_token = NULL, lease_until = NULL, error_code = $2 WHERE id = $1",
+    [locked.attempt.id, code],
+  );
+  await client.query(
+    `UPDATE scheduled_publications SET state = 'needs_reauthorization', error_code = $3
+      WHERE id = $1 AND generation = $2`,
+    [locked.schedule.id, locked.attempt.schedule_generation, code],
+  );
+  await client.query("UPDATE drafts SET state = 'approved', updated_at = now() WHERE id = $1 AND state = 'scheduled'", [
+    locked.draft.id,
+  ]);
+  await audit(client, String(locked.attempt.workspace_id), "publication.paused", "draft", String(locked.draft.id), {
+    code,
+    attemptNo: String(locked.attempt.attempt_no),
+  });
+}
+
+/**
+ * Old generation / changed content / cancelled: abandon the undispatched
+ * attempt; invalidate the schedule only if its generation still matches. A
+ * newer draft or schedule is never overwritten.
+ */
+async function supersede(client: PoolClient, locked: Locked, code: PublishErrorCode): Promise<ClaimOutcome> {
+  const { attempt, schedule } = locked;
+  if (attempt.dispatch_started_at !== null) {
+    await settleUnknown(client, locked, "PUBLISH_OUTCOME_UNKNOWN");
+    return { kind: "unknown", code: "PUBLISH_OUTCOME_UNKNOWN" };
+  }
+  if (attempt.status === "ready" || attempt.status === "in_progress") {
+    await client.query(
+      "UPDATE publishing_attempts SET status = 'abandoned', owner_token = NULL, lease_until = NULL, error_code = $2 WHERE id = $1",
+      [attempt.id, code],
+    );
+  }
+  if (String(schedule.generation) === String(attempt.schedule_generation) && ["pending", "in_flight"].includes(String(schedule.state))) {
+    await client.query(
+      "UPDATE scheduled_publications SET state = 'cancelled', error_code = $2 WHERE id = $1",
+      [schedule.id, code],
+    );
+    await client.query("UPDATE drafts SET state = 'approved', updated_at = now() WHERE id = $1 AND state = 'scheduled'", [
+      locked.draft.id,
+    ]);
+  }
+  await audit(client, String(attempt.workspace_id), "publication.superseded", "draft", String(attempt.draft_id), {
+    code,
+    attemptNo: String(attempt.attempt_no),
+  });
+  return { kind: "superseded", code };
+}
+
+async function settleFailed(client: PoolClient, locked: Locked, code: string): Promise<void> {
+  await client.query(
+    "UPDATE publishing_attempts SET status = 'failed', owner_token = NULL, lease_until = NULL, error_code = $2 WHERE id = $1",
+    [locked.attempt.id, code],
+  );
+  await client.query("UPDATE scheduled_publications SET state = 'failed', error_code = $2 WHERE id = $1", [
+    locked.schedule.id,
+    code,
+  ]);
+  await client.query("UPDATE drafts SET state = 'approved', updated_at = now() WHERE id = $1 AND state = 'scheduled'", [
+    locked.draft.id,
+  ]);
+  await audit(client, String(locked.attempt.workspace_id), "publication.failed", "draft", String(locked.draft.id), {
+    code,
+    attemptNo: String(locked.attempt.attempt_no),
+  });
+}
+
+/** Unknown outcome keeps the draft scheduled (locked) and never resends automatically. */
+async function settleUnknown(client: PoolClient, locked: Locked, code: string): Promise<void> {
+  await client.query(
+    "UPDATE publishing_attempts SET status = 'unknown', owner_token = NULL, lease_until = NULL, error_code = $2 WHERE id = $1",
+    [locked.attempt.id, code],
+  );
+  await client.query("UPDATE scheduled_publications SET state = 'failed', error_code = $2 WHERE id = $1", [
+    locked.schedule.id,
+    code,
+  ]);
+  await audit(client, String(locked.attempt.workspace_id), "publication.outcome_unknown", "draft", String(locked.draft.id), {
+    code,
+    attemptNo: String(locked.attempt.attempt_no),
+  });
+}
+
+async function audit(
+  client: PoolClient,
+  workspaceId: string,
+  action: string,
+  targetType: string,
+  targetId: string,
+  diff: Record<string, unknown>,
+): Promise<void> {
+  await client.query("SELECT audit_append($1, NULL, $2, $3, $4, $5, $6)", [
+    workspaceId,
+    SCHEDULER_ROLE,
+    action,
+    targetType,
+    targetId,
+    diff,
+  ]);
+}
+
+async function readReceipt(client: PoolClient, attemptId: string): Promise<StoredReceipt | undefined> {
+  const res = await client.query("SELECT * FROM publishing_receipts WHERE attempt_id = $1", [attemptId]);
+  const row = res.rows[0] as Row | undefined;
+  return row === undefined ? undefined : receiptFromRow(row);
+}
+
+async function dbNow(client: PoolClient): Promise<Date> {
+  const res = await client.query("SELECT clock_timestamp() AS now");
+  return toDate((res.rows[0] as Row).now);
+}
+
+// ---------------------------------------------------------------------------
+// Row mapping
+// ---------------------------------------------------------------------------
+
+function jobFromLocked(locked: Locked, lease: Lease): ClaimedJob {
+  return {
+    lease,
+    retryCount: Number(locked.schedule.retry_count),
+    ...(locked.attempt.first_dispatch_started_at == null ? {} : { firstDispatchStartedAt: toDate(locked.attempt.first_dispatch_started_at) }),
+    ...(locked.attempt.provider_retry_deadline == null ? {} : { providerRetryDeadline: toDate(locked.attempt.provider_retry_deadline) }),
+    attemptNo: String(locked.attempt.attempt_no),
+    post: executionPost(locked.attempt.post_snapshot as Row, String(locked.attempt.draft_id), lease.idempotencyKey),
+    connection: {
+      id: String(locked.connection.id),
+      provider: String(locked.connection.provider),
+      channelId: String(locked.connection.channel_id),
+      fields: (locked.connection.fields ?? {}) as Record<string, unknown>,
+      createdAt: toDate(locked.connection.created_at),
+    },
+    credential: { id: String(locked.attempt.credential_id), generation: String(locked.attempt.credential_generation) },
+    priorDispatch:
+      locked.attempt.dispatch_started_at === null
+        ? undefined
+        : {
+            startedAt: toDate(locked.attempt.dispatch_started_at),
+            count: Number(locked.attempt.dispatch_count),
+            ...(locked.attempt.provider_retry_deadline === null
+              ? {}
+              : { providerRetryDeadline: toDate(locked.attempt.provider_retry_deadline) }),
+          },
+  };
+}
+
+/**
+ * The immutable approved snapshot as the connector sees it: pipeline-owned
+ * timing (no scheduledAt) and server-injected reserved metadata that a user
+ * cannot pre-set.
+ */
+function executionPost(snapshot: Row, draftId: string, idempotencyKey: string): ExecutionPost {
+  const metadata = snapshot.providerMetadata;
+  return {
+    text: String(snapshot.text ?? ""),
+    mediaAssetIds: Array.isArray(snapshot.mediaAssetIds) ? snapshot.mediaAssetIds.map((v) => String(v)) : [],
+    visibility: String(snapshot.visibility ?? "provider_default"),
+    providerMetadata: {
+      ...(typeof metadata === "object" && metadata !== null && !Array.isArray(metadata) ? (metadata as Row) : {}),
+      draftId,
+      idempotencyKey,
+    },
+  };
+}
+
+function publicationFromRow(row: Row): StoredPublication {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    draftId: String(row.draft_id),
+    connectionId: String(row.connection_id),
+    idempotencyKey: String(row.idempotency_key),
+    remoteId: String(row.remote_id),
+    ...(row.remote_url === null || row.remote_url === undefined ? {} : { remoteUrl: String(row.remote_url) }),
+    publishedAt: toDate(row.published_at),
+    providerMetadata: (row.provider_metadata ?? {}) as Record<string, unknown>,
+  };
+}
+
+function receiptFromRow(row: Row): StoredReceipt {
+  return {
+    id: String(row.id),
+    workspaceId: String(row.workspace_id),
+    attemptId: String(row.attempt_id),
+    remoteId: String(row.remote_id),
+    ...(row.remote_url === null || row.remote_url === undefined ? {} : { remoteUrl: String(row.remote_url) }),
+    ...(row.published_at === null || row.published_at === undefined ? {} : { publishedAt: toDate(row.published_at) }),
+    providerMetadata: (row.provider_metadata ?? {}) as Record<string, unknown>,
+    receivedAt: toDate(row.received_at),
+  };
+}
+
+function toDate(value: unknown): Date {
+  return value instanceof Date ? value : new Date(String(value));
+}
+
+function maxDate(a: Date, b: Date): Date {
+  return a.getTime() >= b.getTime() ? a : b;
+}
diff --git a/packages/publishing-execution/src/schema.ts b/packages/publishing-execution/src/schema.ts
new file mode 100644
index 0000000..15de165
--- /dev/null
+++ b/packages/publishing-execution/src/schema.ts
@@ -0,0 +1,12 @@
+import type { Pool } from "pg";
+/** No runtime DDL: code refuses an incomplete or incorrectly privileged schema. */
+export async function assertPublishingSchema(pool: Pool): Promise<void> {
+  const result = await pool.query<{ ready: boolean }>(`SELECT
+    EXISTS (SELECT 1 FROM schema_migrations WHERE name = '019_publishing_integration.sql')
+    AND EXISTS (SELECT 1 FROM information_schema.columns WHERE table_schema = 'public' AND table_name = 'publishing_attempts' AND column_name = 'first_dispatch_started_at')
+    AND (SELECT count(*) = 2 AND bool_and(relrowsecurity AND relforcerowsecurity) FROM pg_class WHERE oid IN ('publishing_attempts'::regclass, 'publishing_receipts'::regclass))
+    AND NOT EXISTS (SELECT 1 FROM pg_index WHERE indrelid IN ('publishing_attempts'::regclass, 'publishing_receipts'::regclass) AND NOT indisvalid)
+    AND current_user = 'sp_app'
+    AND NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = current_user AND (rolsuper OR rolbypassrls)) AS ready`);
+  if (result.rows[0]?.ready !== true) throw new Error("PUBLISHING_SCHEMA_NOT_READY");
+}
diff --git a/packages/publishing-execution/tsconfig.json b/packages/publishing-execution/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/publishing-execution/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/safe-content/README.md b/packages/safe-content/README.md
new file mode 100644
index 0000000..f6b85a8
--- /dev/null
+++ b/packages/safe-content/README.md
@@ -0,0 +1,40 @@
+# Safe content
+
+The only sanctioned way to render provider content (posts, bios, comments,
+messages, link previews, display names) in the web UI. Proposal §4.5.
+
+Provider text becomes a closed rich-text AST (`text`, `linebreak`, `emoji`,
+`link`, `mention`, `hashtag` inside `paragraph`s) before it reaches React. No
+node can hold HTML, attributes or styles.
+
+- `parsePlainText` handles plain provider text. `parseProviderHtml` handles the
+  Mastodon/PeerTube HTML subset. Neither renders HTML. `script`, `style`,
+  `iframe`, `svg`, `math`, `form`, `template` and similar elements are dropped
+  along with their content. Other tags are unwrapped to text.
+- Links must be absolute http(s) URLs with no credentials, checked by
+  `parseSafeHttpUrl`. Anything else stays as plain text that can't be clicked.
+  Hosts are shown in punycode, and the real host is shown when a link's label
+  doesn't start with it.
+- All media (`emoji`, preview images) goes through `toProxiedMediaUrl`
+  (default `/api/media-proxy?url=…`). The renderer drops any `src` that isn't
+  a canonical proxy URL.
+- Bidi override/isolate characters are stripped from all text. Display names
+  also lose zero-width characters, and `DisplayName` flags mixed-script names
+  that use look-alike letters.
+- Limits: 20k input chars, 2,000 nodes, nesting depth 32, 2,048-char URLs. The
+  tokenizer makes one forward pass, so its run time grows linearly with input
+  size.
+
+`@tactical-media-broadcast-hub/safe-content/react` exports `RichText`, `LinkPreviewCard`,
+`DisplayName` and `SafeLink`. They re-validate every prop with
+`coerceRichTextDocument`/`parseLinkPreview`, so an AST loaded from the DB or
+the network is as safe as a freshly parsed one.
+
+`@tactical-media-broadcast-hub/safe-content/eslint` exports `noRawHtmlSinks`, a flat-config
+block that bans `dangerouslySetInnerHTML`, `innerHTML`/`outerHTML`,
+`insertAdjacentHTML`, `document.write`, `DOMParser.parseFromString`, `eval`
+and `new Function` outside this package. Spread it into the root
+`eslint.config.mjs`.
+
+`@tactical-media-broadcast-hub/safe-content/corpus` exports the malicious-content corpus for
+`packages/testing` and the Playwright suites.
diff --git a/packages/safe-content/package.json b/packages/safe-content/package.json
new file mode 100644
index 0000000..e53e986
--- /dev/null
+++ b/packages/safe-content/package.json
@@ -0,0 +1,33 @@
+{
+  "name": "@tactical-media-broadcast-hub/safe-content",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react.js",
+    "./eslint": "./dist/eslint.js",
+    "./corpus": "./dist/corpus.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "@types/react": "^18.3.3",
+    "@types/react-dom": "^18.3.0",
+    "eslint": "^9.9.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/safe-content/src/ast.ts b/packages/safe-content/src/ast.ts
new file mode 100644
index 0000000..abfe01c
--- /dev/null
+++ b/packages/safe-content/src/ast.ts
@@ -0,0 +1,59 @@
+/**
+ * Closed rich-text AST for provider content (proposal §4.5 "rich content
+ * contract"). Nothing outside these node types can be rendered: there is no
+ * node that carries raw HTML, attributes, styles or arbitrary URLs.
+ *
+ * URL-bearing fields are only ever produced by `parseSafeHttpUrl` /
+ * `toProxiedMediaUrl`, and the renderer re-validates them, so an AST that was
+ * round-tripped through storage or the network cannot smuggle a bad scheme.
+ */
+
+export const RICH_TEXT_VERSION = 1 as const;
+
+export type TextNode = { readonly type: "text"; readonly text: string };
+export type LineBreakNode = { readonly type: "linebreak" };
+/** Custom emoji / emote. `src` is always a media-proxy URL, never the origin URL. */
+export type EmojiNode = { readonly type: "emoji"; readonly shortcode: string; readonly src: string };
+export type LinkNode = {
+  readonly type: "link";
+  /** Absolute http(s) URL, credential-free. */
+  readonly href: string;
+  /** ASCII (punycode) host of `href`, shown to the operator next to the label. */
+  readonly host: string;
+  readonly children: readonly (TextNode | EmojiNode)[];
+};
+export type MentionNode = {
+  readonly type: "mention";
+  /** Handle without the leading "@", e.g. `alice` or `alice@example.social`. */
+  readonly handle: string;
+  readonly href?: string;
+};
+export type HashtagNode = {
+  readonly type: "hashtag";
+  /** Tag without the leading "#". */
+  readonly tag: string;
+  readonly href?: string;
+};
+
+export type InlineNode = TextNode | LineBreakNode | EmojiNode | LinkNode | MentionNode | HashtagNode;
+
+export type ParagraphNode = { readonly type: "paragraph"; readonly children: readonly InlineNode[] };
+
+export type RichTextDocument = {
+  readonly type: "doc";
+  readonly version: typeof RICH_TEXT_VERSION;
+  readonly children: readonly ParagraphNode[];
+  /** True when input exceeded a length/node/depth limit and was cut. */
+  readonly truncated: boolean;
+};
+
+export type LinkPreview = {
+  readonly type: "linkPreview";
+  readonly href: string;
+  readonly host: string;
+  readonly title?: string;
+  readonly description?: string;
+  readonly siteName?: string;
+  /** Media-proxy URL for the preview image. */
+  readonly image?: string;
+};
diff --git a/packages/safe-content/src/builder.ts b/packages/safe-content/src/builder.ts
new file mode 100644
index 0000000..356fe51
--- /dev/null
+++ b/packages/safe-content/src/builder.ts
@@ -0,0 +1,175 @@
+import type { EmojiNode, InlineNode, LinkNode, ParagraphNode, RichTextDocument, TextNode } from "./ast.js";
+import { RICH_TEXT_VERSION } from "./ast.js";
+import { DEFAULT_LIMITS, type SafeContentLimits } from "./limits.js";
+import { neutralizeText } from "./text.js";
+import { DEFAULT_MEDIA_PROXY, parseSafeHttpUrl, toProxiedMediaUrl, type MediaProxyPolicy } from "./url.js";
+
+/** Provider-supplied custom emoji (Mastodon `emojis[]`, Twitch emote sets, …). */
+export type CustomEmoji = { readonly shortcode: string; readonly url: string };
+
+export type ParseOptions = {
+  readonly limits?: Partial<SafeContentLimits>;
+  readonly mediaProxy?: MediaProxyPolicy;
+  readonly emojis?: readonly CustomEmoji[];
+};
+
+const SHORTCODE = /^[A-Za-z0-9_+-]{1,64}$/;
+const SHORTCODE_IN_TEXT = /:([A-Za-z0-9_+-]{1,64}):/g;
+const MAX_EMOJIS = 500;
+
+export function normalizeHandle(raw: string): string | null {
+  const handle = neutralizeText(raw).trim().replace(/^@+/, "");
+  return /^[\p{L}\p{N}_.-]{1,64}(?:@[\p{L}\p{N}.-]{1,253})?$/u.test(handle) ? handle : null;
+}
+
+export function normalizeTag(raw: string): string | null {
+  const tag = neutralizeText(raw).trim().replace(/^#+/, "");
+  return /^[\p{L}\p{N}\p{M}_]{1,100}$/u.test(tag) ? tag : null;
+}
+
+/** Accumulates a document while enforcing node limits; every write is sanitised. */
+export class DocBuilder {
+  readonly limits: SafeContentLimits;
+  readonly mediaProxy: MediaProxyPolicy;
+  private readonly emojis = new Map<string, string>();
+  private readonly paragraphs: ParagraphNode[] = [];
+  private current: InlineNode[] = [];
+  private nodes = 0;
+  private chars = 0;
+  truncated = false;
+
+  constructor(options: ParseOptions = {}) {
+    this.limits = { ...DEFAULT_LIMITS, ...options.limits };
+    this.mediaProxy = options.mediaProxy ?? DEFAULT_MEDIA_PROXY;
+    for (const emoji of (options.emojis ?? []).slice(0, MAX_EMOJIS)) {
+      if (typeof emoji?.shortcode !== "string" || !SHORTCODE.test(emoji.shortcode)) continue;
+      const src = toProxiedMediaUrl(emoji.url, this.mediaProxy);
+      if (src) this.emojis.set(emoji.shortcode, src);
+    }
+  }
+
+  /** Clips raw input to the configured length, flagging truncation. */
+  clip(input: string): string {
+    if (input.length <= this.limits.maxInputLength) return input;
+    this.truncated = true;
+    return input.slice(0, this.limits.maxInputLength);
+  }
+
+  private take(): boolean {
+    if (this.nodes >= this.limits.maxNodes) {
+      this.truncated = true;
+      return false;
+    }
+    this.nodes++;
+    return true;
+  }
+
+  /** Splits text into text + emoji nodes. */
+  inlineText(raw: string): (TextNode | EmojiNode)[] {
+    let text = neutralizeText(raw);
+    // Total text budget; parse paths are already clipped, this bounds forged ASTs.
+    const room = this.limits.maxInputLength - this.chars;
+    if (text.length > room) {
+      this.truncated = true;
+      text = text.slice(0, Math.max(room, 0));
+    }
+    this.chars += text.length;
+    if (text === "") return [];
+    const out: (TextNode | EmojiNode)[] = [];
+    if (this.emojis.size === 0) return [{ type: "text", text }];
+    let last = 0;
+    for (const match of text.matchAll(SHORTCODE_IN_TEXT)) {
+      const shortcode = match[1] as string;
+      const src = this.emojis.get(shortcode);
+      if (!src) continue;
+      if (match.index > last) out.push({ type: "text", text: text.slice(last, match.index) });
+      out.push({ type: "emoji", shortcode, src });
+      last = match.index + match[0].length;
+    }
+    if (last < text.length) out.push({ type: "text", text: text.slice(last) });
+    return out;
+  }
+
+  private push(node: InlineNode): void {
+    const prev = this.current[this.current.length - 1];
+    if (node.type === "text" && prev?.type === "text") {
+      this.current[this.current.length - 1] = { type: "text", text: prev.text + node.text };
+      return;
+    }
+    if (this.take()) this.current.push(node);
+  }
+
+  /** Appends an already-sanitised text/emoji node. */
+  pushLeaf(node: TextNode | EmojiNode): void {
+    this.push(node);
+  }
+
+  text(raw: string): void {
+    for (const node of this.inlineText(raw)) this.push(node);
+  }
+
+  lineBreak(): void {
+    this.push({ type: "linebreak" });
+  }
+
+  /** Emits a link if `href` is safe, otherwise the label as inert text. */
+  link(href: string, label: readonly (TextNode | EmojiNode)[]): void {
+    const safe = parseSafeHttpUrl(href, this.limits.maxUrlLength);
+    if (!safe) {
+      for (const node of label) this.push(node);
+      return;
+    }
+    const children = label.length > 0 ? mergeText(label) : [{ type: "text" as const, text: safe.host }];
+    if (this.nodes + children.length > this.limits.maxNodes) {
+      this.truncated = true;
+      return;
+    }
+    this.nodes += children.length;
+    this.push({ type: "link", href: safe.href, host: safe.host, children } satisfies LinkNode);
+  }
+
+  mention(rawHandle: string, href?: string): void {
+    const handle = normalizeHandle(rawHandle);
+    if (!handle) return this.text(rawHandle);
+    const safe = href === undefined ? null : parseSafeHttpUrl(href, this.limits.maxUrlLength);
+    this.push(safe ? { type: "mention", handle, href: safe.href } : { type: "mention", handle });
+  }
+
+  hashtag(rawTag: string, href?: string): void {
+    const tag = normalizeTag(rawTag);
+    if (!tag) return this.text(rawTag);
+    const safe = href === undefined ? null : parseSafeHttpUrl(href, this.limits.maxUrlLength);
+    this.push(safe ? { type: "hashtag", tag, href: safe.href } : { type: "hashtag", tag });
+  }
+
+  endParagraph(): void {
+    const children = trimParagraph(this.current);
+    this.current = [];
+    // Not budgeted: each non-empty paragraph already holds >= 1 budgeted inline node.
+    if (children.length > 0) this.paragraphs.push({ type: "paragraph", children });
+  }
+
+  finish(): RichTextDocument {
+    this.endParagraph();
+    return { type: "doc", version: RICH_TEXT_VERSION, children: this.paragraphs, truncated: this.truncated };
+  }
+}
+
+function mergeText(nodes: readonly (TextNode | EmojiNode)[]): (TextNode | EmojiNode)[] {
+  const out: (TextNode | EmojiNode)[] = [];
+  for (const node of nodes) {
+    const prev = out[out.length - 1];
+    if (node.type === "text" && prev?.type === "text") out[out.length - 1] = { type: "text", text: prev.text + node.text };
+    else out.push(node);
+  }
+  return out;
+}
+
+function trimParagraph(nodes: InlineNode[]): InlineNode[] {
+  let start = 0;
+  let end = nodes.length;
+  const blank = (n: InlineNode | undefined) => n?.type === "linebreak" || (n?.type === "text" && n.text.trim() === "");
+  while (start < end && blank(nodes[start])) start++;
+  while (end > start && blank(nodes[end - 1])) end--;
+  return nodes.slice(start, end);
+}
diff --git a/packages/safe-content/src/corpus.test.tsx b/packages/safe-content/src/corpus.test.tsx
new file mode 100644
index 0000000..650e6be
--- /dev/null
+++ b/packages/safe-content/src/corpus.test.tsx
@@ -0,0 +1,207 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { ATTACKER_ORIGIN, FORGED_DOCUMENTS, MALICIOUS_HTML, MALICIOUS_LINK_PREVIEWS, MALICIOUS_PLAIN } from "./corpus.js";
+import { parseProviderHtml } from "./html.js";
+import { parsePlainText } from "./plain.js";
+import { DisplayName, LinkPreviewCard, RichText } from "./react.js";
+import { parseSafeHttpUrl } from "./url.js";
+
+const PROXY_PREFIX = "/api/media-proxy?url=";
+const ALLOWED_TAGS = new Set(["div", "p", "a", "span", "br", "img", "strong", "bdi"]);
+const ALLOWED_ATTRS = new Set([
+  "class", "dir", "href", "rel", "target", "referrerpolicy", "src", "alt", "title",
+  "loading", "decoding", "draggable", "data-truncated", "data-confusable",
+]);
+
+function unescapeAttr(value: string): string {
+  return value.replace(/&quot;/g, '"').replace(/&#x27;/g, "'").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
+
+/**
+ * Asserts rendered markup is inert: only allowlisted tags/attributes, every
+ * href an absolute credential-free http(s) URL with the safe rel, every src
+ * routed through the media proxy (so nothing is fetched from an attacker
+ * origin), and no text that the browser could re-parse as markup.
+ */
+function assertInert(html: string): void {
+  const tagRe = /<(\/?)([a-zA-Z][a-zA-Z0-9-]*)((?:\s+[a-zA-Z-]+(?:="[^"]*")?)*)\s*\/?>/g;
+  const stripped = html.replace(tagRe, "");
+  // Anything left that looks like a tag would mean unescaped markup leaked out.
+  expect(stripped).not.toMatch(/<[a-zA-Z!/?]/);
+  for (const match of html.matchAll(tagRe)) {
+    const [, closing, tag, attrs = ""] = match;
+    if (closing) {
+      expect(attrs.trim()).toBe("");
+      continue;
+    }
+    expect(ALLOWED_TAGS, `tag <${tag}> in ${html}`).toContain(tag!.toLowerCase());
+    const attrMap = new Map<string, string>();
+    for (const attr of attrs.matchAll(/([a-zA-Z-]+)(?:="([^"]*)")?/g)) {
+      const name = attr[1]!.toLowerCase();
+      const value = unescapeAttr(attr[2] ?? "");
+      expect(ALLOWED_ATTRS, `attribute ${name} in ${html}`).toContain(name);
+      expect(name).not.toMatch(/^on/);
+      attrMap.set(name, value);
+      if (name === "href") {
+        expect(value).toMatch(/^https?:\/\/[^/]/);
+        expect(parseSafeHttpUrl(value)?.href).toBe(value);
+      }
+      if (name === "src") {
+        expect(value.startsWith(PROXY_PREFIX), `src ${value}`).toBe(true);
+        expect(value).not.toMatch(/^\/\//);
+      }
+      if (name !== "href" && name !== "src") expect(value).not.toMatch(/(javascript|vbscript|data):/i);
+    }
+    if (tag === "a") {
+      expect(attrMap.get("rel")).toBe("noopener noreferrer nofollow ugc");
+      expect(attrMap.get("referrerpolicy")).toBe("no-referrer");
+    }
+    if (tag === "img") expect(attrMap.get("referrerpolicy")).toBe("no-referrer");
+  }
+  expect(html).not.toMatch(/dangerouslySetInnerHTML|srcset|srcdoc|style=/i);
+}
+
+/** Every request-causing attribute (src) targets our own origin only. */
+function assertNoAttackerRequests(html: string): void {
+  for (const m of html.matchAll(/\ssrc="([^"]*)"/g)) {
+    expect(m[1]!.startsWith(PROXY_PREFIX)).toBe(true);
+  }
+  expect(html).not.toMatch(new RegExp(`src="https?://[^"]*${ATTACKER_ORIGIN.replace(".", "\\.")}`));
+}
+
+const emojis = [
+  { shortcode: "blobcat", url: "https://cdn.ok.example/blobcat.png" },
+  { shortcode: "evil", url: "javascript:alert(1)" },
+  { shortcode: "x\" onerror=\"alert(1)", url: "https://cdn.ok.example/x.png" },
+];
+
+describe("malicious HTML corpus", () => {
+  it.each(MALICIOUS_HTML.map((p) => [p]))("renders inert: %s", (payload) => {
+    const doc = parseProviderHtml(payload, { emojis });
+    const html = renderToStaticMarkup(<RichText doc={doc} />);
+    assertInert(html);
+    assertNoAttackerRequests(html);
+    expect(JSON.stringify(doc)).not.toMatch(/javascript:|vbscript:|"data:/i);
+  });
+
+  it("drops script/style/iframe content rather than showing it", () => {
+    const html = renderToStaticMarkup(
+      <RichText doc={parseProviderHtml("<p>a<script>alert(1)</script>b<style>x{}</style>c<iframe>d</iframe>e<svg><text>f</text></svg>g</p>")} />,
+    );
+    expect(html).toBe('<div dir="auto"><p dir="auto">abceg</p></div>');
+  });
+
+  it("renders unsafe-scheme links as non-clickable text", () => {
+    for (const href of ["javascript:alert(1)", "data:text/html,x", "vbscript:x", "//evil.example/", "https://u:p@evil.example/", "file:///etc/passwd"]) {
+      const html = renderToStaticMarkup(<RichText doc={parseProviderHtml(`<a href="${href}">label</a>`)} />);
+      expect(html).toBe('<div dir="auto"><p dir="auto">label</p></div>');
+    }
+  });
+
+  it("shows the real destination host when the label names another host", () => {
+    const html = renderToStaticMarkup(<RichText doc={parseProviderHtml('<a href="https://evil.example/login">https://bank.example/login</a>')} />);
+    expect(html).toContain('<span class="sc-link-host"> (evil.example)</span>');
+  });
+
+  it("exposes homoglyph IDN hosts as punycode", () => {
+    const doc = parseProviderHtml('<a href="https://pаypal.com/">paypal.com</a>');
+    const link = doc.children[0]!.children[0]!;
+    expect(link).toMatchObject({ type: "link", host: "xn--pypal-4ve.com" });
+    expect(renderToStaticMarkup(<RichText doc={doc} />)).toContain("(xn--pypal-4ve.com)");
+  });
+
+  it("strips bidi overrides and isolates from body text", () => {
+    const doc = parseProviderHtml("<p>file‮gnp.exe ⁦x⁩</p>");
+    expect(JSON.stringify(doc)).not.toMatch(/[‪-‮⁦-⁩]/);
+  });
+
+  it("emits entity-encoded markup only as escaped text", () => {
+    const html = renderToStaticMarkup(<RichText doc={parseProviderHtml("&lt;script&gt;alert(1)&lt;/script&gt;")} />);
+    expect(html).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
+  });
+});
+
+describe("malicious plain-text corpus", () => {
+  it.each(MALICIOUS_PLAIN.map((p) => [p]))("renders inert: %s", (payload) => {
+    const html = renderToStaticMarkup(<RichText doc={parsePlainText(payload, { emojis })} />);
+    assertInert(html);
+    assertNoAttackerRequests(html);
+  });
+
+  it("never links javascript:/data: or protocol-relative text", () => {
+    const html = renderToStaticMarkup(<RichText doc={parsePlainText("javascript:alert(1) data:text/html,x //evil.example/x")} />);
+    expect(html).not.toContain("<a");
+  });
+});
+
+describe("link-preview payloads", () => {
+  it.each(MALICIOUS_LINK_PREVIEWS.map((p, i) => [i, p]))("renders inert: #%s", (_i, preview) => {
+    const html = renderToStaticMarkup(<LinkPreviewCard preview={preview} />);
+    assertInert(html);
+    assertNoAttackerRequests(html);
+  });
+
+  it("rejects unsafe targets entirely", () => {
+    expect(renderToStaticMarkup(<LinkPreviewCard preview={{ url: "javascript:alert(1)", title: "x" }} />)).toBe("");
+  });
+
+  it("routes preview images through the media proxy", () => {
+    const html = renderToStaticMarkup(<LinkPreviewCard preview={{ url: "https://ok.example/", image: "https://evil.example/og.png" }} />);
+    expect(html).toContain(`src="${PROXY_PREFIX}https%3A%2F%2Fevil.example%2Fog.png"`);
+  });
+
+  it("caps preview text length", () => {
+    const html = renderToStaticMarkup(<LinkPreviewCard preview={{ url: "https://ok.example/", title: "x".repeat(100_000) }} />);
+    expect(html.length).toBeLessThan(2_000);
+  });
+});
+
+describe("forged ASTs", () => {
+  it.each(FORGED_DOCUMENTS.map((d, i) => [i, d]))("are re-validated at render: #%s", (_i, doc) => {
+    const html = renderToStaticMarkup(<RichText doc={doc} />);
+    assertInert(html);
+    assertNoAttackerRequests(html);
+    expect(html).not.toMatch(/<[^>]*onerror/i);
+  });
+});
+
+describe("display names", () => {
+  it("removes bidi and zero-width spoofing characters", () => {
+    const html = renderToStaticMarkup(<DisplayName name={"ad​min‮nimda <script>"} />);
+    expect(html).toBe("<bdi>adminnimda &lt;script&gt;</bdi>");
+  });
+
+  it("flags mixed-script homoglyph names", () => {
+    expect(renderToStaticMarkup(<DisplayName name={"pаypal"} />)).toContain('data-confusable="true"');
+    expect(renderToStaticMarkup(<DisplayName name="paypal" />)).not.toContain("data-confusable");
+  });
+});
+
+describe("huge and deeply nested input", () => {
+  const cases: [string, string][] = [
+    ["1MB of '<'", "<".repeat(1_000_000)],
+    ["unterminated attribute", "<a href=\"" + "x".repeat(1_000_000)],
+    ["100k nested divs", "<div>".repeat(100_000) + "deep" + "</div>".repeat(100_000)],
+    ["100k nested svg", "<svg>".repeat(100_000) + "<img src=x onerror=alert(1)>"],
+    ["50k links", '<a href="https://ok.example/">x</a>'.repeat(50_000)],
+    ["comment bomb", "<!--".repeat(200_000)],
+    ["attribute flood", "<a " + "x=1 ".repeat(200_000) + 'href="https://ok.example/">x</a>'],
+    ["unclosed raw text", "<script>" + "a".repeat(1_000_000)],
+  ];
+
+  it.each(cases)("%s: bounded time and output, inert", (_name, payload) => {
+    const start = performance.now();
+    const doc = parseProviderHtml(payload);
+    const html = renderToStaticMarkup(<RichText doc={doc} />);
+    expect(performance.now() - start).toBeLessThan(2_000);
+    expect(html.length).toBeLessThan(200_000);
+    assertInert(html);
+    expect(doc.truncated).toBe(true);
+  });
+
+  it("plain text: huge input is clipped", () => {
+    const doc = parsePlainText("https://ok.example/ @a #b\n".repeat(200_000));
+    expect(doc.truncated).toBe(true);
+    assertInert(renderToStaticMarkup(<RichText doc={doc} />));
+  });
+});
diff --git a/packages/safe-content/src/corpus.ts b/packages/safe-content/src/corpus.ts
new file mode 100644
index 0000000..ac9a136
--- /dev/null
+++ b/packages/safe-content/src/corpus.ts
@@ -0,0 +1,140 @@
+/**
+ * Malicious provider-content corpus (proposal §4.5 acceptance). Exported so
+ * `packages/testing` and the Playwright suites can replay the same payloads
+ * through connector mocks.
+ */
+export const ATTACKER_ORIGIN = "evil.example";
+
+export const MALICIOUS_HTML: readonly string[] = [
+  // Script injection
+  "<script>alert(1)</script>",
+  "<SCRIPT SRC=//evil.example/x.js></SCRIPT>",
+  "<script src=https://evil.example/x.js>",
+  "<scr<script>ipt>alert(1)</scr</script>ipt>",
+  "<<script>script>alert(1)<</script>/script>",
+  "<p>hi<script>alert(1)</p>",
+  "<plaintext><script>alert(1)</script>",
+  // Event handlers / attributes
+  "<img src=x onerror=alert(1)>",
+  "<img src=\"https://evil.example/pixel.gif\">",
+  "<img srcset=\"https://evil.example/a.png 1x\" alt=\"pic\">",
+  "<svg onload=alert(1)>",
+  "<svg><script>alert(1)</script><a xlink:href=\"javascript:alert(1)\">x</a></svg>",
+  "<body onload=alert(1)>",
+  "<p onclick=\"alert(1)\" style=\"background:url(https://evil.example/t.png)\">click</p>",
+  "<a href=\"https://ok.example/\" onclick=\"alert(1)\" onmouseover=alert(1) style=\"position:fixed\">ok</a>",
+  "<div style=\"background-image:url('https://evil.example/t.png')\">css</div>",
+  "<details open ontoggle=alert(1)>",
+  "<input autofocus onfocus=alert(1)>",
+  "<video><source onerror=alert(1)></video>",
+  "<marquee onstart=alert(1)>x</marquee>",
+  // Dangerous schemes
+  "<a href=\"javascript:alert(1)\">x</a>",
+  "<a href=\"JaVaScRiPt:alert(1)\">x</a>",
+  "<a href=\" javascript:alert(1)\">x</a>",
+  "<a href=\"java&#x09;script:alert(1)\">x</a>",
+  "<a href=\"java\tscript:alert(1)\">x</a>",
+  "<a href=\"&#106;&#97;&#118;&#97;&#115;&#99;&#114;&#105;&#112;&#116;&#58;alert(1)\">x</a>",
+  "<a href=\"&#x6A;avascript&colon;alert(1)\">x</a>",
+  "<a href=\"data:text/html;base64,PHNjcmlwdD5hbGVydCgxKTwvc2NyaXB0Pg==\">x</a>",
+  "<a href=\"vbscript:msgbox(1)\">x</a>",
+  "<a href=\"file:///etc/passwd\">x</a>",
+  "<a href=\"//evil.example/x\">x</a>",
+  "<a href=\"/\\evil.example/x\">x</a>",
+  "<a href=\"https:evil.example\">x</a>",
+  "<a href=\"https://user:pass@evil.example/\">creds</a>",
+  "<a href=\"https://ok.example@evil.example/\">at-trick</a>",
+  // Container elements
+  "<iframe src=\"https://evil.example/\"></iframe>",
+  "<iframe srcdoc=\"<script>alert(1)</script>\"></iframe>",
+  "<object data=\"https://evil.example/x.swf\"></object>",
+  "<embed src=\"https://evil.example/x.swf\">",
+  "<form action=\"https://evil.example/\"><input name=x><button>go</button></form>",
+  "<base href=\"https://evil.example/\">",
+  "<meta http-equiv=\"refresh\" content=\"0;url=https://evil.example/\">",
+  "<link rel=stylesheet href=\"https://evil.example/x.css\">",
+  "<style>@import 'https://evil.example/x.css'; body{background:url(https://evil.example/t.png)}</style>",
+  "<math><mtext><table><mglyph><style><img src=x onerror=alert(1)>",
+  "<noscript><p title=\"</noscript><img src=x onerror=alert(1)>\">",
+  "<textarea><img src=x onerror=alert(1)></textarea>",
+  "<template><img src=x onerror=alert(1)></template>",
+  "<svg><foreignObject><iframe src=javascript:alert(1)></iframe></foreignObject></svg>",
+  // Encoding / comment / malformed evasions
+  "&lt;script&gt;alert(1)&lt;/script&gt;",
+  "<!--<script>alert(1)</script>-->",
+  "<!--><img src=x onerror=alert(1)>-->",
+  "<![CDATA[<script>alert(1)</script>]]>",
+  "<?xml-stylesheet href=\"https://evil.example/x.xsl\"?>",
+  "<a href=\"https://ok.example/\"<script>alert(1)</script>",
+  "<a href=\"https://ok.example/",
+  "<a href='https://ok.example/' title='\"><script>alert(1)</script>'>quotes</a>",
+  "<a href=https://ok.example/ ><img src=x onerror=alert(1)></a>",
+  "</p></a></div></span><img src=x onerror=alert(1)>",
+  "<a href=\"https://ok.example/\"><a href=\"javascript:alert(1)\">nested</a></a>",
+  "<span class=\"invisible\"><script>alert(1)</script></span>",
+  // Spoofing
+  "<a href=\"https://evil.example/login\">https://bank.example/login</a>",
+  "<a href=\"https://pаypal.com/\">paypal.com</a>",
+  "<p>file‮gnp.exe and zero​width⁦isolate⁩</p>",
+];
+
+export const MALICIOUS_PLAIN: readonly string[] = [
+  "<script>alert(1)</script>",
+  "<img src=x onerror=alert(1)>",
+  "javascript:alert(1)",
+  "click javascript://%0aalert(1) now",
+  "data:text/html,<script>alert(1)</script>",
+  "https://evil.example/\"><script>alert(1)</script>",
+  "see https://user:pass@evil.example/ and //evil.example",
+  "@alice@evil.example #tag <b>bold</b>",
+  "‮txt.exe ​‍",
+  "&lt;script&gt;",
+];
+
+export const MALICIOUS_LINK_PREVIEWS: readonly unknown[] = [
+  { url: "javascript:alert(1)", title: "x" },
+  { url: "data:text/html,<script>alert(1)</script>", title: "x" },
+  { url: "//evil.example/", title: "protocol-relative" },
+  { url: "https://ok.example/", title: "<script>alert(1)</script>", description: "<img src=x onerror=alert(1)>", image: "https://evil.example/og.png" },
+  { url: "https://ok.example/", image: "javascript:alert(1)" },
+  { url: "https://ok.example/", image: "data:image/svg+xml,<svg onload=alert(1)>" },
+  { url: "https://ok.example/", image: "//evil.example/og.png" },
+  { url: "https://ok.example/", siteName: "‮lapyap", title: "x".repeat(100_000) },
+  { type: "linkPreview", href: "javascript:alert(1)", host: "ok.example" },
+  { type: "linkPreview", href: "https://ok.example/", host: "ok.example", image: "https://evil.example/direct.png" },
+  { url: { toString: () => "javascript:alert(1)" } },
+  null,
+  "https://ok.example/",
+];
+
+/** Hand-forged ASTs, as if from a tampered DB row or websocket frame. */
+export const FORGED_DOCUMENTS: readonly unknown[] = [
+  {
+    type: "doc",
+    version: 1,
+    truncated: false,
+    children: [
+      {
+        type: "paragraph",
+        children: [
+          { type: "link", href: "javascript:alert(1)", host: "ok.example", children: [{ type: "text", text: "x" }] },
+          { type: "link", href: "https://ok.example/", host: "ok.example", children: [{ type: "html", html: "<script>alert(1)</script>" }] },
+          { type: "emoji", shortcode: "x", src: "https://evil.example/e.png" },
+          { type: "emoji", shortcode: "x", src: "/api/media-proxy?url=javascript%3Aalert(1)" },
+          { type: "emoji", shortcode: "x\"onerror=alert(1)", src: "/api/media-proxy?url=https%3A%2F%2Fok.example%2Fe.png" },
+          { type: "html", html: "<img src=x onerror=alert(1)>" },
+          { type: "text", text: "<img src=x onerror=alert(1)>" },
+          { type: "mention", handle: "x\"><script>", href: "javascript:alert(1)" },
+          { type: "hashtag", tag: "ok", href: "data:text/html,x" },
+          { type: "text", text: { toString: () => "<script>" } },
+        ],
+      },
+      { type: "script", children: [] },
+      "<script>alert(1)</script>",
+    ],
+  },
+  { type: "doc", children: "nope" },
+  "<script>alert(1)</script>",
+  null,
+  [],
+];
diff --git a/packages/safe-content/src/entities.ts b/packages/safe-content/src/entities.ts
new file mode 100644
index 0000000..04d5e8a
--- /dev/null
+++ b/packages/safe-content/src/entities.ts
@@ -0,0 +1,18 @@
+const NAMED: Record<string, string> = {
+  amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: "\u00A0",
+  hellip: "…", mdash: "—", ndash: "–", lsquo: "‘", rsquo: "’", ldquo: "“", rdquo: "”",
+  copy: "©", reg: "®", trade: "™", laquo: "«", raquo: "»", middot: "·", bull: "•",
+};
+
+/** Decodes HTML character references to plain text. Output is still only ever a React text node. */
+export function decodeEntities(input: string): string {
+  if (!input.includes("&")) return input;
+  return input.replace(/&(?:#[xX]([0-9a-fA-F]{1,8})|#([0-9]{1,10})|([A-Za-z]{2,8}));?/g, (whole, hex, dec, name) => {
+    if (hex !== undefined || dec !== undefined) {
+      const code = hex !== undefined ? parseInt(hex, 16) : parseInt(dec, 10);
+      if (code === 0 || code > 0x10ffff || (code >= 0xd800 && code <= 0xdfff)) return "�";
+      return String.fromCodePoint(code);
+    }
+    return Object.hasOwn(NAMED, name) && whole.endsWith(";") ? (NAMED[name] as string) : whole;
+  });
+}
diff --git a/packages/safe-content/src/eslint.ts b/packages/safe-content/src/eslint.ts
new file mode 100644
index 0000000..7f4c985
--- /dev/null
+++ b/packages/safe-content/src/eslint.ts
@@ -0,0 +1,31 @@
+/**
+ * Flat-config block banning raw-HTML sinks (proposal §4.5 (1)). Spread it into
+ * the root `eslint.config.mjs`; `packages/safe-content/**` is the only
+ * sanctioned renderer and is excluded via `ignores`.
+ *
+ *   import { noRawHtmlSinks } from "@tactical-media-broadcast-hub/safe-content/eslint";
+ *   export default tseslint.config(..., noRawHtmlSinks);
+ */
+const MESSAGE = "Raw HTML sink — render provider content only through @tactical-media-broadcast-hub/safe-content (proposal §4.5).";
+
+export const RAW_HTML_SINK_SELECTORS: readonly string[] = [
+  "JSXAttribute[name.name='dangerouslySetInnerHTML']",
+  "Property[key.name='dangerouslySetInnerHTML']",
+  "AssignmentExpression > MemberExpression.left[property.name=/^(innerHTML|outerHTML)$/]",
+  "CallExpression[callee.property.name=/^(insertAdjacentHTML|createContextualFragment|parseFromString|setHTMLUnsafe)$/]",
+  "CallExpression[callee.object.name='document'][callee.property.name=/^(write|writeln)$/]",
+  "NewExpression[callee.name='Function']",
+  "CallExpression[callee.name='eval']",
+];
+
+export const noRawHtmlSinks: {
+  files: string[];
+  ignores: string[];
+  rules: { "no-restricted-syntax": ["error", ...{ selector: string; message: string }[]] };
+} = {
+  files: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"],
+  ignores: ["packages/safe-content/**"],
+  rules: {
+    "no-restricted-syntax": ["error", ...RAW_HTML_SINK_SELECTORS.map((selector) => ({ selector, message: MESSAGE }))],
+  },
+};
diff --git a/packages/safe-content/src/html.ts b/packages/safe-content/src/html.ts
new file mode 100644
index 0000000..a84a5e8
--- /dev/null
+++ b/packages/safe-content/src/html.ts
@@ -0,0 +1,269 @@
+import type { EmojiNode, RichTextDocument, TextNode } from "./ast.js";
+import { DocBuilder, type ParseOptions } from "./builder.js";
+import { decodeEntities } from "./entities.js";
+
+/*
+ * Converts the Mastodon/PeerTube HTML subset into the rich-text AST. This is
+ * a converter, not an HTML renderer: no tag or attribute survives as markup.
+ * Recognised structure (p, br, a, Mastodon mention/hashtag/invisible/ellipsis
+ * spans) maps to AST nodes; dangerous containers are dropped with their
+ * content; every other tag is unwrapped to its text. The tokenizer is a single
+ * forward scan (no regex backtracking), so huge or malformed input is linear.
+ */
+
+/** Element content parsed as raw text by browsers; skipped up to the matching end tag. */
+const RAW_TEXT = new Set(["script", "style", "textarea", "title", "xmp", "iframe", "noembed", "noframes", "noscript"]);
+/** Elements whose entire content is discarded. */
+const DROP_CONTENT = new Set([
+  "svg", "math", "template", "object", "embed", "applet", "frame", "frameset", "head", "select", "option",
+  "form", "button", "audio", "video", "canvas", "map", "picture", "source", "track", "dialog", "portal",
+]);
+const VOID = new Set(["area", "base", "br", "col", "embed", "hr", "img", "input", "link", "meta", "param", "source", "track", "wbr"]);
+const PARAGRAPH = new Set([
+  "p", "div", "blockquote", "pre", "ul", "ol", "li", "h1", "h2", "h3", "h4", "h5", "h6",
+  "section", "article", "header", "footer", "aside", "table", "tr", "dl", "dt", "dd", "figure", "figcaption", "hr",
+]);
+
+type Token =
+  | { kind: "text"; text: string }
+  | { kind: "start"; name: string; attrs: Map<string, string>; selfClosing: boolean }
+  | { kind: "end"; name: string };
+
+const MAX_ATTRS = 16;
+
+function isAlpha(c: number): boolean {
+  return (c >= 65 && c <= 90) || (c >= 97 && c <= 122);
+}
+function isSpace(c: number): boolean {
+  return c === 32 || c === 9 || c === 10 || c === 12 || c === 13;
+}
+
+function* tokenize(src: string): Generator<Token> {
+  const lower = src.toLowerCase();
+  const n = src.length;
+  let i = 0;
+  while (i < n) {
+    const lt = src.indexOf("<", i);
+    if (lt === -1) {
+      yield { kind: "text", text: src.slice(i) };
+      return;
+    }
+    if (lt > i) yield { kind: "text", text: src.slice(i, lt) };
+    i = lt;
+    const next = src.charCodeAt(i + 1);
+    if (src.startsWith("<!--", i)) {
+      const close = src.indexOf("-->", i + 4);
+      i = close === -1 ? n : close + 3;
+      continue;
+    }
+    if (next === 33 /* ! */ || next === 63 /* ? */ || src.startsWith("</>", i)) {
+      // Bogus comment / doctype / processing instruction / "</>".
+      const close = src.indexOf(">", i + 1);
+      i = close === -1 ? n : close + 1;
+      continue;
+    }
+    const isEnd = next === 47;
+    const nameStart = isEnd ? i + 2 : i + 1;
+    if (!isAlpha(src.charCodeAt(nameStart))) {
+      yield { kind: "text", text: "<" };
+      i++;
+      continue;
+    }
+    let j = nameStart;
+    while (j < n && !isSpace(src.charCodeAt(j)) && src[j] !== "/" && src[j] !== ">") j++;
+    const name = lower.slice(nameStart, j);
+    // Attributes: name[=value], value quoted or unquoted.
+    const attrs = new Map<string, string>();
+    let selfClosing = false;
+    while (j < n && src[j] !== ">") {
+      const c = src.charCodeAt(j);
+      if (isSpace(c)) { j++; continue; }
+      if (src[j] === "/") { selfClosing = true; j++; continue; }
+      selfClosing = false;
+      const an = j;
+      while (j < n && !isSpace(src.charCodeAt(j)) && src[j] !== "/" && src[j] !== ">" && src[j] !== "=") j++;
+      if (j === an) j++; // stray "=": consume to guarantee progress
+      const attrName = lower.slice(an, j);
+      let value = "";
+      while (j < n && isSpace(src.charCodeAt(j))) j++;
+      if (src[j] === "=") {
+        j++;
+        while (j < n && isSpace(src.charCodeAt(j))) j++;
+        const q = src[j];
+        if (q === '"' || q === "'") {
+          const close = src.indexOf(q, j + 1);
+          const end = close === -1 ? n : close;
+          value = src.slice(j + 1, end);
+          j = end + 1;
+        } else {
+          const vs = j;
+          while (j < n && !isSpace(src.charCodeAt(j)) && src[j] !== ">") j++;
+          value = src.slice(vs, j);
+        }
+      }
+      if (attrName && !attrs.has(attrName) && attrs.size < MAX_ATTRS) attrs.set(attrName, decodeEntities(value));
+    }
+    i = j + 1;
+    if (isEnd) {
+      yield { kind: "end", name };
+      continue;
+    }
+    if (name === "plaintext") return;
+    if (RAW_TEXT.has(name)) {
+      const close = lower.indexOf("</" + name, i);
+      i = close === -1 ? n : (() => {
+        const gt = src.indexOf(">", close);
+        return gt === -1 ? n : gt + 1;
+      })();
+      continue;
+    }
+    yield { kind: "start", name, attrs, selfClosing };
+  }
+}
+
+type Frame = { name: string; role: "drop" | "link" | "invisible" | "ellipsis" | "other" };
+
+type OpenLink = { href: string; classes: Set<string>; rel: Set<string>; label: (TextNode | EmojiNode)[] };
+
+function words(value: string | undefined): Set<string> {
+  return new Set((value ?? "").toLowerCase().split(/\s+/).filter(Boolean));
+}
+
+/** Mastodon/PeerTube-style HTML → rich-text AST. */
+export function parseProviderHtml(input: unknown, options: ParseOptions = {}): RichTextDocument {
+  const builder = new DocBuilder(options);
+  if (typeof input !== "string") return builder.finish();
+  const src = builder.clip(input);
+  const stack: Frame[] = [];
+  let dropDepth = 0;
+  let invisibleDepth = 0;
+  let link: OpenLink | null = null;
+
+  const flushLink = () => {
+    if (!link) return;
+    const current = link;
+    link = null;
+    const labelText = current.label.map((n) => (n.type === "text" ? n.text : `:${n.shortcode}:`)).join("").trim();
+    if (current.classes.has("mention") && (current.classes.has("hashtag") || current.rel.has("tag"))) {
+      builder.hashtag(labelText, current.href);
+    } else if (current.classes.has("mention")) {
+      builder.mention(handleFor(labelText, current.href), current.href);
+    } else {
+      builder.link(current.href, current.label);
+    }
+  };
+
+  const emitText = (raw: string) => {
+    if (dropDepth > 0) return;
+    if (link && invisibleDepth > 0) return;
+    const text = decodeEntities(raw).replace(/[\t\n\f\r ]+/g, " ");
+    if (link) link.label.push(...builder.inlineText(text));
+    else builder.text(text);
+  };
+
+  const close = (index: number) => {
+    while (stack.length > index) {
+      const frame = stack.pop() as Frame;
+      if (frame.role === "drop") dropDepth--;
+      else if (frame.role === "invisible") invisibleDepth--;
+      else if (frame.role === "ellipsis" && link && dropDepth === 0) link.label.push({ type: "text", text: "…" });
+      else if (frame.role === "link") flushLink();
+      if (PARAGRAPH.has(frame.name) && dropDepth === 0) {
+        flushLink();
+        builder.endParagraph();
+      }
+    }
+  };
+
+  for (const token of tokenize(src)) {
+    if (token.kind === "text") {
+      emitText(token.text);
+      continue;
+    }
+    if (token.kind === "end") {
+      if (token.name === "br" && dropDepth === 0) builder.lineBreak(); // "</br>" acts as <br> in browsers
+      for (let k = stack.length - 1; k >= 0; k--) {
+        const frame = stack[k] as Frame;
+        // Inside dropped content only the dropped elements' own end tags count.
+        if (frame.name === token.name && (dropDepth === 0 || frame.role === "drop")) {
+          close(k);
+          break;
+        }
+      }
+      continue;
+    }
+    const { name, attrs } = token;
+    if (dropDepth > 0) {
+      if (DROP_CONTENT.has(name) && !VOID.has(name) && !token.selfClosing && stack.length < builder.limits.maxDepth) {
+        stack.push({ name, role: "drop" });
+        dropDepth++;
+      }
+      continue;
+    }
+    if (name === "br") {
+      if (link) link.label.push({ type: "text", text: " " });
+      else builder.lineBreak();
+      continue;
+    }
+    if (name === "img") {
+      const alt = attrs.get("alt") ?? "";
+      if (alt) emitText(alt);
+      continue;
+    }
+    if (PARAGRAPH.has(name)) {
+      flushLink();
+      builder.endParagraph();
+    }
+    if (VOID.has(name) || token.selfClosing && !DROP_CONTENT.has(name) && name !== "a" && name !== "span") continue;
+    if (stack.length >= builder.limits.maxDepth) {
+      // Too deep: stop tracking structure, keep text (inert) and flag it.
+      builder.truncated = true;
+      if (DROP_CONTENT.has(name)) {
+        // Can't track the matching end tag any more; drop the rest of the input.
+        break;
+      }
+      continue;
+    }
+    if (DROP_CONTENT.has(name)) {
+      if (token.selfClosing) continue;
+      stack.push({ name, role: "drop" });
+      dropDepth++;
+      continue;
+    }
+    if (name === "a") {
+      flushLink();
+      link = { href: attrs.get("href") ?? "", classes: words(attrs.get("class")), rel: words(attrs.get("rel")), label: [] };
+      stack.push({ name, role: "link" });
+      continue;
+    }
+    if (name === "span" && link) {
+      const classes = words(attrs.get("class"));
+      if (classes.has("invisible")) {
+        invisibleDepth++;
+        stack.push({ name, role: "invisible" });
+        continue;
+      }
+      if (classes.has("ellipsis")) {
+        stack.push({ name, role: "ellipsis" });
+        continue;
+      }
+    }
+    stack.push({ name, role: "other" });
+  }
+  close(0);
+  flushLink();
+  return builder.finish();
+}
+
+/** Mastodon renders only the local username in mention text; qualify it with the href host. */
+function handleFor(label: string, href: string): string {
+  const handle = label.replace(/^@+/, "");
+  if (handle.includes("@")) return handle;
+  try {
+    const url = new URL(href);
+    if (url.protocol === "http:" || url.protocol === "https:") return `${handle}@${url.hostname}`;
+  } catch {
+    // fall through: unqualified handle
+  }
+  return handle;
+}
diff --git a/packages/safe-content/src/index.ts b/packages/safe-content/src/index.ts
new file mode 100644
index 0000000..1045cdb
--- /dev/null
+++ b/packages/safe-content/src/index.ts
@@ -0,0 +1,15 @@
+export * from "./ast.js";
+export { DEFAULT_LIMITS, LINK_PREVIEW_LIMITS, type SafeContentLimits } from "./limits.js";
+export { hasMixedScriptConfusables, neutralizeDisplayName, neutralizeText } from "./text.js";
+export {
+  DEFAULT_MEDIA_PROXY,
+  isProxiedMediaUrl,
+  parseSafeHttpUrl,
+  toProxiedMediaUrl,
+  type MediaProxyPolicy,
+  type SafeUrl,
+} from "./url.js";
+export type { CustomEmoji, ParseOptions } from "./builder.js";
+export { parsePlainText } from "./plain.js";
+export { parseProviderHtml } from "./html.js";
+export { coerceRichTextDocument, parseLinkPreview, type RawLinkPreview } from "./validate.js";
diff --git a/packages/safe-content/src/limits.ts b/packages/safe-content/src/limits.ts
new file mode 100644
index 0000000..986cb23
--- /dev/null
+++ b/packages/safe-content/src/limits.ts
@@ -0,0 +1,23 @@
+export type SafeContentLimits = {
+  /** Max input characters considered; the rest is dropped and `truncated` set. */
+  readonly maxInputLength: number;
+  /** Max element nesting tracked by the HTML parser; deeper structure is flattened to text. */
+  readonly maxDepth: number;
+  /** Max AST nodes emitted per document. */
+  readonly maxNodes: number;
+  /** Max characters in any single URL. */
+  readonly maxUrlLength: number;
+};
+
+export const DEFAULT_LIMITS: SafeContentLimits = {
+  maxInputLength: 20_000,
+  maxDepth: 32,
+  maxNodes: 2_000,
+  maxUrlLength: 2_048,
+};
+
+export const LINK_PREVIEW_LIMITS = {
+  title: 300,
+  description: 1_000,
+  siteName: 100,
+} as const;
diff --git a/packages/safe-content/src/parse.test.tsx b/packages/safe-content/src/parse.test.tsx
new file mode 100644
index 0000000..ea96503
--- /dev/null
+++ b/packages/safe-content/src/parse.test.tsx
@@ -0,0 +1,179 @@
+import { Linter } from "eslint";
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+import { noRawHtmlSinks } from "./eslint.js";
+import { parseProviderHtml } from "./html.js";
+import { parsePlainText } from "./plain.js";
+import { RichText } from "./react.js";
+import { isProxiedMediaUrl, parseSafeHttpUrl, toProxiedMediaUrl } from "./url.js";
+import { coerceRichTextDocument, parseLinkPreview } from "./validate.js";
+
+describe("Mastodon HTML", () => {
+  const status =
+    '<p><span class="h-card" translate="no"><a href="https://social.example/@alice" class="u-url mention">@<span>alice</span></a></span> ' +
+    'look :blobcat: <a href="https://social.example/tags/fediverse" class="mention hashtag" rel="tag">#<span>fediverse</span></a></p>' +
+    '<p>read <a href="https://news.example/articles/2026/very-long-path" target="_blank" rel="nofollow noopener noreferrer" translate="no">' +
+    '<span class="invisible">https://</span><span class="ellipsis">news.example/articles/2026/v</span><span class="invisible">ery-long-path</span></a><br>bye</p>';
+
+  it("maps mentions, hashtags, links, emoji and breaks to the AST", () => {
+    const doc = parseProviderHtml(status, { emojis: [{ shortcode: "blobcat", url: "https://cdn.example/blobcat.png" }] });
+    expect(doc).toEqual({
+      type: "doc",
+      version: 1,
+      truncated: false,
+      children: [
+        {
+          type: "paragraph",
+          children: [
+            { type: "mention", handle: "alice@social.example", href: "https://social.example/@alice" },
+            { type: "text", text: " look " },
+            { type: "emoji", shortcode: "blobcat", src: "/api/media-proxy?url=https%3A%2F%2Fcdn.example%2Fblobcat.png" },
+            { type: "text", text: " " },
+            { type: "hashtag", tag: "fediverse", href: "https://social.example/tags/fediverse" },
+          ],
+        },
+        {
+          type: "paragraph",
+          children: [
+            { type: "text", text: "read " },
+            {
+              type: "link",
+              href: "https://news.example/articles/2026/very-long-path",
+              host: "news.example",
+              children: [{ type: "text", text: "news.example/articles/2026/v…" }],
+            },
+            { type: "linebreak" },
+            { type: "text", text: "bye" },
+          ],
+        },
+      ],
+    });
+  });
+
+  it("renders the expected markup", () => {
+    const html = renderToStaticMarkup(<RichText doc={parseProviderHtml(status)} />);
+    expect(html).toContain('<a href="https://social.example/@alice" rel="noopener noreferrer nofollow ugc" target="_blank" referrerPolicy="no-referrer" class="sc-mention">@alice@social.example</a>');
+    expect(html).toContain(":blobcat:");
+    expect(html).not.toContain("sc-link-host");
+  });
+});
+
+describe("plain text", () => {
+  it("linkifies http(s) URLs, mentions, hashtags and newlines", () => {
+    const doc = parsePlainText("hi @bob@x.example see https://a.example/p?q=1. #tag\nline2\n\npara2");
+    expect(doc.children).toHaveLength(2);
+    expect(doc.children[0]!.children).toEqual([
+      { type: "text", text: "hi " },
+      { type: "mention", handle: "bob@x.example" },
+      { type: "text", text: " see " },
+      { type: "link", href: "https://a.example/p?q=1", host: "a.example", children: [{ type: "text", text: "a.example/p?q=1" }] },
+      { type: "text", text: ". " },
+      { type: "hashtag", tag: "tag" },
+      { type: "linebreak" },
+      { type: "text", text: "line2" },
+    ]);
+  });
+
+  it("ignores non-string input", () => {
+    expect(parsePlainText(42).children).toEqual([]);
+  });
+});
+
+describe("URL policy", () => {
+  it.each([
+    "javascript:alert(1)", " javascript:alert(1)", "JAVASCRIPT:alert(1)", "java\tscript:alert(1)", "data:text/html,x",
+    "vbscript:x", "file:///etc/passwd", "//evil.example", "/relative", "https:evil.example", "https:/evil.example",
+    "https://user@evil.example/", "https://:pw@evil.example/", "http://evil.example/\u0000", "https://evil.example/‮",
+    "ftp://evil.example/", "https://" + "a".repeat(3_000) + ".example/", "",
+  ])("rejects %j", (raw) => {
+    expect(parseSafeHttpUrl(raw)).toBeNull();
+  });
+
+  it("accepts http(s) and normalises", () => {
+    expect(parseSafeHttpUrl("HTTPS://Ok.Example/a b".replace(" ", "%20"))).toEqual({ href: "https://ok.example/a%20b", host: "ok.example" });
+  });
+
+  it("media proxy URLs are canonical and same-origin", () => {
+    const src = toProxiedMediaUrl("https://cdn.example/a.png");
+    expect(src).toBe("/api/media-proxy?url=https%3A%2F%2Fcdn.example%2Fa.png");
+    expect(isProxiedMediaUrl(src)).toBe(true);
+    expect(isProxiedMediaUrl("https://cdn.example/a.png")).toBe(false);
+    expect(isProxiedMediaUrl("/api/media-proxy?url=https://cdn.example/a.png")).toBe(false);
+    expect(isProxiedMediaUrl("/api/media-proxy?url=javascript%3Aalert(1)")).toBe(false);
+    expect(toProxiedMediaUrl("data:image/png;base64,AAAA")).toBeNull();
+    expect(() => toProxiedMediaUrl("https://cdn.example/a.png", { proxyPath: "//evil.example/p" })).toThrow();
+    expect(() => toProxiedMediaUrl("https://cdn.example/a.png", { proxyPath: "https://evil.example/p" })).toThrow();
+  });
+
+  it("supports a custom proxy path end to end", () => {
+    const mediaProxy = { proxyPath: "/media/p" };
+    const doc = parseProviderHtml("hi :e:", { mediaProxy, emojis: [{ shortcode: "e", url: "https://cdn.example/e.png" }] });
+    const html = renderToStaticMarkup(<RichText doc={doc} mediaProxy={mediaProxy} />);
+    expect(html).toContain('src="/media/p?url=https%3A%2F%2Fcdn.example%2Fe.png"');
+    // Same doc rendered against a different proxy: emoji degrades to text.
+    expect(renderToStaticMarkup(<RichText doc={doc} />)).not.toContain("<img");
+  });
+});
+
+describe("coerceRichTextDocument", () => {
+  it("round-trips a valid document unchanged", () => {
+    const doc = parseProviderHtml('<p>a <a href="https://ok.example/">ok.example</a> @x #y</p>');
+    expect(coerceRichTextDocument(JSON.parse(JSON.stringify(doc)))).toEqual(doc);
+  });
+
+  it("re-applies node limits", () => {
+    const forged = { type: "doc", children: [{ type: "paragraph", children: Array.from({ length: 10_000 }, (_, i) => (i % 2 ? { type: "linebreak" } : { type: "mention", handle: "a" })) }] };
+    const doc = coerceRichTextDocument(forged);
+    expect(doc.truncated).toBe(true);
+    expect(doc.children[0]!.children.length).toBeLessThanOrEqual(2_000);
+  });
+
+  it("bounds total text from forged nodes", () => {
+    const forged = { type: "doc", children: [{ type: "paragraph", children: [{ type: "text", text: "x".repeat(5_000_000) }] }] };
+    const doc = coerceRichTextDocument(forged);
+    expect(doc.truncated).toBe(true);
+    expect(JSON.stringify(doc).length).toBeLessThan(25_000);
+  });
+});
+
+describe("parseLinkPreview", () => {
+  it("builds a preview with proxied image and plain-text fields", () => {
+    expect(parseLinkPreview({ url: "https://ok.example/a", title: "A &amp; <b>B</b>", siteName: "Ok", image: "https://cdn.example/i.png" })).toEqual({
+      type: "linkPreview",
+      href: "https://ok.example/a",
+      host: "ok.example",
+      title: "A & <b>B</b>",
+      siteName: "Ok",
+      image: "/api/media-proxy?url=https%3A%2F%2Fcdn.example%2Fi.png",
+    });
+  });
+});
+
+describe("eslint raw-HTML sink rule", () => {
+  const linter = new Linter({ configType: "flat" });
+  const lint = (code: string) =>
+    linter.verify(code, [
+      {
+        languageOptions: { ecmaVersion: "latest", sourceType: "module", parserOptions: { ecmaFeatures: { jsx: true } } },
+        rules: noRawHtmlSinks.rules,
+      },
+    ]);
+
+  it.each([
+    "const x = <div dangerouslySetInnerHTML={{ __html: post.html }} />;",
+    "React.createElement('div', { dangerouslySetInnerHTML: { __html: s } });",
+    "el.innerHTML = s;",
+    "el.outerHTML = s;",
+    "el.insertAdjacentHTML('beforeend', s);",
+    "document.write(s);",
+    "new Function(s)();",
+    "eval(s);",
+    "new DOMParser().parseFromString(s, 'text/html');",
+  ])("flags %s", (code) => {
+    expect(lint(code).map((m) => m.ruleId)).toContain("no-restricted-syntax");
+  });
+
+  it("allows text rendering", () => {
+    expect(lint("const x = <div>{post.text}</div>; el.textContent = s;")).toEqual([]);
+  });
+});
diff --git a/packages/safe-content/src/plain.ts b/packages/safe-content/src/plain.ts
new file mode 100644
index 0000000..548bf85
--- /dev/null
+++ b/packages/safe-content/src/plain.ts
@@ -0,0 +1,44 @@
+import type { RichTextDocument } from "./ast.js";
+import { DocBuilder, type ParseOptions } from "./builder.js";
+
+// Single-pass, backtracking-safe token scan: URL | @mention | #hashtag.
+const TOKENS =
+  /(https?:\/\/[^\s<>"'`\u0000-\u001F]{1,2048})|(?<![\p{L}\p{N}_@])@([\p{L}\p{N}_.-]{1,64}(?:@[\p{L}\p{N}-]{1,63}(?:\.[\p{L}\p{N}-]{1,63}){0,8})?)|(?<![\p{L}\p{N}_#&])#([\p{L}\p{N}\p{M}_]{1,100})/gu;
+const TRAILING_PUNCT = /[.,;:!?)\]}'"»”’]+$/;
+
+function lineToNodes(builder: DocBuilder, line: string): void {
+  let last = 0;
+  for (const match of line.matchAll(TOKENS)) {
+    const [whole, url, handle, tag] = match;
+    let consumed = whole;
+    if (match.index > last) builder.text(line.slice(last, match.index));
+    if (url !== undefined) {
+      const trimmed = url.replace(TRAILING_PUNCT, "");
+      consumed = trimmed;
+      builder.link(trimmed, builder.inlineText(trimmed.replace(/^https?:\/\//i, "")));
+    } else if (handle !== undefined) {
+      const clean = handle.replace(/[.-]+$/, "");
+      consumed = "@" + clean;
+      builder.mention(clean);
+    } else if (tag !== undefined) {
+      builder.hashtag(tag);
+    }
+    last = match.index + consumed.length;
+  }
+  if (last < line.length) builder.text(line.slice(last));
+}
+
+/** Plain provider text (Bluesky, Telegram, bios, …): newlines, URLs, mentions, hashtags. */
+export function parsePlainText(input: unknown, options: ParseOptions = {}): RichTextDocument {
+  const builder = new DocBuilder(options);
+  if (typeof input !== "string") return builder.finish();
+  const text = builder.clip(input).replace(/\r\n?/g, "\n");
+  for (const paragraph of text.split(/\n{2,}/)) {
+    paragraph.split("\n").forEach((line, i) => {
+      if (i > 0) builder.lineBreak();
+      lineToNodes(builder, line);
+    });
+    builder.endParagraph();
+  }
+  return builder.finish();
+}
diff --git a/packages/safe-content/src/react.tsx b/packages/safe-content/src/react.tsx
new file mode 100644
index 0000000..88a2948
--- /dev/null
+++ b/packages/safe-content/src/react.tsx
@@ -0,0 +1,135 @@
+import type { ReactNode } from "react";
+import type { EmojiNode, InlineNode, LinkPreview, RichTextDocument, TextNode } from "./ast.js";
+import { neutralizeDisplayName, hasMixedScriptConfusables } from "./text.js";
+import { DEFAULT_MEDIA_PROXY, isProxiedMediaUrl, parseSafeHttpUrl, type MediaProxyPolicy } from "./url.js";
+import { coerceRichTextDocument, parseLinkPreview } from "./validate.js";
+
+/*
+ * The single reviewed renderer for provider content (proposal §4.5). Every
+ * provider string reaches the DOM as a React text node; the only attributes
+ * set from provider data are re-validated http(s) `href`s and media-proxy
+ * `src`s. No dangerouslySetInnerHTML, no style, no event handlers.
+ */
+
+export const EXTERNAL_LINK_REL = "noopener noreferrer nofollow ugc";
+
+type CommonProps = { readonly className?: string; readonly mediaProxy?: MediaProxyPolicy };
+
+export function SafeLink(props: { readonly href: string; readonly children?: ReactNode; readonly className?: string }): ReactNode {
+  const safe = parseSafeHttpUrl(props.href);
+  if (!safe) return <span className={props.className}>{props.children}</span>;
+  return (
+    <a href={safe.href} rel={EXTERNAL_LINK_REL} target="_blank" referrerPolicy="no-referrer" className={props.className}>
+      {props.children ?? safe.host}
+    </a>
+  );
+}
+
+function Emoji({ node, mediaProxy }: { node: EmojiNode; mediaProxy: MediaProxyPolicy }): ReactNode {
+  const label = `:${node.shortcode}:`;
+  if (!isProxiedMediaUrl(node.src, mediaProxy)) return label;
+  return (
+    <img
+      src={node.src}
+      alt={label}
+      title={label}
+      className="sc-emoji"
+      draggable={false}
+      loading="lazy"
+      decoding="async"
+      referrerPolicy="no-referrer"
+    />
+  );
+}
+
+function leaf(node: TextNode | EmojiNode, key: number, mediaProxy: MediaProxyPolicy): ReactNode {
+  return node.type === "text" ? node.text : <Emoji key={key} node={node} mediaProxy={mediaProxy} />;
+}
+
+function labelStartsWithHost(children: readonly (TextNode | EmojiNode)[], host: string): boolean {
+  const label = children
+    .map((c) => (c.type === "text" ? c.text : ""))
+    .join("")
+    .trim()
+    .toLowerCase()
+    .replace(/^https?:\/\//, "")
+    .replace(/^www\./, "");
+  const h = host.toLowerCase().replace(/^www\./, "");
+  return label === h || label.startsWith(h + "/") || label.startsWith(h + "?") || label.startsWith(h + "#") || label.startsWith(h + ":");
+}
+
+function inline(node: InlineNode, key: number, mediaProxy: MediaProxyPolicy): ReactNode {
+  switch (node.type) {
+    case "text":
+      return node.text;
+    case "linebreak":
+      return <br key={key} />;
+    case "emoji":
+      return <Emoji key={key} node={node} mediaProxy={mediaProxy} />;
+    case "link":
+      return (
+        <span key={key} className="sc-link">
+          <SafeLink href={node.href}>{node.children.map((c, i) => leaf(c, i, mediaProxy))}</SafeLink>
+          {/* The real destination host is always visible when the label could mislead. */}
+          {labelStartsWithHost(node.children, node.host) ? null : <span className="sc-link-host"> ({node.host})</span>}
+        </span>
+      );
+    case "mention":
+      return node.href ? (
+        <SafeLink key={key} href={node.href} className="sc-mention">{`@${node.handle}`}</SafeLink>
+      ) : (
+        <span key={key} className="sc-mention">{`@${node.handle}`}</span>
+      );
+    case "hashtag":
+      return node.href ? (
+        <SafeLink key={key} href={node.href} className="sc-hashtag">{`#${node.tag}`}</SafeLink>
+      ) : (
+        <span key={key} className="sc-hashtag">{`#${node.tag}`}</span>
+      );
+    default:
+      return null;
+  }
+}
+
+/** Renders a rich-text document. `doc` may be untrusted JSON; it is re-validated first. */
+export function RichText(props: CommonProps & { readonly doc: RichTextDocument | unknown }): ReactNode {
+  const mediaProxy = props.mediaProxy ?? DEFAULT_MEDIA_PROXY;
+  const doc = coerceRichTextDocument(props.doc, { mediaProxy });
+  return (
+    <div className={props.className} dir="auto" data-truncated={doc.truncated ? "true" : undefined}>
+      {doc.children.map((p, i) => (
+        <p key={i} dir="auto">
+          {p.children.map((n, j) => inline(n, j, mediaProxy))}
+        </p>
+      ))}
+    </div>
+  );
+}
+
+/** Link-preview card. `preview` may be raw provider card data or a built `LinkPreview`. */
+export function LinkPreviewCard(props: CommonProps & { readonly preview: LinkPreview | unknown }): ReactNode {
+  const mediaProxy = props.mediaProxy ?? DEFAULT_MEDIA_PROXY;
+  const preview = parseLinkPreview(props.preview, mediaProxy);
+  if (!preview) return null;
+  return (
+    <a href={preview.href} rel={EXTERNAL_LINK_REL} target="_blank" referrerPolicy="no-referrer" className={props.className}>
+      {preview.image && isProxiedMediaUrl(preview.image, mediaProxy) ? (
+        <img src={preview.image} alt="" loading="lazy" decoding="async" referrerPolicy="no-referrer" />
+      ) : null}
+      {preview.siteName ? <span className="sc-preview-site" dir="auto">{preview.siteName}</span> : null}
+      {preview.title ? <strong className="sc-preview-title" dir="auto">{preview.title}</strong> : null}
+      {preview.description ? <span className="sc-preview-description" dir="auto">{preview.description}</span> : null}
+      <span className="sc-preview-host">{preview.host}</span>
+    </a>
+  );
+}
+
+/** Display names / usernames: bidi + zero-width neutralised, isolated, confusables flagged. */
+export function DisplayName(props: { readonly name: unknown; readonly maxLength?: number; readonly className?: string }): ReactNode {
+  const name = typeof props.name === "string" ? neutralizeDisplayName(props.name, props.maxLength) : "";
+  return (
+    <bdi className={props.className} data-confusable={hasMixedScriptConfusables(name) ? "true" : undefined}>
+      {name}
+    </bdi>
+  );
+}
diff --git a/packages/safe-content/src/text.ts b/packages/safe-content/src/text.ts
new file mode 100644
index 0000000..d921a48
--- /dev/null
+++ b/packages/safe-content/src/text.ts
@@ -0,0 +1,57 @@
+/**
+ * Bidi embedding/override/isolate controls (U+202A–U+202E, U+2066–U+2069) can
+ * visually reorder text ("evil" + U+202E + "txt.exe"); they are always removed.
+ */
+const BIDI_CONTROLS = /[\u202A-\u202E\u2066-\u2069]/g;
+/** Marks and zero-width characters used for spoofing look-alike names. */
+const INVISIBLES = /[\u200B-\u200F\u061C\u180E\u2060-\u2064\uFEFF\u034F\u115F\u1160\u3164\uFFA0]/g;
+/** C0/C1 controls except tab and newline; lone surrogates. */
+const CONTROLS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+/** Normalises body text: strips controls and bidi overrides, keeps ZWJ (emoji sequences). */
+export function neutralizeText(input: string): string {
+  return input.replace(CONTROLS, "").replace(BIDI_CONTROLS, "").replace(/\r\n?/g, "\n");
+}
+
+/**
+ * Display names, usernames, channel names: single line, no bidi or zero-width
+ * characters at all, whitespace collapsed, length-capped.
+ */
+export function neutralizeDisplayName(input: string, maxLength = 100): string {
+  const cleaned = input
+    .normalize("NFC")
+    .replace(CONTROLS, "")
+    .replace(BIDI_CONTROLS, "")
+    .replace(INVISIBLES, "")
+    .replace(/\s+/g, " ")
+    .trim();
+  return truncateCodePoints(cleaned, maxLength);
+}
+
+export function truncateCodePoints(input: string, max: number): string {
+  if (input.length <= max) return input;
+  const chars = Array.from(input);
+  return chars.length <= max ? input : chars.slice(0, max).join("") + "…";
+}
+
+const SCRIPT_RUNS: readonly [string, RegExp][] = [
+  ["Latin", /\p{Script=Latin}/u],
+  ["Cyrillic", /\p{Script=Cyrillic}/u],
+  ["Greek", /\p{Script=Greek}/u],
+  ["Armenian", /\p{Script=Armenian}/u],
+  ["Cherokee", /\p{Script=Cherokee}/u],
+];
+
+/**
+ * Homoglyph heuristic: true when a single word mixes Latin with a script that
+ * has Latin look-alikes ("pаypal" with Cyrillic "а"). The UI should flag such
+ * names rather than trust them; it is a warning, not a sanitiser.
+ */
+export function hasMixedScriptConfusables(input: string): boolean {
+  for (const word of input.normalize("NFKC").split(/[\s\p{P}]+/u)) {
+    let seen = 0;
+    for (const [, re] of SCRIPT_RUNS) if (re.test(word)) seen++;
+    if (seen > 1) return true;
+  }
+  return false;
+}
diff --git a/packages/safe-content/src/url.ts b/packages/safe-content/src/url.ts
new file mode 100644
index 0000000..23adebf
--- /dev/null
+++ b/packages/safe-content/src/url.ts
@@ -0,0 +1,69 @@
+import { DEFAULT_LIMITS } from "./limits.js";
+
+export type SafeUrl = { readonly href: string; readonly host: string };
+
+const ABSOLUTE_HTTP = /^https?:\/\/[^/\\]/i;
+
+/**
+ * Accepts only absolute, credential-free http(s) URLs. Everything else —
+ * `javascript:`, `data:`, `vbscript:`, `file:`, protocol-relative, relative,
+ * backslash tricks, embedded controls/whitespace — returns null so the caller
+ * renders the text inertly.
+ */
+export function parseSafeHttpUrl(raw: unknown, maxLength = DEFAULT_LIMITS.maxUrlLength): SafeUrl | null {
+  if (typeof raw !== "string") return null;
+  const input = raw.trim();
+  if (input.length === 0 || input.length > maxLength) return null;
+  // Browsers strip tab/newline inside URLs ("java\tscript:"); refuse instead of guessing.
+  if (/[\u0000-\u0020\u007F-\u00A0\u1680\u2000-\u200F\u2028-\u202F\u205F-\u206F\u3000\uFEFF]/.test(input)) return null;
+  if (!ABSOLUTE_HTTP.test(input)) return null;
+  let url: URL;
+  try {
+    url = new URL(input);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+  if (url.username !== "" || url.password !== "") return null;
+  if (url.hostname === "") return null;
+  if (url.href.length > maxLength) return null;
+  // `URL` serialises IDN hosts as punycode (xn--…), which exposes homoglyph domains.
+  return { href: url.href, host: url.host };
+}
+
+export type MediaProxyPolicy = {
+  /** Same-origin path of the app's media proxy, e.g. `/api/media-proxy`. */
+  readonly proxyPath: string;
+};
+
+export const DEFAULT_MEDIA_PROXY: MediaProxyPolicy = { proxyPath: "/api/media-proxy" };
+
+function assertProxyPath(path: string): void {
+  if (!/^\/[A-Za-z0-9._~\-/]*$/.test(path) || path.startsWith("//") || path.includes("/../") || path.endsWith("/..")) {
+    throw new Error(`safe-content: media proxy path must be a same-origin absolute path, got ${JSON.stringify(path)}`);
+  }
+}
+
+/** Rewrites a remote media URL into a media-proxy URL; null if the origin URL is unsafe. */
+export function toProxiedMediaUrl(raw: unknown, policy: MediaProxyPolicy = DEFAULT_MEDIA_PROXY): string | null {
+  assertProxyPath(policy.proxyPath);
+  const safe = parseSafeHttpUrl(raw);
+  if (!safe) return null;
+  return `${policy.proxyPath}?url=${encodeURIComponent(safe.href)}`;
+}
+
+/** True when `src` is exactly a media-proxy URL produced by `toProxiedMediaUrl`. */
+export function isProxiedMediaUrl(src: unknown, policy: MediaProxyPolicy = DEFAULT_MEDIA_PROXY): src is string {
+  if (typeof src !== "string") return false;
+  assertProxyPath(policy.proxyPath);
+  const prefix = `${policy.proxyPath}?url=`;
+  if (!src.startsWith(prefix)) return false;
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(src.slice(prefix.length));
+  } catch {
+    return false;
+  }
+  // Canonical form only: re-deriving the proxy URL must reproduce `src` exactly.
+  return toProxiedMediaUrl(decoded, policy) === src;
+}
diff --git a/packages/safe-content/src/validate.ts b/packages/safe-content/src/validate.ts
new file mode 100644
index 0000000..1e94e2e
--- /dev/null
+++ b/packages/safe-content/src/validate.ts
@@ -0,0 +1,107 @@
+import type { EmojiNode, LinkPreview, RichTextDocument, TextNode } from "./ast.js";
+import { DocBuilder, normalizeHandle, normalizeTag, type ParseOptions } from "./builder.js";
+import { decodeEntities } from "./entities.js";
+import { LINK_PREVIEW_LIMITS } from "./limits.js";
+import { neutralizeText, truncateCodePoints } from "./text.js";
+import { DEFAULT_MEDIA_PROXY, isProxiedMediaUrl, parseSafeHttpUrl, toProxiedMediaUrl, type MediaProxyPolicy } from "./url.js";
+
+type Unknown = Record<string, unknown>;
+const isObj = (v: unknown): v is Unknown => typeof v === "object" && v !== null && !Array.isArray(v);
+const arr = (v: unknown): readonly unknown[] => (Array.isArray(v) ? v : []);
+
+/**
+ * Rebuilds a document from untrusted JSON (DB row, API payload, websocket
+ * frame). Unknown node types, bad URLs and non-proxied media are dropped;
+ * text is re-neutralised; limits are re-applied. The renderer always calls
+ * this, so a forged AST is as inert as a parsed one.
+ */
+export function coerceRichTextDocument(value: unknown, options: ParseOptions = {}): RichTextDocument {
+  const builder = new DocBuilder({ ...options, emojis: [] });
+  const policy = options.mediaProxy ?? DEFAULT_MEDIA_PROXY;
+  if (!isObj(value) || value.type !== "doc") return builder.finish();
+  if (value.truncated === true) builder.truncated = true;
+  const leaf = (n: unknown): (TextNode | EmojiNode)[] => {
+    if (!isObj(n)) return [];
+    if (n.type === "text" && typeof n.text === "string") return builder.inlineText(n.text);
+    if (n.type === "emoji" && typeof n.shortcode === "string" && /^[A-Za-z0-9_+-]{1,64}$/.test(n.shortcode)) {
+      return isProxiedMediaUrl(n.src, policy)
+        ? [{ type: "emoji", shortcode: n.shortcode, src: n.src }]
+        : [{ type: "text", text: `:${n.shortcode}:` }];
+    }
+    return [];
+  };
+  const capped = (items: unknown): readonly unknown[] => {
+    const all = arr(items);
+    if (all.length <= builder.limits.maxNodes) return all;
+    builder.truncated = true;
+    return all.slice(0, builder.limits.maxNodes);
+  };
+  for (const p of capped(value.children)) {
+    if (!isObj(p) || p.type !== "paragraph") continue;
+    for (const n of capped(p.children)) {
+      if (!isObj(n)) continue;
+      switch (n.type) {
+        case "text":
+          if (typeof n.text === "string") builder.text(n.text);
+          break;
+        case "emoji":
+          for (const e of leaf(n)) builder.pushLeaf(e);
+          break;
+        case "linebreak":
+          builder.lineBreak();
+          break;
+        case "link":
+          builder.link(typeof n.href === "string" ? n.href : "", arr(n.children).slice(0, 64).flatMap(leaf));
+          break;
+        case "mention":
+          if (typeof n.handle === "string" && normalizeHandle(n.handle)) builder.mention(n.handle, typeof n.href === "string" ? n.href : undefined);
+          break;
+        case "hashtag":
+          if (typeof n.tag === "string" && normalizeTag(n.tag)) builder.hashtag(n.tag, typeof n.href === "string" ? n.href : undefined);
+          break;
+      }
+    }
+    builder.endParagraph();
+  }
+  return builder.finish();
+}
+
+export type RawLinkPreview = {
+  readonly url?: unknown;
+  readonly title?: unknown;
+  readonly description?: unknown;
+  readonly siteName?: unknown;
+  readonly image?: unknown;
+};
+
+function previewText(value: unknown, max: number): string | undefined {
+  if (typeof value !== "string") return undefined;
+  // OpenGraph fields are text: entities are decoded, tags are NOT interpreted.
+  const text = neutralizeText(decodeEntities(value.slice(0, max * 4))).replace(/\s+/g, " ").trim();
+  return text === "" ? undefined : truncateCodePoints(text, max);
+}
+
+/**
+ * Link-preview card data (OpenGraph/oEmbed/Mastodon `card`). Returns null when
+ * the target is not a safe http(s) URL. The image is rewritten to the proxy
+ * or dropped. Accepts either raw provider data or a previously built preview.
+ */
+export function parseLinkPreview(raw: unknown, mediaProxy: MediaProxyPolicy = DEFAULT_MEDIA_PROXY): LinkPreview | null {
+  if (!isObj(raw)) return null;
+  const safe = parseSafeHttpUrl(raw.type === "linkPreview" ? raw.href : raw.url);
+  if (!safe) return null;
+  const image = isProxiedMediaUrl(raw.image, mediaProxy) ? raw.image : toProxiedMediaUrl(raw.image, mediaProxy);
+  const title = previewText(raw.title, LINK_PREVIEW_LIMITS.title);
+  const description = previewText(raw.description, LINK_PREVIEW_LIMITS.description);
+  const siteName = previewText(raw.siteName, LINK_PREVIEW_LIMITS.siteName);
+  return {
+    type: "linkPreview",
+    href: safe.href,
+    host: safe.host,
+    ...(title !== undefined && { title }),
+    ...(description !== undefined && { description }),
+    ...(siteName !== undefined && { siteName }),
+    ...(image !== null && { image }),
+  };
+}
+
diff --git a/packages/safe-content/tsconfig.json b/packages/safe-content/tsconfig.json
new file mode 100644
index 0000000..5ec248a
--- /dev/null
+++ b/packages/safe-content/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "lib": ["ES2022", "DOM"],
+    "jsx": "react-jsx"
+  },
+  "include": ["src"]
+}
diff --git a/packages/scheduling/README.md b/packages/scheduling/README.md
new file mode 100644
index 0000000..adbc7de
--- /dev/null
+++ b/packages/scheduling/README.md
@@ -0,0 +1,56 @@
+# Scheduling
+
+Shared schedule time semantics for WP3 (publishing) and WP13 (multi-output
+schedules). Pure functions and types only — no app, database or Temporal
+imports, and no runtime dependency beyond Node's `Intl` tzdata.
+
+A schedule is a five-field cron expression plus an explicit IANA timezone
+(never server-local; `UTC` allowed). Occurrences are evaluated in that zone as
+nominal local date-times, then materialized to UTC fire instants. The
+occurrence key is the materialized UTC instant, so `UNIQUE (workspace_id,
+schedule_id, fire_at_utc)` holds by construction.
+
+## Policies
+
+- **DST gap** (nonexistent local time): fires at the first valid instant after
+  the gap (shift forward). Works for 1-hour gaps and Pacific/Apia's whole-day
+  skip alike.
+- **DST fold** (ambiguous local time): fires ONCE, at its first (earlier-offset)
+  instant.
+- **Collapse**: several nominal local times materializing onto one post-gap
+  instant produce exactly one occurrence, labelled with the latest collapsed
+  slot — the conservative value for the `last_fired_nominal_local` gate.
+- **Re-materialization** on tzdata or timezone change: deletes all unclaimed
+  future occurrences, then regenerates only occurrences strictly after
+  max(change instant, last claimed fire instant) whose nominal slot is strictly
+  later than `last_fired_nominal_local`. A slot already fired under the old
+  zone (daily 09:00 fired in New York, zone switched to Los Angeles) never
+  fires again. The tzdata version is reported for recording.
+
+## API
+
+```ts
+import {
+  parseCron,                 // five-field cron -> sets (rejects 6-field/`?`/`L`/`W`/`#`/macros)
+  nextOccurrences,           // (spec, from, count, {exclusive}) -> Occurrence[]
+  materializeOccurrence,     // ("2024-03-10T02:30", zone) -> epoch ms
+  rematerialize,             // (oldSpec, newSpec, storedRows, {changeInstant, ...})
+  canonicalTimezone,         // validates + canonicalizes; rejects "local"/offsets
+  currentTzdataVersion,      // process.versions.tz
+} from "@tactical-media-broadcast-hub/scheduling";
+```
+
+Errors: `SchedulingError` base, with `InvalidCronError`, `ImpossibleScheduleError`,
+`InvalidTimezoneError`, `InvalidNominalLocalError`, `InvalidInstantError`. Note
+`toInstantMs` rejects offset-less ISO datetimes that would otherwise parse in
+the server's local zone.
+
+## Verification
+
+```
+pnpm exec tsc -p tsconfig.json --noEmit
+pnpm exec vitest run
+```
+
+`pnpm install` is required once so the workspace links this package's
+`vitest`/`typescript` devDependencies into `packages/scheduling/node_modules`.
diff --git a/packages/scheduling/package.json b/packages/scheduling/package.json
new file mode 100644
index 0000000..22fa5d0
--- /dev/null
+++ b/packages/scheduling/package.json
@@ -0,0 +1,20 @@
+{
+  "name": "@tactical-media-broadcast-hub/scheduling",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": { ".": "./dist/index.js" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}
diff --git a/packages/scheduling/src/cron.test.ts b/packages/scheduling/src/cron.test.ts
new file mode 100644
index 0000000..d14e012
--- /dev/null
+++ b/packages/scheduling/src/cron.test.ts
@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+import { parseCron, cronMatchesTime } from "./cron.js";
+import { ImpossibleScheduleError, InvalidCronError } from "./errors.js";
+
+describe("parseCron — valid syntax", () => {
+  it("parses the every-minute expression", () => {
+    const c = parseCron("* * * * *");
+    expect(c.minute.values.size).toBe(60);
+    expect(c.minute.restricted).toBe(false);
+    expect(c.dayOfMonth.restricted).toBe(false);
+    expect(c.dayOfWeek.restricted).toBe(false);
+  });
+  it("parses steps, ranges and lists", () => {
+    const c = parseCron("*/15 8-18/2 * * 1,3,5");
+    expect([...c.minute.values]).toEqual([0, 15, 30, 45]);
+    expect([...c.hour.values]).toEqual([8, 10, 12, 14, 16, 18]);
+    expect([...c.dayOfWeek.values]).toEqual([1, 3, 5]);
+    expect(c.minute.restricted).toBe(true);
+    expect(c.hour.restricted).toBe(true);
+    expect(c.dayOfWeek.restricted).toBe(true);
+  });
+  it("parses month and dow names case-insensitively", () => {
+    const c = parseCron("0 0 1 jan-mar mon-fri");
+    expect([...c.month.values]).toEqual([1, 2, 3]);
+    expect([...c.dayOfWeek.values]).toEqual([1, 2, 3, 4, 5]);
+  });
+  it("accepts a list element of one value", () => {
+    expect([...parseCron("5,10 * * * *").minute.values]).toEqual([5, 10]);
+  });
+  it("treats n/step as n..max/step", () => {
+    expect([...parseCron("20/15 * * * *").minute.values]).toEqual([20, 35, 50]);
+  });
+});
+
+describe("parseCron — rejection", () => {
+  const bad = [
+    "",
+    "   ",
+    "* * * *",
+    "* * * * * *",
+    "60 * * * *",
+    "* 24 * * *",
+    "* * 0 * *",
+    "* * 32 * *",
+    "* * * 0 *",
+    "* * * 13 *",
+    "* * * * 7",
+    "* * * * MON-BR",
+    "a * * * *",
+    "*/0 * * * *",
+    "*/-1 * * * *",
+    "5-1 * * * *",
+    "1--2 * * * *",
+    "@reboot",
+    "@daily",
+    "? * * * *",
+    "* * ? * *",
+    "* * * * * 2025",
+    "0 0 * * MON#1",
+    "0 0 L * *",
+    "0 0 1 W *",
+    "1/2/3 * * * *",
+    "*/ * * * *",
+    "1,,2 * * * *",
+    "-5 * * * *",
+  ];
+  it.each(bad.map((e) => [e]))("rejects %s", (expr) => {
+    expect(() => parseCron(expr)).toThrow(InvalidCronError);
+  });
+  it("rejects non-string input", () => {
+    expect(() => parseCron(undefined as unknown as string)).toThrow(InvalidCronError);
+    expect(() => parseCron(5 as unknown as string)).toThrow(InvalidCronError);
+  });
+  it("rejects impossible schedules", () => {
+    expect(() => parseCron("0 0 31 2 *")).toThrow(ImpossibleScheduleError);
+    expect(() => parseCron("0 0 30 2 *")).toThrow(ImpossibleScheduleError);
+    expect(() => parseCron("0 0 31 4 *")).toThrow(ImpossibleScheduleError);
+  });
+  it("accepts Feb 29 (leap years exist)", () => {
+    expect(() => parseCron("0 0 29 2 *")).not.toThrow();
+  });
+  it("accepts the 31st in long months", () => {
+    expect(() => parseCron("0 0 31 1 *")).not.toThrow();
+    expect(() => parseCron("0 0 31 * *")).not.toThrow();
+  });
+});
+
+describe("cronMatchesTime", () => {
+  const cron = parseCron("*/15 9 * * *");
+  it("matches on the quarter hour in the 9 hour", () => {
+    expect(cronMatchesTime(cron, 9, 0, 0)).toBe(true);
+    expect(cronMatchesTime(cron, 9, 45, 0)).toBe(true);
+  });
+  it("rejects other minutes/hours and any nonzero second", () => {
+    expect(cronMatchesTime(cron, 9, 20, 0)).toBe(false);
+    expect(cronMatchesTime(cron, 10, 0, 0)).toBe(false);
+    expect(cronMatchesTime(cron, 9, 0, 1)).toBe(false);
+  });
+});
diff --git a/packages/scheduling/src/cron.ts b/packages/scheduling/src/cron.ts
new file mode 100644
index 0000000..94e70ae
--- /dev/null
+++ b/packages/scheduling/src/cron.ts
@@ -0,0 +1,249 @@
+import { ImpossibleScheduleError, InvalidCronError } from "./errors.js";
+
+/**
+ * A single field of a five-field cron expression after alias resolution.
+ *
+ * `values` is the expanded set of allowed integers; `restricted` is false only
+ * for the literal `*`, which matters for the cron dom/dow OR rule: when both
+ * fields are restricted the day matches if EITHER matches, and when only one is
+ * restricted it alone constrains the day.
+ */
+export interface CronField {
+  readonly values: ReadonlySet<number>;
+  readonly restricted: boolean;
+}
+
+/**
+ * Parsed five-field cron expression: minute hour day-of-month month
+ * day-of-week. minute/hour/dow are zero-based; month is 1-12, dom 1-31.
+ */
+export interface ParsedCron {
+  readonly minute: CronField;
+  readonly hour: CronField;
+  readonly dayOfMonth: CronField;
+  readonly month: CronField;
+  readonly dayOfWeek: CronField;
+}
+
+interface FieldBounds {
+  readonly min: number;
+  readonly max: number;
+  /** alias -> value, applied before range parsing (MON, JAN, ...) */
+  readonly aliases?: Readonly<Record<string, number>>;
+}
+
+const MONTH_ALIASES: Readonly<Record<string, number>> = {
+  JAN: 1,
+  FEB: 2,
+  MAR: 3,
+  APR: 4,
+  MAY: 5,
+  JUN: 6,
+  JUL: 7,
+  AUG: 8,
+  SEP: 9,
+  OCT: 10,
+  NOV: 11,
+  DEC: 12,
+};
+
+const DOW_ALIASES: Readonly<Record<string, number>> = {
+  SUN: 0,
+  MON: 1,
+  TUE: 2,
+  WED: 3,
+  THU: 4,
+  FRI: 5,
+  SAT: 6,
+};
+
+const MINUTE: FieldBounds = { min: 0, max: 59 };
+const HOUR: FieldBounds = { min: 0, max: 23 };
+const DOM: FieldBounds = { min: 1, max: 31 };
+const MONTH: FieldBounds = { min: 1, max: 12, aliases: MONTH_ALIASES };
+const DOW: FieldBounds = { min: 0, max: 6, aliases: DOW_ALIASES };
+
+export const FIELD_NAMES = ["minute", "hour", "day-of-month", "month", "day-of-week"] as const;
+
+/** Month lengths ignoring leap years (February counted as 29 to stay permissive). */
+const MONTH_LENGTHS: readonly number[] = [0, 31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
+function applyAliases(token: string, bounds: FieldBounds): string {
+  const aliases = bounds.aliases;
+  if (!aliases) return token;
+  const mapped = aliases[token.toUpperCase()];
+  return mapped === undefined ? token : String(mapped);
+}
+
+function parseValue(token: string, bounds: FieldBounds, fieldName: string): number {
+  const mapped = applyAliases(token, bounds);
+  if (!/^\d+$/.test(mapped)) {
+    throw new InvalidCronError(`invalid value "${token}" in ${fieldName} field`);
+  }
+  const value = Number(mapped);
+  if (value < bounds.min || value > bounds.max) {
+    throw new InvalidCronError(
+      `value ${value} out of range ${bounds.min}-${bounds.max} in ${fieldName} field`,
+    );
+  }
+  return value;
+}
+
+function parseStep(token: string, fieldName: string): number {
+  const trimmed = token.trim();
+  if (!/^\d+$/.test(trimmed)) {
+    throw new InvalidCronError(`invalid step "${token}" in ${fieldName} field`);
+  }
+  const step = Number(trimmed);
+  if (!Number.isInteger(step) || step <= 0) {
+    throw new InvalidCronError(`step must be a positive integer, got "${token}" in ${fieldName} field`);
+  }
+  return step;
+}
+
+function parseField(field: string, bounds: FieldBounds, fieldName: string): CronField {
+  const raw = field.trim();
+  if (raw === "") {
+    throw new InvalidCronError(`empty ${fieldName} field`);
+  }
+  const values = new Set<number>();
+  for (const part of raw.split(",")) {
+    const token = part.trim();
+    if (token === "") {
+      throw new InvalidCronError(`empty list element in ${fieldName} field "${field}"`);
+    }
+    // Split off an optional /step suffix, being careful not to break on a bare value.
+    const slash = token.indexOf("/");
+    const range = (slash === -1 ? token : token.slice(0, slash)).trim();
+    const stepPart = slash === -1 ? null : token.slice(slash + 1).trim();
+    if (range === "") {
+      throw new InvalidCronError(`malformed element "${token}" in ${fieldName} field`);
+    }
+    if ((token.match(/\//g) ?? []).length > 1) {
+      throw new InvalidCronError(`malformed element "${token}" in ${fieldName} field`);
+    }
+    const step = stepPart === null ? 1 : parseStep(stepPart, fieldName);
+    let lo: number;
+    let hi: number;
+    if (range === "*") {
+      lo = bounds.min;
+      hi = bounds.max;
+    } else if (range.includes("-")) {
+      const dash = range.indexOf("-");
+      const loToken = range.slice(0, dash).trim();
+      const hiToken = range.slice(dash + 1).trim();
+      if (loToken === "" || hiToken === "") {
+        throw new InvalidCronError(`malformed range "${range}" in ${fieldName} field`);
+      }
+      lo = parseValue(loToken, bounds, fieldName);
+      hi = parseValue(hiToken, bounds, fieldName);
+      if (lo > hi) {
+        throw new InvalidCronError(`descending range "${range}" in ${fieldName} field (use ascending ranges)`);
+      }
+    } else {
+      const value = parseValue(range, bounds, fieldName);
+      if (stepPart === null) {
+        values.add(value);
+        continue;
+      }
+      // `n/step` means "starting at n, every step" — the vixie shorthand for n-max/step.
+      lo = value;
+      hi = bounds.max;
+    }
+    for (let v = lo; v <= hi; v += step) values.add(v);
+  }
+  if (values.size === 0) {
+    throw new InvalidCronError(`${fieldName} field "${field}" selects no values`);
+  }
+  // Only the bare `*` leaves a field unrestricted; `*/15`, `1-5`, lists and
+  // even `*,5` all constrain the field.
+  return { values, restricted: raw !== "*" };
+}
+
+/**
+ * Parse a five-field cron expression. Supported syntax: `*`, integers, ranges
+ * `a-b`, steps `n/step`, `a-b/step`, comma lists, and month/day-of-week names
+ * (`JAN-DEC`, `MON-SUN`, case-insensitive). Anything else — more or fewer than
+ * five fields, seconds/year fields, `@reboot` macros, `?`, `L`, `W`, `#` — is
+ * rejected with `InvalidCronError` rather than silently misinterpreted.
+ *
+ * Throws `ImpossibleScheduleError` when the expression can never fire (for
+ * example `0 0 31 2 *`).
+ */
+export function parseCron(expression: string): ParsedCron {
+  if (typeof expression !== "string") {
+    throw new InvalidCronError(`cron expression must be a string, got ${typeof expression}`);
+  }
+  const trimmed = expression.trim();
+  if (trimmed === "") {
+    throw new InvalidCronError("cron expression must not be empty");
+  }
+  if (trimmed.startsWith("@")) {
+    throw new InvalidCronError(
+      `cron macros like "${trimmed}" are not supported; use a five-field expression`,
+    );
+  }
+  for (const ch of ["?", "L", "W", "#"] as const) {
+    if (trimmed.includes(ch)) {
+      throw new InvalidCronError(
+        `unsupported cron syntax "${ch}" in "${expression}"; this library implements the five-field syntax only`,
+      );
+    }
+  }
+  const fields = trimmed.split(/\s+/);
+  if (fields.length !== 5) {
+    throw new InvalidCronError(
+      `cron expression must have exactly 5 fields (minute hour day-of-month month day-of-week), got ${fields.length} in "${expression}"`,
+    );
+  }
+  const minute = parseField(fields[0]!, MINUTE, FIELD_NAMES[0]);
+  const hour = parseField(fields[1]!, HOUR, FIELD_NAMES[1]);
+  const dayOfMonth = parseField(fields[2]!, DOM, FIELD_NAMES[2]);
+  const month = parseField(fields[3]!, MONTH, FIELD_NAMES[3]);
+  const dayOfWeek = parseField(fields[4]!, DOW, FIELD_NAMES[4]);
+  assertPossible(month, dayOfMonth);
+  return { minute, hour, dayOfMonth, month, dayOfWeek };
+}
+
+function assertPossible(month: CronField, dayOfMonth: CronField): void {
+  for (const m of month.values) {
+    const maxDay = MONTH_LENGTHS[m] ?? 0;
+    for (const d of dayOfMonth.values) {
+      if (d <= maxDay) return;
+    }
+  }
+  throw new ImpossibleScheduleError(
+    `expression can never fire: no allowed month is long enough for day-of-month ${[
+      ...dayOfMonth.values,
+    ].join(", ")}`,
+  );
+}
+
+/**
+ * Does this cron match the given local wall-clock day? Implements the vixie
+ * dom/dow OR rule: if both fields are restricted the day matches when either
+ * matches, otherwise the restricted field alone decides.
+ */
+export function cronMatchesDay(cron: ParsedCron, year: number, month: number, day: number): boolean {
+  if (!cron.month.values.has(month)) return false;
+  const domMatch = cron.dayOfMonth.values.has(day);
+  const dowMatch = cron.dayOfWeek.values.has(dayOfWeekOf(year, month, day));
+  const domRestricted = cron.dayOfMonth.restricted;
+  const dowRestricted = cron.dayOfWeek.restricted;
+  // Vixie rule: neither restricted -> every day; exactly one restricted ->
+  // that field alone; both restricted -> match if EITHER matches.
+  if (domRestricted && dowRestricted) return domMatch || dowMatch;
+  if (domRestricted) return domMatch;
+  if (dowRestricted) return dowMatch;
+  return true;
+}
+
+function dayOfWeekOf(year: number, month: number, day: number): number {
+  return new Date(Date.UTC(year, month - 1, day)).getUTCDay();
+}
+
+/** Does this cron match the given local time-of-day (hour/minute)? */
+export function cronMatchesTime(cron: ParsedCron, hour: number, minute: number, second: number): boolean {
+  if (second !== 0) return false;
+  return cron.minute.values.has(minute) && cron.hour.values.has(hour);
+}
diff --git a/packages/scheduling/src/errors.ts b/packages/scheduling/src/errors.ts
new file mode 100644
index 0000000..8d0afdb
--- /dev/null
+++ b/packages/scheduling/src/errors.ts
@@ -0,0 +1,31 @@
+/**
+ * Error hierarchy for `@tactical-media-broadcast-hub/scheduling`.
+ *
+ * Every failure mode of the library is one of these types; callers can branch
+ * on the class without string matching.
+ */
+export class SchedulingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = new.target.name;
+  }
+}
+
+/** The cron expression is syntactically invalid or uses unsupported syntax. */
+export class InvalidCronError extends SchedulingError {}
+
+/** The timezone is not a usable IANA zone id (never silently server-local). */
+export class InvalidTimezoneError extends SchedulingError {}
+
+/** A nominal local date-time string is malformed or not a real calendar date. */
+export class InvalidNominalLocalError extends SchedulingError {}
+
+/**
+ * An instant input (Date | number | ISO string) is not usable. Notably, an ISO
+ * string that carries a time but no explicit UTC offset is rejected instead of
+ * being parsed in the server's local zone.
+ */
+export class InvalidInstantError extends SchedulingError {}
+
+/** The schedule can never fire (e.g. `0 0 31 2 *` — February 31st). */
+export class ImpossibleScheduleError extends SchedulingError {}
diff --git a/packages/scheduling/src/index.ts b/packages/scheduling/src/index.ts
new file mode 100644
index 0000000..877bdff
--- /dev/null
+++ b/packages/scheduling/src/index.ts
@@ -0,0 +1,58 @@
+/**
+ * @tactical-media-broadcast-hub/scheduling — shared schedule time semantics (WP3, reused by WP13).
+ *
+ * A schedule is a five-field cron expression plus an explicit IANA timezone
+ * (never server-local; UTC allowed). Occurrences are evaluated in that zone as
+ * nominal local times, then materialized to UTC fire instants. The occurrence
+ * key is the materialized UTC instant, so `UNIQUE (workspace_id, schedule_id,
+ * fire_at_utc)` holds by construction.
+ *
+ * - DST gap: a nonexistent local time fires at the first valid instant after
+ *   the gap (shift forward).
+ * - DST fold: an ambiguous local time fires once, at its earlier instant.
+ * - Collapse: several nominal local times mapping onto one post-gap instant
+ *   yield exactly one occurrence.
+ * - Re-materialization on tzdata/timezone change deletes unclaimed future
+ *   occurrences and regenerates only strictly-later slots, never refiring a
+ *   slot already fired under the old zone.
+ *
+ * Pure functions only: no app, DB or Temporal imports.
+ */
+export {
+  SchedulingError,
+  InvalidCronError,
+  InvalidTimezoneError,
+  InvalidNominalLocalError,
+  InvalidInstantError,
+  ImpossibleScheduleError,
+} from "./errors.js";
+export {
+  canonicalTimezone,
+  isValidTimezone,
+  assertValidTimezone,
+  wallOfInstant,
+  offsetMs,
+  toInstantMs,
+  currentTzdataVersion,
+  epochOfWall,
+} from "./timezone.js";
+export type { WallClock, NominalLocal } from "./timezone.js";
+export { parseCron, cronMatchesDay, cronMatchesTime, FIELD_NAMES } from "./cron.js";
+export type { ParsedCron, CronField } from "./cron.js";
+export { formatNominal, parseNominal, compareWall, wallEquals, wallAsEpochMs } from "./nominal.js";
+export { resolveWallToInstant } from "./materialize.js";
+export { materializeOccurrence } from "./materialize-api.js";
+export {
+  prepareSchedule,
+  sortedHours,
+  sortedMinutes,
+  slotNominal,
+  matchingLocalDays,
+  stepOneLocalDay,
+} from "./schedule.js";
+export type { ScheduleSpec, Occurrence, PreparedSchedule } from "./schedule.js";
+export { nextOccurrencesPrepared } from "./occurrences.js";
+export type { NextOccurrencesOptions } from "./occurrences.js";
+export { nextOccurrences, materializeOccurrences } from "./occurrences_extra.js";
+export { rematerialize } from "./rematerialize.js";
+export type { StoredOccurrence, RematerializeOptions, RematerializeResult } from "./rematerialize.js";
diff --git a/packages/scheduling/src/materialize-api.ts b/packages/scheduling/src/materialize-api.ts
new file mode 100644
index 0000000..9c6d9ba
--- /dev/null
+++ b/packages/scheduling/src/materialize-api.ts
@@ -0,0 +1,16 @@
+import { resolveWallToInstant } from "./materialize.js";
+import { canonicalTimezone } from "./timezone.js";
+import { parseNominal } from "./nominal.js";
+import type { NominalLocal } from "./timezone.js";
+
+/**
+ * Materialize one nominal local date-time (e.g. `2024-03-10T02:30`) in an
+ * explicit IANA zone to its UTC fire instant in epoch milliseconds.
+ *
+ * Gap -> first valid instant after the gap; fold -> single firing at the
+ * earlier instant. Throws on a malformed nominal string or an invalid zone.
+ */
+export function materializeOccurrence(nominalLocal: NominalLocal, timezone: string): number {
+  const zone = canonicalTimezone(timezone);
+  return resolveWallToInstant(parseNominal(nominalLocal), zone);
+}
diff --git a/packages/scheduling/src/materialize.test.ts b/packages/scheduling/src/materialize.test.ts
new file mode 100644
index 0000000..fc173c9
--- /dev/null
+++ b/packages/scheduling/src/materialize.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, it } from "vitest";
+import { materializeOccurrence } from "./materialize-api.js";
+import { compareWall } from "./nominal.js";
+import { InvalidNominalLocalError } from "./errors.js";
+import { wallOfInstant } from "./timezone.js";
+
+const ISO = (ms: number) => new Date(ms).toISOString().replace(".000Z", "Z");
+
+describe("materializeOccurrence — normal (unambiguous) times", () => {
+  it("resolves a plain New York evening slot", () => {
+    expect(ISO(materializeOccurrence("2024-03-09T21:00", "America/New_York")))
+      .toBe("2024-03-10T02:00:00Z");
+  });
+  it("passes UTC straight through", () => {
+    expect(ISO(materializeOccurrence("2024-03-10T02:30", "UTC")))
+      .toBe("2024-03-10T02:30:00Z");
+  });
+  it("resolves Kolkata (no DST, half-hour offset)", () => {
+    expect(ISO(materializeOccurrence("2024-06-01T09:00", "Asia/Kolkata")))
+      .toBe("2024-06-01T03:30:00Z");
+  });
+});
+
+describe("DST gap — nonexistent local time fires at the first valid instant after", () => {
+  it("2:30 on New York spring-forward (2024-03-10) shifts to 3:00 local / 07:00Z", () => {
+    const fire = materializeOccurrence("2024-03-10T02:30", "America/New_York");
+    expect(ISO(fire)).toBe("2024-03-10T07:00:00Z");
+    const wall = wallOfInstant(fire, "America/New_York");
+    expect(`${wall.hour}:${String(wall.minute).padStart(2, "0")}`).toBe("3:00");
+  });
+  it("2:45 shifts to 3:00 as well", () => {
+    expect(ISO(materializeOccurrence("2024-03-10T02:45", "America/New_York")))
+      .toBe("2024-03-10T07:00:00Z");
+  });
+  it("2:00 (whole gap hour) shifts to 3:00", () => {
+    expect(ISO(materializeOccurrence("2024-03-10T02:00", "America/New_York")))
+      .toBe("2024-03-10T07:00:00Z");
+  });
+  it("1:59 — last pre-gap minute — is untouched", () => {
+    expect(ISO(materializeOccurrence("2024-03-10T01:59", "America/New_York")))
+      .toBe("2024-03-10T06:59:00Z");
+  });
+  it("Berlin 02:30 spring-forward shifts to 03:00 local", () => {
+    // EU transitions at 01:00 UTC: 2024-03-31 02:00->03:00 local
+    expect(ISO(materializeOccurrence("2024-03-31T02:30", "Europe/Berlin")))
+      .toBe("2024-03-31T01:00:00Z");
+  });
+  it("whole-day gap: Pacific/Apia skipped 2011-12-30; a slot on that day fires at the first valid instant after the gap", () => {
+    // The zone jumped 2011-12-29T23:59:59-10:00 -> 2011-12-31T00:00:00+14:00,
+    // so 2011-12-30 never existed. First valid instant after the gap is
+    // 2011-12-31T00:00 local == 2011-12-30T10:00Z.
+    const fire = materializeOccurrence("2011-12-30T09:00", "Pacific/Apia");
+    expect(ISO(fire)).toBe("2011-12-30T10:00:00Z");
+    const wall = wallOfInstant(fire, "Pacific/Apia");
+    expect(`${wall.year}-${wall.month}-${String(wall.day).padStart(2, "0")}T${wall.hour}:${wall.minute}`).toBe("2011-12-31T0:0");
+  });
+  it("a slot just before the Apia skip (23:00 on 12-29) is untouched", () => {
+    expect(ISO(materializeOccurrence("2011-12-29T23:00", "Pacific/Apia")))
+      .toBe("2011-12-30T09:00:00Z");
+  });
+});
+
+describe("DST fold — ambiguous local time fires once, at the earlier instant", () => {
+  it("1:30 on New York fall-back (2024-11-03) fires at EDT (earlier offset)", () => {
+    // 01:30 EDT == 05:30Z; the later reading 01:30 EST == 06:30Z is NOT used.
+    const fire = materializeOccurrence("2024-11-03T01:30", "America/New_York");
+    expect(ISO(fire)).toBe("2024-11-03T05:30:00Z");
+    expect(fire).not.toBe(Date.parse("2024-11-03T06:30:00Z"));
+  });
+  it("1:30 fires exactly once at 05:30Z (not 06:30Z)", () => {
+    expect(ISO(materializeOccurrence("2024-11-03T01:30", "America/New_York")))
+      .toBe("2024-11-03T05:30:00Z");
+  });
+  it("1:00 fold hour fires at 05:00Z (earlier)", () => {
+    expect(ISO(materializeOccurrence("2024-11-03T01:00", "America/New_York")))
+      .toBe("2024-11-03T05:00:00Z");
+  });
+  it("2:00 after the fold is unambiguous again", () => {
+    expect(ISO(materializeOccurrence("2024-11-03T02:00", "America/New_York")))
+      .toBe("2024-11-03T07:00:00Z");
+  });
+});
+
+describe("validation", () => {
+  it("rejects malformed nominal strings", () => {
+    for (const bad of ["2024-3-10T02:30", "2024-03-10", "2024-03-10T2:30", "2024-13-01T00:00", "2024-03-32T00:00", "2024-03-10T25:00", "nonsense"]) {
+      expect(() => materializeOccurrence(bad, "UTC")).toThrow(InvalidNominalLocalError);
+    }
+  });
+  it("rejects invalid zones", () => {
+    expect(() => materializeOccurrence("2024-03-10T02:30", "America/Nowhere")).toThrow();
+    expect(() => materializeOccurrence("2024-03-10T02:30", "local")).toThrow();
+  });
+  it("is pure — repeated calls agree", () => {
+    const a = materializeOccurrence("2024-03-10T02:30", "America/New_York");
+    const b = materializeOccurrence("2024-03-10T02:30", "America/New_York");
+    const c = materializeOccurrence("2024-03-10T02:30", "America/New_York");
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+  });
+  it("compareWall orders wall clocks chronologically", () => {
+    const w = (s: string) => ({
+      year: +s.slice(0, 4), month: +s.slice(5, 7), day: +s.slice(8, 10),
+      hour: +s.slice(11, 13), minute: +s.slice(14, 16), second: 0,
+    });
+    expect(compareWall(w("2024-03-10T01:59"), w("2024-03-10T03:00"))).toBeLessThan(0);
+    expect(compareWall(w("2024-11-03T01:30"), w("2024-11-03T01:30"))).toBe(0);
+  });
+});
+
+export {};
diff --git a/packages/scheduling/src/materialize.ts b/packages/scheduling/src/materialize.ts
new file mode 100644
index 0000000..75f5341
--- /dev/null
+++ b/packages/scheduling/src/materialize.ts
@@ -0,0 +1,96 @@
+import { compareWall, wallAsEpochMs } from "./nominal.js";
+import { offsetMs, wallOfInstant } from "./timezone.js";
+import type { WallClock } from "./timezone.js";
+
+export { materializeOccurrence } from "./materialize-api.js";
+
+const SIX_HOURS = 6 * 3600_000;
+
+/**
+ * Resolve one nominal local wall time in a zone to its UTC fire instant
+ * (epoch ms).
+ *
+ * Normal: the unique instant reading that wall time. Fold (ambiguous): fires
+ * once, at the earlier instant. Gap (nonexistent): the first valid instant
+ * after the gap — the earliest instant whose local reading is strictly later
+ * than the target.
+ *
+ * The candidate instant is found by fixed-point iteration (guess = local-as-UTC
+ * minus the offset at the guess), which converges for normal and fold times.
+ * Neighbouring offsets are probed to catch the second reading of a fold; the
+ * earliest matching instant wins. A non-matching iteration means the wall time
+ * does not exist (gap), resolved by a bracketed binary search for the exact
+ * first valid instant after the transition — correct for 1-hour gaps and
+ * Pacific/Apia's whole-day skip alike.
+ */
+export function resolveWallToInstant(wall: WallClock, zone: string): number {
+  if (zone === "UTC") return wallAsEpochMs(wall);
+  const asUtc = wallAsEpochMs(wall);
+
+  // Fixed-point iteration from the naive reading.
+  let guess = asUtc;
+  let resolved: number | null = null;
+  for (let i = 0; i < 6; i++) {
+    guess = asUtc - offsetMs(guess, zone);
+    if (compareWall(wallOfInstant(guess, zone), wall) === 0) {
+      resolved = guess;
+      break;
+    }
+  }
+
+  // Collect every instant reading this wall time: the resolved one plus
+  // candidates derived from the offsets in effect on either side of it.
+  const matches: number[] = [];
+  const consider = (instant: number) => {
+    if (compareWall(wallOfInstant(instant, zone), wall) === 0) matches.push(instant);
+  };
+  if (resolved !== null) {
+    consider(resolved);
+    consider(asUtc - offsetMs(resolved - SIX_HOURS, zone));
+    consider(asUtc - offsetMs(resolved + SIX_HOURS, zone));
+  }
+  if (matches.length > 0) {
+    // Fold: exactly one firing, at the earliest (earlier-offset) instant.
+    return Math.min(...matches);
+  }
+
+  // Gap: the wall time does not exist. First valid instant after the gap.
+  return firstInstantAfterGap(asUtc, wall, zone);
+}
+
+/**
+ * Earliest instant whose wall clock in `zone` is strictly after `wall`.
+ * A coarse 15-minute scan brackets the transition, then a binary search
+ * narrows to the exact instant (works for 1-hour and whole-day gaps).
+ */
+function firstInstantAfterGap(asUtc: number, wall: WallClock, zone: string): number {
+  const stepMs = 15 * 60_000;
+  // Establish the search invariant wall(lo) <= wall first: the local-as-UTC
+  // reading can already lie past the gap when the transition is large (e.g. a
+  // whole-day skip), so step back until the reading is at or before the target.
+  let lo = asUtc;
+  for (let i = 0; i < 8 * 96 && compareWall(wallOfInstant(lo, zone), wall) > 0; i++) {
+    lo -= stepMs;
+  }
+  for (let i = 0; i < 16 * 96; i++) {
+    const next = lo + stepMs;
+    if (compareWall(wallOfInstant(next, zone), wall) > 0) {
+      return binarySearchFirstAfter(lo, next, wall, zone);
+    }
+    lo = next;
+  }
+  throw new Error(`no instant found after gap at ${JSON.stringify(wall)} in ${zone}`);
+}
+
+/** Invariant: wall(lo) <= wall < wall(hi); returns the smallest such hi. */
+function binarySearchFirstAfter(lo: number, hi: number, wall: WallClock, zone: string): number {
+  while (hi - lo > 1) {
+    const mid = lo + Math.floor((hi - lo) / 2);
+    if (compareWall(wallOfInstant(mid, zone), wall) > 0) {
+      hi = mid;
+    } else {
+      lo = mid;
+    }
+  }
+  return hi;
+}
diff --git a/packages/scheduling/src/nominal.ts b/packages/scheduling/src/nominal.ts
new file mode 100644
index 0000000..592e094
--- /dev/null
+++ b/packages/scheduling/src/nominal.ts
@@ -0,0 +1,65 @@
+import { InvalidNominalLocalError } from "./errors.js";
+import type { NominalLocal, WallClock } from "./timezone.js";
+
+/** Format a wall clock as a nominal local date-time string, `YYYY-MM-DDTHH:mm`. */
+export function formatNominal(wall: WallClock): NominalLocal {
+  const y = String(wall.year).padStart(4, "0");
+  const mo = String(wall.month).padStart(2, "0");
+  const d = String(wall.day).padStart(2, "0");
+  const h = String(wall.hour).padStart(2, "0");
+  const mi = String(wall.minute).padStart(2, "0");
+  return `${y}-${mo}-${d}T${h}:${mi}`;
+}
+
+const NOMINAL_RE = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2})(?::(\d{2}))?$/;
+
+/**
+ * Parse a nominal local date-time string back into a wall clock. Rejects
+ * malformed strings and impossible calendar values with
+ * `InvalidNominalLocalError`. Note the string may denote a wall time that does
+ * not exist in a zone (gap) or exists twice (fold); existence is a
+ * materialization concern, not a parse concern.
+ */
+export function parseNominal(nominal: NominalLocal): WallClock {
+  const match = NOMINAL_RE.exec(nominal);
+  if (!match) {
+    throw new InvalidNominalLocalError(`malformed nominal local date-time: "${nominal}"`);
+  }
+  const wall: WallClock = {
+    year: Number(match[1]),
+    month: Number(match[2]),
+    day: Number(match[3]),
+    hour: Number(match[4]),
+    minute: Number(match[5]),
+    second: match[6] === undefined ? 0 : Number(match[6]),
+  };
+  if (wall.month < 1 || wall.month > 12) {
+    throw new InvalidNominalLocalError(`month out of range in "${nominal}"`);
+  }
+  if (wall.day < 1 || wall.day > 31) {
+    throw new InvalidNominalLocalError(`day out of range in "${nominal}"`);
+  }
+  if (wall.hour > 23 || wall.minute > 59 || wall.second > 59) {
+    throw new InvalidNominalLocalError(`time of day out of range in "${nominal}"`);
+  }
+  return wall;
+}
+
+/** Total ordering over wall clocks; safe because fields are validated. */
+export function compareWall(a: WallClock, b: WallClock): number {
+  if (a.year !== b.year) return a.year < b.year ? -1 : 1;
+  if (a.month !== b.month) return a.month < b.month ? -1 : 1;
+  if (a.day !== b.day) return a.day < b.day ? -1 : 1;
+  if (a.hour !== b.hour) return a.hour < b.hour ? -1 : 1;
+  if (a.minute !== b.minute) return a.minute < b.minute ? -1 : 1;
+  return a.second < b.second ? -1 : a.second > b.second ? 1 : 0;
+}
+
+export function wallEquals(a: WallClock, b: WallClock): boolean {
+  return compareWall(a, b) === 0;
+}
+
+/** Milliseconds between two wall readings when interpreted as UTC. */
+export function wallAsEpochMs(wall: WallClock): number {
+  return Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second);
+}
diff --git a/packages/scheduling/src/occurrences.test.ts b/packages/scheduling/src/occurrences.test.ts
new file mode 100644
index 0000000..f344c48
--- /dev/null
+++ b/packages/scheduling/src/occurrences.test.ts
@@ -0,0 +1,249 @@
+import { describe, expect, it } from "vitest";
+import { nextOccurrences, materializeOccurrences } from "./occurrences_extra.js";
+import { prepareSchedule } from "./schedule.js";
+import { nextOccurrencesPrepared } from "./occurrences.js";
+import { InvalidCronError } from "./errors.js";
+
+const ISO = (occ: { fireAtUtc: number }) => new Date(occ.fireAtUtc).toISOString().replace(".000Z", "Z");
+
+describe("UTC passthrough", () => {
+  it("emits exactly the cron slots with no offset math", () => {
+    const out = nextOccurrences({ cron: "0 9 * * *", timezone: "UTC" }, "2024-03-09T00:00:00Z", 3);
+    expect(out.map(ISO)).toEqual([
+      "2024-03-09T09:00:00Z",
+      "2024-03-10T09:00:00Z",
+      "2024-03-11T09:00:00Z",
+    ]);
+    expect(out.map((o) => o.nominalLocal)).toEqual([
+      "2024-03-09T09:00",
+      "2024-03-10T09:00",
+      "2024-03-11T09:00",
+    ]);
+  });
+  it("daily at 02:30 UTC is unaffected by any DST", () => {
+    const out = nextOccurrences({ cron: "30 2 * * *", timezone: "UTC" }, "2024-03-09T00:00:00Z", 3);
+    expect(out.map(ISO)).toEqual([
+      "2024-03-09T02:30:00Z",
+      "2024-03-10T02:30:00",
+      "2024-03-11T02:30:00Z",
+    ].map((x) => (x.endsWith("Z") ? x : `${x}Z`)));
+  });
+  it("respects hour and minute fields", () => {
+    const out = nextOccurrences({ cron: "15,45 6 * * *", timezone: "UTC" }, "2024-03-09T00:00:00Z", 4);
+    expect(out.map(ISO)).toEqual([
+      "2024-03-09T06:15:00Z",
+      "2024-03-09T06:45:00Z",
+      "2024-03-10T06:15:00Z",
+      "2024-03-10T06:45:00Z",
+    ]);
+  });
+});
+
+describe("Europe/New_York spring-forward gap (2024-03-10 02:00->03:00)", () => {
+  it("daily 02:30: the gap day fires at the shifted-forward instant 03:00 local (07:00Z)", () => {
+    const out = nextOccurrences({ cron: "30 2 * * *", timezone: "America/New_York" }, "2024-03-08T00:00:00Z", 3);
+    expect(out.map(ISO)).toEqual([
+      "2024-03-08T07:30:00Z", // 02:30 EST
+      "2024-03-09T07:30:00Z", // 02:30 EST
+      "2024-03-10T07:00:00Z", // 02:30 does not exist; fires 03:00 EDT
+    ]);
+    // The nominal slot is preserved on the gap day even though the instant
+    // shifted — that is what last_fired_nominal_local records.
+    expect(out[2]!.nominalLocal).toBe("2024-03-10T02:30");
+  });
+  it("a 02:00-only schedule still fires on the gap day, shifted to 03:00 local", () => {
+    const out = nextOccurrences({ cron: "0 2 * * *", timezone: "America/New_York" }, "2024-03-09T00:00:00Z", 3);
+    expect(out.map(ISO)).toEqual([
+      "2024-03-09T07:00:00Z", // 02:00 EST
+      "2024-03-10T07:00:00Z", // 02:00 nonexistent -> 03:00 EDT
+      "2024-03-11T06:00:00Z", // 02:00 EDT
+    ]);
+  });
+});
+
+describe("collapse-dedup: */15 across the spring-forward hour fires once per instant", () => {
+  it("02:00..02:45 nominal slots collapse; the gap instant appears exactly once", () => {
+    const out = nextOccurrences(
+      { cron: "*/15 * * * *", timezone: "America/New_York" },
+      "2024-03-10T05:00:00Z",
+      8,
+    );
+    // 03:00 EDT == 07:00Z is the first valid instant after the gap. The slots
+    // 02:00, 02:15, 02:30, 02:45 all materialize there -> ONE occurrence.
+    // 05:00Z == 00:15 local. The next slots are 00:30(05:30Z), 00:45(05:45Z),
+    // 01:00(06:00Z), 01:15(06:15Z), then the four nominal slots 01:30(06:30Z),
+    // 01:45(06:45Z), 02:00, 02:15, 02:30, 02:45 — of which everything in the
+    // gap collapses onto 03:00 local == 07:00Z — ONE occurrence — followed by
+    // the normal 03:15 cadence.
+    expect(out.map(ISO)).toEqual([
+      "2024-03-10T05:15:00Z",
+      "2024-03-10T05:30:00Z",
+      "2024-03-10T05:45:00Z",
+      "2024-03-10T06:00:00Z",
+      "2024-03-10T06:15:00Z",
+      "2024-03-10T06:30:00Z",
+      "2024-03-10T06:45:00Z",
+      "2024-03-10T07:00:00Z",
+    ]);
+    // The single surviving occurrence at the gap edge carries the LATEST
+    // nominal slot that collapsed onto it — the conservative never-refire label.
+    expect(out[7]!.nominalLocal).toBe("2024-03-10T03:00");
+  });
+  it("the collapse instant appears exactly once even when asking for many", () => {
+    const out = nextOccurrences({ cron: "*/15 * * * *", timezone: "America/New_York" }, "2024-03-10T05:00:00Z", 40);
+    const atEdge = out.filter((o) => o.fireAtUtc === Date.parse("2024-03-10T07:00:00Z"));
+    expect(atEdge.length).toBe(1);
+  });
+  it("produces globally unique fire instants (occurrence key uniqueness)", () => {
+    const out = nextOccurrences({ cron: "*/15 * * * *", timezone: "America/New_York" }, "2024-03-09T00:00:00Z", 200);
+    const instants = out.map((o) => o.fireAtUtc);
+    expect(new Set(instants).size).toBe(instants.length);
+  });
+  it("fold hour: */15 emits each ambiguous quarter-hour once, at the earlier instant", () => {
+    const out = nextOccurrences(
+      { cron: "*/15 * * * *", timezone: "America/New_York" },
+      "2024-11-03T04:00:00Z",
+      8,
+      { exclusive: false },
+    );
+    expect(out.map(ISO)).toEqual([
+      "2024-11-03T04:00:00Z", // 00:00 EDT
+      "2024-11-03T04:15:00Z",
+      "2024-11-03T04:30:00Z",
+      "2024-11-03T04:45:00Z",
+      "2024-11-03T05:00:00Z", // 01:00 EDT (earlier reading)
+      "2024-11-03T05:15:00Z",
+      "2024-11-03T05:30:00Z",
+      "2024-11-03T05:45:00Z",
+    ]);
+  });
+});
+
+describe("fall-back fold — daily 01:30 fires once at the earlier instant", () => {
+  it("fires 05:30Z (EDT), never 06:30Z, and continues next day", () => {
+    const out = nextOccurrences({ cron: "30 1 * * *", timezone: "America/New_York" }, "2024-11-01T00:00:00Z", 3);
+    expect(out.map(ISO)).toEqual([
+      "2024-11-01T05:30:00Z", // 01:30 EDT
+      "2024-11-02T05:30:00Z", // 01:30 EDT
+      "2024-11-03T05:30:00Z", // 01:30 exists twice; fires ONCE at EDT (05:30Z)
+    ]);
+    // and never the later EST reading
+    expect(out.map(ISO)).not.toContain("2024-11-03T06:30:00Z");
+  });
+});
+
+describe("cron day-of-month/month handling", () => {
+  it("monthly on the 1st at 09:00", () => {
+    const out = nextOccurrences({ cron: "0 9 1 * *", timezone: "UTC" }, "2024-01-15T00:00:00Z", 3);
+    expect(out.map(ISO)).toEqual([
+      "2024-02-01T09:00:00Z",
+      "2024-03-01T09:00:00Z",
+      "2024-04-01T09:00:00Z",
+    ]);
+  });
+  it("monthly last-day-ish: the 31st only in long months", () => {
+    const out = nextOccurrences({ cron: "0 9 31 * *", timezone: "UTC" }, "2024-01-01T00:00:00Z", 4);
+    expect(out.map(ISO)).toEqual([
+      "2024-01-31T09:00:00Z",
+      "2024-03-31T09:00:00Z",
+      "2024-05-31T09:00:00Z",
+      "2024-07-31T09:00:00Z",
+    ]);
+  });
+  it("day-of-week: weekly on Monday 09:00", () => {
+    const out = nextOccurrences({ cron: "0 9 * * 1", timezone: "UTC" }, "2024-03-08T00:00:00Z", 3);
+    // 2024-03-08 is a Friday and does not match; the Mondays follow.
+    expect(out.map(ISO)).toEqual([
+      "2024-03-11T09:00:00Z",
+      "2024-03-18T09:00:00Z",
+      "2024-03-25T09:00:00Z",
+    ]);
+    expect(out.every((o) => new Date(o.fireAtUtc).getUTCDay() === 1)).toBe(true);
+  });
+  it("dom/dow OR rule: both restricted means either matches", () => {
+    // 13th OR every Friday (2024-03-01 is itself a Friday but sits exactly at
+    // `from`, so the exclusive default drops it; 03-02 would keep it).
+    const out = nextOccurrences({ cron: "0 0 13 * 5", timezone: "UTC" }, "2024-03-01T00:00:00Z", 6);
+    expect(out.map((o) => o.nominalLocal)).toEqual([
+      "2024-03-08T00:00",
+      "2024-03-13T00:00",
+      "2024-03-15T00:00",
+      "2024-03-22T00:00",
+      "2024-03-29T00:00",
+      "2024-04-05T00:00",
+    ]);
+  });
+  it("dow-only restriction drives the day when dom is *", () => {
+    // Mondays and Fridays only
+    const out = nextOccurrences({ cron: "0 12 * * 1,5", timezone: "UTC" }, "2024-03-04T00:00:00Z", 4);
+    expect(out.map((o) => o.nominalLocal)).toEqual([
+      "2024-03-04T12:00", // Monday
+      "2024-03-08T12:00", // Friday
+      "2024-03-11T12:00", // Monday
+      "2024-03-15T12:00", // Friday
+    ]);
+  });
+  it("hour range with step: 8-18/2 hours", () => {
+    const out = nextOccurrences({ cron: "0 8-18/2 * * *", timezone: "UTC" }, "2024-03-09T00:00:00Z", 7);
+    expect(out.map((o) => o.nominalLocal.slice(11))).toEqual(["08:00", "10:00", "12:00", "14:00", "16:00", "18:00", "08:00"]);
+  });
+  it("month names and dow names", () => {
+    const out = nextOccurrences({ cron: "0 9 1 JAN-MAR *", timezone: "UTC" }, "2024-01-02T00:00:00Z", 2);
+    expect(out.map(ISO)).toEqual(["2024-02-01T09:00:00Z", "2024-03-01T09:00:00Z"]);
+  });
+});
+
+describe("Pacific/Apia whole-day skip in generation", () => {
+  it("daily 09:00 skips 2011-12-30 entirely and resumes 12-31", () => {
+    const out = nextOccurrences({ cron: "0 9 * * *", timezone: "Pacific/Apia" }, "2011-12-28T00:00:00Z", 3);
+    expect(out.map((o) => o.nominalLocal)).toEqual([
+      "2011-12-28T09:00",
+      "2011-12-29T09:00",
+      // The skipped day's slot (12-30 09:00) still fires — shifted forward to
+      // the first valid instant — and keeps its own nominal label so it can
+      // never be refired as a "new" slot later.
+      "2011-12-30T09:00",
+    ]);
+    // Its fire instant is the zone's first valid instant after the skip.
+    expect(new Date(out[2]!.fireAtUtc).toISOString()).toBe("2011-12-30T10:00:00.000Z");
+  });
+});
+
+describe("generation hygiene", () => {
+  it("prepared and unprepared agree", () => {
+    const spec = { cron: "*/20 * * * *", timezone: "America/New_York" };
+    const a = nextOccurrences(spec, "2024-03-09T00:00:00Z", 50);
+    const b = nextOccurrencesPrepared(prepareSchedule(spec), "2024-03-09T00:00:00Z", 50);
+    expect(a).toEqual(b);
+  });
+  it("exclusive default: regenerating from the last emitted instant does not re-emit it", () => {
+    const spec = { cron: "0 * * * *", timezone: "UTC" };
+    const first = nextOccurrences(spec, "2024-03-09T00:00:00Z", 5);
+    const last = first[first.length - 1]!;
+    const second = nextOccurrences(spec, last.fireAtUtc, 5);
+    expect(second[0]!.fireAtUtc).toBeGreaterThan(last.fireAtUtc);
+    expect(second.map(ISO)).toEqual([
+      "2024-03-09T06:00:00Z",
+      "2024-03-09T07:00:00Z",
+      "2024-03-09T08:00:00Z",
+      "2024-03-09T09:00:00Z",
+      "2024-03-09T10:00:00Z",
+    ]);
+  });
+  it("inclusive option includes a slot exactly at from", () => {
+    const out = nextOccurrences({ cron: "0 * * * *", timezone: "UTC" }, "2024-03-09T05:00:00Z", 2, { exclusive: false });
+    expect(out.map(ISO)).toEqual(["2024-03-09T05:00:00Z", "2024-03-09T06:00:00Z"]);
+  });
+  it("rejects a bad count", () => {
+    expect(() => nextOccurrences({ cron: "* * * * *", timezone: "UTC" }, "2024-01-01T00:00:00Z", 0)).toThrow(RangeError);
+    expect(() => nextOccurrences({ cron: "* * * * *", timezone: "UTC" }, "2024-01-01T00:00:00Z", 1.5)).toThrow(RangeError);
+  });
+  it("materializeOccurrences is the generation batch", () => {
+    const out = materializeOccurrences({ cron: "0 9 * * *", timezone: "UTC" }, "2024-03-09T00:00:00Z", 2);
+    expect(out.map(ISO)).toEqual(["2024-03-09T09:00:00Z", "2024-03-10T09:00:00Z"]);
+  });
+  it("rejects invalid cron/zone at generation time", () => {
+    expect(() => nextOccurrences({ cron: "not cron", timezone: "UTC" }, "2024-01-01T00:00:00Z", 1)).toThrow(InvalidCronError);
+    expect(() => nextOccurrences({ cron: "* * * * *", timezone: "local" }, "2024-01-01T00:00:00Z", 1)).toThrow();
+  });
+});
diff --git a/packages/scheduling/src/occurrences.ts b/packages/scheduling/src/occurrences.ts
new file mode 100644
index 0000000..550ece3
--- /dev/null
+++ b/packages/scheduling/src/occurrences.ts
@@ -0,0 +1,120 @@
+import { cronMatchesDay } from "./cron.js";
+import { resolveWallToInstant } from "./materialize.js";
+import { slotNominal, sortedHours, sortedMinutes, type PreparedSchedule } from "./schedule.js";
+import { toInstantMs, wallOfInstant } from "./timezone.js";
+import type { WallClock } from "./timezone.js";
+import type { Occurrence } from "./schedule.js";
+
+export interface NextOccurrencesOptions {
+  /**
+   * When true (default) a slot whose fire instant is exactly `from` is
+   * skipped; when false it is included. The default keeps re-generation
+   * idempotent: re-running generation from the last emitted instant never
+   * re-emits it.
+   */
+  readonly exclusive?: boolean;
+}
+
+
+/** Nominal calendar day (local midnight reading) containing `epochMs`. */
+function startNominalDay(epochMs: number, zone: string): WallClock {
+  const wall = wallOfInstant(epochMs, zone);
+  return { year: wall.year, month: wall.month, day: wall.day, hour: 0, minute: 0, second: 0 };
+}
+
+/** Advance a nominal calendar day by one, purely calendar arithmetic. */
+function nextNominalDay(day: WallClock): WallClock {
+  const next = new Date(Date.UTC(day.year, day.month - 1, day.day + 1));
+  return {
+    year: next.getUTCFullYear(),
+    month: next.getUTCMonth() + 1,
+    day: next.getUTCDate(),
+    hour: 0,
+    minute: 0,
+    second: 0,
+  };
+}
+
+/**
+ * The next `count` occurrences at or after `from`, evaluated in the schedule
+ * zone and materialized to UTC instants.
+ *
+ * Each local day's matching slots are emitted in ascending local order; a
+ * slot's materialization (gap shift-forward, fold earlier-instant) may collide
+ * with another slot's instant — such collisions are deduplicated so each
+ * materialized instant appears exactly once (occurrence key stays unique).
+ * Generation is capped at `maxYears` of local days to bound work for
+ * sparse schedules.
+ */
+export function nextOccurrencesPrepared(
+  prepared: PreparedSchedule,
+  from: Date | number | string,
+  count: number,
+  options?: NextOccurrencesOptions,
+  maxYears = 8,
+): Occurrence[] {
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new RangeError(`count must be a positive integer, got ${count}`);
+  }
+  const zone = prepared.timezone;
+  const cron = prepared.cron;
+  const fromMs = toInstantMs(from);
+  const exclusive = options?.exclusive ?? true;
+  const hours = sortedHours(cron);
+  const minutes = sortedMinutes(cron);
+  const out: Occurrence[] = [];
+  const seen = new Set<number>();
+  // Index of the emitted occurrence per fire instant, so a later nominal slot
+  // collapsing onto an already-emitted instant can take over the label.
+  const indexAt = new Map<number, number>();
+  const dayLimit = Math.ceil(maxYears * 366);
+  // Iterate NOMINAL calendar days (not materialized midnights) so a skipped
+  // local day (Pacific/Apia 2011-12-30) still contributes its slots: every
+  // slot of that day materializes to the first valid instant after the gap and
+  // collapses onto a single occurrence there.
+  let day = startNominalDay(fromMs, zone);
+  // Once `count` occurrences exist, generation may continue only far enough to
+  // finish the collapse set of the LAST emitted instant — later slots of that
+  // same instant must still be able to take over its nominal label — and then
+  // stops. Occurrences are emitted in ascending instant order, so the first
+  // slot materializing strictly after the boundary ends generation.
+  let boundary: number | null = null;
+  for (let dayIndex = 0; dayIndex < dayLimit; dayIndex++) {
+    if (cronMatchesDay(cron, day.year, day.month, day.day)) {
+      for (const hour of hours) {
+        for (const minute of minutes) {
+          const slotWall: WallClock = {
+            year: day.year, month: day.month, day: day.day,
+            hour, minute, second: 0,
+          };
+          const fireAt = resolveWallToInstant(slotWall, zone);
+          if (exclusive ? fireAt <= fromMs : fireAt < fromMs) continue;
+          if (boundary !== null && fireAt > boundary) return out;
+          if (seen.has(fireAt)) {
+            // Collapse: several nominal slots materialized onto one instant
+            // (post-gap). Exactly one occurrence survives per instant, carrying
+            // the LATEST collapsed nominal slot — the conservative value for
+            // the last_fired_nominal_local never-refire gate.
+            const index = indexAt.get(fireAt);
+            if (index !== undefined) {
+              out[index] = {
+                nominalLocal: slotNominal(day.year, day.month, day.day, hour, minute),
+                fireAtUtc: fireAt,
+              };
+            }
+            continue;
+          }
+          seen.add(fireAt);
+          indexAt.set(fireAt, out.length);
+          out.push({
+            nominalLocal: slotNominal(day.year, day.month, day.day, hour, minute),
+            fireAtUtc: fireAt,
+          });
+          if (out.length >= count) boundary = fireAt;
+        }
+      }
+    }
+    day = nextNominalDay(day);
+  }
+  return out;
+}
diff --git a/packages/scheduling/src/occurrences_extra.ts b/packages/scheduling/src/occurrences_extra.ts
new file mode 100644
index 0000000..dbc8bd5
--- /dev/null
+++ b/packages/scheduling/src/occurrences_extra.ts
@@ -0,0 +1,26 @@
+// Convenience wrappers kept in a separate module so occurrences.ts stays a
+// single-purpose iterator. Re-exported through index.ts.
+import { nextOccurrencesPrepared } from "./occurrences.js";
+import { prepareSchedule, type Occurrence, type ScheduleSpec } from "./schedule.js";
+
+/** The next `count` occurrences of `spec` at or after `from` (strictly after). */
+export function nextOccurrences(
+  spec: ScheduleSpec,
+  from: Date | number | string,
+  count: number,
+  options?: { exclusive?: boolean },
+): Occurrence[] {
+  return nextOccurrencesPrepared(prepareSchedule(spec), from, count, options);
+}
+
+/**
+ * Occurrence rows a worker should insert for `spec` from an instant — the
+ * materialization batch keyed by (schedule_id, fire_at_utc).
+ */
+export function materializeOccurrences(
+  spec: ScheduleSpec,
+  from: Date | number | string,
+  count: number,
+): Occurrence[] {
+  return nextOccurrences(spec, from, count);
+}
diff --git a/packages/scheduling/src/property.test.ts b/packages/scheduling/src/property.test.ts
new file mode 100644
index 0000000..f33d9d0
--- /dev/null
+++ b/packages/scheduling/src/property.test.ts
@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import { nextOccurrences } from "./occurrences_extra.js";
+import { materializeOccurrence } from "./materialize-api.js";
+import { wallOfInstant } from "./timezone.js";
+
+/**
+ * Brute-force oracle: scan every minute with Intl and apply the spec rules
+ * independently of the engine's search strategy.
+ *
+ * - a wall reading that matches a cron slot fires at that instant;
+ * - a fold (reading repeats one already seen) fires only at its first instant;
+ * - a gap (the wall clock jumps forward over slot(s)) fires at the instant of
+ *   the jump, labelled with the LATEST skipped slot;
+ * - several slots landing on one instant collapse to a single occurrence.
+ */
+function oracle(cronMinutes: number[], cronHours: number[], zone: string, fromMs: number, toMs: number) {
+  const wanted = new Set<string>();
+  for (const h of cronHours) for (const m of cronMinutes) wanted.add(`${h}:${m}`);
+  const wallKey = (y: number, mo: number, d: number, h: number, mi: number) =>
+    Date.UTC(y, mo - 1, d, h, mi);
+  const byInstant = new Map<number, string>();
+  const seenWalls = new Set<number>();
+  let prevKey: number | null = null;
+  for (let t = fromMs; t <= toMs - 60_000; t += 60_000) {
+    const w = wallOfInstant(t, zone);
+    const key = wallKey(w.year, w.month, w.day, w.hour, w.minute);
+    const label = `${w.year}-${pad(w.month)}-${pad(w.day)}T${pad(w.hour)}:${pad(w.minute)}`;
+    // Fold: this wall reading already fired at its earlier instant.
+    if (seenWalls.has(key)) {
+      prevKey = key;
+      continue;
+    }
+    seenWalls.add(key);
+    // Gap: the wall clock jumped. Any wanted slot strictly between the previous
+    // reading and this one did not exist; it fires HERE (shift forward), and
+    // several skipped slots collapse onto this single instant.
+    if (prevKey !== null && key - prevKey > 60_000) {
+      for (let k = prevKey + 60_000; k < key; k += 60_000) {
+        const kk = new Date(k);
+        if (wanted.has(`${kk.getUTCHours()}:${kk.getUTCMinutes()}`)) {
+          const d = kk.getUTCDate();
+          const mo = kk.getUTCMonth() + 1;
+          const y = kk.getUTCFullYear();
+          byInstant.set(t, `${y}-${pad(mo)}-${pad(d)}T${pad(kk.getUTCHours())}:${pad(kk.getUTCMinutes())}`);
+        }
+      }
+    }
+    if (wanted.has(`${w.hour}:${w.minute}`)) {
+      byInstant.set(t, label);
+    }
+    prevKey = key;
+  }
+  return [...byInstant.entries()]
+    .sort((a, b) => a[0] - b[0])
+    .map(([fireAtUtc, nominalLocal]) => ({ nominalLocal, fireAtUtc }));
+}
+
+const pad = (n: number) => String(n).padStart(2, "0");
+
+describe("cross-zone property: generator matches a brute-force minute oracle", () => {
+  const cases: Array<{ name: string; zone: string; from: string; to: string; cron: string }> = [
+    { name: "NY hourly across both 2024 transitions", zone: "America/New_York", from: "2024-03-09T00:00:00Z", to: "2024-03-12T00:00:00Z", cron: "0 * * * *" },
+    { name: "NY quarter-hours across spring-forward", zone: "America/New_York", from: "2024-03-10T00:00:00Z", to: "2024-03-11T00:00:00Z", cron: "*/15 * * * *" },
+    { name: "NY quarter-hours across fall-back", zone: "America/New_York", from: "2024-11-03T00:00:00Z", to: "2024-11-04T00:00:00Z", cron: "*/15 * * * *" },
+    { name: "Berlin hourly across spring-forward", zone: "Europe/Berlin", from: "2024-03-30T00:00:00Z", to: "2024-04-02T00:00:00Z", cron: "0 * * * *" },
+    { name: "Apia daily across the 2011 whole-day skip", zone: "Pacific/Apia", from: "2011-12-27T00:00:00Z", to: "2012-01-02T00:00:00Z", cron: "0 9 * * *" },
+    { name: "Apia hourly across the skip", zone: "Pacific/Apia", from: "2011-12-29T00:00:00Z", to: "2011-12-31T00:00:00Z", cron: "30 * * * *" },
+    { name: "Lord Howe 30-minute transition (spring)", zone: "Australia/Lord_Howe", from: "2024-10-04T00:00:00Z", to: "2024-10-08T00:00:00Z", cron: "0 * * * *" },
+    { name: "Lord Howe 30-minute transition (fall)", zone: "Australia/Lord_Howe", from: "2024-04-04T00:00:00Z", to: "2024-04-08T00:00:00Z", cron: "0 * * * *" },
+    { name: "Kathmandu 45-minute offset (no DST)", zone: "Asia/Kathmandu", from: "2024-03-01T00:00:00Z", to: "2024-03-04T00:00:00Z", cron: "*/20 * * * *" },
+    { name: "Chatham Islands 45-min offset with DST", zone: "Pacific/Chatham", from: "2024-04-05T00:00:00Z", to: "2024-04-09T00:00:00Z", cron: "0 * * * *" },
+    { name: "UTC passthrough", zone: "UTC", from: "2024-03-09T00:00:00Z", to: "2024-03-11T00:00:00Z", cron: "*/30 * * * *" },
+    { name: "Santiago delayed transition (midnight)", zone: "America/Santiago", from: "2024-09-07T00:00:00Z", to: "2024-09-10T00:00:00Z", cron: "0 * * * *" },
+  ];
+
+  it.each(cases.map((c) => [c.name, c] as const))("%s", (_name, c) => {
+    const fromMs = Date.parse(c.from);
+    const toMs = Date.parse(c.to);
+    // Derive the oracle's slot sets from the same cron fields the generator
+    // parses, so the comparison exercises materialization and ordering — not
+    // cron parsing (covered separately in cron.test.ts).
+    const fields = c.cron.split(/\s+/);
+    const minuteField = fields[0]!;
+    const hourField = fields[1]!;
+    const minutes = minuteField.startsWith("*/")
+      ? Array.from({ length: Math.ceil(60 / Number(minuteField.slice(2))) }, (_, i) => i * Number(minuteField.slice(2))).filter((m) => m < 60)
+      : minuteField.split(",").map(Number);
+    const hours = hourField === "*" ? Array.from({ length: 24 }, (_, i) => i) : hourField.split(",").map(Number);
+    const wanted = oracle(minutes, hours, c.zone, fromMs, toMs);
+    // Inclusive so the generator's window matches the oracle's inclusive scan.
+    const got = nextOccurrences({ cron: c.cron, timezone: c.zone }, c.from, wanted.length || 1, { exclusive: false });
+    expect(got.map((o) => [o.nominalLocal, o.fireAtUtc])).toEqual(wanted.map((o) => [o.nominalLocal, o.fireAtUtc]));
+  });
+});
+
+describe("materializeOccurrence inverts wallOfInstant", () => {
+  const zones = ["America/New_York", "Europe/Berlin", "Pacific/Apia", "Australia/Lord_Howe", "Pacific/Chatham", "Asia/Kathmandu", "UTC"];
+  // Hourly around each hemisphere's 2024 transitions (where inversions can
+  // happen) plus a coarse 12-hourly annual sweep.
+  const windows = [
+    ["2024-03-08T00:00:00Z", "2024-03-13T00:00:00Z"],
+    ["2024-11-01T00:00:00Z", "2024-11-06T00:00:00Z"],
+    ["2024-09-28T00:00:00Z", "2024-10-10T00:00:00Z"],
+    ["2024-04-01T00:00:00Z", "2024-04-09T00:00:00Z"],
+    ["2011-12-27T00:00:00Z", "2012-01-03T00:00:00Z"],
+  ] as const;
+  const steps: Array<[number, number]> = [
+    ...windows.map((w) => [Date.parse(w[0]), Date.parse(w[1])] as [number, number]),
+    [Date.parse("2024-01-01T00:00:00Z"), Date.parse("2025-01-01T00:00:00Z")],
+  ];
+  it.each(zones.map((z) => [z]))("round-trips wall readings in %s", (zone) => {
+    let folds = 0;
+    let checked = 0;
+    for (const [start, end] of steps) {
+      const step = end - start > 20 * 86400_000 ? 12 * 3600_000 : 3600_000;
+      for (let t = start; t < end; t += step) {
+        const w = wallOfInstant(t, zone);
+        const nominal = `${w.year}-${String(w.month).padStart(2, "0")}-${String(w.day).padStart(2, "0")}T${String(w.hour).padStart(2, "0")}:${String(w.minute).padStart(2, "0")}`;
+        const back = materializeOccurrence(nominal, zone);
+        checked++;
+        if (back === t) continue;
+        // Only fold readings may differ, and only by the offset delta (back < t).
+        expect(back).toBeLessThan(t);
+        expect(t - back).toBeLessThanOrEqual(3600_000);
+        folds++;
+      }
+    }
+    expect(checked).toBeGreaterThan(100);
+    expect(folds).toBeLessThanOrEqual(6);
+  });
+});
diff --git a/packages/scheduling/src/rematerialize.test.ts b/packages/scheduling/src/rematerialize.test.ts
new file mode 100644
index 0000000..5970ce6
--- /dev/null
+++ b/packages/scheduling/src/rematerialize.test.ts
@@ -0,0 +1,198 @@
+import { describe, expect, it } from "vitest";
+import { rematerialize } from "./rematerialize.js";
+import { nextOccurrences } from "./occurrences_extra.js";
+import type { StoredOccurrence } from "./rematerialize.js";
+
+/** Build stored rows as a worker would have persisted them. */
+function storedFrom(spec: { cron: string; timezone: string }, from: string, count: number): StoredOccurrence[] {
+  return nextOccurrences(spec, from, count).map((o) => ({
+    nominalLocal: o.nominalLocal,
+    fireAtUtc: o.fireAtUtc,
+    claimed: false,
+  }));
+}
+
+describe("rematerialize — invalidation and regeneration", () => {
+  it("deletes unclaimed future occurrences and regenerates from the change instant", () => {
+    const oldSpec = { cron: "0 9 * * *", timezone: "America/New_York" };
+    const stored = storedFrom(oldSpec, "2024-03-01T00:00:00Z", 5);
+    // One past occurrence was claimed.
+    stored[0] = { ...stored[0]!, claimed: true };
+    const changeInstant = "2024-03-02T00:00:00Z";
+
+    const result = rematerialize(oldSpec, { cron: "0 10 * * *", timezone: "America/New_York" }, stored, {
+      changeInstant,
+      lastFiredNominalLocal: stored[0]!.nominalLocal,
+      count: 3,
+    });
+
+    // Unclaimed future rows are invalidated.
+    expect(result.toDeleteFireAtUtc).toEqual(
+      stored.slice(1).map((r) => r.fireAtUtc),
+    );
+    // New occurrences start strictly after the change instant and the last claim.
+    expect(result.toInsert.length).toBe(3);
+    expect(result.toInsert[0]!.fireAtUtc).toBeGreaterThan(Date.parse(changeInstant));
+    expect(result.toInsert[0]!.nominalLocal).toBe("2024-03-02T10:00");
+    // The new tzdata version is reported for recording.
+    expect(result.tzdataVersion).toMatch(/.+/);
+  });
+
+  it("never refires a nominal slot already fired under the old zone (NY -> LA same day)", () => {
+    // Daily 09:00. Under New York the 2024-03-01 09:00 slot fired at 14:00Z.
+    const oldSpec = { cron: "0 9 * * *", timezone: "America/New_York" };
+    const stored: StoredOccurrence[] = [
+      { nominalLocal: "2024-03-01T09:00", fireAtUtc: Date.parse("2024-03-01T14:00:00Z"), claimed: true },
+      ...storedFrom(oldSpec, "2024-03-02T00:00:00Z", 3),
+    ];
+    const result = rematerialize(oldSpec, { cron: "0 9 * * *", timezone: "America/Los_Angeles" }, stored, {
+      changeInstant: "2024-03-01T15:00:00Z", // later the same day, after the NY firing
+      lastFiredNominalLocal: "2024-03-01T09:00",
+      count: 3,
+    });
+    // 09:00 in Los Angeles on 03-01 is 17:00Z — but that nominal slot was
+    // already fired under New York, so it must NOT appear.
+    expect(result.toInsert.map((o) => o.nominalLocal)).not.toContain("2024-03-01T09:00");
+    expect(result.toInsert.map((o) => o.nominalLocal)).toEqual([
+      "2024-03-02T09:00",
+      "2024-03-03T09:00",
+      "2024-03-04T09:00",
+    ].slice(0, 3));
+    expect(result.toInsert[0]!.fireAtUtc).toBe(Date.parse("2024-03-02T17:00:00Z"));
+  });
+
+  it("claimed rows are never deleted", () => invariants());
+
+  function invariants(): boolean {
+    const oldSpec = { cron: "0 9 * * *", timezone: "America/New_York" };
+    const stored = storedFrom(oldSpec, "2024-03-01T00:00:00Z", 5);
+    stored[0] = { ...stored[0]!, claimed: true };
+    const result = rematerialize(oldSpec, oldSpec, stored, {
+      changeInstant: "2024-03-02T00:00:00Z",
+      lastFiredNominalLocal: stored[0]!.nominalLocal,
+      count: 3,
+    });
+    expect(result.toDeleteFireAtUtc).not.toContain(stored[0]!.fireAtUtc);
+    return true;
+  }
+
+  it("inserts never collide with SURVIVING rows (deletes are applied first)", () => {
+    const oldSpec = { cron: "0 9 * * *", timezone: "America/New_York" };
+    const stored = storedFrom(oldSpec, "2024-03-01T00:00:00Z", 5);
+    stored[0] = { ...stored[0]!, claimed: true };
+    const result = rematerialize(oldSpec, oldSpec, stored, {
+      changeInstant: "2024-03-01T00:00:00Z",
+      lastFiredNominalLocal: stored[0]!.nominalLocal,
+      count: 10,
+    });
+    const deleting = new Set(result.toDeleteFireAtUtc);
+    const surviving = stored.filter((r) => !deleting.has(r.fireAtUtc)).map((r) => r.fireAtUtc);
+    expect(surviving).toEqual([stored[0]!.fireAtUtc]); // only the claimed row survives
+    for (const o of result.toInsert) {
+      expect(surviving.includes(o.fireAtUtc)).toBe(false);
+    }
+  });
+
+  it("unchanged spec regenerates the same instants it deleted (idempotent)", () => {
+    const spec = { cron: "0 9 * * *", timezone: "America/New_York" };
+    const stored = storedFrom(spec, "2024-03-01T00:00:00Z", 5);
+    stored[0] = { ...stored[0]!, claimed: true };
+    const result = rematerialize(spec, spec, stored, {
+      changeInstant: "2024-03-01T00:00:00Z",
+      lastFiredNominalLocal: stored[0]!.nominalLocal,
+      count: stored.length - 1, // regenerate exactly the deleted horizon
+    });
+    const deletedSorted = [...result.toDeleteFireAtUtc].sort((a, b) => a - b);
+    expect(result.toInsert.map((o) => o.fireAtUtc)).toEqual(deletedSorted);
+  });
+
+  it("toInsert fire instants are unique among themselves and cross the gap once", () => {
+    const spec = { cron: "*/15 * * * *", timezone: "America/New_York" };
+    const stored = storedFrom(spec, "2024-03-08T00:00:00Z", 20);
+    // 150 quarter-hours from 03-09 00:15Z reaches past the 03-10 07:00Z edge.
+    const result = rematerialize(spec, spec, stored, { changeInstant: "2024-03-09T00:00:00Z", count: 150 });
+    const instants = result.toInsert.map((o) => o.fireAtUtc);
+    expect(new Set(instants).size).toBe(instants.length);
+    const edge = instants.filter((i) => i === Date.parse("2024-03-10T07:00:00Z"));
+    expect(edge.length).toBe(1);
+    // The nominal slots 02:00..02:45 collapse onto that one instant, and the
+    // surviving occurrence carries the latest collapsed nominal slot.
+    const atEdge = result.toInsert.find((o) => o.fireAtUtc === Date.parse("2024-03-10T07:00:00Z"));
+    expect(atEdge?.nominalLocal).toBe("2024-03-10T03:00");
+  });
+
+  it("tzdata-only change (same zone) still regenerates correctly", () => {
+    const spec = { cron: "0 9 * * *", timezone: "America/New_York" };
+    const stored = storedFrom(spec, "2024-03-01T00:00:00Z", 3);
+    const result = rematerialize(spec, spec, stored, {
+      changeInstant: "2024-03-01T00:00:00Z",
+      tzdataVersion: "2025a",
+      count: 2,
+    });
+    expect(result.tzdataVersion).toBe("2025a");
+    expect(result.toInsert.length).toBe(2);
+  });
+
+  it("reports the current tzdata version when not overridden", () => {
+    const spec = { cron: "0 9 * * *", timezone: "UTC" };
+    const result = rematerialize(spec, spec, [], { changeInstant: "2024-01-01T00:00:00Z" });
+    expect(typeof result.tzdataVersion).toBe("string");
+    expect(result.tzdataVersion.length).toBeGreaterThan(0);
+  });
+
+  it("a schedule with no history regenerates from the change instant alone", () => {
+    const spec = { cron: "0 9 * * *", timezone: "UTC" };
+    const result = rematerialize(spec, { ...spec, timezone: "Europe/Berlin" }, [], {
+      changeInstant: "2024-03-05T00:00:00Z",
+      count: 2,
+    });
+    expect(result.toInsert.map((o) => o.nominalLocal)).toEqual([
+      "2024-03-05T09:00",
+      "2024-03-06T09:00",
+    ]);
+    expect(result.toDeleteFireAtUtc).toEqual([]);
+  });
+
+  it("unclaimed PAST occurrences are not deleted (only future ones)", () => {
+    const spec = { cron: "0 9 * * *", timezone: "UTC" };
+    const stored: StoredOccurrence[] = [
+      { nominalLocal: "2024-02-01T09:00", fireAtUtc: Date.parse("2024-02-01T09:00:00Z"), claimed: false },
+      { nominalLocal: "2024-04-01T09:00", fireAtUtc: Date.parse("2024-04-01T09:00:00Z"), claimed: false },
+    ];
+    const result = rematerialize(spec, spec, stored, { changeInstant: "2024-03-01T00:00:00Z" });
+    expect(result.toDeleteFireAtUtc).toEqual([Date.parse("2024-04-01T09:00:00Z")]);
+  });
+
+  it("survives a whole-day skip: Apia daily 09:00 across the 2011 change", () => {
+    const spec = { cron: "0 9 * * *", timezone: "Pacific/Apia" };
+    const stored = storedFrom(spec, "2011-12-28T00:00:00Z", 3);
+    const result = rematerialize(spec, spec, stored, {
+      changeInstant: "2011-12-29T12:00:00Z",
+      lastFiredNominalLocal: "2011-12-28T09:00",
+      count: 2,
+    });
+    expect(result.toInsert.map((o) => o.nominalLocal)).toEqual([
+      "2011-12-29T09:00",
+      "2011-12-30T09:00", // skipped day, shifted forward
+    ]);
+  });
+});
+
+describe("rematerialize — input validation", () => {
+  it("rejects an invalid new zone", () => {
+    const spec = { cron: "0 9 * * *", timezone: "UTC" };
+    expect(() =>
+      rematerialize(spec, { cron: "0 9 * * *", timezone: "local" }, [], { changeInstant: "2024-01-01T00:00:00Z" }),
+    ).toThrow();
+  });
+  it("rejects an invalid new cron", () => {
+    const spec = { cron: "0 9 * * *", timezone: "UTC" };
+    expect(() =>
+      rematerialize(spec, { cron: "99 * * * *", timezone: "UTC" }, [], { changeInstant: "2024-01-01T00:00:00Z" }),
+    ).toThrow();
+  });
+  it("rejects an offset-less change instant", () => {
+    const spec = { cron: "0 9 * * *", timezone: "UTC" };
+    expect(() => rematerialize(spec, spec, [], { changeInstant: "2024-01-01T00:00:00" })).toThrow();
+  });
+});
diff --git a/packages/scheduling/src/rematerialize.ts b/packages/scheduling/src/rematerialize.ts
new file mode 100644
index 0000000..ef19e27
--- /dev/null
+++ b/packages/scheduling/src/rematerialize.ts
@@ -0,0 +1,121 @@
+import { nextOccurrencesPrepared } from "./occurrences.js";
+import { prepareSchedule, type Occurrence, type ScheduleSpec } from "./schedule.js";
+import { currentTzdataVersion, toInstantMs } from "./timezone.js";
+import type { NominalLocal } from "./timezone.js";
+
+/** A stored occurrence row, as read from `schedule_occurrences`. */
+export interface StoredOccurrence {
+  /** Nominal local slot of this row (e.g. `2024-03-10T09:00`). */
+  readonly nominalLocal: NominalLocal;
+  /** Materialized UTC fire instant, epoch ms. */
+  readonly fireAtUtc: number;
+  /** Whether a claim has been taken on this row. */
+  readonly claimed: boolean;
+}
+
+export interface RematerializeOptions {
+  /**
+   * Instant the zone/tzdata change was applied (epoch ms). New occurrences
+   * must fire strictly after max(this, last claimed fire instant).
+   */
+  readonly changeInstant: Date | number | string;
+  /**
+   * `last_fired_nominal_local` recorded on the schedule — the local slot of
+   * the last claimed occurrence. New occurrences must be in a strictly later
+   * nominal slot, so a slot already fired under the old zone never refires.
+   */
+  readonly lastFiredNominalLocal?: NominalLocal;
+  /** How many future occurrences to generate after the change. */
+  readonly count?: number;
+  /** Override the recorded tzdata version in tests. */
+  readonly tzdataVersion?: string;
+}
+
+export interface RematerializeResult {
+  /** Occurrences to insert, ascending by fire instant. */
+  readonly toInsert: Occurrence[];
+  /** Fire instants (epoch ms) of unclaimed future rows to delete. */
+  readonly toDeleteFireAtUtc: number[];
+  /** The tzdata version backing this materialization, to record on the schedule. */
+  readonly tzdataVersion: string;
+}
+
+/**
+ * Re-materialize a schedule after a tzdata or timezone change.
+ *
+ * Order of operations mirrors the spec: first, all *unclaimed* future
+ * occurrences are invalidated (their fire instants are returned for deletion);
+ * then new occurrences are generated — only those whose fire instant is
+ * strictly after max(change instant, last claimed fire instant) AND whose
+ * nominal local slot is strictly later than `last_fired_nominal_local`, so a
+ * slot already fired under the old zone (daily 09:00 fired in New York, then
+ * zone switched to Los Angeles) is never fired again.
+ *
+ * Claimed rows are never deleted and never regenerate: their fire instants
+ * already happened or are owned by a claim.
+ */
+export function rematerialize(
+  oldSpec: ScheduleSpec,
+  newSpec: ScheduleSpec,
+  stored: readonly StoredOccurrence[],
+  options: RematerializeOptions,
+): RematerializeResult {
+  const changeMs = toInstantMs(options.changeInstant);
+  const lastFiredNominal = options.lastFiredNominalLocal;
+  const tzVersion = options.tzdataVersion ?? currentTzdataVersion();
+
+  // 1) Invalidate every unclaimed future occurrence: its fire instant is
+  //    returned for deletion. Claimed rows survive untouched.
+  const toDeleteFireAtUtc: number[] = [];
+  let lastClaimedFireMs: number | null = null;
+  let maxClaimedNominal: NominalLocal | null = null;
+  for (const row of stored) {
+    if (row.claimed) {
+      if (lastClaimedFireMs === null || row.fireAtUtc > lastClaimedFireMs) {
+        lastClaimedFireMs = row.fireAtUtc;
+        maxClaimedNominal = row.nominalLocal;
+      }
+      continue;
+    }
+    if (row.fireAtUtc > changeMs) {
+      toDeleteFireAtUtc.push(row.fireAtUtc);
+    }
+  }
+
+  // Effective refire gate: max(change instant, last claimed fire instant).
+  const gateMs = Math.max(changeMs, lastClaimedFireMs ?? Number.NEGATIVE_INFINITY);
+  // Effective nominal gate: the later of the recorded last-fired slot and the
+  // latest claimed row's slot (rows are the runtime truth).
+  let nominalGate: NominalLocal | null = lastFiredNominal ?? null;
+  if (maxClaimedNominal !== null && (nominalGate === null || maxClaimedNominal > nominalGate)) {
+    nominalGate = maxClaimedNominal;
+  }
+
+  // 2) Generate forward from the gate, skipping any slot not strictly later
+  //    than the nominal gate.
+  const count = options.count ?? 32;
+  const prepared = prepareSchedule(newSpec);
+  const candidates = nextOccurrencesPrepared(
+    prepared,
+    gateMs,
+    count * 4,
+    { exclusive: true },
+  );
+  // Only rows that SURVIVE the change may block regeneration: claimed rows and
+  // unclaimed rows already in the past. Rows being deleted are being replaced,
+  // so their instants must not suppress the regenerated occurrences.
+  const deleting = new Set(toDeleteFireAtUtc);
+  const existing = new Set(
+    stored.filter((row) => !deleting.has(row.fireAtUtc)).map((row) => row.fireAtUtc),
+  );
+  const toInsert: Occurrence[] = [];
+  for (const occurrence of candidates) {
+    if (occurrence.fireAtUtc <= gateMs) continue;
+    if (nominalGate !== null && occurrence.nominalLocal <= nominalGate) continue;
+    if (existing.has(occurrence.fireAtUtc)) continue;
+    toInsert.push(occurrence);
+    if (toInsert.length >= count) break;
+  }
+  toInsert.sort((a, b) => a.fireAtUtc - b.fireAtUtc);
+  return { toInsert, toDeleteFireAtUtc, tzdataVersion: tzVersion };
+}
diff --git a/packages/scheduling/src/schedule.ts b/packages/scheduling/src/schedule.ts
new file mode 100644
index 0000000..6ff35e6
--- /dev/null
+++ b/packages/scheduling/src/schedule.ts
@@ -0,0 +1,96 @@
+import { cronMatchesDay, type ParsedCron } from "./cron.js";
+import { formatNominal } from "./nominal.js";
+import { resolveWallToInstant } from "./materialize.js";
+import { canonicalTimezone, wallOfInstant } from "./timezone.js";
+import { parseCron } from "./cron.js";
+import type { NominalLocal } from "./timezone.js";
+
+/** A schedule's time specification: five-field cron in an explicit IANA zone. */
+export interface ScheduleSpec {
+  /** Five-field cron expression, e.g. `*\/15 * * * *`. */
+  readonly cron: string;
+  /** Explicit IANA zone id — never server-local. `UTC` is allowed. */
+  readonly timezone: string;
+}
+
+/** A materialized occurrence: nominal local slot plus its UTC fire instant. */
+export interface Occurrence {
+  /** Local date-time of this slot in the schedule zone, e.g. `2024-03-10T02:30`. */
+  nominalLocal: NominalLocal;
+  /** Materialized UTC fire instant in epoch milliseconds. */
+  fireAtUtc: number;
+}
+
+/** A schedule validated once, reusable across calls. */
+export interface PreparedSchedule {
+  readonly cron: ParsedCron;
+  readonly timezone: string;
+  readonly spec: ScheduleSpec;
+}
+
+/**
+ * Validate a spec (cron + zone) once. Throws `InvalidCronError`,
+ * `ImpossibleScheduleError` or `InvalidTimezoneError` on bad input.
+ */
+export function prepareSchedule(spec: ScheduleSpec): PreparedSchedule {
+  return {
+    cron: parseCron(spec.cron),
+    timezone: canonicalTimezone(spec.timezone),
+    spec: { cron: spec.cron, timezone: spec.timezone },
+  };
+}
+
+/** Hour values sorted ascending for deterministic day-slot iteration. */
+export function sortedHours(cron: ParsedCron): number[] {
+  return [...cron.hour.values].sort((a, b) => a - b);
+}
+
+
+
+/** Builds the nominal-local string for one slot on a matching local day. */
+export function slotNominal(year: number, month: number, day: number, hour: number, minute: number): NominalLocal {
+  const y = String(year).padStart(4, "0");
+  const mo = String(month).padStart(2, "0");
+  const d = String(day).padStart(2, "0");
+  const h = String(hour).padStart(2, "0");
+  const mi = String(minute).padStart(2, "0");
+  return `${y}-${mo}-${d}T${h}:${mi}`;
+}
+
+/**
+ * Iterate matching local days at or after a starting local day. Returns each
+ * matching day's wall clock at local midnight (materialized to an instant so
+ * the caller can step by absolute time across DST).
+ */
+export function* matchingLocalDays(
+  cron: ParsedCron,
+  startDayEpoch: number,
+  zone: string,
+  maxDays: number,
+): Generator<{ wall: ReturnType<typeof wallOfInstant>; midnightInstant: number }> {
+  let cursor = startDayEpoch;
+  for (let i = 0; i < maxDays; i++) {
+    const wall = wallOfInstant(cursor, zone);
+    if (cronMatchesDay(cron, wall.year, wall.month, wall.day)) {
+      yield { wall, midnightInstant: cursor };
+    }
+    cursor = stepOneLocalDay(cursor, zone);
+  }
+}
+
+/** Advance to the next local midnight, robust across 23/24/25-hour days. */
+export function stepOneLocalDay(dayEpoch: number, zone: string): number {
+  const nextApprox = dayEpoch + 24 * 3600_000;
+  const nextWall = wallOfInstant(nextApprox, zone);
+  return resolveWallToInstant(
+    { year: nextWall.year, month: nextWall.month, day: nextWall.day, hour: 0, minute: 0, second: 0 },
+    zone,
+  );
+}
+
+export { formatNominal };
+
+/** Minute values sorted ascending for deterministic day-slot iteration. */
+export function sortedMinutes(cron: ParsedCron): number[] {
+  return [...cron.minute.values].sort((a, b) => a - b);
+}
diff --git a/packages/scheduling/src/timezone.test.ts b/packages/scheduling/src/timezone.test.ts
new file mode 100644
index 0000000..454327e
--- /dev/null
+++ b/packages/scheduling/src/timezone.test.ts
@@ -0,0 +1,92 @@
+import { describe, expect, it } from "vitest";
+import {
+  canonicalTimezone,
+  currentTzdataVersion,
+  isValidTimezone,
+  offsetMs,
+  toInstantMs,
+  wallOfInstant,
+} from "./timezone.js";
+import { InvalidInstantError, InvalidTimezoneError } from "./errors.js";
+
+describe("canonicalTimezone", () => {
+  it("accepts and canonicalizes IANA ids", () => {
+    expect(canonicalTimezone("America/New_York")).toBe("America/New_York");
+    expect(canonicalTimezone("US/Eastern")).toBe("America/New_York");
+    expect(canonicalTimezone("  Europe/Paris ")).toBe("Europe/Paris");
+    expect(canonicalTimezone("Etc/GMT+5")).toBe("Etc/GMT+5");
+  });
+  it("accepts UTC in several spellings", () => {
+    expect(canonicalTimezone("UTC")).toBe("UTC");
+    expect(canonicalTimezone("gmt")).toBe("UTC");
+    expect(canonicalTimezone("Zulu")).toBe("UTC");
+  });
+  it("rejects unknown zones", () => {
+    expect(() => canonicalTimezone("America/Nowhere")).toThrow(InvalidTimezoneError);
+    expect(() => canonicalTimezone("Mars/Olympus")).toThrow(InvalidTimezoneError);
+  });
+  it("rejects offset spellings and empty input", () => {
+    for (const bad of ["UTC+3", "+05:30", "-08:00", "5", ""]) {
+      expect(() => canonicalTimezone(bad)).toThrow(InvalidTimezoneError);
+    }
+  });
+  it("rejects server-local idioms — a schedule zone must be explicit", () => {
+    for (const bad of ["local", "system", "server", "SERVER", "server-local", "machine"]) {
+      expect(() => canonicalTimezone(bad)).toThrow(InvalidTimezoneError);
+    }
+  });
+  it("isValidTimezone mirrors canonicalTimezone", () => {
+    expect(isValidTimezone("Europe/Berlin")).toBe(true);
+    expect(isValidTimezone("local")).toBe(false);
+    expect(isValidTimezone("America/Nowhere")).toBe(false);
+  });
+});
+
+describe("wallOfInstant / offsetMs", () => {
+  it("reads New York offsets across the 2024 transitions", () => {
+    expect(offsetMs(Date.parse("2024-03-10T06:59:59Z"), "America/New_York")).toBe(-5 * 3600_000);
+    expect(offsetMs(Date.parse("2024-03-10T07:00:00Z"), "America/New_York")).toBe(-4 * 3600_000);
+    expect(offsetMs(Date.parse("2024-11-03T05:59:59Z"), "America/New_York")).toBe(-4 * 3600_000);
+    expect(offsetMs(Date.parse("2024-11-03T06:00:00Z"), "America/New_York")).toBe(-5 * 3600_000);
+  });
+  it("reads half-hour and 45-minute zones", () => {
+    expect(offsetMs(Date.parse("2024-06-01T12:00:00Z"), "Asia/Kolkata")).toBe(5.5 * 3600_000);
+    expect(offsetMs(Date.parse("2024-06-01T12:00:00Z"), "Asia/Kathmandu")).toBe(5.75 * 3600_000);
+  });
+  it("sees Pacific/Apia's 2011 whole-day skip", () => {
+    const before = wallOfInstant(Date.parse("2011-12-29T09:59:59Z"), "Pacific/Apia");
+    const after = wallOfInstant(Date.parse("2011-12-30T10:00:00Z"), "Pacific/Apia");
+    expect(`${before.year}-${before.month}-${before.day}`).toBe("2011-12-28");
+    expect(`${after.year}-${after.month}-${after.day}`).toBe("2011-12-31");
+  });
+  it("returns UTC fields without a formatter", () => {
+    const wall = wallOfInstant(Date.parse("2024-03-10T02:30:00Z"), "UTC");
+    expect([wall.year, wall.month, wall.day, wall.hour, wall.minute]).toEqual([2024, 3, 10, 2, 30]);
+  });
+});
+
+describe("toInstantMs", () => {
+  it("accepts dates, numbers and offset-carrying ISO strings", () => {
+    expect(toInstantMs(new Date("2024-03-10T02:30:00Z"))).toBe(Date.parse("2024-03-10T02:30:00Z"));
+    expect(toInstantMs(1710038400000)).toBe(1710038400000);
+    expect(toInstantMs("2024-03-10T02:30:00Z")).toBe(Date.parse("2024-03-10T02:30:00Z"));
+    expect(toInstantMs("2024-03-10T04:30:00+02:00")).toBe(Date.parse("2024-03-10T02:30:00Z"));
+  });
+  it("rejects offset-less datetimes that would parse server-local", () => {
+    for (const bad of ["2024-03-10T02:30:00", "2024-03-10 02:30", "2024-03-10T02:30:00.500"]) {
+      expect(() => toInstantMs(bad)).toThrow(InvalidInstantError);
+    }
+  });
+  it("rejects NaN/Infinity/garbage", () => {
+    expect(() => toInstantMs(new Date(NaN))).toThrow(InvalidInstantError);
+    expect(() => toInstantMs(Number.NaN)).toThrow(InvalidInstantError);
+    expect(() => toInstantMs(Number.POSITIVE_INFINITY)).toThrow(InvalidInstantError);
+    expect(() => toInstantMs("not a date")).toThrow(InvalidInstantError);
+  });
+});
+
+describe("currentTzdataVersion", () => {
+  it("returns a non-empty version string", () => {
+    expect(currentTzdataVersion()).toMatch(/.+/);
+  });
+});
diff --git a/packages/scheduling/src/timezone.ts b/packages/scheduling/src/timezone.ts
new file mode 100644
index 0000000..6040218
--- /dev/null
+++ b/packages/scheduling/src/timezone.ts
@@ -0,0 +1,212 @@
+import { InvalidInstantError, InvalidTimezoneError } from "./errors.js";
+
+/**
+ * Wall-clock reading of an instant in some zone. Fields are the raw numeric
+ * calendar values (month 1-12, day 1-31, hour 0-23).
+ */
+export interface WallClock {
+  readonly year: number;
+  readonly month: number;
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+}
+
+/**
+ * Nominal local date-time, e.g. `2024-03-10T02:30`. Lexicographic order of
+ * these strings is chronological order, which is what the
+ * `last_fired_nominal_local` refire gate relies on.
+ */
+export type NominalLocal = string;
+
+const WALL_FORMAT_OPTIONS: Intl.DateTimeFormatOptions = {
+  hourCycle: "h23",
+  year: "numeric",
+  month: "2-digit",
+  day: "2-digit",
+  hour: "2-digit",
+  minute: "2-digit",
+  second: "2-digit",
+};
+
+const wallFormatters = new Map<string, Intl.DateTimeFormat>();
+
+function wallFormatter(zone: string): Intl.DateTimeFormat {
+  const cached = wallFormatters.get(zone);
+  if (cached) return cached;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    ...WALL_FORMAT_OPTIONS,
+    timeZone: zone,
+  });
+  wallFormatters.set(zone, formatter);
+  return formatter;
+}
+
+const IDIOMS_REJECTED = new Set(["local", "system", "server", "server-local", "machine"]);
+
+/**
+ * Validate a timezone and return its canonical IANA id.
+ *
+ * Accepts real IANA ids (including `Etc/GMT+5` style fixed zones and `UTC`),
+ * canonicalizing whatever Intl resolves (e.g. `US/Eastern` -> `America/New_York`).
+ * Rejects unknown ids, offset spellings like `UTC+3`/`+05:30`, empty input and
+ * the strings `local`/`system` — the schedule zone is never allowed to fall
+ * back to the process zone.
+ */
+export function canonicalTimezone(timezone: string): string {
+  if (typeof timezone !== "string") {
+    throw new InvalidTimezoneError(`timezone must be a string, got ${typeof timezone}`);
+  }
+  const trimmed = timezone.trim();
+  if (trimmed === "") {
+    throw new InvalidTimezoneError("timezone must be an explicit IANA zone id, not an empty string");
+  }
+  if (IDIOMS_REJECTED.has(trimmed.toLowerCase())) {
+    throw new InvalidTimezoneError(
+      `timezone "${timezone}" is not an IANA zone id; a schedule must carry an explicit zone (never server-local)`,
+    );
+  }
+  if (/^[+-]?\d{1,2}(:?\d{2})?$/.test(trimmed) || /^UTC[+-]\d/.test(trimmed)) {
+    throw new InvalidTimezoneError(
+      `timezone "${timezone}" is a UTC offset, not an IANA zone id; store an IANA zone (UTC is allowed)`,
+    );
+  }
+  let resolved: string;
+  try {
+    resolved = new Intl.DateTimeFormat("en-US", { timeZone: trimmed }).resolvedOptions().timeZone;
+  } catch {
+    throw new InvalidTimezoneError(`unknown IANA time zone: "${timezone}"`);
+  }
+  if (!resolved) {
+    throw new InvalidTimezoneError(`unknown IANA time zone: "${timezone}"`);
+  }
+  return resolved;
+}
+
+/** True when `canonicalTimezone` would accept the value. */
+export function isValidTimezone(timezone: string): boolean {
+  try {
+    canonicalTimezone(timezone);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Validate and canonicalize, throwing `InvalidTimezoneError` on rejection. */
+export function assertValidTimezone(timezone: string): string {
+  return canonicalTimezone(timezone);
+}
+
+/** Local wall clock struck by an instant, in the given zone. */
+export function wallOfInstant(epochMs: number, zone: string): WallClock {
+  if (zone === "UTC") {
+    return decodeUtc(epochMs);
+  }
+  const parts = wallFormatter(zone).formatToParts(new Date(epochMs));
+  let year = 0;
+  let month = 0;
+  let day = 0;
+  let hour = 0;
+  let minute = 0;
+  let second = 0;
+  for (const part of parts) {
+    switch (part.type) {
+      case "year":
+        year = Number(part.value);
+        break;
+      case "month":
+        month = Number(part.value);
+        break;
+      case "day":
+        day = Number(part.value);
+        break;
+      case "hour":
+        hour = Number(part.value);
+        break;
+      case "minute":
+        minute = Number(part.value);
+        break;
+      case "second":
+        second = Number(part.value);
+        break;
+      default:
+        break;
+    }
+  }
+  return { year, month, day, hour, minute, second };
+}
+
+/** The UTC instant a wall-clock reading would denote if the offset were zero. */
+export function epochOfWall(wall: WallClock): number {
+  return Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second);
+}
+
+function decodeUtc(epochMs: number): WallClock {
+  const d = new Date(epochMs);
+  return {
+    year: d.getUTCFullYear(),
+    month: d.getUTCMonth() + 1,
+    day: d.getUTCDate(),
+    hour: d.getUTCHours(),
+    minute: d.getUTCMinutes(),
+    second: d.getUTCSeconds(),
+  };
+}
+
+/**
+ * Zone offset (ms east of UTC) in effect at an instant. Minute-precision
+ * arithmetic against `Intl`; UTC short-circuits without touching a formatter.
+ */
+export function offsetMs(epochMs: number, zone: string): number {
+  if (zone === "UTC") return 0;
+  return epochOfWall(wallOfInstant(epochMs, zone)) - epochMs;
+}
+
+const OFFSET_ISO_TAIL = /(?:Z|[+-]\d{2}:\d{2})$/;
+
+/**
+ * Coerce an instant input to epoch milliseconds.
+ *
+ * `Date` and finite numbers pass through. Strings must be ISO-8601; a string
+ * that carries a time component must also carry an explicit UTC offset (`Z` or
+ * `±hh:mm`) — otherwise `Date.parse` would silently apply the server's local
+ * zone, which this library exists to prevent.
+ */
+export function toInstantMs(value: Date | number | string): number {
+  if (value instanceof Date) {
+    const ms = value.getTime();
+    if (Number.isNaN(ms)) throw new InvalidInstantError("invalid Date (NaN)");
+    return ms;
+  }
+  if (typeof value === "number") {
+    if (!Number.isFinite(value)) throw new InvalidInstantError(`invalid instant number: ${value}`);
+    return value;
+  }
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    const hasTime = /[T ]\d/.test(trimmed);
+    if (hasTime && !OFFSET_ISO_TAIL.test(trimmed)) {
+      throw new InvalidInstantError(
+        `instant "${value}" has a time but no UTC offset; supply ...Z or ...±hh:mm (never server-local)`,
+      );
+    }
+    const ms = Date.parse(trimmed);
+    if (Number.isNaN(ms)) throw new InvalidInstantError(`unparseable instant: "${value}"`);
+    return ms;
+  }
+  throw new InvalidInstantError(`unsupported instant input: ${String(value)}`);
+}
+
+type ProcessVersionsLike = { tz?: string };
+
+/**
+ * tzdata version backing this process (`process.versions.tz`, e.g. `2026a`),
+ * or `"unknown"` outside Node. Recorded per schedule so tzdata-driven
+ * re-materialization can detect drift.
+ */
+export function currentTzdataVersion(): string {
+  const proc = (globalThis as { process?: { versions?: ProcessVersionsLike } }).process;
+  return proc?.versions?.tz ?? "unknown";
+}
diff --git a/packages/scheduling/src/verify.test.ts b/packages/scheduling/src/verify.test.ts
new file mode 100644
index 0000000..eb3dcda
--- /dev/null
+++ b/packages/scheduling/src/verify.test.ts
@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+import { nextOccurrences } from "./occurrences_extra.js";
+
+const ISO = (o: { fireAtUtc: number }) => new Date(o.fireAtUtc).toISOString().replace(".000Z", "Z");
+
+describe("count boundary semantics", () => {
+  it("never returns more than count", () => {
+    for (const count of [1, 2, 5, 17]) {
+      const out = nextOccurrences({ cron: "*/15 * * * *", timezone: "America/New_York" }, "2024-03-09T00:00:00Z", count);
+      expect(out.length).toBe(count);
+    }
+  });
+  it("stops at the collapse edge with the latest collapsed label", () => {
+    // Exclusive from 05:00Z (== 00:00 local): the first slot is 00:15. The
+    // eighth occurrence is the collapse edge — nominal slots 02:00..03:00 all
+    // materialize onto 07:00Z — and it carries the LATEST label (03:00), with
+    // nothing beyond the edge emitted.
+    const out = nextOccurrences({ cron: "*/15 * * * *", timezone: "America/New_York" }, "2024-03-10T05:00:00Z", 8);
+    expect(out.length).toBe(8);
+    expect(out.map(ISO)[7]).toBe("2024-03-10T07:00:00Z");
+    expect(out[7]!.nominalLocal).toBe("2024-03-10T03:00");
+    // The same result whether the boundary is reached with 8 or 80 requested,
+    // because generation stops at the first slot after the boundary instant.
+    const wide = nextOccurrences({ cron: "*/15 * * * *", timezone: "America/New_York" }, "2024-03-10T05:00:00Z", 80);
+    expect(wide[7]!.nominalLocal).toBe("2024-03-10T03:00");
+  });
+});
diff --git a/packages/scheduling/tsconfig.json b/packages/scheduling/tsconfig.json
new file mode 100644
index 0000000..5a24989
--- /dev/null
+++ b/packages/scheduling/tsconfig.json
@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}
diff --git a/packages/testing/package.json b/packages/testing/package.json
new file mode 100644
index 0000000..eaac368
--- /dev/null
+++ b/packages/testing/package.json
@@ -0,0 +1,22 @@
+{
+  "name": "@tactical-media-broadcast-hub/testing",
+  "private": true,
+  "version": "0.1.0",
+  "type": "module",
+  "bin": {
+    "live-source-simulator": "src/simulator.ts"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "simulate": "tsx src/simulator.ts"
+  },
+  "dependencies": {
+    "tsx": "^4.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.5.4"
+  }
+}
diff --git a/packages/testing/src/scenarios.ts b/packages/testing/src/scenarios.ts
new file mode 100644
index 0000000..0f256e5
--- /dev/null
+++ b/packages/testing/src/scenarios.ts
@@ -0,0 +1,32 @@
+export interface ScenarioStep {
+  /** Source that changes state in this step. */
+  source: "A" | "B" | "C";
+  action: "go-live" | "fail" | "recover" | "go-offline";
+  /** Seconds to hold after this step before the next one. */
+  holdSeconds: number;
+}
+
+export interface Scenario {
+  name: string;
+  description: string;
+  steps: ScenarioStep[];
+}
+
+export const SCENARIOS: Record<string, Scenario> = {
+  "dod-flap": {
+    name: "dod-flap",
+    description: "Deterministic Auto Director exercise: A live → B live → A fails → C live → A recovers",
+    steps: [
+      { source: "A", action: "go-live", holdSeconds: 20 },
+      { source: "B", action: "go-live", holdSeconds: 20 },
+      { source: "A", action: "fail", holdSeconds: 10 },
+      { source: "C", action: "go-live", holdSeconds: 20 },
+      { source: "A", action: "recover", holdSeconds: 20 },
+    ],
+  },
+  "single-live": {
+    name: "single-live",
+    description: "One source goes live and holds — baseline relay check",
+    steps: [{ source: "A", action: "go-live", holdSeconds: 60 }],
+  },
+};
diff --git a/packages/testing/src/simulator.ts b/packages/testing/src/simulator.ts
new file mode 100644
index 0000000..9369d81
--- /dev/null
+++ b/packages/testing/src/simulator.ts
@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * Live-source simulator: drives ffmpeg testsrc-based streams through a
+ * scripted live/offline/fail scenario so the Auto Director can be exercised
+ * deterministically without real PeerTube instances.
+ */
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+import { SCENARIOS, type Scenario } from "./scenarios.js";
+
+function ffmpegAvailable(): boolean {
+  const probe = spawnSync("ffmpeg", ["-version"], { encoding: "utf8" });
+  return probe.status === 0;
+}
+
+function runStep(step: Scenario["steps"][number], sinkUrl: string): void {
+  const label = `${step.source}-${step.action}`;
+  const duration = step.holdSeconds;
+  const args = [
+    "-re",
+    "-f", "lavfi",
+    "-i", `testsrc2=size=640x360:rate=30:duration=${duration}`,
+    "-f", "lavfi",
+    "-i", `sine=frequency=${step.source === "A" ? 440 : step.source === "B" ? 550 : 660}:duration=${duration}`,
+    "-c:v", "libx264", "-preset", "veryfast", "-tune", "zerolatency",
+    "-c:a", "aac", "-b:a", "128k",
+    "-f", "flv",
+    `${sinkUrl}/${label}`,
+  ];
+  process.stdout.write(`[${new Date().toISOString()}] ${label}: pushing ${duration}s to ${sinkUrl}\n`);
+  const result = spawnSync("ffmpeg", args, { stdio: "inherit" });
+  if (result.status !== 0) {
+    process.stderr.write(`[${label}] ffmpeg exited ${result.status}\n`);
+  }
+}
+
+function usage(): never {
+  process.stderr.write(
+    "usage: live-source-simulator --scenario <name> [--sink rtmp://localhost:1935/mock]\n" +
+      "scenarios: " + Object.keys(SCENARIOS).join(", ") + "\n",
+  );
+  process.exit(2);
+}
+
+const args = process.argv.slice(2);
+if (args.includes("--help") || args.includes("-h")) {
+  process.stdout.write(
+    "usage: live-source-simulator --scenario <name> [--sink rtmp://localhost:1935/mock]\n" +
+      "scenarios: " + Object.keys(SCENARIOS).join(", ") + "\n",
+  );
+  process.exit(0);
+}
+const scenarioIdx = args.indexOf("--scenario");
+const sinkIdx = args.indexOf("--sink");
+if (scenarioIdx === -1 || !args[scenarioIdx + 1]) usage();
+const scenario: Scenario | undefined = SCENARIOS[args[scenarioIdx + 1] ?? ""];
+if (!scenario) usage();
+const sink = (sinkIdx !== -1 && args[sinkIdx + 1]) || "rtmp://localhost:1935/mock";
+
+if (!ffmpegAvailable()) {
+  process.stderr.write("ffmpeg not found on PATH — install ffmpeg (the simulator is the deterministic test source)\n");
+  process.exit(1);
+}
+
+process.stdout.write(`scenario ${scenario.name}: ${scenario.description}\n`);
+for (const step of scenario.steps) {
+  runStep(step, sink);
+}
+process.stdout.write("scenario complete\n");
diff --git a/packages/testing/tsconfig.json b/packages/testing/tsconfig.json
new file mode 100644
index 0000000..7962fd2
--- /dev/null
+++ b/packages/testing/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  },
+  "include": ["src"]
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
new file mode 100644
index 0000000..e5ff257
--- /dev/null
+++ b/pnpm-lock.yaml
@@ -0,0 +1,8685 @@
+lockfileVersion: '9.0'
+
+settings:
+  autoInstallPeers: true
+  excludeLinksFromLockfile: false
+
+importers:
+
+  .:
+    devDependencies:
+      eslint:
+        specifier: ^9.9.0
+        version: 9.39.5(jiti@2.7.0)
+      turbo:
+        specifier: ^2.1.3
+        version: 2.11.7
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      typescript-eslint:
+        specifier: ^8.5.0
+        version: 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+
+  apps/api:
+    dependencies:
+      '@aws-sdk/client-s3':
+        specifier: ^3.1146.0
+        version: 3.1146.0
+      '@aws-sdk/s3-request-presigner':
+        specifier: ^3.1146.0
+        version: 3.1146.0
+      '@nestjs/common':
+        specifier: ^10.4.1
+        version: 10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/core':
+        specifier: ^10.4.1
+        version: 10.4.22(@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/platform-express@10.4.22)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/platform-express':
+        specifier: ^10.4.1
+        version: 10.4.22(@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@10.4.22)
+      '@opentelemetry/api':
+        specifier: ^1.9.1
+        version: 1.9.1
+      '@opentelemetry/auto-instrumentations-node':
+        specifier: ^0.80.0
+        version: 0.80.0(@opentelemetry/api@1.9.1)(@opentelemetry/core@2.11.0(@opentelemetry/api@1.9.1))
+      '@opentelemetry/exporter-trace-otlp-http':
+        specifier: ^0.222.0
+        version: 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-node':
+        specifier: ^0.222.0
+        version: 0.222.0(@opentelemetry/api@1.9.1)
+      '@tactical-media-broadcast-hub/connector-mastodon':
+        specifier: workspace:*
+        version: link:../../packages/connector-mastodon
+      '@tactical-media-broadcast-hub/connector-runtime':
+        specifier: workspace:*
+        version: link:../../packages/connector-runtime
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../../packages/connector-sdk
+      '@tactical-media-broadcast-hub/connector-telegram':
+        specifier: workspace:*
+        version: link:../../packages/connector-telegram
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../../packages/core
+      '@tactical-media-broadcast-hub/publishing-execution':
+        specifier: workspace:*
+        version: link:../../packages/publishing-execution
+      '@temporalio/client':
+        specifier: 1.24.0
+        version: 1.24.0
+      jose:
+        specifier: ^6.2.12
+        version: 6.2.12
+      pg:
+        specifier: ^8.23.1
+        version: 8.23.1
+      pino:
+        specifier: ^9.3.2
+        version: 9.14.0
+      reflect-metadata:
+        specifier: ^0.2.2
+        version: 0.2.2
+      rxjs:
+        specifier: ^7.8.1
+        version: 7.8.2
+    devDependencies:
+      '@tactical-media-broadcast-hub/connector-mock-livestream':
+        specifier: workspace:^
+        version: link:../../packages/connector-mock-livestream
+      '@types/express':
+        specifier: ^4.17.21
+        version: 4.17.25
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.20.5
+      '@types/pg':
+        specifier: ^8.23.1
+        version: 8.23.1
+      tsx:
+        specifier: ^4.17.0
+        version: 4.23.15
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  apps/media-worker:
+    dependencies:
+      pino:
+        specifier: ^9.3.2
+        version: 9.14.0
+    devDependencies:
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.20.5
+      tsx:
+        specifier: ^4.17.0
+        version: 4.23.15
+
+  apps/scheduler:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-mastodon':
+        specifier: workspace:*
+        version: link:../../packages/connector-mastodon
+      '@tactical-media-broadcast-hub/connector-runtime':
+        specifier: workspace:*
+        version: link:../../packages/connector-runtime
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../../packages/connector-sdk
+      '@tactical-media-broadcast-hub/connector-telegram':
+        specifier: workspace:*
+        version: link:../../packages/connector-telegram
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../../packages/core
+      '@tactical-media-broadcast-hub/publishing-execution':
+        specifier: workspace:*
+        version: link:../../packages/publishing-execution
+      '@temporalio/activity':
+        specifier: 1.24.0
+        version: 1.24.0
+      '@temporalio/client':
+        specifier: 1.24.0
+        version: 1.24.0
+      '@temporalio/common':
+        specifier: 1.24.0
+        version: 1.24.0
+      '@temporalio/worker':
+        specifier: 1.24.0
+        version: 1.24.0(lightningcss@1.32.0)
+      '@temporalio/workflow':
+        specifier: 1.24.0
+        version: 1.24.0
+      pg:
+        specifier: ^8.23.1
+        version: 8.23.1
+      pino:
+        specifier: ^9.3.2
+        version: 9.14.0
+    devDependencies:
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.20.5
+      '@types/pg':
+        specifier: ^8.23.1
+        version: 8.23.1
+      tsx:
+        specifier: ^4.17.0
+        version: 4.23.15
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  apps/web:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:^
+        version: link:../../packages/connector-sdk
+      '@tailwindcss/postcss':
+        specifier: ^4.3.3
+        version: 4.3.3
+      '@tanstack/react-virtual':
+        specifier: ^3.14.13
+        version: 3.14.13(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@tiptap/extension-character-count':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-placeholder':
+        specifier: ^3.31.4
+        version: 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/react':
+        specifier: ^3.31.4
+        version: 3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@tiptap/starter-kit':
+        specifier: ^3.31.4
+        version: 3.31.4
+      cmdk:
+        specifier: ^1.1.1
+        version: 1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      next:
+        specifier: ^14.2.5
+        version: 14.2.35(@opentelemetry/api@1.9.1)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      postcss:
+        specifier: ^8.5.29
+        version: 8.5.29
+      react:
+        specifier: ^18.3.1
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
+      tailwindcss:
+        specifier: ^4.3.3
+        version: 4.3.3
+    devDependencies:
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.20.5
+      '@types/react':
+        specifier: ^18.3.3
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ^18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+      playwright:
+        specifier: ^1.63.0
+        version: 1.63.0
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+
+  packages/connector-bluesky:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-discord:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-example:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-facebook:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-instagram:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-linkedin:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-mastodon:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-mock-livestream:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-mock-social:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-mock-video:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-peertube:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-reddit:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-runtime:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-mastodon':
+        specifier: workspace:*
+        version: link:../connector-mastodon
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/connector-telegram':
+        specifier: workspace:*
+        version: link:../connector-telegram
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+      pg:
+        specifier: ^8.23.1
+        version: 8.23.1
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      '@types/pg':
+        specifier: ^8.23.1
+        version: 8.23.1
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-sdk:
+    dependencies:
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-slack:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-telegram:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-threads:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/connector-twitch:
+    dependencies:
+      '@tactical-media-broadcast-hub/connector-sdk':
+        specifier: workspace:*
+        version: link:../connector-sdk
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/core:
+    devDependencies:
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/egress:
+    dependencies:
+      pg:
+        specifier: ^8.23.1
+        version: 8.23.1
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      '@types/pg':
+        specifier: ^8.23.1
+        version: 8.23.1
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/media-sandbox:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/publishing-execution:
+    dependencies:
+      '@tactical-media-broadcast-hub/core':
+        specifier: workspace:*
+        version: link:../core
+      pg:
+        specifier: ^8.23.1
+        version: 8.23.1
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      '@types/pg':
+        specifier: ^8.23.1
+        version: 8.23.1
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/safe-content:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      '@types/react':
+        specifier: ^18.3.3
+        version: 18.3.31
+      '@types/react-dom':
+        specifier: ^18.3.0
+        version: 18.3.7(@types/react@18.3.31)
+      eslint:
+        specifier: ^9.9.0
+        version: 9.39.5(jiti@2.7.0)
+      react:
+        specifier: ^18.3.1
+        version: 18.3.1
+      react-dom:
+        specifier: ^18.3.1
+        version: 18.3.1(react@18.3.1)
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/scheduling:
+    devDependencies:
+      '@types/node':
+        specifier: ^22.20.5
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+      vitest:
+        specifier: ^2.0.5
+        version: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  packages/testing:
+    dependencies:
+      tsx:
+        specifier: ^4.17.0
+        version: 4.23.15
+    devDependencies:
+      '@types/node':
+        specifier: ^22.5.0
+        version: 22.20.5
+      typescript:
+        specifier: ^5.5.4
+        version: 5.9.3
+
+packages:
+
+  '@alloc/quick-lru@5.3.0':
+    resolution: {integrity: sha512-U4+70Pc5ZS9osnCBCE5Jha/ciHM+Yp+CNMNC/7HvYbNRk1Ldd+f7qO65W5qfhu/TCv+/ozljlXXe9Nj8419DMA==}
+    engines: {node: '>=10'}
+
+  '@aws-sdk/checksums@3.1001.1':
+    resolution: {integrity: sha512-x12Q17KYlJAd3nKf8LV5LV0vt8sh8/6YfQLGPtrGnQf/tW4jqxPGq5GPpuVitpQYM3eUR4XB7CbxZf751NMbLw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/client-s3@3.1146.0':
+    resolution: {integrity: sha512-WY0YCBzxc4muFfY6UbGpA+oib0nGT/Px2aEPGYX7pp1la2OmDLChnK81mu8H7LdYvwGU1pLAsLIa/qgad0Wd7g==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/core@3.978.1':
+    resolution: {integrity: sha512-LbY9aGsEiznDWmUc30Nwv3aIX/+dbwTx8KfS0yOC3NPYMO+O91e6jkT1azf34FwjOndq8/Q+RcVVZz5xnerwdg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-env@3.972.72':
+    resolution: {integrity: sha512-xTKO/FWJPozTIXbozVnVGoNBhaGba8TBcx+KyUjRVeOlXE+dUc7GTR1cLvu0uTdIdmemzaFbqqCshXeZA1fZew==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-http@3.972.74':
+    resolution: {integrity: sha512-u91E/hT8f4d1xy0Jl7VG4nVKJ3lxbrZkoBTeSVoJdWBiSEUMwMS/9+e0H/aJVQV//Lt5wuzP+E69v4aRSsNTmw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-ini@3.973.17':
+    resolution: {integrity: sha512-ged4KXdBkvIC81bLvNHHuQKdKak/VXhQTR1NWYTTqW0474nlmsxy9O/vlgTIohDDWH3xpBdtVMZRyjb+DnocDA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-login@3.972.79':
+    resolution: {integrity: sha512-L+Z85anONJd8MaiuraO4wRxATCdEejBZ3K3eymzWI5JPXa9sOS9CkIm72PBKqXKX+Z9p9NGMX5AIMXm0LEflgw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-node@3.972.84':
+    resolution: {integrity: sha512-oHt854odINVwzwsh+c5x69j0ajm4DbqqqVJ+O1ECsCIZeMDAbzFpXItaqP7UZstJj/ATdTk/KFSH0LaNAgV+kA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-process@3.972.72':
+    resolution: {integrity: sha512-rLIp2xbMjX/k9/od7APpqq1ZgXXnV0pOL1Th3ZsL8Wu0TRtBsDTVS8iPqcfRFcHakFxPvR04OSTv2ka2qOb/2A==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-sso@3.973.16':
+    resolution: {integrity: sha512-IGihaJfFZYacJJr/odqILCoK7W/mvrZ7cuK7ECn3sAu4vLC6u0V8bS7mCGbdugJ8Aum2tnvqmx0F2MRFp2rn9g==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/credential-provider-web-identity@3.972.78':
+    resolution: {integrity: sha512-/y9WvNtlcPBGLR0qc1a+9J/xtYZfVczvLUOuXaVWylzttH7ewsxwHtjmiJSolNrVSDorIxHGHMU61CbonRkmwA==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/middleware-sdk-s3@3.972.77':
+    resolution: {integrity: sha512-E7W2UOeUoc+lg3uIfR/dM7ZwusHwhBQrKMnlkRv4EXRR+C0YtV1pg25xC7GdZIhXH+NAMgZPCbE7o5to2cjFiw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/nested-clients@3.997.46':
+    resolution: {integrity: sha512-oRxtBcka/JGHGs9l9p9IVajGoTP8vTPmoAzdHGy4Qcy9P5vPnDf6nhIeM/COQNY9k/OahImTRaLkHftoXvfcmQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/s3-request-presigner@3.1146.0':
+    resolution: {integrity: sha512-5BEfVr2OYX2bwB45NSWAXPoTN5M2NPLOHohgKV+XfMNcL5TF7UQN4hAOVF4S6DwrA4BrI3MsAry7vqdZ2aJEjg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/signature-v4-multi-region@3.996.47':
+    resolution: {integrity: sha512-Zk08macMvQTHzQJCLJVkOlviVoqwYMrpXv4lmLN7b7sAbiMoOK7Go0NYdR5UeF+MW8LIbRmwrNy9u/5VvX1U5g==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/token-providers@3.1138.0':
+    resolution: {integrity: sha512-GpyAr0DD63YOEmYFM6Df+gJuIgC92MMTiBK4FTKfxii5MJ9ge20epR7LyroulscYlG89J+ZB2ivFDPjvfQhzdw==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/types@3.974.6':
+    resolution: {integrity: sha512-v/clNZzZnDxGyvpHMOGpJKVXFAExJzUNAAjaWGdcx8QAcXLGwTaOkw33p5SHAi0YAioK32xB3hWwOekRVfmfKg==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws-sdk/xml-builder@3.972.41':
+    resolution: {integrity: sha512-ctjVSyCMegrWfXlx6VqzSBFI6UqmQ5ZlnfMhdLIiWmhoH8UAQxSCP5N3OpG7X3k4LnS7ou74C4mt20+bfTW2aQ==}
+    engines: {node: '>=20.0.0'}
+
+  '@aws/lambda-invoke-store@0.3.0':
+    resolution: {integrity: sha512-sl4Bm6yiMNYrZKkqqDFWN0UfnWhlS8ivKxrYl+6t0gCLrqr8y3B2IqZZbFRkfaVVp7C/baApyh71P+LeE1A2sQ==}
+    engines: {node: '>=18.0.0'}
+
+  '@borewit/text-codec@0.2.2':
+    resolution: {integrity: sha512-DDaRehssg1aNrH4+2hnj1B7vnUGEjU6OIlyRdkMd0aUdIUvKXrJfXsy8LVtXAy7DRvYVluWbMspsRhz2lcW0mQ==}
+
+  '@esbuild/aix-ppc64@0.21.5':
+    resolution: {integrity: sha512-1SDgH6ZSPTlggy1yI6+Dbkiz8xzpHJEVAlF/AM1tHPLsf5STom9rwtjE4hKAF20FfXXNTFqEYXyJNWh1GiZedQ==}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/aix-ppc64@0.28.2':
+    resolution: {integrity: sha512-XExcO+dvLKvVtNTibSTBej1NCAbaGhWn9Ww1ZPx80qsahhPFe/8jgWP0IchNe0F3HwkU7n8ejhH8bjonqht8mQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [aix]
+
+  '@esbuild/android-arm64@0.21.5':
+    resolution: {integrity: sha512-c0uX9VAUBQ7dTDCjq+wdyGLowMdtR/GoC2U5IYk/7D1H1JYC0qseD7+11iMP2mRLN9RcCMRcjC4YMclCzGwS/A==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm64@0.28.2':
+    resolution: {integrity: sha512-5YfKeeI8qWfBZIX+u2xZC3Zlb3Os/gLS2sbEKM+I4ZOcsWmHS2WLysCcQZDAFRslDUU5Oiq44gf6PYN1vGwG5A==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [android]
+
+  '@esbuild/android-arm@0.21.5':
+    resolution: {integrity: sha512-vCPvzSjpPHEi1siZdlvAlsPxXl7WbOVUBBAowWug4rJHb68Ox8KualB+1ocNvT5fjv6wpkX6o/iEpbDrf68zcg==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-arm@0.28.2':
+    resolution: {integrity: sha512-kXXoiPVVGQcnIYGOeaovwOURpniDBpSq4A03qkQ+BMQqtGG6HYap3xne9C1O1yo4TR3qxlCX5IqqmX6fFo2Lqg==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [android]
+
+  '@esbuild/android-x64@0.21.5':
+    resolution: {integrity: sha512-D7aPRUUNHRBwHxzxRvp856rjUHRFW1SdQATKXH2hqA0kAZb1hKmi02OpYRacl0TxIGz/ZmXWlbZgjwWYaCakTA==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/android-x64@0.28.2':
+    resolution: {integrity: sha512-O387ite7SzUyCcy3JQX4P4bLtEA7bLLkx+esve5JHnyYfNTxcVpXZo9jhdB0lTKN44gztELTdU7nS8Nr16Fs1Q==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [android]
+
+  '@esbuild/darwin-arm64@0.21.5':
+    resolution: {integrity: sha512-DwqXqZyuk5AiWWf3UfLiRDJ5EDd49zg6O9wclZ7kUMv2WRFr4HKjXp/5t8JZ11QbQfUS6/cRCKGwYhtNAY88kQ==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-arm64@0.28.2':
+    resolution: {integrity: sha512-n4KqkOQrraxHJcgjM1RvwbigfQKIKJVpM7xp+KsxiyUSrRdIXnt73VhrPAx0fV44hgfmIVKjxMN9J1t5jySVkw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.21.5':
+    resolution: {integrity: sha512-se/JjF8NlmKVG4kNIuyWMV/22ZaerB+qaSi5MdrXtd6R08kvs2qCN4C09miupktDitvh8jRFflwGFBQcxZRjbw==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/darwin-x64@0.28.2':
+    resolution: {integrity: sha512-uq6suIWYP37qzGddBKPw5QEQPi6HiLGsO7UmkpfyaYNQ3D+rN6w6WfwH+nuqcGXWvawGwxOEroO4YGnFh95azw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@esbuild/freebsd-arm64@0.21.5':
+    resolution: {integrity: sha512-5JcRxxRDUJLX8JXp/wcBCy3pENnCgBR9bN6JsY4OmhfUtIHe3ZW0mawA7+RDAcMLrMIZaf03NlQiX9DGyB8h4g==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-arm64@0.28.2':
+    resolution: {integrity: sha512-n+I0BTSRIoy+d6RPKnEVwql5UwBJolytvY4mAOIEJorKlqgPII8ix6slVVrfZ5Tnj7glIZvloylbB/EJPMWEXw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.21.5':
+    resolution: {integrity: sha512-J95kNBj1zkbMXtHVH29bBriQygMXqoVQOQYA+ISs0/2l3T9/kj42ow2mpqerRBxDJnmkUDCaQT/dfNXWX/ZZCQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/freebsd-x64@0.28.2':
+    resolution: {integrity: sha512-78XJTJkvPs0kz2w61301PJjXl4g7q3JqiYMZ/M/yVI73EHBrCRTgkhu9oqG7vPqq+a/yadEW8aD+agKlk5xrmg==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@esbuild/linux-arm64@0.21.5':
+    resolution: {integrity: sha512-ibKvmyYzKsBeX8d8I7MH/TMfWDXBF3db4qM6sy+7re0YXya+K1cem3on9XgdT2EQGMu4hQyZhan7TeQ8XkGp4Q==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm64@0.28.2':
+    resolution: {integrity: sha512-pW4AC0P3it8c7do9MVM4p51FzHzdM/TZrerurgRcHJ2WTa1VQ1CIq18xncfpBJw4ojkiZZrKW2yIBWBP92j6Ug==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.21.5':
+    resolution: {integrity: sha512-bPb5AHZtbeNGjCKVZ9UGqGwo8EUu4cLq68E95A53KlxAPRmUyYv2D6F0uUI65XisGOL1hBP5mTronbgo+0bFcA==}
+    engines: {node: '>=12'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-arm@0.28.2':
+    resolution: {integrity: sha512-XlDnu2q5yoqems+xay6wSAcg9DDD7K9RLKZEBOMZm3ckNpJBvOX20tSfby8KfrrhINDyv9V2YVZKY/SpoGJI8w==}
+    engines: {node: '>=18'}
+    cpu: [arm]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.21.5':
+    resolution: {integrity: sha512-YvjXDqLRqPDl2dvRODYmmhz4rPeVKYvppfGYKSNGdyZkA01046pLWyRKKI3ax8fbJoK5QbxblURkwK/MWY18Tg==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-ia32@0.28.2':
+    resolution: {integrity: sha512-CYbnj78HsIeA+DhgUKgFCfvNsTHFhMMrinUrMZpDXJXKN8T3XViTZ/+wtHeVxEWY8ewSzTFN+nRmSwO2tZaLUQ==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.21.5':
+    resolution: {integrity: sha512-uHf1BmMG8qEvzdrzAqg2SIG/02+4/DHB6a9Kbya0XDvwDEKCoC8ZRWI5JJvNdUjtciBGFQ5PuBlpEOXQj+JQSg==}
+    engines: {node: '>=12'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-loong64@0.28.2':
+    resolution: {integrity: sha512-buwkd8nsph4R+ajRvw0qM5Hja/TXQow3ptzWO2EbG/cqcIkHloRrdlBtQlshyYGTNFvfkfJ5tpPLVkY4DtsPfQ==}
+    engines: {node: '>=18'}
+    cpu: [loong64]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.21.5':
+    resolution: {integrity: sha512-IajOmO+KJK23bj52dFSNCMsz1QP1DqM6cwLUv3W1QwyxkyIWecfafnI555fvSGqEKwjMXVLokcV5ygHW5b3Jbg==}
+    engines: {node: '>=12'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-mips64el@0.28.2':
+    resolution: {integrity: sha512-ZVykbDyk7519VwiNb9Lcj9m8XM6v5V9uKPvrEMkkEedVewf+0itkhahp4HDpgERXhwLRpWFypsGbG/J8s0QjJA==}
+    engines: {node: '>=18'}
+    cpu: [mips64el]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.21.5':
+    resolution: {integrity: sha512-1hHV/Z4OEfMwpLO8rp7CvlhBDnjsC3CttJXIhBi+5Aj5r+MBvy4egg7wCbe//hSsT+RvDAG7s81tAvpL2XAE4w==}
+    engines: {node: '>=12'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-ppc64@0.28.2':
+    resolution: {integrity: sha512-CAXl+Dtd9UUuJd8pKKdwh6MLm3MUMiqMPmhZ3tTSXPqfyQ3vDl6R5hZdZ/kYojK4ofXtdfSv1tFq8XzWx3heNQ==}
+    engines: {node: '>=18'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.21.5':
+    resolution: {integrity: sha512-2HdXDMd9GMgTGrPWnJzP2ALSokE/0O5HhTUvWIbD3YdjME8JwvSCnNGBnTThKGEB91OZhzrJ4qIIxk/SBmyDDA==}
+    engines: {node: '>=12'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-riscv64@0.28.2':
+    resolution: {integrity: sha512-GeXCej4IQtU1B+QlDV8W/RRvbzI3O/Stss+/bCXv4lZls5WGRtu2a+3JkA3i4qIUlMXpcHebWpF8AkJhATowuA==}
+    engines: {node: '>=18'}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.21.5':
+    resolution: {integrity: sha512-zus5sxzqBJD3eXxwvjN1yQkRepANgxE9lgOW2qLnmr8ikMTphkjgXu1HR01K4FJg8h1kEEDAqDcZQtbrRnB41A==}
+    engines: {node: '>=12'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-s390x@0.28.2':
+    resolution: {integrity: sha512-3H1weTYZPxt/WOhByszQZybS9w5lKzUn1FDMsgEChbHWQwHYQQRfBxgCcZvPhjHfKyJjIievvMmEUawJrdY9Dg==}
+    engines: {node: '>=18'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.21.5':
+    resolution: {integrity: sha512-1rYdTpyv03iycF1+BhzrzQJCdOuAOtaqHTWJZCWvijKD2N5Xu0TtVC8/+1faWqcP9iBCWOmjmhoH94dH82BxPQ==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/linux-x64@0.28.2':
+    resolution: {integrity: sha512-4xTZr1FUmSoQW4XIWmit3tzQrUTZM+N3P0XV8xROKYF50XfI7xeO90+1bZvNwxIufQ9hDQVRJH5YhgPVF8A/HQ==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [linux]
+
+  '@esbuild/netbsd-arm64@0.28.2':
+    resolution: {integrity: sha512-sSATRjPeDBg3pdgHoQfoYBob11Kk1FGa9lui5RIHZCoCkJa9QKlvl3/vKz2usCmYYjs7ymJR/2Nnsqe+Hjt5nw==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.21.5':
+    resolution: {integrity: sha512-Woi2MXzXjMULccIwMnLciyZH4nCIMpWQAs049KEeMvOcNADVxo0UBIQPfSmxB3CWKedngg7sWZdLvLczpe0tLg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/netbsd-x64@0.28.2':
+    resolution: {integrity: sha512-lqnzCV+mM0gIADaKihiCg6ifgfU2L3h5E33rNQBN1Y4MaVGnzryzmvvf7UHxprpQdE8hpqLolJ9Rl+SkIRDpyw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [netbsd]
+
+  '@esbuild/openbsd-arm64@0.28.2':
+    resolution: {integrity: sha512-AL2qJILH7lNjrDmCQDvdxMfAUIv8KMNZOvrwAQ8i8//ntL9FflhOyMJ8OZSMBb8/AWXe3/5v5S20y3zCoZWKoQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.21.5':
+    resolution: {integrity: sha512-HLNNw99xsvx12lFBUwoT8EVCsSvRNDVxNpjZ7bPn947b8gJPzeHWyNVhFsaerc0n3TsbOINvRP2byTZ5LKezow==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openbsd-x64@0.28.2':
+    resolution: {integrity: sha512-QtiuPytchRyC4rwUKhexJdQKvDuZ6hWloi3igqPQNUJCS1/v9EiO3UTOXR6A3FoMo4fnAKbWJdqaIwhOzh8qEw==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@esbuild/openharmony-arm64@0.28.2':
+    resolution: {integrity: sha512-WkhYDmpTjLvGlScA1rwjRUmhl4k8oXR3cIbtqWmELgU/dFeHHlEllxDvdWcNJV9rbzCexB5vz8gtNewWLgCT7Q==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@esbuild/sunos-x64@0.21.5':
+    resolution: {integrity: sha512-6+gjmFpfy0BHU5Tpptkuh8+uw3mnrvgs+dSPQXQOv3ekbordwnzTVEb4qnIvQcYXq6gzkyTnoZ9dZG+D4garKg==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/sunos-x64@0.28.2':
+    resolution: {integrity: sha512-GPMSkTOtMnv2U2F8gxe4Io6qmVs+YKyp832Etqqxr0hFngmXQ3rzwytelm3GIn7T4VviRUlf3sOgBOiTdvaf7g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [sunos]
+
+  '@esbuild/win32-arm64@0.21.5':
+    resolution: {integrity: sha512-Z0gOTd75VvXqyq7nsl93zwahcTROgqvuAcYDUr+vOv8uHhNSKROyU961kgtCD1e95IqPKSQKH7tBTslnS3tA8A==}
+    engines: {node: '>=12'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-arm64@0.28.2':
+    resolution: {integrity: sha512-PIhhEkE9uPBleRBrQEJpUn7MBnibZzbGzYWPmY3x+YoVg/95zbjB4CxPPOQ8l5tYYM4mMaCthF8/1DIfBQQyWQ==}
+    engines: {node: '>=18'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.21.5':
+    resolution: {integrity: sha512-SWXFF1CL2RVNMaVs+BBClwtfZSvDgtL//G/smwAc5oVK/UPu2Gu9tIaRgFmYFFKrmg3SyAjSrElf0TiJ1v8fYA==}
+    engines: {node: '>=12'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-ia32@0.28.2':
+    resolution: {integrity: sha512-YmJbfTlvU7Sdn9BB+4PRES4oB6pxgS37MAONj+hBr/cpXS1aBPKXxNnDbu+QCWPj0o9dgyxeq79g6c5P8KeuYA==}
+    engines: {node: '>=18'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.21.5':
+    resolution: {integrity: sha512-tQd/1efJuzPC6rCFwEvLtci/xNFcTZknmXs98FYDfGE4wP9ClFV98nyKrzJKVPMhdDnjzLhdUyMX4PsQAPjwIw==}
+    engines: {node: '>=12'}
+    cpu: [x64]
+    os: [win32]
+
+  '@esbuild/win32-x64@0.28.2':
+    resolution: {integrity: sha512-5ebpxr3nWMzrL/rnUI755Jkuee0bHL/Gq0WTF9lvcpv73wAp5eu8MfBUgWK9bhWvZjj7yX8etf/8tI8Ney695g==}
+    engines: {node: '>=18'}
+    cpu: [x64]
+    os: [win32]
+
+  '@eslint-community/eslint-utils@4.10.1':
+    resolution: {integrity: sha512-cuadcxVFE8sDK6iWJbs8Sn0av2Nrh2QSGQhVlBW9AaAHqHwjWsZHT8LJ4hFGPh7ASBV2deFdM7H/DPjulmh8rg==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+    peerDependencies:
+      eslint: ^6.0.0 || ^7.0.0 || >=8.0.0
+
+  '@eslint-community/regexpp@4.12.2':
+    resolution: {integrity: sha512-EriSTlt5OC9/7SXkRSCAhfSxxoSUgBm33OH+IkwbdpgoqsSsUg7y3uh+IICI/Qg4BBWr3U2i39RpmycbxMq4ew==}
+    engines: {node: ^12.0.0 || ^14.0.0 || >=16.0.0}
+
+  '@eslint/config-array@0.21.2':
+    resolution: {integrity: sha512-nJl2KGTlrf9GjLimgIru+V/mzgSK0ABCDQRvxw5BjURL7WfH5uoWmizbH7QB6MmnMBd8cIC9uceWnezL1VZWWw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/config-helpers@0.4.2':
+    resolution: {integrity: sha512-gBrxN88gOIf3R7ja5K9slwNayVcZgK6SOUORm2uBzTeIEfeVaIhOpCtTox3P6R7o2jLFwLFTLnC7kU/RGcYEgw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/core@0.17.0':
+    resolution: {integrity: sha512-yL/sLrpmtDaFEiUj1osRP4TI2MDz1AddJL+jZ7KSqvBuliN4xqYY54IfdN8qD8Toa6g1iloph1fxQNkjOxrrpQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/eslintrc@3.3.7':
+    resolution: {integrity: sha512-F42g89Qd5oAWtp0k0nnSrjziAKza7w8SVT4mStc18LZMaRb4J1HQAHLCalEtDCxrTuksx7NU9qsmeLwpOfPqWw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/js@9.39.5':
+    resolution: {integrity: sha512-QywQuszQh77pIXCsq998c8hbhSTI/azTty1Z6N53dmAudKHhy573j3yvRLsX2BSp8YpLtoCEG8E9DJe+8zUh4A==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/object-schema@2.1.7':
+    resolution: {integrity: sha512-VtAOaymWVfZcmZbp6E2mympDIHvyjXs/12LqWYjVw6qjrfF+VK+fyG33kChz3nnK+SU5/NeHOqrTEHS8sXO3OA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@eslint/plugin-kit@0.4.1':
+    resolution: {integrity: sha512-43/qtrDUokr7LJqoF2c3+RInu/t4zfrpYdoSDfYyhg52rwLV6TnOvdG4fXm7IkSB3wErkcmJS9iEhjVtOSEjjA==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@floating-ui/core@1.8.0':
+    resolution: {integrity: sha512-0CIZ5itps/8x7BG8dEIhs53BvCUH2PCoogtakwRTut+Arm58sJooJ0AuZhLw2HJYIR5cMLNPBSS728sPho2khQ==}
+
+  '@floating-ui/dom@1.8.0':
+    resolution: {integrity: sha512-yXSrzeHZBTZadLOlfyhCkJHNeLJnHRnRInwdZ40L7ZiaAtrBwoYlsDrX3v5zB1Utk7CLfzcOVnVVWoXEky7Ceg==}
+
+  '@floating-ui/utils@0.2.12':
+    resolution: {integrity: sha512-HpCo8tmWzLVad5s2d19EhAz5zqrrQ6s69qd6moPMQvkOuSwDT1YgRfWSVuc4ennqrgv3OHppiOGMQ7oC13yIww==}
+
+  '@grpc/grpc-js@1.14.5':
+    resolution: {integrity: sha512-7VZM+SVdEcUUqSQeNI3zM8Qs/BhQKZndPo2h5VkYkAM8Iz0wJIa8mKV5ekQGqG8UUsnkQ0NMxIxwkIHYvj0qOw==}
+    engines: {node: '>=12.10.0'}
+
+  '@grpc/proto-loader@0.8.1':
+    resolution: {integrity: sha512-wtF6h+DY6M3YaDBPAmvuuA6jV8Sif9MjtOI5euKFWRgCDl5PeDpPsHR9u2l6St5ceY8AZgoNDww5+HvEsXFsGg==}
+    engines: {node: '>=6'}
+    hasBin: true
+
+  '@humanfs/core@0.19.2':
+    resolution: {integrity: sha512-UhXNm+CFMWcbChXywFwkmhqjs3PRCmcSa/hfBgLIb7oQ5HNb1wS0icWsGtSAUNgefHeI+eBrA8I1fxmbHsGdvA==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/node@0.16.8':
+    resolution: {integrity: sha512-gE1eQNZ3R++kTzFUpdGlpmy8kDZD/MLyHqDwqjkVQI0JMdI1D51sy1H958PNXYkM2rAac7e5/CnIKZrHtPh3BQ==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanfs/types@0.15.0':
+    resolution: {integrity: sha512-ZZ1w0aoQkwuUuC7Yf+7sdeaNfqQiiLcSRbfI08oAxqLtpXQr9AIVX7Ay7HLDuiLYAaFPu8oBYNq/QIi9URHJ3Q==}
+    engines: {node: '>=18.18.0'}
+
+  '@humanwhocodes/module-importer@1.0.1':
+    resolution: {integrity: sha512-bxveV4V8v5Yb4ncFTT3rPSgZBOpCkjfK0y4oVVVJwIuDVBRMDXrPyXRL988i5ap9m9bnyEEjWfm5WkBmtffLfA==}
+    engines: {node: '>=12.22'}
+
+  '@humanwhocodes/retry@0.4.3':
+    resolution: {integrity: sha512-bV0Tgo9K4hfPCek+aMAn81RppFKv2ySDQeMoSZuvTASywNTnVJCArCZE2FWqpvIatKu7VMRLWlR1EazvVhDyhQ==}
+    engines: {node: '>=18.18'}
+
+  '@isaacs/cliui@8.0.2':
+    resolution: {integrity: sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==}
+    engines: {node: '>=12'}
+
+  '@jridgewell/gen-mapping@0.3.13':
+    resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}
+
+  '@jridgewell/remapping@2.3.5':
+    resolution: {integrity: sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==}
+
+  '@jridgewell/resolve-uri@3.1.2':
+    resolution: {integrity: sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==}
+    engines: {node: '>=6.0.0'}
+
+  '@jridgewell/source-map@0.3.11':
+    resolution: {integrity: sha512-ZMp1V8ZFcPG5dIWnQLr3NSI1MiCU7UETdS/A0G8V/XWHvJv3ZsFqutJn1Y5RPmAPX6F3BiE397OqveU/9NCuIA==}
+
+  '@jridgewell/sourcemap-codec@1.6.0':
+    resolution: {integrity: sha512-T7jf+5zgsZHwNJ4lvQ7/aezbyk0nNX+zJVWpmHA7VYsEx7a7qr5Rg5IbtJFqkgze5Y2sruq1RUY8Q837Od7iFw==}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    resolution: {integrity: sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==}
+
+  '@js-sdsl/ordered-map@4.4.2':
+    resolution: {integrity: sha512-iUKgm52T8HOE/makSxjqoWhe95ZJA1/G1sYsGev2JDKUSS14KAgg1LHb+Ba+IPow0xflbnSkOsZcO08C7w1gYw==}
+
+  '@jsonjoy.com/base64@1.1.2':
+    resolution: {integrity: sha512-q6XAnWQDIMA3+FTiOYajoYqySkO+JSat0ytXGSuRdq9uXE7o92gzuQwQM14xaCRlBLGq3v5miDGC4vkVTn54xA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/base64@17.67.0':
+    resolution: {integrity: sha512-5SEsJGsm15aP8TQGkDfJvz9axgPwAEm98S5DxOuYe8e1EbfajcDmgeXXzccEjh+mLnjqEKrkBdjHWS5vFNwDdw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/buffers@1.2.1':
+    resolution: {integrity: sha512-12cdlDwX4RUM3QxmUbVJWqZ/mrK6dFQH4Zxq6+r1YXKXYBNgZXndx2qbCJwh3+WWkCSn67IjnlG3XYTvmvYtgA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/buffers@17.67.0':
+    resolution: {integrity: sha512-tfExRpYxBvi32vPs9ZHaTjSP4fHAfzSmcahOfNxtvGHcyJel+aibkPlGeBB+7AoC6hL7lXIE++8okecBxx7lcw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/codegen@1.0.0':
+    resolution: {integrity: sha512-E8Oy+08cmCf0EK/NMxpaJZmOxPqM+6iSe2S4nlSBrPZOORoDJILxtbSUEDKQyTamm/BVAhIGllOBNU79/dwf0g==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/codegen@17.67.0':
+    resolution: {integrity: sha512-idnkUplROpdBOV0HMcwhsCUS5TRUi9poagdGs70A6S4ux9+/aPuKbh8+UYRTLYQHtXvAdNfQWXDqZEx5k4Dj2Q==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-core@4.80.0':
+    resolution: {integrity: sha512-qMKWshnyjbyhm+NbzqGE3w5y1mckFFEMj0aDPU2/JBNh1BzIjVy9esq9lBmRnNVmhMEkxwDzLZ8Gqh5G1P5Dag==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-fsa@4.80.0':
+    resolution: {integrity: sha512-ZBEKl7J6dbkRCfmrFV48Re211A/FHqniTUhsWCsaRteNSOqMgkX3qF1UreVgwB9oSPm81JLAwhIi6Lb/NH/PoA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node-builtins@4.80.0':
+    resolution: {integrity: sha512-OIOIhqaWiwUySFMny4epIAoviXsyMaQQ63PTc3zH+5HEOvarl5hpUmZIhp2m5+OfyKAh5ylxXnQIgew1OgJDVw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node-to-fsa@4.80.0':
+    resolution: {integrity: sha512-ljeaR5xwtX1EyRmB0wvXANUMQZ3mjKcm7z8s2N8D8SLQ04CcAGtUhHFRZQXFb9mhgFyEVMydQGQtSOFS7pcrFQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node-utils@4.80.0':
+    resolution: {integrity: sha512-xwHeVVi3f+Khg/Fmb8i5qoYVmQ08QznE5TWhQokUmIZjz4KBPzU+zt/+bahBI6G1ghtqajt27lWuAciIxApuzA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-node@4.80.0':
+    resolution: {integrity: sha512-yiBlUfkMMRFFGy8CD/h2zd5rPnrM6bjlF+nx2LRAxNV6hOSiuObQIUEE7m7y2VTMisjxCRtzINH94bFGySWL7g==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-print@4.80.0':
+    resolution: {integrity: sha512-1ocZLJw/m/xlq0moaIHO7HV9nHRVBUvdc2zMzhsJGkFOrqfwWvexfCv5cYCPPLRhP+9p3yunoi4Ep5YhRORC9Q==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/fs-snapshot@4.80.0':
+    resolution: {integrity: sha512-3AV23Q1H228KTtJKTUE0nNq8FCtxSvtENOLrEat80wkAJCKHuqQEv8yjhpS8Bei2OEFJAnluGXp9Ri2SWBlROw==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pack@1.21.0':
+    resolution: {integrity: sha512-+AKG+R2cfZMShzrF2uQw34v3zbeDYUqnQ+jg7ORic3BGtfw9p/+N6RJbq/kkV8JmYZaINknaEQ2m0/f693ZPpg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pack@17.67.0':
+    resolution: {integrity: sha512-t0ejURcGaZsn1ClbJ/3kFqSOjlryd92eQY465IYrezsXmPcfHPE/av4twRSxf6WE+TkZgLY+71vCZbiIiFKA/w==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pointer@1.0.2':
+    resolution: {integrity: sha512-Fsn6wM2zlDzY1U+v4Nc8bo3bVqgfNTGcn6dMgs6FjrEnt4ZCe60o6ByKRjOGlI2gow0aE/Q41QOigdTqkyK5fg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/json-pointer@17.67.0':
+    resolution: {integrity: sha512-+iqOFInH+QZGmSuaybBUNdh7yvNrXvqR+h3wjXm0N/3JK1EyyFAeGJvqnmQL61d1ARLlk/wJdFKSL+LHJ1eaUA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/util@1.9.0':
+    resolution: {integrity: sha512-pLuQo+VPRnN8hfPqUTLTHk126wuYdXVxE6aDmjSeV4NCAgyxWbiOIeNJVtID3h1Vzpoi9m4jXezf73I6LgabgQ==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@jsonjoy.com/util@17.67.0':
+    resolution: {integrity: sha512-6+8xBaz1rLSohlGh68D1pdw3AwDi9xydm8QNlAFkvnavCJYSze+pxoW2VKP8p308jtlMRLs5NTHfPlZLd4w7ew==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  '@lukeed/csprng@1.1.0':
+    resolution: {integrity: sha512-Z7C/xXCiGWsg0KuKsHTKJxbWhpI3Vs5GwLfOean7MGyVFGqdRgBbAjOCh6u4bbjPc/8MJ2pZmK/0DLdCbivLDA==}
+    engines: {node: '>=8'}
+
+  '@napi-rs/lzma-linux-x64-gnu@1.5.1':
+    resolution: {integrity: sha512-oTXEIha4SsuXdTA4Iyskj0kpdx2yVXdhd75c2v3xGrHFfVMsbhTPZU/nMPL4sWKo4pBHm3aucLaqGlF696dTyQ==}
+    engines: {node: ^22.20 || ^24.12 || >=25}
+    cpu: [x64]
+    os: [linux]
+
+  '@nestjs/common@10.4.22':
+    resolution: {integrity: sha512-fxJ4v85nDHaqT1PmfNCQ37b/jcv2OojtXTaK1P2uAXhzLf9qq6WNUOFvxBrV4fhQek1EQoT1o9oj5xAZmv3NRw==}
+    peerDependencies:
+      class-transformer: '*'
+      class-validator: '*'
+      reflect-metadata: ^0.1.12 || ^0.2.0
+      rxjs: ^7.1.0
+    peerDependenciesMeta:
+      class-transformer:
+        optional: true
+      class-validator:
+        optional: true
+
+  '@nestjs/core@10.4.22':
+    resolution: {integrity: sha512-6IX9+VwjiKtCjx+mXVPncpkQ5ZjKfmssOZPFexmT+6T9H9wZ3svpYACAo7+9e7Nr9DZSoRZw3pffkJP7Z0UjaA==}
+    peerDependencies:
+      '@nestjs/common': ^10.0.0
+      '@nestjs/microservices': ^10.0.0
+      '@nestjs/platform-express': ^10.0.0
+      '@nestjs/websockets': ^10.0.0
+      reflect-metadata: ^0.1.12 || ^0.2.0
+      rxjs: ^7.1.0
+    peerDependenciesMeta:
+      '@nestjs/microservices':
+        optional: true
+      '@nestjs/platform-express':
+        optional: true
+      '@nestjs/websockets':
+        optional: true
+
+  '@nestjs/platform-express@10.4.22':
+    resolution: {integrity: sha512-ySSq7Py/DFozzZdNDH67m/vHoeVdphDniWBnl6q5QVoXldDdrZIHLXLRMPayTDh5A95nt7jjJzmD4qpTbNQ6tA==}
+    peerDependencies:
+      '@nestjs/common': ^10.0.0
+      '@nestjs/core': ^10.0.0
+
+  '@next/env@14.2.35':
+    resolution: {integrity: sha512-DuhvCtj4t9Gwrx80dmz2F4t/zKQ4ktN8WrMwOuVzkJfBilwAwGr6v16M5eI8yCuZ63H9TTuEU09Iu2HqkzFPVQ==}
+
+  '@next/swc-darwin-arm64@14.2.33':
+    resolution: {integrity: sha512-HqYnb6pxlsshoSTubdXKu15g3iivcbsMXg4bYpjL2iS/V6aQot+iyF4BUc2qA/J/n55YtvE4PHMKWBKGCF/+wA==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@next/swc-darwin-x64@14.2.33':
+    resolution: {integrity: sha512-8HGBeAE5rX3jzKvF593XTTFg3gxeU4f+UWnswa6JPhzaR6+zblO5+fjltJWIZc4aUalqTclvN2QtTC37LxvZAA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@next/swc-linux-arm64-gnu@14.2.33':
+    resolution: {integrity: sha512-JXMBka6lNNmqbkvcTtaX8Gu5by9547bukHQvPoLe9VRBx1gHwzf5tdt4AaezW85HAB3pikcvyqBToRTDA4DeLw==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@next/swc-linux-arm64-musl@14.2.33':
+    resolution: {integrity: sha512-Bm+QulsAItD/x6Ih8wGIMfRJy4G73tu1HJsrccPW6AfqdZd0Sfm5Imhgkgq2+kly065rYMnCOxTBvmvFY1BKfg==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@next/swc-linux-x64-gnu@14.2.33':
+    resolution: {integrity: sha512-FnFn+ZBgsVMbGDsTqo8zsnRzydvsGV8vfiWwUo1LD8FTmPTdV+otGSWKc4LJec0oSexFnCYVO4hX8P8qQKaSlg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@next/swc-linux-x64-musl@14.2.33':
+    resolution: {integrity: sha512-345tsIWMzoXaQndUTDv1qypDRiebFxGYx9pYkhwY4hBRaOLt8UGfiWKr9FSSHs25dFIf8ZqIFaPdy5MljdoawA==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@next/swc-win32-arm64-msvc@14.2.33':
+    resolution: {integrity: sha512-nscpt0G6UCTkrT2ppnJnFsYbPDQwmum4GNXYTeoTIdsmMydSKFz9Iny2jpaRupTb+Wl298+Rh82WKzt9LCcqSQ==}
+    engines: {node: '>= 10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@next/swc-win32-ia32-msvc@14.2.33':
+    resolution: {integrity: sha512-pc9LpGNKhJ0dXQhZ5QMmYxtARwwmWLpeocFmVG5Z0DzWq5Uf0izcI8tLc+qOpqxO1PWqZ5A7J1blrUIKrIFc7Q==}
+    engines: {node: '>= 10'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@next/swc-win32-x64-msvc@14.2.33':
+    resolution: {integrity: sha512-nOjfZMy8B94MdisuzZo9/57xuFVLHJaDj5e/xrduJp9CV2/HrfxTRH2fbyLe+K9QT41WBLUd4iXX3R7jBp0EUg==}
+    engines: {node: '>= 10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@nuxtjs/opencollective@0.3.2':
+    resolution: {integrity: sha512-um0xL3fO7Mf4fDxcqx9KryrB7zgRM5JSlvGN5AGkP6JLM5XEKyjeAiPbNxdXVXQ16isuAhYpvP88NgL2BGd6aA==}
+    engines: {node: '>=8.0.0', npm: '>=5.0.0'}
+    hasBin: true
+
+  '@opentelemetry/api-logs@0.222.0':
+    resolution: {integrity: sha512-9mb1If+IF6u0ZVXkHQ6ogEae5HwA6ajIVUgpSDQyRASxft6BSXHvBvPooRle3yFN/fKnCdSOnuu0OC3PLcF6+g==}
+    engines: {node: '>=8.0.0'}
+
+  '@opentelemetry/api@1.9.1':
+    resolution: {integrity: sha512-gLyJlPHPZYdAk1JENA9LeHejZe1Ti77/pTeFm/nMXmQH/HFZlcS/O2XJB+L8fkbrNSqhdtlvjBVjxwUYanNH5Q==}
+    engines: {node: '>=8.0.0'}
+
+  '@opentelemetry/auto-instrumentations-node@0.80.0':
+    resolution: {integrity: sha512-McPSxdNZqudZnC8WsYti63QyDoj+QOB4EKVp3Ndrq+gq5UOoi2GcDvXjphIxgXUFoJ3jzWoiczhReKW23OKsOw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.4.1
+      '@opentelemetry/core': ^2.0.0
+
+  '@opentelemetry/configuration@0.222.0':
+    resolution: {integrity: sha512-zNWGmEvyX7CUbS6F6PKi7hf3CF/SffzeBYyWVQAfadZ8hODrvLmqV3IUGVt1SiqyYanRPHc8VuhoO0Qh9OEuug==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.9.0
+
+  '@opentelemetry/context-async-hooks@2.11.0':
+    resolution: {integrity: sha512-Tr79DyWI8itsBdg+jH+opjfrwLzX+erk1/ExkIwhWoAVjVrJIn2y5+cGjTC0Vy8fyNIA/y8wuJPZwr1T3xCZeQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/core@2.11.0':
+    resolution: {integrity: sha512-7YP44XH0tV6+Mb54x2YGf84i7yi+31MBZlE8JwvozkxyTvXbSp10X7cI7YE49ChJ3shMJoBmCJF3+1QFBJctGA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/exporter-logs-otlp-grpc@0.222.0':
+    resolution: {integrity: sha512-HH4Oi/E8HXBKtcjgcVPJGsrg+lSstdw1m93brRdpVj5CjMpyTkv/O0ZYMXP6QXVEaLjjFivtzUu4Y8+i1UJpjw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-logs-otlp-http@0.222.0':
+    resolution: {integrity: sha512-GqwLZohJTf/sttYlOpT1oFTJ9ScYaKnk0sOx4Qe/+KmXYVOa+v94cfnkUkFKDuvTODWhCL50Hz3gvsZD6ngQpg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-logs-otlp-proto@0.222.0':
+    resolution: {integrity: sha512-LlCDJuaznfFPzjHoKXjN/r9T5pgCZpmVheZ/EmwMUhMvpxI7RXDmsdLXoYpl5suYQNkwyXAUZhVEXKe3lev8Hg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-metrics-otlp-grpc@0.222.0':
+    resolution: {integrity: sha512-nPU2gpQWJfQttf+A71aLkKEOQoO6n6QGs5QTtPagi/rb3Lc1I55bqRXoLQEZsWqWimc8eas2Vo168NkTaByxQw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-metrics-otlp-http@0.222.0':
+    resolution: {integrity: sha512-6Ko+0bgNP6V4G/RsmNBSk5lO1B/lo9z6tvLpFY3ykPPevXNzFmOW3C9hEmTt0zKCvHovyrol3TYlg4HVb5gwjg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-metrics-otlp-proto@0.222.0':
+    resolution: {integrity: sha512-s1ZPwS8Ig7cpRmL3kCobPaFbemM81dJ03LNPrsuN32h3mCDvNF2NQ1pRHruOju0P0o1TZ24LkZA685rtQal1KA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-prometheus@0.222.0':
+    resolution: {integrity: sha512-I7nalnnBZrhlTgjlqsVeEjJGcQCFK5kKAYVk7XTz/cbubvj5fvjLOal/Many0taHF2GIkOWmegsbQ8vbQJjhFg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-trace-otlp-grpc@0.222.0':
+    resolution: {integrity: sha512-uisilePEdOMa3hIfXW82XXU6FofF8gw3iv+PoboIMWEUBC7XbJB3XnIHSdrSDsqCw3njR/If08qD0yzOY1U9Sg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-trace-otlp-http@0.222.0':
+    resolution: {integrity: sha512-RCnPWcHppwiquQ+cV3nWvNwdf0MG1w26e5jewW2T83nTZOlXgcg88sY9ulCVgagGHcq1mj0L0GP6YHgzk2v8oA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-trace-otlp-proto@0.222.0':
+    resolution: {integrity: sha512-imLrLzNhnABJt3tUyT63h6MqfZrG3Gdv3TE7+OUQTvwD088RfCUx3rF01lcgfu2KXBFk13vwi0yKZLvFEalkIA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/exporter-zipkin@2.11.0':
+    resolution: {integrity: sha512-mFibA45yXLEETIj+VcTVycFFe4R91iD41d+r3CU0f3DDWJCrICiHxUIjmYBTCZIuywXEeNo++2lncQeWnH7lWQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/instrumentation-amqplib@0.69.0':
+    resolution: {integrity: sha512-hoSfNGxqospEFw0S2RH7cY8MF5U1BRKsAfX7PhiiZgGDWxPcmfAKYdXilmn0DqPBGRFYzq+HbtSp+R+2sy4mXA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-aws-lambda@0.74.0':
+    resolution: {integrity: sha512-N7L+NIyndEUWC0EjtN7OmNBF0J5beXQ81+46qt1NCA2YDC95os9TIh2iWfKL+U3wINkJeStMWBEQgFZhEvj1qw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-aws-sdk@0.77.0':
+    resolution: {integrity: sha512-igri8DF7ZWlYtQjT1u2A3v6Grb59VSsYiheGrLpnI7rlEAxmFeWHPwiwzzko39lM0LO7Ntf3VJPRBA1ZNGwF1w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-bunyan@0.67.0':
+    resolution: {integrity: sha512-a/ucku1yx4qW2zpYpepTM/rZlv92DG/C+k/Kxn/nqhh5HOoe3pHFbXUXunvy2EtHW/7l81PI++AUm+rIxXqlTg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-cassandra-driver@0.67.0':
+    resolution: {integrity: sha512-PIHbjmBWfYeYqAH8XDCyoJoXaR6TkEakNw3BX8uDt8b9zjYk3uetjCoP8nubRDb8m30vkDbs09Qg09pFOXKj2w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-connect@0.65.0':
+    resolution: {integrity: sha512-i7xkOkzzeaYbaK2Gjpxa6g9FJd1nqoH0+KFyRXV0iweH/F2+xZPintRFD5gcSN5/H4mpfslsLbDqRT897CvzEQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-cucumber@0.38.0':
+    resolution: {integrity: sha512-sorgrR3FOBy+YEwVutxcm84JTI0luCNIGp0kiL+jSoUrH9W/pYVSpP4isLB3VtQMgNnD4cd0e9qNvvr7RwKLpA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/instrumentation-dataloader@0.39.0':
+    resolution: {integrity: sha512-01+jNP1hESK8GYTCuRMoiQAEf9ZI5b3XwfSk7bWDiXLB2/zml5Md/U/xaWyFHQ2kYyU553Qvr8dcyup5Beu7qA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-dns@0.65.0':
+    resolution: {integrity: sha512-7QXICs4eV/GeihRqPnsR7TnK6ugAK8/B7tWr8UFxRzGTfNG97LEfByevhNfMEE8pFFLHUhiCE5metED2lO8nhw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-express@0.70.0':
+    resolution: {integrity: sha512-OHdj/2apRZNhMKkd6w4OV4SnX/aS2LWMLyHwGGNYhWratgh88o+cVJS9FvqC+HCYWSDWTEWEfl/8d7BdEI7c+g==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-fs@0.41.0':
+    resolution: {integrity: sha512-rk1RcxvOeb5j7Gi6P/PB6M9MRRYQzp4t9ZYN/i6jVM+m0j2zCUYGH4Xo6omNh0FhTDhhytDPG6o95p82eXFL2w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-generic-pool@0.65.0':
+    resolution: {integrity: sha512-iKkn/8m0oerf00qCxz9/xeua+EieX6tlSmLhGiVLgLsOspmV1sb33ee8RPiWnJiandGVJgKA0GTGUZXwVKgPnQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-graphql@0.70.0':
+    resolution: {integrity: sha512-zyBTEG0Dxm6rYf0IaoIqt1ZRAuiq4AUPDhAi0vl/hBbYweU56CleS5zH8n+GQ3+EsTBW6KYKULHvXk21+UJo9w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-grpc@0.222.0':
+    resolution: {integrity: sha512-5gUFhJF5X8ss60apt2p7czvIeIzTHZQSq1QowiKVS4gBfP5nHZNhBYoOtq1j14A8IXs/qL8Hn/sfni4kaPVLRA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-hapi@0.68.0':
+    resolution: {integrity: sha512-wJShEI4aKajQT5Sg/sJ6jV3xF6SqJKfXHTLDdrmWMv0h1sDXp4mpSTD1XUJfO5H0lZFUtEJapxtWl126zAmf9w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-host-metrics@0.5.0':
+    resolution: {integrity: sha512-rAw5lmY2u3bwUFohRtR4ZYNDnhMTiSeQqq8BB4Bo+aJQ+7vIOOwW/3d4awLPMDQ69VeA5jsh+ICL5oJinrWIwA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-http@0.222.0':
+    resolution: {integrity: sha512-HhMHW32LyGzIJEmUElxaML4oUe6JiCq0Hvjt/Awxb60SlMsSFetFLFjed45g/0wrPr1n7z+xW+x1B/584WBAkg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-ioredis@0.70.0':
+    resolution: {integrity: sha512-AUyn8K5vlSGkIF2AXPlUsa5d5ZXRidHMXlAHNAykvgW3u8juDZqGTgsOKJMYnLfllawygawLrqK6Fr2lnPcBUQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-kafkajs@0.31.0':
+    resolution: {integrity: sha512-9/EBOb1aW5ai4+U7mu2ER5fhJ7OYZNK/ghRSETfCf92xCeoQkZcS8LEF8e05w6OlrgZCwq7x+vLuUxXtkRPv3w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-knex@0.66.0':
+    resolution: {integrity: sha512-tPI1T0ur+P2qvsOWcadv9ViWtJ8g0XsKOAMPiR5rasZBZAC6nEI4u4BAnAhaZtdZkuMJrGa4uZur5xTn1bv7MQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-koa@0.70.0':
+    resolution: {integrity: sha512-+CFyL7V0auN0FzKvGUwOIOGT/8VTC3BM8cd8X0UoHRmPKEdYfwNWuHIkA6zknZPDMXN9WLfZCxdZ0Ln/YqLx4w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.9.0
+
+  '@opentelemetry/instrumentation-lru-memoizer@0.66.0':
+    resolution: {integrity: sha512-kYJQFqkR2eEwGzqTRw2Nc/NiQyrQRU3rLHmsEvdnlf40YRfCBadbDu3I8C5GWoVn1XyEKFTvmn85UoslRpbUjA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-memcached@0.65.0':
+    resolution: {integrity: sha512-QLGrx33THENogCdkBi1DJxPwvWe4QInoKUbx7u15zb37bxrKww68ZrqbMF4luq9YZbGQUFqEsnSprHV8kU93QA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-mongodb@0.75.0':
+    resolution: {integrity: sha512-Bf9Az6zdOsnRFUew1CToTKpfhcFkAJ4SgmnGpxID/vuzVHI31oZhAwuKBTHny/Eq7ydXfncDbET8jV6d3L8REw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-mongoose@0.68.0':
+    resolution: {integrity: sha512-GrDPpy9XHwWJUpKb4NjH8bdRU9EvtS37D102LhMOnjNOp6ouvtVBmFcPLMsJKsZcFOG4YykSERnau4l5a+sy2w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-mysql2@0.68.0':
+    resolution: {integrity: sha512-xNvUL0nwk/t0gGPb1GSQJWKiR3gj4Cd3vk4palrttLy/FYbnRBOOBRCobik3grAMzjsynEgyYdzEziXx/CvpyQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-mysql@0.68.0':
+    resolution: {integrity: sha512-N6TCMiWmisdG9DzSuMHxZ+N5qD3meoCy70mVE6fneZj6M24EXj86e56BzLFQ8Pkd6BgaPBJcdMTT/GBfPuW15w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-nestjs-core@0.68.0':
+    resolution: {integrity: sha512-BCsqKPLWVDgrTDyVScRwENWg8uNH7LA0QBy+ojuPQx9C9F85yOhNkale5MdmQG0su7L6BLLTNPByZOZeKp3c5A==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-net@0.66.0':
+    resolution: {integrity: sha512-OxnzC0696+Ne7zHisHo95RZkYT4e2C4OoB+q0dqQyZ0/9klLQ9CyC/Yu+OzYrQzPjdzRQVVPNDhoW+5+cXk3XQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-openai@0.20.0':
+    resolution: {integrity: sha512-vl8ReH9dq9goRWbajF0xQt/mnCZDl2KCcmOvgC1sSKCRA8DnqSMq7Z9ZVKPA9PnaV4tGInb39qtGdGIORUkEqQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-oracledb@0.47.0':
+    resolution: {integrity: sha512-3DDgcsl2CFX4829TxZiNYD29pFN9xyT71HUBN475CuFQ94eq+1jyMZPshO+K7qJltrJY2Df3MWV2ANrlw8H8fQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-pg@0.74.0':
+    resolution: {integrity: sha512-8i59Z7M0FjEwp2hF1eRqEr+NZtiwjvPYGl2xsGWEfL/hF6ffmPERWbySyK1EXa7gGyHCArwNkHLShsMfFywqpQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-pino@0.68.0':
+    resolution: {integrity: sha512-U0ggAM9eqDe7jsUnZeFMv6QIZwahNfyPZQAlUV9ZQ3aAYpaq+Ag9Okec75Fgzwh72+e4gewfT99HObkDg6Y/bA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-redis@0.70.0':
+    resolution: {integrity: sha512-jXHduXt6GQWluGtqBPibAvpw27seRjA6SMyLp0Oc41AzSQz1JFZq1CNw6gvdOrRasH4AJPpRykPxw02IjHYr0A==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-restify@0.67.0':
+    resolution: {integrity: sha512-T4sjjxX0CaeYNEMUNEDbCL9nGPIRkEmAzj7b1HwI0YJgZV459aStVsgJRTKmuaeIoJSihTqH2yUmcB+gdR5Qxg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-router@0.66.0':
+    resolution: {integrity: sha512-18GWiTNuIMDFxepxYV0PVikAAMmcqLZsMziJXi2PyuP3r9msPjMJnU7RZ+DLS1N8amwWit3EZYmFI4dNE4d9uQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-runtime-node@0.35.0':
+    resolution: {integrity: sha512-/cOW4Qlv4nnr4QXDCkv0TEtOBa9R9lXHu//JuD5+nRPYR74g9iLmf5tadcYvn32oz2R8vQnV8FTnMLzjfAGMCQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-socket.io@0.69.0':
+    resolution: {integrity: sha512-VlS6GFeWd32d09WziTZR9cfLPNJ1nV747suBCgUivRVzIwrg1UG+DBCmMX/kvrMmGJcFRAbf6I6s6nLsR6+Jag==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-tedious@0.41.0':
+    resolution: {integrity: sha512-dtrHwEs40nzD/fR9jkSNbSiHqCIHf2sXcMM8nY29Ekc25pw0EADRBqN4Ya2prrCSNGVtIx6N9o3fTS7fsACysA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation-undici@0.32.0':
+    resolution: {integrity: sha512-Ms8oPkrCHa6hJOYodcFC8QOt1AFlns3KD1CqXBEihXyTFeLXDO84tIXYyKlXNHr8jMrl1Gm2velDvsSDXAuh9w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.7.0
+
+  '@opentelemetry/instrumentation-winston@0.66.0':
+    resolution: {integrity: sha512-wwBZnlq9/2qiBpIoLB5yC88Ws0zoOLFde6DuIbEYL+SmC+bgYBITYV59AIlaDGpvos/n7AM+k8EFw+y/ZQVudw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/instrumentation@0.222.0':
+    resolution: {integrity: sha512-fhbRDuAgzPKpq1k5+hX3uS+3QAYNca0on0Ngot/R8dDsQtuFaADeZnG2uSgxABuvcI7S2phAaRhbct9jieeKZw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/otlp-exporter-base@0.222.0':
+    resolution: {integrity: sha512-YbywG3veEm2Fb6TbdxRkuquWob6eVWXuA8/Ba1tXz9jHfUqpdE3keilOHEtPboC4CvS1bjeeVfNkWGOOrLj+lw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/otlp-grpc-exporter-base@0.222.0':
+    resolution: {integrity: sha512-Kw5WqDBYYpCgY+edHWZS/Jp3bdguqNkCyEWOsqFhf8RmtcEuWYzPFA9i+L6UsNoJXTs8ngeQB6dwELH1czNYjA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/otlp-transformer@0.222.0':
+    resolution: {integrity: sha512-/F3BZ89+CJQnZkMh2tCrtcdB+XT2Dxhj4FFE+WPQ//413hmFL0/RfEX6vgOIWGhiSzrkHWTK3+6SiT7K5/g/jQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.3.0
+
+  '@opentelemetry/propagator-aws-xray@2.2.0':
+    resolution: {integrity: sha512-Yjvt2EjL+tfpkVOdKbhTPgpM4SIAez9nG6Q/QjQ3yfcJcjIWp59ph70SLfvmkSL6++3DCnuBG3iWcB18PwWavQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/propagator-b3@2.11.0':
+    resolution: {integrity: sha512-ldyRZXx6qsqu9Spqd7rVxo6SNAUJqP8Ir3vwIi4N8xyZLXNl/2XeQmIHvFneiVOqNwWkU+JGFg2O9/T1fefU0w==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/propagator-jaeger@2.11.0':
+    resolution: {integrity: sha512-RUOqgoIqXOPQTOhpBrs07Y8sBlxVoLY5Fka6ueZ0prW+k6fWQsba/nHDY4gm+gmfuwtRqbX5Y9YKhDvktjbIqQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/redis-common@0.38.3':
+    resolution: {integrity: sha512-VCghU1JYs/4gP6Gqf/xro9MEsZ7LrMv2uONVsaESKL38ZOB9BqnI98FfS23wjMnHlpuE+TTaWSoAVNpTwYXzjw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+
+  '@opentelemetry/resource-detector-alibaba-cloud@0.37.0':
+    resolution: {integrity: sha512-tEbi6ZPrPZG79oZdQlzw5xR7sirtYy+LBbt/S/JxDUZnmSWEYmo7l2jp985XU4UhsfMDpcfdOY+Gnt2bPMtvyQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/resource-detector-aws@2.22.0':
+    resolution: {integrity: sha512-3kM+xfsSHs0hShUAx9IFhX5jniaXxJL3CTjbCMNCFS+EY7bswWbukV3au0jfqEgzeNxGxHEy8RLA1TOhAVLpTQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/resource-detector-azure@0.30.0':
+    resolution: {integrity: sha512-fwGDPVGJ6PyRMc5CPdHBfASX5prg3mLhZA0rs+n8ZJK4DjpJw9CvB1FujWl8l0QAsTmvrYBm9Deal3fvfqZBkQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/resource-detector-container@0.8.13':
+    resolution: {integrity: sha512-44AKD/FOpC4amfsZkKvtymUnThWLBPTrZavv5tpRPVE3REEtFCbQV0rMT5lTRXmDkg8rk8M/2RX49NZdTSnpjw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/resource-detector-gcp@0.57.0':
+    resolution: {integrity: sha512-wp+hk7jD7mxA6swAqa5wQ3jws2egh1DCPZ9FfEgntmFw/mc8MaGZjwuttOoMeRjIlcBCCaNUHuN8B+MZaujAXQ==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.0.0
+
+  '@opentelemetry/resources@2.11.0':
+    resolution: {integrity: sha512-Ie7+8q8MDF4FAEQCKVMTx3ReUvxiIAgIiiW3c9JdmP8+HMcDy20puT+AHjexnExgnbvBxjQ9fjkFDWrikJ2jQA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.3.0 <1.10.0'
+
+  '@opentelemetry/sdk-logs@0.222.0':
+    resolution: {integrity: sha512-+19YHODIjaUCArxleaJtuufFZVpz/xvvK+VllQqE+W8hHolxdoRwHfK/s667zezwh1hkx6FFF+oYzetYgqK+Bg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.4.0 <1.10.0'
+
+  '@opentelemetry/sdk-metrics@2.11.0':
+    resolution: {integrity: sha512-7GXXcObyHyDUUSG+L+kJoquty01bzm7ivE7+SSgXXJcHuPzGviptxwARmI2c+bnnxjexGQbJnyNlN8HxBP/Y7A==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.9.0 <1.10.0'
+
+  '@opentelemetry/sdk-node@0.222.0':
+    resolution: {integrity: sha512-t8tlFN/ezYV7iI4k6u3t2jFbIReX99Z0iVMVSYLJscE4McxIW9YGHhdOldeY1elHeoq8mjEO4B9s4Fk7+zJbsg==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.3.0 <1.10.0'
+
+  '@opentelemetry/sdk-trace-base@2.11.0':
+    resolution: {integrity: sha512-H19x/TX/LZdqiYOjM7fqtSxwlplC5pgelavqbQdHbhdq0q/AI/TGkM2dfGuuynTXmJPeF2HoZVoPDu+TGoW78A==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.3.0 <1.10.0'
+
+  '@opentelemetry/sdk-trace-node@2.11.0':
+    resolution: {integrity: sha512-CuvCMJmZxswhNLlM2LfuLOW3h3fZujA4hsG4B+Sz4dX2zvaXO8Ng74cnDHWD64gLszTlhiG3c0iNUjj4g+0/sA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.0.0 <1.10.0'
+
+  '@opentelemetry/sdk-trace@2.11.0':
+    resolution: {integrity: sha512-fFnTqGm8/G73GQVnxYi7LXa1ZVYEUvgL6XI1LpvV0bPC7WQ/ZGgKxCSl8FnlZBKto9JHHEFTO6s6CUpvvtwFrA==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': '>=1.3.0 <1.10.0'
+
+  '@opentelemetry/semantic-conventions@1.43.0':
+    resolution: {integrity: sha512-eSYWTm620tTk45EKSedaUL8MFYI8hW164hIXsgIHyxu3VobUB3fFCu5t0hQby6OoWRPsG1KkKUG2M5UadiLiVg==}
+    engines: {node: '>=14'}
+
+  '@opentelemetry/sql-common@0.42.0':
+    resolution: {integrity: sha512-nwUwUU+8O8a4bnLqk6CodWeegGMEANgC94KTAhXcpGWLrW/2/hek/0ajNbjXnSOoNuCX+nteUPs46HFHhou9Xw==}
+    engines: {node: ^18.19.0 || >=20.6.0}
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+
+  '@pinojs/redact@0.4.0':
+    resolution: {integrity: sha512-k2ENnmBugE/rzQfEcdWHcCY+/FM3VLzH9cYEsbdsoqrvzAKRhUZeRNhAZvB8OitQJ1TBed3yqWtdjzS6wJKBwg==}
+
+  '@pkgjs/parseargs@0.11.0':
+    resolution: {integrity: sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==}
+    engines: {node: '>=14'}
+
+  '@protobufjs/aspromise@1.1.2':
+    resolution: {integrity: sha512-j+gKExEuLmKwvz3OgROXtrJ2UG2x8Ch2YZUxahh+s1F2HZ+wAceUNLkvy6zKCPVRkU++ZWQrdxsUeQXmcg4uoQ==}
+
+  '@protobufjs/base64@1.1.2':
+    resolution: {integrity: sha512-AZkcAA5vnN/v4PDqKyMR5lx7hZttPDgClv83E//FMNhR2TMcLUhfRUBHCmSl0oi9zMgDDqRUJkSxO3wm85+XLg==}
+
+  '@protobufjs/codegen@2.0.5':
+    resolution: {integrity: sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==}
+
+  '@protobufjs/eventemitter@1.1.1':
+    resolution: {integrity: sha512-vW1GmwMZNnL+gMRaovlh9yZX74kc+TTU3FObkkurpMaRtBfLP3ldjS9KQWlwZgraRE0+dheEEoAxdzcJQ8eXZg==}
+
+  '@protobufjs/fetch@1.1.1':
+    resolution: {integrity: sha512-GpptLrs57adMSuHi3VNj0mAF8dwh36LMaYF6XyJ6JMWlVsc+t42tm1HSEDmOs3A8fC9yyeisgLhsTVQokOZ0zw==}
+
+  '@protobufjs/float@1.0.2':
+    resolution: {integrity: sha512-Ddb+kVXlXst9d+R9PfTIxh1EdNkgoRe5tOX6t01f1lYWOvJnSPDBlG241QLzcyPdoNTsblLUdujGSE4RzrTZGQ==}
+
+  '@protobufjs/path@1.1.2':
+    resolution: {integrity: sha512-6JOcJ5Tm08dOHAbdR3GrvP+yUUfkjG5ePsHYczMFLq3ZmMkAD98cDgcT2iA1lJ9NVwFd4tH/iSSoe44YWkltEA==}
+
+  '@protobufjs/pool@1.1.0':
+    resolution: {integrity: sha512-0kELaGSIDBKvcgS4zkjz1PeddatrjYcmMWOlAuAPwAeccUrPHdUqo/J6LiymHHEiJT5NrF1UVwxY14f+fy4WQw==}
+
+  '@protobufjs/utf8@1.1.2':
+    resolution: {integrity: sha512-b1UQwcEZ4yCnMCD8DAL1VlbvBJE9/IX4FTIp7BG1xYpf29SLazLSrqUkj4w7Y5y7cCVP6E5tcqqcI0xemPkHug==}
+
+  '@radix-ui/primitive@1.1.7':
+    resolution: {integrity: sha512-rqWnm76nYT8HoNNqEjpgJ7Pw/DrBj5iBTrmEPo6HTX5+VJyBNOqTdv4g89G63HuR5g0AaENoAcH7Is5fF2kZ8Q==}
+
+  '@radix-ui/react-compose-refs@1.1.5':
+    resolution: {integrity: sha512-+48PbAAbq3didjJxa+OaWY2ZwgAKsNiRGyeHKszblZMQ+kcpd9pAaT11cMkGEie0vsOi3QdeTE6d5Fe3Gn61kA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-context@1.2.2':
+    resolution: {integrity: sha512-RHCUGwKHDr0hDGg4X7ma4JG4/+12qxw8rkh5QKdDldlCvtja6nUx1Ef/8HVrJze81lEsgLQlqjzjGNHantgnQA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-dialog@1.2.0':
+    resolution: {integrity: sha512-l5CX8HdNL+9cc4s7HkNyplumSA3FIx68sg9dttBHKr286fRBwq1MBniDVTeI/tkof92/APntMQvC1YG1Khb0Cg==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-dismissable-layer@1.1.20':
+    resolution: {integrity: sha512-35WHRrycfnj2m4LvPiKMKHGLM3Y2WvUA744CkRdxjs1BGDX1c8PVMfmiSGTUwnHRbqdtIoxveYTXvcJSt7VfgQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-focus-guards@1.1.6':
+    resolution: {integrity: sha512-RNOJjfZMTyBM6xYmV3IVGXkPjIhcBAuv48POevAXwrGJhkWZ9p1rFoIS1JFooPuT193AZmRsCPhpoVJxx6OPoQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-focus-scope@1.2.0':
+    resolution: {integrity: sha512-I5S7vsAOozx2lWSBAyuXjWIJ/A8qx4fjbv6115WoaRYQSb1yZDaeNHonUAQzXyE8oD+0whJHbQRl4HIE2gQ0Xw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-id@1.1.4':
+    resolution: {integrity: sha512-TMQp2llA+RYn7JcjnrMnz7wN4pcVttPZnRZo52PLQsoLVKzNlVwUeHmfePgTgRluXFvlD3GD5g5MOVVTJCO0qA==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-portal@1.1.18':
+    resolution: {integrity: sha512-ygFIJ+QXNKf72AAq8x3hd22+ws7pYpmc1S0E4kW0Je+qD4qEb3FvxeKVQRGrVDMOkQaYfsB+Qs+KDh81a1gAOw==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-presence@1.1.11':
+    resolution: {integrity: sha512-Z7/atlkab36Z8hm+V8zYc79r0W+tiOB1o0tun1By94JyadkekLQmtEAnBSP9XKXBNQsStoStS4+gX10JpS5akA==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-primitive@2.1.11':
+    resolution: {integrity: sha512-RzcaSw5aKl0OPhBJ1wbolKSF6nVvN+0o/QLeIVq+09npiPdnCkPggy2k6gI6yetxl4ZyrlBPYFgCB8BQJZwXcQ==}
+    peerDependencies:
+      '@types/react': '*'
+      '@types/react-dom': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+      react-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+      '@types/react-dom':
+        optional: true
+
+  '@radix-ui/react-slot@1.4.0':
+    resolution: {integrity: sha512-IuMVHZ+Ah5fkctu3X3qeFrV/ZrBcuWuDTFUUPfS/L5hvoTjzhp/HdWGE14CsQombPdEidsa33HVlYZXi49PZ1Q==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-callback-ref@1.1.4':
+    resolution: {integrity: sha512-R6OUY2e2fA6Yn6s+VSx5KBV6Nx8LQEhu+cz7LCej18rQ1HLyg9PSC9jP/ZNx0o6FAIK9c0F1kHylzSxKsdlkrQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-controllable-state@1.2.6':
+    resolution: {integrity: sha512-uEQJGT97ZA/TgP/Hydw47lHu+/vQj6z/0jA+WeTbK1o9Rx45GImjpD0tc3W5ad3D6XTSR6e1yEO0FvGq6WQfVQ==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-effect-event@0.0.5':
+    resolution: {integrity: sha512-7cshFL8HGS/7HEiHH+9kL9HBwp2sa9yX18Knwek6KYWmXwM7pegMgta2AXMQKI+rq3JnfSj9x8wYqFMTdG1Jgg==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@radix-ui/react-use-layout-effect@1.1.4':
+    resolution: {integrity: sha512-K20DkRkUwDnxEYMBPcg3Y6voLkEy5p5QQmszZgLngKKiC7dzBR/aEuK3w1qlx2JWDUNH6FluahYdgR3BP+QbYw==}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8 || ^17.0 || ^18.0 || ^19.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  '@rollup/rollup-android-arm-eabi@4.64.0':
+    resolution: {integrity: sha512-FLLpX941CD/7aBvX3GqLGBM9OvY5PGXTryPJkG5r5/OuBpZpV5k45Uo3RxAvqd35tsyc3hH1bhtz921IKzoIzg==}
+    cpu: [arm]
+    os: [android]
+
+  '@rollup/rollup-android-arm64@4.64.0':
+    resolution: {integrity: sha512-iI32XM/jnDYJsvx5ai/za/7gWO9XoSeFFtU06/ZCaRgyilfJOjaopD3nOpk2WrTCGOyeDt4hleUiGOAnd5tHNg==}
+    cpu: [arm64]
+    os: [android]
+
+  '@rollup/rollup-darwin-arm64@4.64.0':
+    resolution: {integrity: sha512-dRBZlbt2sEtF8Mn4MODThze9fIPdDoOhVSlXMAKy5dQbOYK9pOOoPY4Fat3OTtr0+8zbJo5TTZwlsfxY/kDNJg==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@rollup/rollup-darwin-x64@4.64.0':
+    resolution: {integrity: sha512-Y3whrJOMucfkhgNkvcM93M6j8C53iEAMmPMYD99C6G1kUy4ELigLWk9ar2/4aCBSRgsql0zdlOemLgW2m5GZgQ==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@rollup/rollup-freebsd-arm64@4.64.0':
+    resolution: {integrity: sha512-S6S1GEzPjFF6IONYJX3AKt/799+8RgBgCcwRnUo+Ep1IvBxUbw5M51iU0TDdK2NWWVnSvCQ8yi6Em0fGASMOng==}
+    cpu: [arm64]
+    os: [freebsd]
+
+  '@rollup/rollup-freebsd-x64@4.64.0':
+    resolution: {integrity: sha512-Ed1DPoFENkXj4IGzSB12SesV40iP6LxCCrbTIkSGIQBpOOxpBM+0kj62lmaeIHfMWTDoddqTOtqc7s8LYfn+Pw==}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.64.0':
+    resolution: {integrity: sha512-J/6xhutJPtFyIkmHdf4olOdHHKH5kOJNumojdWn+Elv5ICEYTVOa362Vw27TxsK0BLzb1le3EDlO3UbvFK1lnQ==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm-musleabihf@4.64.0':
+    resolution: {integrity: sha512-G4L/Nnx59d2LvDoV/P4S5lZ7oVLT6hodOHMacqjiq2LL2gts86KbkEBTYL53+fBt0odhf7XPIbIATGoYiJctxg==}
+    cpu: [arm]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-gnu@4.64.0':
+    resolution: {integrity: sha512-zF16pvJDEUksGYRbfnXne7pdklAyj2XDmJeYKgP93oq0cUyX9Y8O7lUo1R+IY1GagP/YBvCEDCe7eEcAKpw//g==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-arm64-musl@4.64.0':
+    resolution: {integrity: sha512-nIggWn8n+w12+R5lsV+PYYoUY8vuObxPAQqJI7WES+9v0qspYuAHoZMfYM0yLxlipasT5BY9ht5W8t5c/rSCkg==}
+    cpu: [arm64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-gnu@4.64.0':
+    resolution: {integrity: sha512-WLOTiHPzszP0dxIMsHpFeDSOSB5I49Mj8K4+yKE3H1X/D0JRG5XZ5jrctJLMjnUc/LUzaKiwq6EHWNJ8pup8PA==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-loong64-musl@4.64.0':
+    resolution: {integrity: sha512-35RK9aRhh7g7Pmeu5gQ01aCvrhXzj9LoBE6xtUcEH1ns+nyTaSzxSpADmBQINu4QiTDGvmQYwo1j5hlg1rRXFw==}
+    cpu: [loong64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-gnu@4.64.0':
+    resolution: {integrity: sha512-RqTfnpoTjuWfPAmqK5p2edt2AMCDJWm6oTn7sKfmyx+6tRga0ip05SJ977o6udTcIiDeF/CJMUfkaN4gtWt6Aw==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-ppc64-musl@4.64.0':
+    resolution: {integrity: sha512-RQjZPigjxFvFZDijG6rjlSXxhRaTf9zLYVpGK+lVcga64oMqP1GbgVqCb46eHTTceSIgp89Ja0y5aPe3GFBYHg==}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-gnu@4.64.0':
+    resolution: {integrity: sha512-tjL58mgQcTRnDRpeky+Sth1MKQeYi2Ct6r3Luq9E5aTSjnM/i/JbozqZkKqp9thM5+oDSZxo+05f9kdQedfTGA==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-riscv64-musl@4.64.0':
+    resolution: {integrity: sha512-ictoRyVaoZ8C67myHef+8hhCa6IplXJJ/xUCkVCxziV4zxMZh+jvhkhGsPBLqj1S72fnqD0QH5zL4lcaa4X7DQ==}
+    cpu: [riscv64]
+    os: [linux]
+
+  '@rollup/rollup-linux-s390x-gnu@4.64.0':
+    resolution: {integrity: sha512-8aVvZ2hfr9RLFzBQkQNmYeHLDja8fLeQAmLt757zdKN/B+8L809KlLJKctQjS22wZotptV8G6o7fVPuAs8S1tQ==}
+    cpu: [s390x]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-gnu@4.64.0':
+    resolution: {integrity: sha512-2dEF8GAcDKwshUfydD+GhosppNyBzhVUHkdFF3CXd3FpOkzj/RZzF5aoEtzklujklT5qFVRU2GK/cFeLaTNKVg==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-linux-x64-musl@4.64.0':
+    resolution: {integrity: sha512-3XHTvoo2hKkh0MiOfS7SkhHjMaaWF7P4F3drocZZaho/Z8w7h/jpnuBHm91BOQLfvrKHs1yR+zir4E8RI3XzTQ==}
+    cpu: [x64]
+    os: [linux]
+
+  '@rollup/rollup-openbsd-x64@4.64.0':
+    resolution: {integrity: sha512-HKtkzodL4a3KFWDXDoO61cRynAWTR3LnAE0oGtfG9lcNFpNuVYUFOByxDgNqEvic9rvaQbAj+SFwTEWDptRaIw==}
+    cpu: [x64]
+    os: [openbsd]
+
+  '@rollup/rollup-openharmony-arm64@4.64.0':
+    resolution: {integrity: sha512-JBsxqiY16uyyCujtoC3s7zL+SrYyNElptD7K4V+KUoJ2V8/XG3hPWpheK+SuPwNh1cikJvIZmIdsrYXvD6PLJw==}
+    cpu: [arm64]
+    os: [openharmony]
+
+  '@rollup/rollup-win32-arm64-msvc@4.64.0':
+    resolution: {integrity: sha512-S5Qrijh37qhnUYQ0ay8WN3LuWeKjow7wTUyCOPMZtnXiBXYXdsZETI6ZLfYnQAKovltckPLBFdNeD61P2rJc7g==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@rollup/rollup-win32-ia32-msvc@4.64.0':
+    resolution: {integrity: sha512-zbZ6iMmLFEsCtTdc2/y1F/cDFVNNCPF7Ae8PCT/wdPE//hGwYp6r+MyCLMFX+kOeIe09Pz6ASfnnfpSTN1FJQQ==}
+    cpu: [ia32]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-gnu@4.64.0':
+    resolution: {integrity: sha512-L6Hw69oNpuYaOr1zCG30v0/DqKYCSRwodPGwIcVZ/6f8SOzq9rxtL/xNVI5MO4wjli+Ko0ErK9uHJL3mNPt8wQ==}
+    cpu: [x64]
+    os: [win32]
+
+  '@rollup/rollup-win32-x64-msvc@4.64.0':
+    resolution: {integrity: sha512-nl+CTWIgOGszQmUz/kanfgrfFZ4qiwxKIfT/ryl3N3Ewk5tqizmYtNXiqb7Bu/fDtNgu1kyxdFiAUJNur3iysg==}
+    cpu: [x64]
+    os: [win32]
+
+  '@smithy/core@3.35.1':
+    resolution: {integrity: sha512-i4YPS4B6ts7bjn7UwLnGjiZdprOvHvgGobFZsYK3GIY3E5hIqtj0rReU69BcTpGp+fvtraSNXeG1l+jtJvF55w==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/credential-provider-imds@4.5.2':
+    resolution: {integrity: sha512-A9uSdn72ozbRUSit0eib0TW7nXuNPlaeM0zcGkJ+nE6tFcSDbnmtwoxbTCFBukVQcszDAyvsd7+rTduPTXpygg==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/fetch-http-handler@5.8.0':
+    resolution: {integrity: sha512-ycSJu3tFAQ4v04CBB0agqFMVsSQ1iG3yw+SpgxRqKfaURpQD4CZ8Wn0zPMmSnOuTpTh65Vz+EA0rMrw089wvkA==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/node-http-handler@4.12.1':
+    resolution: {integrity: sha512-ThMkboGeONWXAelq9FvGsuJC4rOi+qyC4/zhUF58xYpxUg5sQKx2VXZYJmtNjr4dSuBJ1HeJXETQILCz3wOHvw==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/signature-v4@5.7.4':
+    resolution: {integrity: sha512-tHy0K0VtqNd5Y7Y41h0a0Lhh0L1GzC08dTWg0F7vRJWFtTENg7IZikf3wQkanYIRdb7ngoIPMTmqgUi401fEeQ==}
+    engines: {node: '>=18.0.0'}
+
+  '@smithy/types@4.19.0':
+    resolution: {integrity: sha512-r7jh49VJxGerfAcTQA6gXcKc+98zOp/tqRwzYjgOE+iSQsP6cEU1hq2QzbuipmP68QtYdY9wKEhiCQZIzHgZ4Q==}
+    engines: {node: '>=18.0.0'}
+
+  '@swc/core-darwin-arm64@1.16.13':
+    resolution: {integrity: sha512-JrMH2h7ohd4mOIneNRx/diqTmCDSdWfp9uOdQ8VJ2V2CA7jOJ1jWb+qp8RoZLqgiVmwDDC7eySKB1kbvZ+jVXQ==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@swc/core-darwin-x64@1.16.13':
+    resolution: {integrity: sha512-HauZMRxpOImRxgY6GXjw5gbD8ts2NcPZuLMM8htY8Mic7j1Izt/lxkXrKYUwqyU56YLwQZ4dHRT+6jFHkztcag==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@swc/core-linux-arm-gnueabihf@1.16.13':
+    resolution: {integrity: sha512-tUSojGIythnHJKrElDM9OvuhBnK+FF39eM9iIBgj9kdfbAm6PhAM7dKbaSDcnX2gOLG2slkasjD0Z8m/YUlzOA==}
+    engines: {node: '>=10'}
+    cpu: [arm]
+    os: [linux]
+
+  '@swc/core-linux-arm64-gnu@1.16.13':
+    resolution: {integrity: sha512-qS3bk/ezRrLXGn1b764S/EG3/oKj6uRhnTNRAALpnuu8d9I0YwSiUkQghnX7lOH9X/yRr+qrFI3R0wAruO47Tg==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@swc/core-linux-arm64-musl@1.16.13':
+    resolution: {integrity: sha512-aeoYoG6fQsOS3mFOuTKvnJo1aaaxYNI0aRRlhdHaGP4q1YQx4XOc5Hkd35IFduWCBG3eZl3fPTjRuYvxpl7eTA==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@swc/core-linux-ppc64-gnu@1.16.13':
+    resolution: {integrity: sha512-eEFoueZXWZ2S1lsqL8Ve2C8RjhzH9+Ktj8U4IGTUQL6CNG04+VhQiYQWJOf5xfVBU6I+PbH80yvsYegqZOOSZQ==}
+    engines: {node: '>=10'}
+    cpu: [ppc64]
+    os: [linux]
+
+  '@swc/core-linux-s390x-gnu@1.16.13':
+    resolution: {integrity: sha512-K0q1ReVXL3d5bzBgZxS+yJq5q2xRjg4k2XXGj9yiCEpE5ZqJGQ4Gtk1sRrk8W2lo3KY0DCJD3Myt6x2SMvGArQ==}
+    engines: {node: '>=10'}
+    cpu: [s390x]
+    os: [linux]
+
+  '@swc/core-linux-x64-gnu@1.16.13':
+    resolution: {integrity: sha512-Qvpihw30irhIjy2f91BR1pamcJBCgf8hmr9XWenztAX1YLkneRkkTB/PFGWQubhaBqQhY2uZKViMj/xV61uMBQ==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@swc/core-linux-x64-musl@1.16.13':
+    resolution: {integrity: sha512-iCGxHbh3Cq5vqRvCPlw3XkkDz4RlkPSyQwfFKbOKTMj5tiEuojY/rLmf4BMfI9Z8yPJTf9VB07t3NbKInoC97g==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [linux]
+
+  '@swc/core-win32-arm64-msvc@1.16.13':
+    resolution: {integrity: sha512-iOabn6cd+hg3cnoKlAC8j3Yufv8nQHBVU5OIDX8dCPA95PjAZ0B0TlDn9sWivk8ezo/cLJux7p9n0B9vRej+1Q==}
+    engines: {node: '>=10'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@swc/core-win32-ia32-msvc@1.16.13':
+    resolution: {integrity: sha512-+1b/3xBNuVbpnJIZUCAaSdscOPYRWq85eohKx44y/3qbPp56UMiCJWBiWtyr7K5F1nf1JENXm2IBSEJaLgWq6Q==}
+    engines: {node: '>=10'}
+    cpu: [ia32]
+    os: [win32]
+
+  '@swc/core-win32-x64-msvc@1.16.13':
+    resolution: {integrity: sha512-6kEJhYshk7OVoVIWryiHqjCNuwZeOlPTS6et+bKV/WhtHs8fLA01wyTLrQGi+4ultgRe/o0M4b25K/KKdvl0dQ==}
+    engines: {node: '>=10'}
+    cpu: [x64]
+    os: [win32]
+
+  '@swc/core@1.16.13':
+    resolution: {integrity: sha512-k4uUsIMS0IwOKVsrQs48IZK75O4roV3FnuJEdL7ES+DFESftdgvz73QBqN3VUAbUmUr78We4tzG0kgYj36M22Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@swc/helpers': '>=0.5.17'
+    peerDependenciesMeta:
+      '@swc/helpers':
+        optional: true
+
+  '@swc/counter@0.1.3':
+    resolution: {integrity: sha512-e2BR4lsJkkRlKZ/qCHPw9ZaSxc0MVUd7gtbtaB7aMvHeJVYe8sOB8DBZkP2DtISHGSku9sCK6T6cnY0CtXrOCQ==}
+
+  '@swc/helpers@0.5.5':
+    resolution: {integrity: sha512-KGYxvIOXcceOAbEk4bi/dVLEK9z8sZ0uBB3Il5b1rhfClSpcX0yfRO0KmTkqR2cnQDymwLB+25ZyMzICg/cm/A==}
+
+  '@swc/types@0.1.28':
+    resolution: {integrity: sha512-V6Mnml8v09QALx6K0elJ7o9K/MkVDtW3t6L+7Ou/JcWtb3xwId2AH4FeOceySd2JaO87IMw4+6vSZxLm34LPbw==}
+
+  '@tailwindcss/node@4.3.3':
+    resolution: {integrity: sha512-/T8IKEsf9VTU6tLjgC7+sv2mOPtQxzE2jMw7u4Tt40Tx+QSZxpzh95/H6cMKoja9XuW7iMdLJYBB0o9G1CaAgg==}
+
+  '@tailwindcss/oxide-android-arm64@4.3.3':
+    resolution: {integrity: sha512-Y85A2gmPSkl5Ve5qR86GL4HT509cFqQh1aes9p3sSkyTPwt0Pppf3GkwGe4JPACcRYjgJIEhQgM6dBClnr0NYw==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [android]
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.3':
+    resolution: {integrity: sha512-BiaWatpBcERQFDlOjRDpIVXuFK5PJez5SA4JMg6VYZdBYU+qKfV/vqjcIs+IYmtitf1xYQZTwXvU/8y4lfZUGw==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-darwin-x64@4.3.3':
+    resolution: {integrity: sha512-fAeUqfV5ndhxRwai8cXGzdLvul9utWOmeTkv69unv4ZXixjn61Z+p9lCWdwOwA3TYboG3BwdVuN/RDjhBRl0mw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [darwin]
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.3':
+    resolution: {integrity: sha512-iyf5bV6+wnAlflVeEy7R25dupxTNECZN5QMI0qNT6eT+EgaGdZcKhGkr5SdoaWiLJ3spLqIY9VCeSGrwmtg4kw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [freebsd]
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.3':
+    resolution: {integrity: sha512-aAYUprJAJQWWbRrPvtjdroZ56Md+JM8pMiopS6xGEwDfLhqj+2ver2p4nU4Mb3CRqcMmNBjo8KkUgcxhkzVQGQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.3':
+    resolution: {integrity: sha512-nDxldcEENOxZRzC2uu9jrutZdAAQtb+8WWDCSnWL1zvBk1+FN+x6MtDViPB5AJMfttVCUhehGWus3XBPgatM/w==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.3':
+    resolution: {integrity: sha512-Md44bD6veX/PC5iyF8cDVnw4HBIANZepRZZ7a8DQOvkfo5WUBwcp6iAuCUz23u+4SUkhJlD3eL7hNdW8ezd/kA==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.3':
+    resolution: {integrity: sha512-tx7us1muwOKAKWao2v/GaafFeQboE6aj88vC6ziN2NCGcRm8gWUhwjzg+YdVB1e4boAtdtma4L43onunI6NS4w==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.3':
+    resolution: {integrity: sha512-SJxX60smvHgasZoBy11dX6YRjXJFovwWBoedhbQPOBzgFWBHGB+TVPWB9BxzR7TTxU8FQZAI2AyiNCMzFm8Img==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [linux]
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.3':
+    resolution: {integrity: sha512-jx1+rPhY/5Ympkktd656HBWEBLxP7dH06losBLjjf5vgCODXvi9KhtftWcMIwTFIDqBr7cRnQkdLnAG+IOlGvQ==}
+    engines: {node: '>=14.0.0'}
+    cpu: [wasm32]
+    bundledDependencies:
+      - '@napi-rs/wasm-runtime'
+      - '@emnapi/core'
+      - '@emnapi/runtime'
+      - '@tybys/wasm-util'
+      - '@emnapi/wasi-threads'
+      - tslib
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.3':
+    resolution: {integrity: sha512-3rc292Ca2ceK6Ulcc/bAVnTs/3nDtoPhyEKlgPv+yQJQi/JS/AMJlqzxvlDacL1nekbrcf6bTqp/jV4qgnPxNQ==}
+    engines: {node: '>= 20'}
+    cpu: [arm64]
+    os: [win32]
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.3':
+    resolution: {integrity: sha512-yJ0pwIVc/nYeGoV02WtsN8KYyLQv7kyI2wDnkezyJlGGjkd4QLwDGAwl47YpPJeuI0M0ObaXGSPjvWDPeTPggw==}
+    engines: {node: '>= 20'}
+    cpu: [x64]
+    os: [win32]
+
+  '@tailwindcss/oxide@4.3.3':
+    resolution: {integrity: sha512-krXjAikiaFSPaK/FkAQT5UTx3VormQaiZ5hBFlJZ9UFQGB/rwg1MZIhHAG9smMQRTdyJxP6Qt5MwMtdyU5FWrA==}
+    engines: {node: '>= 20'}
+
+  '@tailwindcss/postcss@4.3.3':
+    resolution: {integrity: sha512-JTSZZGQi1AyKirbLN3azmjVzef92tcX7h+iSqPdaeStyFpGpDlKvvpxeOE8njhbUanbRwr3z8DyzhICWnMtQeg==}
+
+  '@tanstack/react-virtual@3.14.13':
+    resolution: {integrity: sha512-JbDTAwtzZ99aOeCrAfW5EsE5KSq5RWh6Af2dtFwyLIIk48Ja7vm6n4axu/43T3vfjFnEGJalxJ1wyYjSQD6bSg==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tanstack/virtual-core@3.17.11':
+    resolution: {integrity: sha512-+ILjvtHup6Y2hzQ6YzwMgX1Q+oQpxEGOXCEsCNaPoIP0VxMbizIBTmYTDtkerkIQS8/CbP1BRuyt8V/8BCsy1g==}
+
+  '@temporalio/activity@1.24.0':
+    resolution: {integrity: sha512-eBBho/r9XHe2KczYGzmaSp6e9+6c9ta/GGOBldIBr00D/cV34kJ76iAY3Ue1pQTaP7YaX3phMuOz07uUg/IKyA==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/client@1.24.0':
+    resolution: {integrity: sha512-/GGg6ZYl+pN/bQEvq414CyjDvyM+MM1WsMzi/7SCYb3UlivVXx9nOmH/6BGx8OfYFayp11fkmfSh6rt7vW/ePQ==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/common@1.24.0':
+    resolution: {integrity: sha512-jXp77fXwynBcVNc/CaGMT33TVYnhcN26S959HDv7Q71oc0rN6d8RHWR5z0nRCDAu5CQwZQRRhVK0TRdyAiEg7Q==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/core-bridge@1.24.0':
+    resolution: {integrity: sha512-6kzPB8RsHcPU6HDNUSDBFC0JG2UFrV3ThmPmJkeEafKh2DFrKARM8IzxgKeE5MzvdIXYmONFM0UmHg+TZ0/qrQ==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/nexus@1.24.0':
+    resolution: {integrity: sha512-SQOQia98KFowgpgH6Cn+7rcpWVEjmJbV5FlqQVQoDH82Q7yl5gT81GO9vN7YRYj5RE2P+DVzEsCc8ohT7Hy57g==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/proto@1.24.0':
+    resolution: {integrity: sha512-vhlhB9GpoyJx+78r3lDahHywpdri6LKx7kt7djLIw6XzHyb8FQTIi4lX8DSJBqKp3+HVfL1CLwiqO26KFRzg/g==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/worker@1.24.0':
+    resolution: {integrity: sha512-Lq79WAHOQFuCFJe1ZJcwcs/u8ZPhHyoTpnWZq1gr6mnB9IRMImAYrJFXY/MY/VdXVltTpy+7T6u/V+P327J+gQ==}
+    engines: {node: '>= 20.3.0'}
+
+  '@temporalio/workflow@1.24.0':
+    resolution: {integrity: sha512-pIA9nxkDCCbBnNuMSffQ44HWHYe3zXFfrDpDLwzh/FUSx8uLbsBM8jwf5oUMf+5eV/qVW9PknZhOu9IFO4XnPA==}
+    engines: {node: '>= 20.3.0'}
+
+  '@tiptap/core@3.31.4':
+    resolution: {integrity: sha512-cIVUQYBycighzsk6GbmCef8ZiEDVxoT5EuAe4xg2q9dNkDqCXVqI4YGr9aavCQEiAS4uHiRwqvcsPqJHipFDfg==}
+    peerDependencies:
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-blockquote@3.31.4':
+    resolution: {integrity: sha512-FHnbvCIW0eDKgUUFjmvEB0ax9YUBW7/Unm+38qpuQROvU872yRqhnDtycKT9IKk46jNdjM4A4fAGUbge10CrAA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-bold@3.31.4':
+    resolution: {integrity: sha512-QX1xoXvO0gz6uVsoLegumqQ4MJXL7lcUDQZ4J7la7LBqiIh4efrCmp2EXbhpr37M/YQL7w8q3g7H/VovSh7xIg==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-bubble-menu@3.31.4':
+    resolution: {integrity: sha512-Ml/yswuys+3QkOMajfXyAGlUKCxEbT3dMyF8vHwQ5mDk9MDm+dqp10It5CrDBkUT/KkVTa6AJI3kb0TXZJZiAA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-bullet-list@3.31.4':
+    resolution: {integrity: sha512-gHn1RDR4olCnmKpH+G9x+f8R+iKPNVdLlvbFkIpR/stjabZi7fB4Rr5GiHWsulbtxAjdQrNjnVeNdGM4rBxApw==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-character-count@3.31.4':
+    resolution: {integrity: sha512-JWftIQ7wBwgQ5sMGxkGTY+310uJv9yc6irNFC1t+FRyYxClqUNBGWoGG5z+H8x5AyoCQqFyBCkCVG9IKp2kkSA==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-code-block@3.31.4':
+    resolution: {integrity: sha512-su/B/cfQ1HpiHl6JfJ6wa+RVEptiYsV4dCntE8XQNj2dUcII4y6w6PQbbswOoDrU79uXHsAvpy44215rghG4LA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-code@3.31.4':
+    resolution: {integrity: sha512-pzi8GNDs5J1DEoO1HNYiJ5WZpgOZzlc/2VIa77mMpEuD4hZxuK0BQzlF/O6Ps/O5P1lGJT4xS0Yowpzb9mD9RA==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-document@3.31.4':
+    resolution: {integrity: sha512-vT20u62RWR+BLIyNJ54e24MPUY4zm8VF7tcgJnxQXi7BgVJWcNMtMWWDIkPJ4JNXwfoIznKh3jzYsaYmbCJgQQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-dropcursor@3.31.4':
+    resolution: {integrity: sha512-5TbCPCC4RL+QT1NYHjXCYDBHBtVqYOFvFEnk3v98lvXCM2PNL13ofXUfJPuykAVy1OdTAx4DlZOQAD9WKy/IdQ==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-floating-menu@3.31.4':
+    resolution: {integrity: sha512-pKzulkDmolpVt7IP9FSPsC5pKbXQ5pyeqkaAYr8cyOVW+KUObpPRIzAuXvEso8PCjWgwJ1f2qyishOEMw8MbfQ==}
+    peerDependencies:
+      '@floating-ui/dom': ^1.0.0
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-gapcursor@3.31.4':
+    resolution: {integrity: sha512-hBogUAepQH6IQUhaePhPWzQ1Oeu+yqlJVMKO06Eue5m36uRy1PZZAQ780pCGT0SC4R5MH2td1N8EUQ7bupQdDA==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-hard-break@3.31.4':
+    resolution: {integrity: sha512-oLNajLyUvRMg1qtzFgKGduygTlpaHFB9PU+M+pUWdA4sa1bRnxS2Y++Ao4lHYopJ7nxatLndrYoCIHkotqkPDQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-heading@3.31.4':
+    resolution: {integrity: sha512-KqlSeLathpdxCc3kVHBCA/RkHvb+V7u5vgiSEu1Cv3L70r7F19COMGODav/k1AGYBgEXKL6lM9cy8cloE5/28g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-horizontal-rule@3.31.4':
+    resolution: {integrity: sha512-ws0Kh8kfHL7ESILSXj0HJAXs8G10ewlW1sedXKm8dm0op9L8il+xl8bEJVoqG/jMf77900Fc2CaQldcCGRpF1g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-italic@3.31.4':
+    resolution: {integrity: sha512-pftTQBPYZocNDAj/u6OyDIp7YxmN0+N895cQPogJQ6qMHdLiRhzgawiEewJkniyN1w8k3Wx/Etp8pTKrxaOOBQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-link@3.31.4':
+    resolution: {integrity: sha512-LLxW3qfeL9gvDdMPVdxYFYZ0zZSjsoIDhOqjJ5U2UfaK3U2iwkKTBgV2qT+FWf3uUHmBRjBZ08q3dRPmWBAD5g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-list-item@3.31.4':
+    resolution: {integrity: sha512-ao8XAPvhOrtGFILs+fKtOM91omDSpUC8X19m44gbaq5xJDVpIMZ0rP+NAVUS72G7LskhcHa0bu/Pm022bUVjVw==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-list-keymap@3.31.4':
+    resolution: {integrity: sha512-etdkl/YnYfwtALDxecJ+4WYgJAez1fn1vzzZqJklZBpgqiZtny3NxpvWS7/JhsltNG84Wo/oovpfJgVmzhddrw==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-list@3.31.4':
+    resolution: {integrity: sha512-Wd4YRYxOdf+TtF33/QsRo1RK1CecVxjYGjUBIKNGHAywfh8tghgV4YOUCiV1iJqYt2IBs+RWlIqTmdIPzBrd4A==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-ordered-list@3.31.4':
+    resolution: {integrity: sha512-UNWyF+Dhm08znszIMnT8Y2kJ1lvtiCvUGs1aG7m9cPHxDa7VycWnOqdtXWkc+6xRLNiC0zgWCFWgLLHduV8pRQ==}
+    peerDependencies:
+      '@tiptap/extension-list': 3.31.4
+
+  '@tiptap/extension-paragraph@3.31.4':
+    resolution: {integrity: sha512-WZlBgw+XVKXerRlmEsoQ7x1PwSU+dh3X+b70+ViZsLebdfsmmYBIaNDrvIGwG9UQr5eLnddJnZplMSTI2YKs+g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-placeholder@3.31.4':
+    resolution: {integrity: sha512-3SoJopaOzaA9IZHSk9ZXHiO6ib8ErPh7ssRh3bIaxfD+BqRyXcm4hV4yfFXTqrDCnl5FE+DbBRGmeVAVkDko3g==}
+    peerDependencies:
+      '@tiptap/extensions': 3.31.4
+
+  '@tiptap/extension-strike@3.31.4':
+    resolution: {integrity: sha512-4MBr63TJIMqxCjE+gAPdlY1IdELgvbAP516K3Ntn/BkcpEbEoPMEYVz+XTxULyHQEuARDO6jsXPPxRXpA74jaw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-text@3.31.4':
+    resolution: {integrity: sha512-WL2ZRpFksgQcXJN05/UQH09YCH9LlhdLrSEcviASvEH/aAfsKiJlDrouN8PET+YAWK/F5xFc5/Q1z0xj+I23jw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extension-underline@3.31.4':
+    resolution: {integrity: sha512-0iFGPIqmqGkCrOFh1OPo7Dzv5s86dVN3bZaugsz0jK04otkb8bn04ZDKP2/6Wq+lcK0M9DfJ0QqfW5hC2nBZxQ==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+
+  '@tiptap/extensions@3.31.4':
+    resolution: {integrity: sha512-nIupIne/sHpV2Kw1M4MOmr4+G454KI8BXM5+LWKOU2EpzfALZWVSy7koF9lVRna4Zp5Gv8hfg5Z8kvmrYQvhkw==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/pm@3.31.4':
+    resolution: {integrity: sha512-x7dwth79cQp4QGae66/RJqMDJQv0+n7b7dD7cyFQBWqzPFLJxN/4paHY4qbWedZjNLhRyIOAD9a5q4AYM1zmPA==}
+
+  '@tiptap/react@3.31.4':
+    resolution: {integrity: sha512-mBvvXgdPhMinT1NPfwHvFK1dFdMXHVWMSeNn0IPj7/zV0XBmOnASkEOwoIvl8NluKYEtpZBE1yA+6pN2enLa5g==}
+    peerDependencies:
+      '@tiptap/core': 3.31.4
+      '@tiptap/pm': 3.31.4
+      '@types/react': ^17.0.0 || ^18.0.0 || ^19.0.0
+      '@types/react-dom': ^17.0.0 || ^18.0.0 || ^19.0.0
+      react: ^17.0.0 || ^18.0.0 || ^19.0.0
+      react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  '@tiptap/starter-kit@3.31.4':
+    resolution: {integrity: sha512-u7HIJ9vK6kFe4S4J2CIcDLrhRZzoTMSyU0XxjQ6lUNF7pWW3rMi//pvi8RcsZmxGjyb8CpXAqYgNl7f9WyaUeA==}
+
+  '@tokenizer/inflate@0.2.7':
+    resolution: {integrity: sha512-MADQgmZT1eKjp06jpI2yozxaU9uVs4GzzgSL+uEq7bVcJ9V1ZXQkeGNql1fsSI0gMy1vhvNTNbUqrx+pZfJVmg==}
+    engines: {node: '>=18'}
+
+  '@tokenizer/token@0.3.0':
+    resolution: {integrity: sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A==}
+
+  '@turbo/darwin-64@2.11.7':
+    resolution: {integrity: sha512-Z2LFOxwbiJueD1miByXJS/BrW21vv6YaQXZustty5jEX4vQYw6zyh101Sz1QO7WG0mqBzKagZ/DoAeeujI0/Sw==}
+    cpu: [x64]
+    os: [darwin]
+
+  '@turbo/darwin-arm64@2.11.7':
+    resolution: {integrity: sha512-Vhv8ybgIflosNDSSRD9fNXHlCFA60dsGyTqQmc7l28SEX5jOaweCCD4BBYNd8/p0WGkw3e7tZbfA9w6FsujGvw==}
+    cpu: [arm64]
+    os: [darwin]
+
+  '@turbo/linux-64@2.11.7':
+    resolution: {integrity: sha512-rAqRp3blQKk1+ylMGlZHAW0eJjVNuuGUm4ZrC6RU1Im8tLryvaO4a2zLQ/FQi1TRlmKqKV9YXBki2YeytlLbXA==}
+    cpu: [x64]
+    os: [android, linux]
+
+  '@turbo/linux-arm64@2.11.7':
+    resolution: {integrity: sha512-thVYGov7S+llXAxrl3kBb/efalav0xhrjl5NHCR6AfKx14JkbqaetvbVwyss4FvZ9rt+Pv3xsTb+8SIYix8DTg==}
+    cpu: [arm64]
+    os: [android, linux]
+
+  '@turbo/windows-64@2.11.7':
+    resolution: {integrity: sha512-ZIoKT7J7KutgYl4bGxmmgeUQjG+7E0nY8BF9dxUOiMH2vdTsM4JQ2uSwTYFkTR2Llbg6ghGjSmuZ8LQtkLEYjg==}
+    cpu: [x64]
+    os: [win32]
+
+  '@turbo/windows-arm64@2.11.7':
+    resolution: {integrity: sha512-88Xv2f7SLGVJ68lRRx8o375dKmnZYNdDtvlKcPA0kZpcF93eAQd8l96BKQ0/AMHG0bMJA0Z5QqoqtetxzNsC+g==}
+    cpu: [arm64]
+    os: [win32]
+
+  '@types/aws-lambda@8.10.164':
+    resolution: {integrity: sha512-XOnrazWcOd6yWPnR7DxqCBPPYciDjHq+NN8LPwwqBCJNXLyPJgKo47fZpJ113+oyAn9Zti0Cf6H4k6yPcE3WFg==}
+
+  '@types/body-parser@1.19.6':
+    resolution: {integrity: sha512-HLFeCYgz89uk22N5Qg3dvGvsv46B8GLvKKo1zKG4NybA8U2DiEO3w9lqGg29t/tfLRJpJ6iQxnVw4OnB7MoM9g==}
+
+  '@types/connect@3.4.38':
+    resolution: {integrity: sha512-K6uROf1LD88uDQqJCktA4yzL1YYAK6NgfsI0v/mTgyPKWsX1CnJ0XPSDhViejru1GcRkLWb8RlzFYJRqGUbaug==}
+
+  '@types/estree@1.0.9':
+    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}
+
+  '@types/express-serve-static-core@4.19.9':
+    resolution: {integrity: sha512-QP2ESEe/ImWY0HDwNAnK9PvEffUyhLTnWkk7KXzHfyeWAnlrDe1fN77bXl6ia8KT3wPlmA7t9/VPRpnf4Ex9sg==}
+
+  '@types/express@4.17.25':
+    resolution: {integrity: sha512-dVd04UKsfpINUnK0yBoYHDF3xu7xVH4BuDotC/xGuycx4CgbP48X/KF/586bcObxT0HENHXEU8Nqtu6NR+eKhw==}
+
+  '@types/http-errors@2.0.5':
+    resolution: {integrity: sha512-r8Tayk8HJnX0FztbZN7oVqGccWgw98T/0neJphO91KkmOzug1KkofZURD4UaD5uH8AqcFLfdPErnBod0u71/qg==}
+
+  '@types/json-schema@7.0.15':
+    resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}
+
+  '@types/memcached@2.2.10':
+    resolution: {integrity: sha512-AM9smvZN55Gzs2wRrqeMHVP7KE8KWgCJO/XL5yCly2xF6EKa4YlbpK+cLSAH4NG/Ah64HrlegmGqW8kYws7Vxg==}
+
+  '@types/mime@1.3.5':
+    resolution: {integrity: sha512-/pyBZWSLD2n0dcHE3hq8s8ZvcETHtEuF+3E7XVt0Ig2nvsVQXdghHVcEkIWjy9A0wKfTn97a/PSDYohKIlnP/w==}
+
+  '@types/node@22.20.5':
+    resolution: {integrity: sha512-U2+DNr+wSjpsTS/wZGYHq7GcwfuSmKiKvoPvK22zwTlRhU91yOniN4qRR5KhIjvif7ysw/dz/hKmfDH0Ris4aA==}
+
+  '@types/pg-pool@2.0.7':
+    resolution: {integrity: sha512-U4CwmGVQcbEuqpyju8/ptOKg6gEC+Tqsvj2xS9o1g71bUh8twxnC6ZL5rZKCsGN0iyH0CwgUyc9VR5owNQF9Ng==}
+
+  '@types/pg@8.15.6':
+    resolution: {integrity: sha512-NoaMtzhxOrubeL/7UZuNTrejB4MPAJ0RpxZqXQf2qXuVlTPuG6Y8p4u9dKRaue4yjmC7ZhzVO2/Yyyn25znrPQ==}
+
+  '@types/pg@8.23.1':
+    resolution: {integrity: sha512-fKVHpikPdg4GKks3JuLEhvwSyvwzF23hnabPy6DD8ljVbC7+6J5dQzdv4arV6jqq57djnMgs1HKBxX4P8aBI3A==}
+
+  '@types/prop-types@15.7.15':
+    resolution: {integrity: sha512-F6bEyamV9jKGAFBEmlQnesRPGOQqS2+Uwi0Em15xenOxHaf2hv6L8YCVn3rPdPJOiJfPiCnLIRyvwVaqMY3MIw==}
+
+  '@types/qs@6.15.1':
+    resolution: {integrity: sha512-GZHUBZR9hckSUhrxmp1nG6NwdpM9fCunJwyThLW1X3AyHgd9IlHb6VANpQQqDr2o/qQp6McZ3y/IA2rVzKzSbw==}
+
+  '@types/range-parser@1.2.7':
+    resolution: {integrity: sha512-hKormJbkJqzQGhziax5PItDUTMAM9uE2XXQmM37dyd4hVM+5aVl7oVxMVUiVQn2oCQFN/LKCZdvSM0pFRqbSmQ==}
+
+  '@types/react-dom@18.3.7':
+    resolution: {integrity: sha512-MEe3UeoENYVFXzoXEWsvcpg6ZvlrFNlOQ7EOsvhI3CfAXwzPfO8Qwuxd40nepsYKqyyVQnTdEfv68q91yLcKrQ==}
+    peerDependencies:
+      '@types/react': ^18.0.0
+
+  '@types/react@18.3.31':
+    resolution: {integrity: sha512-vfEqpXTvwT91yhmwdfouStN2hSKwTvyRs8qpLfADyrq/kxDw0hZM7Wk9Ug1FELj8hIby+S/+kQCSRFF32nv2Qw==}
+
+  '@types/send@0.17.6':
+    resolution: {integrity: sha512-Uqt8rPBE8SY0RK8JB1EzVOIZ32uqy8HwdxCnoCOsYrvnswqmFZ/k+9Ikidlk/ImhsdvBsloHbAlewb2IEBV/Og==}
+
+  '@types/send@1.2.1':
+    resolution: {integrity: sha512-arsCikDvlU99zl1g69TcAB3mzZPpxgw0UQnaHeC1Nwb015xp8bknZv5rIfri9xTOcMuaVgvabfIRA7PSZVuZIQ==}
+
+  '@types/serve-static@1.15.10':
+    resolution: {integrity: sha512-tRs1dB+g8Itk72rlSI2ZrW6vZg0YrLI81iQSTkMmOqnqCaNr/8Ek4VwWcN5vZgCYWbg/JJSGBlUaYGAOP73qBw==}
+
+  '@types/use-sync-external-store@0.0.6':
+    resolution: {integrity: sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==}
+
+  '@typescript-eslint/eslint-plugin@8.71.0':
+    resolution: {integrity: sha512-pqcS9c1HxZTHt7End4nXqd0s5lJrrFzrgCkKFJrsbUnaL6M3+6oBFZaslg6Gjsl3argl2DDRFROnXARaZ2e4Nw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      '@typescript-eslint/parser': ^8.71.0
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/parser@8.71.0':
+    resolution: {integrity: sha512-CG4nPk1f2zc8yw4pALqHsFYH2hdo+h1T9daSp21+Hnxi9LOE3GT9hAfTKJCBXVNM2GmYs1eMEP615wPoeOgk3A==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/project-service@8.71.0':
+    resolution: {integrity: sha512-aABjw5rjBacYONVPaPiWOCjJu0vEF4a25iQuodlmQYL1trtLZ0X/y+2Vzl3BKI1odM4LnwLE1oUDXYp1wzx1TQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/scope-manager@8.71.0':
+    resolution: {integrity: sha512-gWF0BhUcnjZxSpLE8ngS/59n2SB0J3YqRxvX1+2aoRJk9hNtHSLOV+TcarFiOr5ipXm3yc1QrI4c9YZc8zyCxw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/tsconfig-utils@8.71.0':
+    resolution: {integrity: sha512-Z1UlWHADEK2Mlb9NpWfDeSjqoZ5EyrOv4R3eQpbkzqn/EwaIdOpXXupEA1+0ZIOSJSZZDBHG0BrQyN8zUG6Pwg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/type-utils@8.71.0':
+    resolution: {integrity: sha512-i8uO1qbdxeKgRnS5sCRt6On3/nfo2d2DwQe3Yvjx543zLy7r8ySqRuPPiIIXAhS03U0v5NfAFx+rUgxFzKKwNw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/types@8.71.0':
+    resolution: {integrity: sha512-cJ4OoxPGWvFnBTnSZyaU+qJzGTqPTGJY+gDchj6cRyLRdmIdt4rcsE4twj+zPfrNiWuVi38wijHzShL++Z9atQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@typescript-eslint/typescript-estree@8.71.0':
+    resolution: {integrity: sha512-PEEF4G5sLLWAS5BpPrUvms4ySZkiBQQZM4z+3ReI46axK5Vqr/vXBQatJQIZZOYdGyPUAKTtsrWzpqKuU+3DEw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/utils@8.71.0':
+    resolution: {integrity: sha512-pKR/tEMVrXZG23UFKUn5BQf3zfmfk7KQceI2cGzywZ5nxM5Eu3hEJU1utjWzydtzBbcJAQhHN8iPCxobHpPcZQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  '@typescript-eslint/visitor-keys@8.71.0':
+    resolution: {integrity: sha512-8eQ9R218XORK+KLosnf4bu/QsUXvUyVwTbArg7/0NMB1Pu87OJKvj4nhFblkYE8gQV73mW1dx1ptlPCkwRGa7A==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  '@vitest/expect@2.1.9':
+    resolution: {integrity: sha512-UJCIkTBenHeKT1TTlKMJWy1laZewsRIzYighyYiJKZreqtdxSos/S1t+ktRMQWu2CKqaarrkeszJx1cgC5tGZw==}
+
+  '@vitest/mocker@2.1.9':
+    resolution: {integrity: sha512-tVL6uJgoUdi6icpxmdrn5YNo3g3Dxv+IHJBr0GXHaEdTcw3F+cPKnsXFhli6nO+f/6SDKPHEK1UN+k+TQv0Ehg==}
+    peerDependencies:
+      msw: ^2.4.9
+      vite: ^5.0.0
+    peerDependenciesMeta:
+      msw:
+        optional: true
+      vite:
+        optional: true
+
+  '@vitest/pretty-format@2.1.9':
+    resolution: {integrity: sha512-KhRIdGV2U9HOUzxfiHmY8IFHTdqtOhIzCpd8WRdJiE7D/HUcZVD0EgQCVjm+Q9gkUXWgBvMmTtZgIG48wq7sOQ==}
+
+  '@vitest/runner@2.1.9':
+    resolution: {integrity: sha512-ZXSSqTFIrzduD63btIfEyOmNcBmQvgOVsPNPe0jYtESiXkhd8u2erDLnMxmGrDCwHCCHE7hxwRDCT3pt0esT4g==}
+
+  '@vitest/snapshot@2.1.9':
+    resolution: {integrity: sha512-oBO82rEjsxLNJincVhLhaxxZdEtV0EFHMK5Kmx5sJ6H9L183dHECjiefOAdnqpIgT5eZwT04PoggUnW88vOBNQ==}
+
+  '@vitest/spy@2.1.9':
+    resolution: {integrity: sha512-E1B35FwzXXTs9FHNK6bDszs7mtydNi5MIfUWpceJ8Xbfb1gBMscAnwLbEu+B44ed6W3XjL9/ehLPHR1fkf1KLQ==}
+
+  '@vitest/utils@2.1.9':
+    resolution: {integrity: sha512-v0psaMSkNJ3A2NMrUEHFRzJtDPFn+/VWZ5WxImB21T9fjucJRmS7xCS3ppEnARb9y11OAzaD+P2Ps+b+BGX5iQ==}
+
+  '@webassemblyjs/ast@1.14.1':
+    resolution: {integrity: sha512-nuBEDgQfm1ccRp/8bCQrx1frohyufl4JlbMMZ4P1wpeOfDhF6FQkxZJ1b/e+PLwr6X1Nhw6OLme5usuBWYBvuQ==}
+
+  '@webassemblyjs/floating-point-hex-parser@1.13.2':
+    resolution: {integrity: sha512-6oXyTOzbKxGH4steLbLNOu71Oj+C8Lg34n6CqRvqfS2O71BxY6ByfMDRhBytzknj9yGUPVJ1qIKhRlAwO1AovA==}
+
+  '@webassemblyjs/helper-api-error@1.13.2':
+    resolution: {integrity: sha512-U56GMYxy4ZQCbDZd6JuvvNV/WFildOjsaWD3Tzzvmw/mas3cXzRJPMjP83JqEsgSbyrmaGjBfDtV7KDXV9UzFQ==}
+
+  '@webassemblyjs/helper-buffer@1.14.1':
+    resolution: {integrity: sha512-jyH7wtcHiKssDtFPRB+iQdxlDf96m0E39yb0k5uJVhFGleZFoNw1c4aeIcVUPPbXUVJ94wwnMOAqUHyzoEPVMA==}
+
+  '@webassemblyjs/helper-numbers@1.13.2':
+    resolution: {integrity: sha512-FE8aCmS5Q6eQYcV3gI35O4J789wlQA+7JrqTTpJqn5emA4U2hvwJmvFRC0HODS+3Ye6WioDklgd6scJ3+PLnEA==}
+
+  '@webassemblyjs/helper-wasm-bytecode@1.13.2':
+    resolution: {integrity: sha512-3QbLKy93F0EAIXLh0ogEVR6rOubA9AoZ+WRYhNbFyuB70j3dRdwH9g+qXhLAO0kiYGlg3TxDV+I4rQTr/YNXkA==}
+
+  '@webassemblyjs/helper-wasm-section@1.14.1':
+    resolution: {integrity: sha512-ds5mXEqTJ6oxRoqjhWDU83OgzAYjwsCV8Lo/N+oRsNDmx/ZDpqalmrtgOMkHwxsG0iI//3BwWAErYRHtgn0dZw==}
+
+  '@webassemblyjs/ieee754@1.13.2':
+    resolution: {integrity: sha512-4LtOzh58S/5lX4ITKxnAK2USuNEvpdVV9AlgGQb8rJDHaLeHciwG4zlGr0j/SNWlr7x3vO1lDEsuePvtcDNCkw==}
+
+  '@webassemblyjs/leb128@1.13.2':
+    resolution: {integrity: sha512-Lde1oNoIdzVzdkNEAWZ1dZ5orIbff80YPdHx20mrHwHrVNNTjNr8E3xz9BdpcGqRQbAEa+fkrCb+fRFTl/6sQw==}
+
+  '@webassemblyjs/utf8@1.13.2':
+    resolution: {integrity: sha512-3NQWGjKTASY1xV5m7Hr0iPeXD9+RDobLll3T9d2AO+g3my8xy5peVyjSag4I50mR1bBSN/Ct12lo+R9tJk0NZQ==}
+
+  '@webassemblyjs/wasm-edit@1.14.1':
+    resolution: {integrity: sha512-RNJUIQH/J8iA/1NzlE4N7KtyZNHi3w7at7hDjvRNm5rcUXa00z1vRz3glZoULfJ5mpvYhLybmVcwcjGrC1pRrQ==}
+
+  '@webassemblyjs/wasm-gen@1.14.1':
+    resolution: {integrity: sha512-AmomSIjP8ZbfGQhumkNvgC33AY7qtMCXnN6bL2u2Js4gVCg8fp735aEiMSBbDR7UQIj90n4wKAFUSEd0QN2Ukg==}
+
+  '@webassemblyjs/wasm-opt@1.14.1':
+    resolution: {integrity: sha512-PTcKLUNvBqnY2U6E5bdOQcSM+oVP/PmrDY9NzowJjislEjwP/C4an2303MCVS2Mg9d3AJpIGdUFIQQWbPds0Sw==}
+
+  '@webassemblyjs/wasm-parser@1.14.1':
+    resolution: {integrity: sha512-JLBl+KZ0R5qB7mCnud/yyX08jWFw5MsoalJ1pQ4EdFlgj9VdXKGuENGsiCIjegI1W7p91rUlcB/LB5yRJKNTcQ==}
+
+  '@webassemblyjs/wast-printer@1.14.1':
+    resolution: {integrity: sha512-kPSSXE6De1XOR820C90RIo2ogvZG+c3KiHzqUoO/F34Y2shGzesfqv7o57xrxovZJH/MetF5UjroJ/R/3isoiw==}
+
+  '@xtuc/ieee754@1.2.0':
+    resolution: {integrity: sha512-DX8nKgqcGwsc0eJSqYt5lwP4DH5FlHnmuWWBRy7X0NcaGR0ZtuyeESgMwTYVEtxmsNGY+qit4QYT/MIYTOTPeA==}
+
+  '@xtuc/long@4.2.2':
+    resolution: {integrity: sha512-NuHqBY1PB/D8xU6s/thBgOAiAP7HOYDQ32+BFZILJ8ivkUkAHQnWfn6WhL79Owj1qmUnoN/YPhktdIoucipkAQ==}
+
+  abort-controller@3.0.0:
+    resolution: {integrity: sha512-h8lQ8tacZYnR3vNQTgibj+tODHI5/+l06Au2Pcriv/Gmet0eaj4TwWH41sO9wnHDiQsEj19q0drzdWdeAHtweg==}
+    engines: {node: '>=6.5'}
+
+  accepts@1.3.8:
+    resolution: {integrity: sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==}
+    engines: {node: '>= 0.6'}
+
+  acorn-jsx@5.3.2:
+    resolution: {integrity: sha512-rq9s+JNhf0IChjtDXxllJ7g41oZk5SlXtp0LHwyA5cejwn7vKmKp4pPri6YEePv2PU65sAsegbXtIinmDFDXgQ==}
+    peerDependencies:
+      acorn: ^6.0.0 || ^7.0.0 || ^8.0.0
+
+  acorn@8.19.0:
+    resolution: {integrity: sha512-oJlA3XiRm7Cyk6qFD2Jn8ak9B7jSy0qy00ADO3+8dpT0LSjFihQYv4C02LFCSYJV3Q37xYwwRy5m+IpIiUzqWw==}
+    engines: {node: '>=0.4.0'}
+    hasBin: true
+
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
+  ajv-formats@3.0.1:
+    resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
+    peerDependencies:
+      ajv: ^8.0.0
+    peerDependenciesMeta:
+      ajv:
+        optional: true
+
+  ajv-keywords@5.1.0:
+    resolution: {integrity: sha512-YCS/JNFAUyr5vAuhk1DWm1CBxRHW9LbJ2ozWeemrIqpbsqKjHVxYPyi5GC0rjZIT5JxJ3virVTS8wk4i/Z+krw==}
+    peerDependencies:
+      ajv: ^8.8.2
+
+  ajv@6.15.0:
+    resolution: {integrity: sha512-fgFx7Hfoq60ytK2c7DhnF8jIvzYgOMxfugjLOSMHjLIPgenqa7S7oaagATUq99mV6IYvN2tRmC0wnTYX6iPbMw==}
+
+  ajv@8.20.0:
+    resolution: {integrity: sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA==}
+
+  ansi-regex@5.0.1:
+    resolution: {integrity: sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==}
+    engines: {node: '>=8'}
+
+  ansi-regex@6.4.0:
+    resolution: {integrity: sha512-KzTVk2tCWAHtYrvvvaP8bJKJq2pVinhLcGEQdtLIYPbmNGNyYe8QwNaTUYQp2J7/vIsUKt5QCqAfUkYyG9DkOw==}
+    engines: {node: '>=12'}
+
+  ansi-styles@4.3.0:
+    resolution: {integrity: sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==}
+    engines: {node: '>=8'}
+
+  ansi-styles@6.2.3:
+    resolution: {integrity: sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==}
+    engines: {node: '>=12'}
+
+  append-field@1.0.0:
+    resolution: {integrity: sha512-klpgFSWLW1ZEs8svjfb7g4qWY0YS5imI82dTg+QahUvJ8YqAY0P10Uk8tTyh9ZGuYEZEMaeJYCF5BFuX552hsw==}
+
+  argparse@2.0.1:
+    resolution: {integrity: sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==}
+
+  aria-hidden@1.2.6:
+    resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
+    engines: {node: '>=10'}
+
+  array-flatten@1.1.1:
+    resolution: {integrity: sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==}
+
+  assertion-error@2.0.1:
+    resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
+    engines: {node: '>=12'}
+
+  atomic-sleep@1.0.0:
+    resolution: {integrity: sha512-kNOjDqAh7px0XWNI+4QbzoiR/nTkHAWNud2uvnJquD1/x5a7EQZMJT0AczqK0Qn67oY/TTQ1LbUKajZpp3I9tQ==}
+    engines: {node: '>=8.0.0'}
+
+  balanced-match@1.0.2:
+    resolution: {integrity: sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==}
+
+  balanced-match@4.0.4:
+    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
+    engines: {node: 18 || 20 || >=22}
+
+  baseline-browser-mapping@2.11.27:
+    resolution: {integrity: sha512-ElY12DaROGuan+lMmZ8Cvo/ZUbXPe7Enc/9VU/b1T3Kp4dwytRcNdR8DoSJN5SNJT/CuvcCA0DHDVmMOCePdRQ==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  bignumber.js@9.3.1:
+    resolution: {integrity: sha512-Ko0uX15oIUS7wJ3Rb30Fs6SkVbLmPBAKdlm7q9+ak9bbIeFf0MwuBsQV6z7+X768/cHsfg+WlysDWJcmthjsjQ==}
+
+  body-parser@1.20.4:
+    resolution: {integrity: sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA==}
+    engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16}
+
+  bowser@2.14.1:
+    resolution: {integrity: sha512-tzPjzCxygAKWFOJP011oxFHs57HzIhOEracIgAePE4pqB3LikALKnSzUyU4MGs9/iCEUuHlAJTjTc5M+u7YEGg==}
+
+  brace-expansion@1.1.21:
+    resolution: {integrity: sha512-9zeA+KLZNNzglF2TPKRQEDyx6Yby7daAkuy8MiPzpXPsYDWi/DRM8jmwUDxokQjYqBpv5DgPiwD4h4ZZSy1Ujw==}
+
+  brace-expansion@2.1.7:
+    resolution: {integrity: sha512-uZbew1NqdmPDTMJ8ah1y+b+9QEJrfkXFk3RcTQw3X0jW/xRUvFKsg1CfQdSYGdTbXZWExtU3J3ccxtnfw1Fi0g==}
+
+  brace-expansion@5.0.12:
+    resolution: {integrity: sha512-YovQ3rzhaLMIrDjNDMkNS01tea93qhEhG5xy8f6+R0l+dw3Ki+5sCoIoI942iuLZTHWogWktgwVDhU09iNEimQ==}
+    engines: {node: 20 || >=22}
+
+  browserslist@4.29.3:
+    resolution: {integrity: sha512-1R4kiYKXGViqEN0CnoDrXc1StD9niAwu+j2dukWzrD4bJgsD4lDmEp0CRbc6E/vYJIfTHwPmwyaKtVSudICdPA==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  buffer-from@1.1.2:
+    resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==}
+
+  busboy@1.6.0:
+    resolution: {integrity: sha512-8SFQbg/0hQ9xy3UNTB0YEnsNBbWfhf7RtnzpL7TkBiTBRfrQ9Fxcnz7VJsleJpyp6rVLvXiuORqjlHi5q+PYuA==}
+    engines: {node: '>=10.16.0'}
+
+  bytes@3.1.2:
+    resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==}
+    engines: {node: '>= 0.8'}
+
+  cac@6.7.14:
+    resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==}
+    engines: {node: '>=8'}
+
+  call-bind-apply-helpers@1.0.2:
+    resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==}
+    engines: {node: '>= 0.4'}
+
+  call-bound@1.0.4:
+    resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==}
+    engines: {node: '>= 0.4'}
+
+  callsites@3.1.0:
+    resolution: {integrity: sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==}
+    engines: {node: '>=6'}
+
+  caniuse-lite@1.0.30001814:
+    resolution: {integrity: sha512-/Uaf1lAzr59XcMpW0o96WoEfr+VXK2OX4U9AgFoiSHsVJ4HppnIFUjtYzsyDH2+tgANaQb2/oxYGwCPapN1FpA==}
+
+  chai@5.3.3:
+    resolution: {integrity: sha512-4zNhdJD/iOjSH0A05ea+Ke6MU5mmpQcbQsSOkgdaUMJ9zTlDTD/GYlwohmIE2u0gaxHYiVHEn1Fw9mZ/ktJWgw==}
+    engines: {node: '>=18'}
+
+  chalk@4.1.2:
+    resolution: {integrity: sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==}
+    engines: {node: '>=10'}
+
+  check-error@2.1.3:
+    resolution: {integrity: sha512-PAJdDJusoxnwm1VwW07VWwUN1sl7smmC3OKggvndJFadxxDRyFJBX/ggnu/KE4kQAB7a3Dp8f/YXC1FlUprWmA==}
+    engines: {node: '>= 16'}
+
+  chrome-trace-event@1.0.4:
+    resolution: {integrity: sha512-rNjApaLzuwaOTjCiT8lSDdGN1APCiqkChLMJxJPWLunPAt5fy8xgU9/jNOchV84wfIxrA0lRQB7oCT8jrn/wrQ==}
+    engines: {node: '>=6.0'}
+
+  cjs-module-lexer@2.3.0:
+    resolution: {integrity: sha512-lmNyBzi6iYiqyrExTctfmjd8tInx+dHu9PBomTfH5RXS53c27JMFJgzNv5TyAnm3PgGf+MLy0+Ws41/HlVxdKQ==}
+
+  client-only@0.0.1:
+    resolution: {integrity: sha512-IV3Ou0jSMzZrd3pZ48nLkT9DA7Ag1pnPzaiQhpW7c3RbcqqzvzzVu+L8gfqMp/8IM2MQtSiqaCxrrcfu8I8rMA==}
+
+  cliui@8.0.1:
+    resolution: {integrity: sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==}
+    engines: {node: '>=12'}
+
+  cmdk@1.1.1:
+    resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}
+    peerDependencies:
+      react: ^18 || ^19 || ^19.0.0-rc
+      react-dom: ^18 || ^19 || ^19.0.0-rc
+
+  color-convert@2.0.1:
+    resolution: {integrity: sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==}
+    engines: {node: '>=7.0.0'}
+
+  color-name@1.1.4:
+    resolution: {integrity: sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==}
+
+  commander@2.20.3:
+    resolution: {integrity: sha512-GpVkmM8vF2vQUkj2LvZmD35JxeJOLCwJ9cUkugyk2nuhbv3+mJvpLYYt+0+USMxE+oj+ey/lJEnhZw75x/OMcQ==}
+
+  concat-map@0.0.1:
+    resolution: {integrity: sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==}
+
+  concat-stream@2.0.0:
+    resolution: {integrity: sha512-MWufYdFw53ccGjCA+Ol7XJYpAlW6/prSMzuPOTRnJGcGzuhLn4Scrz7qf6o8bROZ514ltazcIFJZevcfbo0x7A==}
+    engines: {'0': node >= 6.0}
+
+  consola@2.15.3:
+    resolution: {integrity: sha512-9vAdYbHj6x2fLKC4+oPH0kFzY/orMZyG2Aj+kNylHxKGJ/Ed4dpNyAQYwJOdqO4zdM7XpVHmyejQDcQHrnuXbw==}
+
+  content-disposition@0.5.4:
+    resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==}
+    engines: {node: '>= 0.6'}
+
+  content-type@1.0.5:
+    resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==}
+    engines: {node: '>= 0.6'}
+
+  cookie-signature@1.0.7:
+    resolution: {integrity: sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==}
+
+  cookie@0.7.2:
+    resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==}
+    engines: {node: '>= 0.6'}
+
+  cors@2.8.5:
+    resolution: {integrity: sha512-KIHbLJqu73RGr/hnbrO9uBeixNGuvSQjul/jdFvS/KFSIH1hWVd1ng7zOHx+YrEfInLG7q4n6GHQ9cDtxv/P6g==}
+    engines: {node: '>= 0.10'}
+
+  cross-spawn@7.0.6:
+    resolution: {integrity: sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==}
+    engines: {node: '>= 8'}
+
+  csstype@3.2.3:
+    resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==}
+
+  data-uri-to-buffer@4.0.1:
+    resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==}
+    engines: {node: '>= 12'}
+
+  debug@2.6.9:
+    resolution: {integrity: sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  debug@4.4.3:
+    resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==}
+    engines: {node: '>=6.0'}
+    peerDependencies:
+      supports-color: '*'
+    peerDependenciesMeta:
+      supports-color:
+        optional: true
+
+  deep-eql@5.0.2:
+    resolution: {integrity: sha512-h5k/5U50IJJFpzfL6nO9jaaumfjO/f2NjK/oYB2Djzm4p9L+3T9qWpZqZ2hAbLPuuYq9wrU08WQyBTL5GbPk5Q==}
+    engines: {node: '>=6'}
+
+  deep-is@0.1.4:
+    resolution: {integrity: sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==}
+
+  depd@2.0.0:
+    resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==}
+    engines: {node: '>= 0.8'}
+
+  destroy@1.2.0:
+    resolution: {integrity: sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==}
+    engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16}
+
+  detect-libc@2.1.2:
+    resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==}
+    engines: {node: '>=8'}
+
+  detect-node-es@1.1.0:
+    resolution: {integrity: sha512-ypdmJU/TbBby2Dxibuv7ZLW3Bs1QEmM7nHjEANfohJLvE0XVujisn1qPJcZxg+qDucsr+bP6fLD1rPS3AhJ7EQ==}
+
+  dunder-proto@1.0.1:
+    resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
+    engines: {node: '>= 0.4'}
+
+  eastasianwidth@0.2.0:
+    resolution: {integrity: sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==}
+
+  ee-first@1.1.1:
+    resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
+
+  electron-to-chromium@1.5.444:
+    resolution: {integrity: sha512-5ss/uJfoDYDHT0lfJzT6FbcskIzROIOPf0BbbFkGcvDzoJU7i//9GDrwwIHQVmIsrAGiF3ihpADBRIsrEFt1rQ==}
+
+  emoji-regex@8.0.0:
+    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}
+
+  emoji-regex@9.2.2:
+    resolution: {integrity: sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==}
+
+  encodeurl@2.0.0:
+    resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==}
+    engines: {node: '>= 0.8'}
+
+  enhanced-resolve@5.26.0:
+    resolution: {integrity: sha512-9vhedylFonb2YGogzUKX6+Ja72gOJbN1QHAqdrvqLwhdl/QWbKopzoUC9EbQNVsAns/bx/4uyqalrQAoy1IByw==}
+    engines: {node: '>=10.13.0'}
+
+  es-define-property@1.0.1:
+    resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==}
+    engines: {node: '>= 0.4'}
+
+  es-errors@1.3.0:
+    resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==}
+    engines: {node: '>= 0.4'}
+
+  es-module-lexer@1.7.0:
+    resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==}
+
+  es-module-lexer@2.3.2:
+    resolution: {integrity: sha512-poHGpORABojJJucnV9KbOavETW8lBVnphkW77ER5/BQ5Fz7oXSoCNek7IH3vR5nRjdsEz926ibFYX8KtLQmdyw==}
+
+  es-module-lexer@3.0.3:
+    resolution: {integrity: sha512-yWGe1O/j+almnV4hOYrmZo8u58JdnmXEMneRQAYkWtqSiT86yoMIEKF4rpqEDj52tbYl3xceBD3DQIBwcsC9Pw==}
+
+  es-object-atoms@1.1.2:
+    resolution: {integrity: sha512-HWcBoN6NileqtSydK2FqHbS/LoDd2pqrnQHLyJzBj4kOp/ky2MWMN694xOfkK8/SnUsW2DH7EfyVlydKCsm1Zw==}
+    engines: {node: '>= 0.4'}
+
+  esbuild@0.21.5:
+    resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==}
+    engines: {node: '>=12'}
+    hasBin: true
+
+  esbuild@0.28.2:
+    resolution: {integrity: sha512-HKVLS8dvII+xoKW9kmqxbRKrnWEXfJJr/FZhhJmiqIB0e053QNYFqOBouTMO/k5sID4MvCiUCvv8b9M4h32wIA==}
+    engines: {node: '>=18'}
+    hasBin: true
+
+  escalade@3.2.0:
+    resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==}
+    engines: {node: '>=6'}
+
+  escape-html@1.0.3:
+    resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==}
+
+  escape-string-regexp@4.0.0:
+    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
+    engines: {node: '>=10'}
+
+  eslint-scope@8.4.0:
+    resolution: {integrity: sha512-sNXOfKCn74rt8RICKMvJS7XKV/Xk9kA7DyJr8mJik3S7Cwgy3qlkkmyS2uQB3jiJg6VNdZd/pDBJu0nvG2NlTg==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  eslint-visitor-keys@3.4.3:
+    resolution: {integrity: sha512-wpc+LXeiyiisxPlEkUzU6svyS1frIO3Mgxj1fdy7Pm8Ygzguax2N3Fa/D/ag1WqbOprdI+uY6wMUl8/a2G+iag==}
+    engines: {node: ^12.22.0 || ^14.17.0 || >=16.0.0}
+
+  eslint-visitor-keys@4.2.1:
+    resolution: {integrity: sha512-Uhdk5sfqcee/9H/rCOJikYz67o0a2Tw2hGRPOG2Y1R2dg7brRe1uG0yaNQDHu+TO/uQPF/5eCapvYSmHUjt7JQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  eslint-visitor-keys@5.0.1:
+    resolution: {integrity: sha512-tD40eHxA35h0PEIZNeIjkHoDR4YjjJp34biM0mDvplBe//mB+IHCqHDGV7pxF+7MklTvighcCPPZC7ynWyjdTA==}
+    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
+
+  eslint@9.39.5:
+    resolution: {integrity: sha512-DgZS62aPLXKlnxILS/AYCoRvHaZeXceIzlXPkkGGzJWSow1aEk0lbTlxUSlyjC8jcaKxAdOnTDz+o1JFSBsyjw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    deprecated: This version is no longer supported. Please see https://eslint.org/version-support for other options.
+    hasBin: true
+    peerDependencies:
+      jiti: '*'
+    peerDependenciesMeta:
+      jiti:
+        optional: true
+
+  espree@10.4.0:
+    resolution: {integrity: sha512-j6PAQ2uUr79PZhBjP5C5fhl8e39FmRnOjsD5lGnWrFU8i2G776tBK7+nP8KuQUTTyAZUwfQqXAgrVH5MbH9CYQ==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+
+  esquery@1.7.0:
+    resolution: {integrity: sha512-Ap6G0WQwcU/LHsvLwON1fAQX9Zp0A2Y6Y/cJBl9r/JbW90Zyg4/zbG6zzKa2OTALELarYHmKu0GhpM5EO+7T0g==}
+    engines: {node: '>=0.10'}
+
+  esrecurse@4.3.0:
+    resolution: {integrity: sha512-KmfKL3b6G+RXvP8N1vr3Tq1kL/oCFgn2NYXEtqP8/L3pKapUA4G8cFVaoF3SU323CD4XypR/ffioHmkti6/Tag==}
+    engines: {node: '>=4.0'}
+
+  estraverse@5.3.0:
+    resolution: {integrity: sha512-MMdARuVEQziNTeJD8DgMqmhwR11BRQ/cBP+pLtYdSTnf3MIO8fFeiINEbX36ZdNlfU/7A9f3gUw49B3oQsvwBA==}
+    engines: {node: '>=4.0'}
+
+  estree-walker@3.0.3:
+    resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==}
+
+  esutils@2.0.3:
+    resolution: {integrity: sha512-kVscqXk4OCp68SZ0dkgEKVi6/8ij300KBWTJq32P/dYeWTSwK41WyTxalN1eRmA5Z9UU/LX9D7FWSmV9SAYx6g==}
+    engines: {node: '>=0.10.0'}
+
+  etag@1.8.1:
+    resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==}
+    engines: {node: '>= 0.6'}
+
+  event-target-shim@5.0.1:
+    resolution: {integrity: sha512-i/2XbnSz/uxRCU6+NdVJgKWDTM427+MqYbkQzD321DuCQJUqOuJKIA0IM2+W2xtYHdKOmZ4dR6fExsd4SXL+WQ==}
+    engines: {node: '>=6'}
+
+  events@3.3.0:
+    resolution: {integrity: sha512-mQw+2fkQbALzQ7V0MY0IqdnXNOeTtP4r0lN9z7AAawCXgqea7bDii20AYrIBrFd/Hx0M2Ocz6S111CaFkUcb0Q==}
+    engines: {node: '>=0.8.x'}
+
+  expect-type@1.4.0:
+    resolution: {integrity: sha512-KfYbmpRm0VbLjEvVa9yGwCi9GI34xvi7A/HXYWQO65CSD2u3MczUJSuwXKFIxlGsgBQizV9q5J9NHj4VG0n+pA==}
+    engines: {node: '>=12.0.0'}
+
+  express@4.22.1:
+    resolution: {integrity: sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==}
+    engines: {node: '>= 0.10.0'}
+
+  extend@3.0.2:
+    resolution: {integrity: sha512-fjquC59cD7CyW6urNXK0FBufkZcoiGG80wTuPujX590cB5Ttln20E2UB4S/WARVqhXffZl2LNgS+gQdPIIim/g==}
+
+  fast-deep-equal@3.1.3:
+    resolution: {integrity: sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==}
+
+  fast-equals@5.4.3:
+    resolution: {integrity: sha512-8unmvA0qrfpFWBYUate9BTGtQdKHWBYt+KdAIkag7Vvxe7wz8Q2nJg7fLMC0bJqe0bjP31kca7Ckaawrs4Istg==}
+    engines: {node: '>=6.0.0'}
+
+  fast-json-stable-stringify@2.1.0:
+    resolution: {integrity: sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==}
+
+  fast-levenshtein@2.0.6:
+    resolution: {integrity: sha512-DCXu6Ifhqcks7TZKY3Hxp3y6qphY5SJZmrWMDrKcERSOXWQdMhU9Ig/PYrzyw/ul9jOIyh0N4M0tbC5hodg8dw==}
+
+  fast-safe-stringify@2.1.1:
+    resolution: {integrity: sha512-W+KJc2dmILlPplD/H4K9l9LcAHAfPtP6BY84uVLXQ6Evcz9Lcg33Y2z1IVblT6xdY54PXYVHEv+0Wpq8Io6zkA==}
+
+  fast-uri@3.1.8:
+    resolution: {integrity: sha512-GZMtZUTNRpOVIECoXwLNZS5xUGE+mVNbTB8h/7Rwh2TFWcBQiPzTgyZi05BF9UMZKkLJv8XBRJTlU7zg8+ZfMg==}
+
+  fdir@6.5.0:
+    resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==}
+    engines: {node: '>=12.0.0'}
+    peerDependencies:
+      picomatch: ^3 || ^4
+    peerDependenciesMeta:
+      picomatch:
+        optional: true
+
+  fetch-blob@3.2.0:
+    resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==}
+    engines: {node: ^12.20 || >= 14.13}
+
+  fflate@0.8.3:
+    resolution: {integrity: sha512-tbZNuJrLwGUp3zshBtdy4W+ORxZuIh8a5ilyIEQDC5rY1f3U20JMry0Ll3WBzU58EZKsEuJFXhb5gwv8CsPvgA==}
+
+  file-entry-cache@8.0.0:
+    resolution: {integrity: sha512-XXTUwCvisa5oacNGRP9SfNtYBNAMi+RPwBFmblZEF7N7swHYQS6/Zfk7SRwx4D5j3CH211YNRco1DEMNVfZCnQ==}
+    engines: {node: '>=16.0.0'}
+
+  file-type@20.4.1:
+    resolution: {integrity: sha512-hw9gNZXUfZ02Jo0uafWLaFVPter5/k2rfcrjFJJHX/77xtSDOfJuEFb6oKlFV86FLP1SuyHMW1PSk0U9M5tKkQ==}
+    engines: {node: '>=18'}
+
+  finalhandler@1.3.2:
+    resolution: {integrity: sha512-aA4RyPcd3badbdABGDuTXCMTtOneUCAYH/gxoYRTZlIJdF0YPWuGqiAsIrhNnnqdXGswYk6dGujem4w80UJFhg==}
+    engines: {node: '>= 0.8'}
+
+  find-up@5.0.0:
+    resolution: {integrity: sha512-78/PXT1wlLLDgTzDs7sjq9hzz0vXD+zn+7wypEe4fXQxCmdmqfGsEPQxmiCSQI3ajFV91bVSsvNtrJRiW6nGng==}
+    engines: {node: '>=10'}
+
+  flat-cache@4.0.1:
+    resolution: {integrity: sha512-f7ccFPK3SXFHpx15UIGyRJ/FJQctuKZ0zVuN3frBo4HnK3cay9VEW0R6yPYFHC0AgqhukPzKjq22t5DmAyqGyw==}
+    engines: {node: '>=16'}
+
+  flatted@3.4.4:
+    resolution: {integrity: sha512-5+ybhBZANEJxaH3X5evAFatUxLfEHSr7n6kYJ+1Qd0mUqr4eu9gIf6GDbWHf8RJijHrjjO8G+la14SlL2SeS1Q==}
+
+  foreground-child@3.3.1:
+    resolution: {integrity: sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==}
+    engines: {node: '>=14'}
+
+  formdata-polyfill@4.0.10:
+    resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==}
+    engines: {node: '>=12.20.0'}
+
+  forwarded-parse@2.1.2:
+    resolution: {integrity: sha512-alTFZZQDKMporBH77856pXgzhEzaUVmLCDk+egLgIgHst3Tpndzz8MnKe+GzRJRfvVdn69HhpW7cmXzvtLvJAw==}
+
+  forwarded@0.2.0:
+    resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==}
+    engines: {node: '>= 0.6'}
+
+  fresh@0.5.2:
+    resolution: {integrity: sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==}
+    engines: {node: '>= 0.6'}
+
+  fs-monkey@1.1.0:
+    resolution: {integrity: sha512-QMUezzXWII9EV5aTFXW1UBVUO77wYPpjqIF8/AviUCThNeSYZykpoTixUeaNNBwmCev0AMDWMAni+f8Hxb1IFw==}
+
+  fsevents@2.3.3:
+    resolution: {integrity: sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==}
+    engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0}
+    os: [darwin]
+
+  function-bind@1.1.2:
+    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}
+
+  gaxios@7.1.3:
+    resolution: {integrity: sha512-YGGyuEdVIjqxkxVH1pUTMY/XtmmsApXrCVv5EU25iX6inEPbV+VakJfLealkBtJN69AQmh1eGOdCl9Sm1UP6XQ==}
+    engines: {node: '>=18'}
+
+  gcp-metadata@8.1.4:
+    resolution: {integrity: sha512-iJ9KMsiu+xKtNRX0PmGLSaIU3bUBAyzWTyqKemKPzNPsmmsBCQYmlNg+brEbES7IHSXtdVwzBPzx1vz3FAaipw==}
+    engines: {node: '>=18'}
+
+  get-caller-file@2.0.5:
+    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
+    engines: {node: 6.* || 8.* || >= 10.*}
+
+  get-intrinsic@1.3.0:
+    resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==}
+    engines: {node: '>= 0.4'}
+
+  get-nonce@1.0.1:
+    resolution: {integrity: sha512-FJhYRoDaiatfEkUK8HKlicmu/3SGFD51q3itKDGoSTysQJBnfOcxU5GxnhE1E6soB76MbT0MBtnKJuXyAx+96Q==}
+    engines: {node: '>=6'}
+
+  get-proto@1.0.1:
+    resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==}
+    engines: {node: '>= 0.4'}
+
+  glob-parent@6.0.2:
+    resolution: {integrity: sha512-XxwI8EOhVQgWp6iDL+3b0r86f4d6AX6zSU55HfB4ydCEuXLXc5FcYeOu+nnGftS4TEju/11rt4KJPTMgbfmv4A==}
+    engines: {node: '>=10.13.0'}
+
+  glob-to-regex.js@1.3.1:
+    resolution: {integrity: sha512-zhWhMRsgnOym+1txhUmYJGD6eUsbUdrZv55gCYKuJX8t2p3+M8My23PD09bEIsreGUs5pnSa/idmcfp2/IlqGg==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  glob@10.5.0:
+    resolution: {integrity: sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==}
+    deprecated: Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me
+    hasBin: true
+
+  globals@14.0.0:
+    resolution: {integrity: sha512-oahGvuMGQlPw/ivIYBjVSrWAfWLBeku5tpPE2fOPLi+WHffIWbuh2tCjhyQhTBPMf5E9jDEH4FOmTYgYwbKwtQ==}
+    engines: {node: '>=18'}
+
+  google-logging-utils@1.1.3:
+    resolution: {integrity: sha512-eAmLkjDjAFCVXg7A1unxHsLf961m6y17QFqXqAXGj/gVkKFrEICfStRfwUlGNfeCEjNRa32JEWOUTlYXPyyKvA==}
+    engines: {node: '>=14'}
+
+  gopd@1.2.0:
+    resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==}
+    engines: {node: '>= 0.4'}
+
+  graceful-fs@4.2.11:
+    resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==}
+
+  has-flag@4.0.0:
+    resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==}
+    engines: {node: '>=8'}
+
+  has-symbols@1.1.0:
+    resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==}
+    engines: {node: '>= 0.4'}
+
+  hasown@2.0.4:
+    resolution: {integrity: sha512-T2UbfbBEF32wiepXIsMlTW9+dDYC6wMh/t/vYA4tuOMKqWz/n3vr1NFSxQiyP+zk2mXsoMA/i/7qV6LKut1t1A==}
+    engines: {node: '>= 0.4'}
+
+  heap-js@2.7.1:
+    resolution: {integrity: sha512-EQfezRg0NCZGNlhlDR3Evrw1FVL2G3LhU7EgPoxufQKruNBSYA8MiRPHeWbU+36o+Fhel0wMwM+sLEiBAlNLJA==}
+    engines: {node: '>=10.0.0'}
+
+  http-errors@2.0.1:
+    resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
+    engines: {node: '>= 0.8'}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
+  hyperdyperid@1.2.0:
+    resolution: {integrity: sha512-Y93lCzHYgGWdrJ66yIktxiaGULYc6oGiABxhcO5AufBeOyoIdZF7bIfLaOrbM0iGIOXQQgxxRrFEnb+Y6w1n4A==}
+    engines: {node: '>=10.18'}
+
+  iconv-lite@0.4.24:
+    resolution: {integrity: sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==}
+    engines: {node: '>=0.10.0'}
+
+  iconv-lite@0.6.3:
+    resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==}
+    engines: {node: '>=0.10.0'}
+
+  ieee754@1.2.1:
+    resolution: {integrity: sha512-dcyqhDvX1C46lXZcVqCpK+FtMRQVdIMN6/Df5js2zouUsqG7I6sFxitIC+7KYK29KdXOLHdu9zL4sFnoVQnqaA==}
+
+  ignore@5.3.2:
+    resolution: {integrity: sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==}
+    engines: {node: '>= 4'}
+
+  ignore@7.0.12:
+    resolution: {integrity: sha512-/8UvqAPU9DGTI9k4mxtf49U37Isfwr8Uts96+SBHIkFxPJnHS0Ew4f00sM4Scd8V8EjM0jUNtVDdv1kPdt35lg==}
+    engines: {node: '>= 4'}
+
+  import-fresh@3.3.1:
+    resolution: {integrity: sha512-TR3KfrTZTYLPB6jUjfx6MF9WcWrHL9su5TObK4ZkYgBdWKPOFoSoQIdEuTuR82pmtxH2spWG9h6etwfr1pLBqQ==}
+    engines: {node: '>=6'}
+
+  import-in-the-middle@3.5.2:
+    resolution: {integrity: sha512-WseIA/4o56+GYO3RmlOPvejYi771OFeJEeK/ejROsr9bdjW+E5NXTOD1Di8TL40Qgg3JJX9aa97Hf8iiSVIKZw==}
+    engines: {node: '>=18'}
+
+  imurmurhash@0.1.4:
+    resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
+    engines: {node: '>=0.8.19'}
+
+  inherits@2.0.4:
+    resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==}
+
+  ipaddr.js@1.9.1:
+    resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==}
+    engines: {node: '>= 0.10'}
+
+  is-extglob@2.1.1:
+    resolution: {integrity: sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==}
+    engines: {node: '>=0.10.0'}
+
+  is-fullwidth-code-point@3.0.0:
+    resolution: {integrity: sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==}
+    engines: {node: '>=8'}
+
+  is-glob@4.0.3:
+    resolution: {integrity: sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==}
+    engines: {node: '>=0.10.0'}
+
+  isexe@2.0.0:
+    resolution: {integrity: sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==}
+
+  iterare@1.2.1:
+    resolution: {integrity: sha512-RKYVTCjAnRthyJes037NX/IiqeidgN1xc3j1RjFfECFp28A1GVwK9nA+i0rJPaHqSZwygLzRnFlzUuHFoWWy+Q==}
+    engines: {node: '>=6'}
+
+  jackspeak@3.4.3:
+    resolution: {integrity: sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==}
+
+  jest-worker@27.5.1:
+    resolution: {integrity: sha512-7vuh85V5cdDofPyxn58nrPjBktZo0u9x1g8WtjQol+jZDaE+fhN+cIvTj11GndBnMnyfrUOG1sZQxCdjKh+DKg==}
+    engines: {node: '>= 10.13.0'}
+
+  jiti@2.7.0:
+    resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
+    hasBin: true
+
+  jose@6.2.12:
+    resolution: {integrity: sha512-9NiFmJEex0sy2Dk58j2UGBSHgUs2ypF9eZSu4L6vjOX3Dp96Sw1F3uL+H+D1sx02jZZdzUT0HgvCy59CuvXcWw==}
+
+  js-tokens@4.0.0:
+    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}
+
+  js-yaml@4.3.2:
+    resolution: {integrity: sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==}
+    hasBin: true
+
+  json-bigint@1.0.0:
+    resolution: {integrity: sha512-SiPv/8VpZuWbvLSMtTDU8hEfrZWg/mH/nV/b4o0CYbSxu1UIQPLdwKOCIyLQX+VIPO5vrLX3i8qtqFyhdPSUSQ==}
+
+  json-buffer@3.0.1:
+    resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}
+
+  json-schema-traverse@0.4.1:
+    resolution: {integrity: sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==}
+
+  json-schema-traverse@1.0.0:
+    resolution: {integrity: sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==}
+
+  json-stable-stringify-without-jsonify@1.0.1:
+    resolution: {integrity: sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==}
+
+  keyv@4.5.4:
+    resolution: {integrity: sha512-oxVHkHR/EJf2CNXnWxRLW6mg7JyCCUcG0DtEGmL2ctUo1PNTin1PUil+r/+4r5MpVgC/fn1kjsx7mjSujKqIpw==}
+
+  levn@0.4.1:
+    resolution: {integrity: sha512-+bT2uH4E5LGE7h/n3evcS/sQlJXCpIp6ym8OWJ5eV6+67Dsql/LaaT7qJBAt2rzfoa/5QBGBhxDix1dMt2kQKQ==}
+    engines: {node: '>= 0.8.0'}
+
+  lightningcss-android-arm64@1.32.0:
+    resolution: {integrity: sha512-YK7/ClTt4kAK0vo6w3X+Pnm0D2cf2vPHbhOXdoNti1Ga0al1P4TBZhwjATvjNwLEBCnKvjJc2jQgHXH0NEwlAg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [android]
+
+  lightningcss-darwin-arm64@1.32.0:
+    resolution: {integrity: sha512-RzeG9Ju5bag2Bv1/lwlVJvBE3q6TtXskdZLLCyfg5pt+HLz9BqlICO7LZM7VHNTTn/5PRhHFBSjk5lc4cmscPQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [darwin]
+
+  lightningcss-darwin-x64@1.32.0:
+    resolution: {integrity: sha512-U+QsBp2m/s2wqpUYT/6wnlagdZbtZdndSmut/NJqlCcMLTWp5muCrID+K5UJ6jqD2BFshejCYXniPDbNh73V8w==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [darwin]
+
+  lightningcss-freebsd-x64@1.32.0:
+    resolution: {integrity: sha512-JCTigedEksZk3tHTTthnMdVfGf61Fky8Ji2E4YjUTEQX14xiy/lTzXnu1vwiZe3bYe0q+SpsSH/CTeDXK6WHig==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [freebsd]
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    resolution: {integrity: sha512-x6rnnpRa2GL0zQOkt6rts3YDPzduLpWvwAF6EMhXFVZXD4tPrBkEFqzGowzCsIWsPjqSK+tyNEODUBXeeVHSkw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm]
+    os: [linux]
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    resolution: {integrity: sha512-0nnMyoyOLRJXfbMOilaSRcLH3Jw5z9HDNGfT/gwCPgaDjnx0i8w7vBzFLFR1f6CMLKF8gVbebmkUN3fa/kQJpQ==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    resolution: {integrity: sha512-UpQkoenr4UJEzgVIYpI80lDFvRmPVg6oqboNHfoH4CQIfNA+HOrZ7Mo7KZP02dC6LjghPQJeBsvXhJod/wnIBg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [linux]
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    resolution: {integrity: sha512-V7Qr52IhZmdKPVr+Vtw8o+WLsQJYCTd8loIfpDaMRWGUZfBOYEJeyJIkqGIDMZPwPx24pUMfwSxxI8phr/MbOA==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-linux-x64-musl@1.32.0:
+    resolution: {integrity: sha512-bYcLp+Vb0awsiXg/80uCRezCYHNg1/l3mt0gzHnWV9XP1W5sKa5/TCdGWaR/zBM2PeF/HbsQv/j2URNOiVuxWg==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [linux]
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    resolution: {integrity: sha512-8SbC8BR40pS6baCM8sbtYDSwEVQd4JlFTOlaD3gWGHfThTcABnNDBda6eTZeqbofalIJhFx0qKzgHJmcPTnGdw==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [arm64]
+    os: [win32]
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    resolution: {integrity: sha512-Amq9B/SoZYdDi1kFrojnoqPLxYhQ4Wo5XiL8EVJrVsB8ARoC1PWW6VGtT0WKCemjy8aC+louJnjS7U18x3b06Q==}
+    engines: {node: '>= 12.0.0'}
+    cpu: [x64]
+    os: [win32]
+
+  lightningcss@1.32.0:
+    resolution: {integrity: sha512-NXYBzinNrblfraPGyrbPoD19C1h9lfI/1mzgWYvXUTe414Gz/X1FD2XBZSZM7rRTrMA8JL3OtAaGifrIKhQ5yQ==}
+    engines: {node: '>= 12.0.0'}
+
+  linkifyjs@4.3.3:
+    resolution: {integrity: sha512-P8aEP5U/D1/IlTY2OeYsErdwh9bGuLE30NcXtKEjgdHcahveQoQwM2yZNsioQHsWFz0P7KKudisbrzCgR0sDHg==}
+
+  locate-path@6.0.0:
+    resolution: {integrity: sha512-iPZK6eYjbxRu3uB4/WZ3EsEIMJFMqAoopl3R+zuq0UjcAm/MO6KCweDgPfP3elTztoKP3KtnVHxTn2NHBSDVUw==}
+    engines: {node: '>=10'}
+
+  lodash.camelcase@4.3.0:
+    resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}
+
+  lodash.merge@4.6.2:
+    resolution: {integrity: sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==}
+
+  long@5.3.2:
+    resolution: {integrity: sha512-mNAgZ1GmyNhD7AuqnTG3/VQ26o760+ZYBPKjPvugO8+nLbYfX6TVpJPseBvopbdY+qpZ/lKUnmEc1LeZYS3QAA==}
+
+  loose-envify@1.4.0:
+    resolution: {integrity: sha512-lyuxPGr/Wfhrlem2CL/UcnUc1zcqKAImBDzukY7Y5F/yQiNdko6+fRLevlw1HgMySw7f611UIY408EtxRSoK3Q==}
+    hasBin: true
+
+  loupe@3.2.1:
+    resolution: {integrity: sha512-CdzqowRJCeLU72bHvWqwRBBlLcMEtIvGrlvef74kMnV2AolS9Y8xUv1I0U/MNAWMhBlKIoyuEgoJ0t/bbwHbLQ==}
+
+  lru-cache@10.4.3:
+    resolution: {integrity: sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==}
+
+  magic-string@0.30.21:
+    resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==}
+
+  math-intrinsics@1.1.0:
+    resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==}
+    engines: {node: '>= 0.4'}
+
+  media-typer@0.3.0:
+    resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==}
+    engines: {node: '>= 0.6'}
+
+  memfs@4.80.0:
+    resolution: {integrity: sha512-N70W2isi44XdGn7uPo9NJ4zRukcdkwSFHlnYx42SWOH/+hzqNc8P7+tVoA2up4z7faHvNi1RSNCFjxoYQ71VPQ==}
+
+  merge-descriptors@1.0.3:
+    resolution: {integrity: sha512-gaNvAS7TZ897/rVaZ0nMtAyxNyi/pdbjbAwUpFQpN70GqnVfOiXpeUUMKRBmzXaSQ8DdTX4/0ms62r2K+hE6mQ==}
+
+  merge-stream@2.0.0:
+    resolution: {integrity: sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==}
+
+  methods@1.1.2:
+    resolution: {integrity: sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==}
+    engines: {node: '>= 0.6'}
+
+  mime-db@1.52.0:
+    resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==}
+    engines: {node: '>= 0.6'}
+
+  mime-db@1.54.0:
+    resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==}
+    engines: {node: '>= 0.6'}
+
+  mime-types@2.1.35:
+    resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==}
+    engines: {node: '>= 0.6'}
+
+  mime@1.6.0:
+    resolution: {integrity: sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==}
+    engines: {node: '>=4'}
+    hasBin: true
+
+  minimatch@10.2.6:
+    resolution: {integrity: sha512-vpLQEs+VLCr1nU0BXS07maYoFwlDAH0gngQuuttxIwutDFEMHq2blX+8vpgxDdK3J1PwjCJiep77OitTZ4Ll1A==}
+    engines: {node: 18 || 20 || >=22}
+
+  minimatch@3.1.5:
+    resolution: {integrity: sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==}
+
+  minimatch@9.0.9:
+    resolution: {integrity: sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
+  minimizer-webpack-plugin@5.13.0:
+    resolution: {integrity: sha512-OO1NF2zHj6sf4CNv2AsUWYcS8WEwkVKQDXxxKzlOxx1Xl+WlqYtVC+oNlGNwGkLAOnpj277BSHypWwRtd9w4JQ==}
+    engines: {node: '>= 10.13.0'}
+    peerDependencies:
+      '@minify-html/node': '*'
+      '@napi-rs/image': '*'
+      '@swc/core': '*'
+      '@swc/css': '*'
+      '@swc/html': '*'
+      clean-css: '*'
+      cssnano: '*'
+      csso: '*'
+      esbuild: '*'
+      html-minifier-terser: '*'
+      imagemin: '*'
+      lightningcss: '*'
+      postcss: '*'
+      sharp: '*'
+      svgo: '*'
+      uglify-js: '*'
+      webpack: ^5.1.0
+    peerDependenciesMeta:
+      '@minify-html/node':
+        optional: true
+      '@napi-rs/image':
+        optional: true
+      '@swc/core':
+        optional: true
+      '@swc/css':
+        optional: true
+      '@swc/html':
+        optional: true
+      clean-css:
+        optional: true
+      cssnano:
+        optional: true
+      csso:
+        optional: true
+      esbuild:
+        optional: true
+      html-minifier-terser:
+        optional: true
+      imagemin:
+        optional: true
+      lightningcss:
+        optional: true
+      postcss:
+        optional: true
+      sharp:
+        optional: true
+      svgo:
+        optional: true
+      uglify-js:
+        optional: true
+
+  minipass@7.1.3:
+    resolution: {integrity: sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==}
+    engines: {node: '>=16 || 14 >=14.17'}
+
+  mkdirp@0.5.6:
+    resolution: {integrity: sha512-FP+p8RB8OWpF3YZBCrP5gtADmtXApB5AMLn+vdyA+PyxCjrCs00mjyUozssO33cwDeT3wNGdLxJ5M//YqtHAJw==}
+    hasBin: true
+
+  module-details-from-path@1.0.4:
+    resolution: {integrity: sha512-EGWKgxALGMgzvxYF1UyGTy0HXX/2vHLkw6+NvDKW2jypWbHpjQuj4UMcqQWXHERJhVGKikolT06G3bcKe4fi7w==}
+
+  ms@2.0.0:
+    resolution: {integrity: sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==}
+
+  ms@2.1.3:
+    resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
+
+  ms@3.0.0-canary.1:
+    resolution: {integrity: sha512-kh8ARjh8rMN7Du2igDRO9QJnqCb2xYTJxyQYK7vJJS4TvLLmsbyhiKpSW+t+y26gyOyMd0riphX0GeWKU3ky5g==}
+    engines: {node: '>=12.13'}
+
+  multer@2.0.2:
+    resolution: {integrity: sha512-u7f2xaZ/UG8oLXHvtF/oWTRvT44p9ecwBBqTwgJVq0+4BW1g8OW01TyMEGWBHbyMOYVHXslaut7qEQ1meATXgw==}
+    engines: {node: '>= 10.16.0'}
+
+  nanoid@3.3.20:
+    resolution: {integrity: sha512-uKdg2G3GNCKQn9byYOpxbGqrT2fGO5KRt5J/8b3pok8rT6qxGWF6hxMyJiEYtAf+FVyYuD9hRaDqX5uPFYJ4ZQ==}
+    engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1}
+    hasBin: true
+
+  natural-compare@1.4.0:
+    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}
+
+  negotiator@0.6.3:
+    resolution: {integrity: sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==}
+    engines: {node: '>= 0.6'}
+
+  next@14.2.35:
+    resolution: {integrity: sha512-KhYd2Hjt/O1/1aZVX3dCwGXM1QmOV4eNM2UTacK5gipDdPN/oHHK/4oVGy7X8GMfPMsUTUEmGlsy0EY1YGAkig==}
+    engines: {node: '>=18.17.0'}
+    hasBin: true
+    peerDependencies:
+      '@opentelemetry/api': ^1.1.0
+      '@playwright/test': ^1.41.2
+      react: ^18.2.0
+      react-dom: ^18.2.0
+      sass: ^1.3.0
+    peerDependenciesMeta:
+      '@opentelemetry/api':
+        optional: true
+      '@playwright/test':
+        optional: true
+      sass:
+        optional: true
+
+  nexus-rpc@0.0.3:
+    resolution: {integrity: sha512-ksIBeYHDv6FHAR1h3Vwk0kQ6REhdo1STqDHXMzu/yn/VN/XzgOor2IUjewG6paoA7IgxlIPZoOU/PD78PC6HTg==}
+    engines: {node: '>= 20.0.0'}
+
+  node-domexception@1.0.0:
+    resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==}
+    engines: {node: '>=10.5.0'}
+    deprecated: Use your platform's native DOMException instead
+
+  node-fetch@2.7.0:
+    resolution: {integrity: sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==}
+    engines: {node: 4.x || >=6.0.0}
+    peerDependencies:
+      encoding: ^0.1.0
+    peerDependenciesMeta:
+      encoding:
+        optional: true
+
+  node-fetch@3.3.2:
+    resolution: {integrity: sha512-dRB78srN/l6gqWulah9SrxeYnxeddIG30+GOqK/9OlLVyLg3HPnr6SqOWTWOXKRwC2eGYCkZ59NNuSgvSrpgOA==}
+    engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0}
+
+  node-releases@2.0.57:
+    resolution: {integrity: sha512-kQK9LGGFiHtrWiNhZtA7Qbw17AQz+dmsEKODRIVTXA9+e5MS/2gZEBhYJt13GrAz5/IOZKddH/0Z3TP/Zgo+yw==}
+    engines: {node: '>=18'}
+
+  object-assign@4.1.1:
+    resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==}
+    engines: {node: '>=0.10.0'}
+
+  object-inspect@1.13.4:
+    resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==}
+    engines: {node: '>= 0.4'}
+
+  on-exit-leak-free@2.1.2:
+    resolution: {integrity: sha512-0eJJY6hXLGf1udHwfNftBqH+g73EU4B504nZeKpz1sYRKafAghwxEJunB2O7rDZkL4PGfsMVnTXZ2EjibbqcsA==}
+    engines: {node: '>=14.0.0'}
+
+  on-finished@2.4.1:
+    resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==}
+    engines: {node: '>= 0.8'}
+
+  optionator@0.9.4:
+    resolution: {integrity: sha512-6IpQ7mKUxRcZNLIObR0hz7lxsapSSIYNZJwXPGeF0mTVqGKFIXj1DQcMoT22S3ROcLyY/rz0PWaWZ9ayWmad9g==}
+    engines: {node: '>= 0.8.0'}
+
+  orderedmap@2.1.1:
+    resolution: {integrity: sha512-TvAWxi0nDe1j/rtMcWcIj94+Ffe6n7zhow33h40SKxmsmozs6dz/e+EajymfoFcHd7sxNn8yHM8839uixMOV6g==}
+
+  p-limit@3.1.0:
+    resolution: {integrity: sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==}
+    engines: {node: '>=10'}
+
+  p-locate@5.0.0:
+    resolution: {integrity: sha512-LaNjtRWUBY++zB5nE/NwcaoMylSPk+S+ZHNB1TzdbMJMny6dynpAGt7X/tl/QYq3TIeE6nxHppbo2LGymrG5Pw==}
+    engines: {node: '>=10'}
+
+  package-json-from-dist@1.0.1:
+    resolution: {integrity: sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==}
+
+  parent-module@1.0.1:
+    resolution: {integrity: sha512-GQ2EWRpQV8/o+Aw8YqtfZZPfNRWZYkbidE9k5rpl/hC3vtHHBfGm2Ifi6qWV+coDGkrUKZAxE3Lot5kcsRlh+g==}
+    engines: {node: '>=6'}
+
+  parseurl@1.3.3:
+    resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==}
+    engines: {node: '>= 0.8'}
+
+  path-exists@4.0.0:
+    resolution: {integrity: sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==}
+    engines: {node: '>=8'}
+
+  path-key@3.1.1:
+    resolution: {integrity: sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==}
+    engines: {node: '>=8'}
+
+  path-scurry@1.11.1:
+    resolution: {integrity: sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==}
+    engines: {node: '>=16 || 14 >=14.18'}
+
+  path-to-regexp@0.1.13:
+    resolution: {integrity: sha512-A/AGNMFN3c8bOlvV9RreMdrv7jsmF9XIfDeCd87+I8RNg6s78BhJxMu69NEMHBSJFxKidViTEdruRwEk/WIKqA==}
+
+  path-to-regexp@3.3.0:
+    resolution: {integrity: sha512-qyCH421YQPS2WFDxDjftfc1ZR5WKQzVzqsp4n9M2kQhVOo/ByahFoUNJfl58kOcEGfQ//7weFTDhm+ss8Ecxgw==}
+
+  pathe@1.1.2:
+    resolution: {integrity: sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==}
+
+  pathval@2.0.1:
+    resolution: {integrity: sha512-//nshmD55c46FuFw26xV/xFAaB5HF9Xdap7HJBBnrKdAd6/GxDBaNA1870O79+9ueg61cZLSVc+OaFlfmObYVQ==}
+    engines: {node: '>= 14.16'}
+
+  pg-cloudflare@1.4.1:
+    resolution: {integrity: sha512-6PQbsFWZcp9EmJEwy5cGQ2La+AMWpP46lgbb8X+U/XsHIUweYDNCpeuKck5RxL2MdVFi7krbbEi5nX4Zh7JhrQ==}
+
+  pg-connection-string@2.14.1:
+    resolution: {integrity: sha512-qR3kGNPBLpCNtz0evbKA0Y/MRFXwSSdT+pTJvYp/bXTcReZbvX1kzF0IyTc1QnxqF7AZbOeBhNL8R5mYQZV/MA==}
+
+  pg-int8@1.0.1:
+    resolution: {integrity: sha512-WCtabS6t3c8SkpDBUlb1kjOs7l66xsGdKpIPZsg4wR+B3+u9UAum2odSsF9tnvxg80h4ZxLWMy4pRjOsFIqQpw==}
+    engines: {node: '>=4.0.0'}
+
+  pg-pool@3.14.0:
+    resolution: {integrity: sha512-gKtPkFdQPU3DksooVLi9LsjZxrsBUZIpa+7aVx+LV5pNh0KzP4Zleud2po+ConrxbuXGBJ6Hfer6hdgpIBpBaw==}
+    peerDependencies:
+      pg: '>=8.0'
+
+  pg-protocol@1.16.1:
+    resolution: {integrity: sha512-p9VOFMiHB/ZbJATetbg+99PxssTVSQRnyuPSQ67mN1+1KBOjZaZ83ZQzltnxPhJwSsC3nwVjJ10DVJlerbFzLg==}
+
+  pg-types@2.2.0:
+    resolution: {integrity: sha512-qTAAlrEsl8s4OiEQY69wDvcMIdQN6wdz5ojQiOy6YRMuynxenON0O5oCpJI6lshc6scgAY8qvJ2On/p+CXY0GA==}
+    engines: {node: '>=4'}
+
+  pg@8.23.1:
+    resolution: {integrity: sha512-aL96AHANtWjPLDOLqnhx+ngp9+UK7ETEU8VJrDCGvsSSi/mGLcWYsS6Herg7lmaBJe4uwrfqsa7gTEFaSizDoQ==}
+    engines: {node: '>= 16.0.0'}
+    peerDependencies:
+      pg-native: '>=3.0.1'
+    peerDependenciesMeta:
+      pg-native:
+        optional: true
+
+  pgpass@1.0.5:
+    resolution: {integrity: sha512-FdW9r/jQZhSeohs1Z3sI1yxFQNFvMcnmfuj4WBMUTxOrAyLMaTcE1aAMBiTlbMNaXvBCQuVi0R7hd8udDSP7ug==}
+
+  picocolors@1.1.1:
+    resolution: {integrity: sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==}
+
+  picomatch@4.0.7:
+    resolution: {integrity: sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==}
+    engines: {node: '>=12'}
+
+  pino-abstract-transport@2.0.0:
+    resolution: {integrity: sha512-F63x5tizV6WCh4R6RHyi2Ml+M70DNRXt/+HANowMflpgGFMAym/VKm6G7ZOQRjqN7XbGxK1Lg9t6ZrtzOaivMw==}
+
+  pino-std-serializers@7.1.0:
+    resolution: {integrity: sha512-BndPH67/JxGExRgiX1dX0w1FvZck5Wa4aal9198SrRhZjH3GxKQUKIBnYJTdj2HDN3UQAS06HlfcSbQj2OHmaw==}
+
+  pino@9.14.0:
+    resolution: {integrity: sha512-8OEwKp5juEvb/MjpIc4hjqfgCNysrS94RIOMXYvpYCdm/jglrKEiAYmiumbmGhCvs+IcInsphYDFwqrjr7398w==}
+    hasBin: true
+
+  playwright-core@1.63.0:
+    resolution: {integrity: sha512-rYCsBF/M5HjUch52bbtVONEFjv6Xu8sm8h72dNlR5bzIE1fvC/bxgspzkjSfU+MweEMmPM8KJebG6nnyxo5mCg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  playwright@1.63.0:
+    resolution: {integrity: sha512-+7ziBLidS4NaNCdt57SUDT+wYmmd5fmiQejUic/kb+YsYSCPyOOE9sebzMjNmQrsnNpDJqd4WHvV/8lfKfUDUg==}
+    engines: {node: '>=20'}
+    hasBin: true
+
+  postcss@8.4.31:
+    resolution: {integrity: sha512-PS08Iboia9mts/2ygV3eLpY5ghnUcfLV/EXTOW1E2qYxJKGGBUtNjN76FYHnMs36RmARn41bC0AZmn+rR0OVpQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  postcss@8.5.29:
+    resolution: {integrity: sha512-49cGhUbXj8Qenv0iTMxA1cFBzxXoctpC9Ujd77t1WcbJIr6nF/eI7g/8MgxrYldFRuAXvja7xQRwavoW7kgrxQ==}
+    engines: {node: ^10 || ^12 || >=14}
+
+  postgres-array@2.0.0:
+    resolution: {integrity: sha512-VpZrUqU5A69eQyW2c5CA1jtLecCsN2U/bD6VilrFDWq5+5UIEVO7nazS3TEcHf1zuPYO/sqGvUvW62g86RXZuA==}
+    engines: {node: '>=4'}
+
+  postgres-bytea@1.0.1:
+    resolution: {integrity: sha512-5+5HqXnsZPE65IJZSMkZtURARZelel2oXUEO8rH83VS/hxH5vv1uHquPg5wZs8yMAfdv971IU+kcPUczi7NVBQ==}
+    engines: {node: '>=0.10.0'}
+
+  postgres-date@1.0.7:
+    resolution: {integrity: sha512-suDmjLVQg78nMK2UZ454hAG+OAW+HQPZ6n++TNDUX+L0+uUlLywnoxJKDou51Zm+zTCjrCl0Nq6J9C5hP9vK/Q==}
+    engines: {node: '>=0.10.0'}
+
+  postgres-interval@1.2.0:
+    resolution: {integrity: sha512-9ZhXKM/rw350N1ovuWHbGxnGh/SNJ4cnxHiM0rxE4VN41wsg8P8zWn9hv/buK00RP4WvlOyr/RBDiptyxVbkZQ==}
+    engines: {node: '>=0.10.0'}
+
+  prelude-ls@1.2.1:
+    resolution: {integrity: sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==}
+    engines: {node: '>= 0.8.0'}
+
+  process-warning@5.1.0:
+    resolution: {integrity: sha512-jQSaVHsPgtyw60e1rQ/A+/ArPEj/S8pS/vFnyGa/gYFXrKk/6RuDkoqVDQ5NI5MmS01698ltlAk0NoDBNLujRw==}
+
+  prosemirror-changeset@2.4.4:
+    resolution: {integrity: sha512-Gyuz9jYdrAeA9I7AholyOes9KUmv/lEwsC5O9s5xF5VB3EgTPsXMGUxz4+H1B+wKVPdZbvRcg1Cp3x8qX+8ofA==}
+
+  prosemirror-commands@1.7.2:
+    resolution: {integrity: sha512-q6Q6szxqdu9Xd6EcdKsqXghu5nQdZTpB4Q9yd04WRc7/jt763e/rT60Owh0L1GYY+T46o5rD+9lEN36dZS43tw==}
+
+  prosemirror-dropcursor@1.8.4:
+    resolution: {integrity: sha512-VmKxhcA6a+h5oPSYmfF1ZNeQqPbyYaIxqZsKqeYCyTlPtrjUgNaHL3P8vVaO19oqAV0zuaM/axkowZHrB1P3Tg==}
+
+  prosemirror-gapcursor@1.4.1:
+    resolution: {integrity: sha512-pMdYaEnjNMSwl11yjEGtgTmLkR08m/Vl+Jj443167p9eB3HVQKhYCc4gmHVDsLPODfZfjr/MmirsdyZziXbQKw==}
+
+  prosemirror-history@1.5.1:
+    resolution: {integrity: sha512-onlwnqKvgtFg6srZOmDOAhlAy1FIHQpOExORybX0S+DvJepE5tPALrB9iGet/2sqqqrelSnB10OoiOJqAvu2DA==}
+
+  prosemirror-inputrules@1.5.1:
+    resolution: {integrity: sha512-7wj4uMjKaXWAQ1CDgxNzNtR9AlsuwzHfdFH1ygEHA2KHF2DOEaXl1CJfNPAKCg9qNEh4rum975QLaCiQPyY6Fw==}
+
+  prosemirror-keymap@1.2.3:
+    resolution: {integrity: sha512-4HucRlpiLd1IPQQXNqeo81BGtkY8Ai5smHhKW9jjPKRc2wQIxksg7Hl1tTI2IfT2B/LgX6bfYvXxEpJl7aKYKw==}
+
+  prosemirror-model@1.25.12:
+    resolution: {integrity: sha512-Ue2gTmXMa7EhpLNhC7J+h4+ykD8ha12K6rrZFFKKJHBForfIStw5gJ6Zrf1mqqAa9NmpmEB4wp9bKmA4eUVjWg==}
+
+  prosemirror-schema-list@1.5.1:
+    resolution: {integrity: sha512-927lFx/uwyQaGwJxLWCZRkjXG0p48KpMj6ueoYiu4JX05GGuGcgzAy62dfiV8eFZftgyBUvLx76RsMe20fJl+Q==}
+
+  prosemirror-state@1.4.4:
+    resolution: {integrity: sha512-6jiYHH2CIGbCfnxdHbXZ12gySFY/fz/ulZE333G6bPqIZ4F+TXo9ifiR86nAHpWnfoNjOb3o5ESi7J8Uz1jXHw==}
+
+  prosemirror-tables@1.8.5:
+    resolution: {integrity: sha512-V/0cDCsHKHe/tfWkeCmthNUcEp1IVO3p6vwN8XtwE9PZQLAZJigbw3QoraAdfJPir4NKJtNvOB8oYGKRl+t0Dw==}
+
+  prosemirror-transform@1.12.2:
+    resolution: {integrity: sha512-PE/aY0HEY4zczvmqrilgkUK/WautF0chvMqkmM/iN5/aPHvwrCWaQZjS6CIZp+K84YrvPFqrL+YArrfJX8xX7g==}
+
+  prosemirror-view@1.42.6:
+    resolution: {integrity: sha512-3g25f6hKV2bBxo3puH3EcYWmmVNSH0iWmNsMVT7sugDSpA025jgpOLarcDWr39SdzPjYMaiYtRdNtXialPSjEQ==}
+
+  protobufjs@7.6.6:
+    resolution: {integrity: sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==}
+    engines: {node: '>=12.0.0'}
+
+  protobufjs@8.8.0:
+    resolution: {integrity: sha512-N3xhQ5yyBx3vQq4gubBfASzYhJGNzeDbjqBpu61g7UVylsN/qyffU96TKWD3GbbLOKF82VGNRNvv1+BFgE31Eg==}
+    engines: {node: '>=12.0.0'}
+
+  proxy-addr@2.0.8:
+    resolution: {integrity: sha512-5nnx0yGyVUcY6t9RnWcARWtwT9F1D8O9rt08htPvnd49W1IgZtmLkhu9WfMzQj1cFxjHIO6connUNVW5k7AVyQ==}
+    engines: {node: '>= 0.10'}
+
+  punycode@2.3.1:
+    resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==}
+    engines: {node: '>=6'}
+
+  qs@6.14.2:
+    resolution: {integrity: sha512-V/yCWTTF7VJ9hIh18Ugr2zhJMP01MY7c5kh4J870L7imm6/DIzBsNLTXzMwUA3yZ5b/KBqLx8Kp3uRvd7xSe3Q==}
+    engines: {node: '>=0.6'}
+
+  quick-format-unescaped@4.0.4:
+    resolution: {integrity: sha512-tYC1Q1hgyRuHgloV/YXs2w15unPVh8qfu/qCTfhTYamaw7fyhumKa2yGpdSo87vY32rIclj+4fWYQXUMs9EHvg==}
+
+  range-parser@1.2.1:
+    resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==}
+    engines: {node: '>= 0.6'}
+
+  raw-body@2.5.3:
+    resolution: {integrity: sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA==}
+    engines: {node: '>= 0.8'}
+
+  react-dom@18.3.1:
+    resolution: {integrity: sha512-5m4nQKp+rZRb09LNH59GM4BxTh9251/ylbKIbpe7TpGxfJ+9kv6BLkLBXIjjspbgbnIBNqlI23tRnTWT0snUIw==}
+    peerDependencies:
+      react: ^18.3.1
+
+  react-remove-scroll-bar@2.3.8:
+    resolution: {integrity: sha512-9r+yi9+mgU33AKcj6IbT9oRCO78WriSj6t/cF8DWBZJ9aOGPOTEDvdUDz1FwKim7QXWwmHqtdHnRJfhAxEG46Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-remove-scroll@2.7.2:
+    resolution: {integrity: sha512-Iqb9NjCCTt6Hf+vOdNIZGdTiH1QSqr27H/Ek9sv/a97gfueI/5h1s3yRi1nngzMUaOOToin5dI1dXKdXiF+u0Q==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react-style-singleton@2.2.3:
+    resolution: {integrity: sha512-b6jSvxvVnyptAiLjbkWLE/lOnR4lfTtDAl+eUC7RZy+QQWc6wRzIV2CE6xBuMmDxc2qIihtDCZD5NPOFl7fRBQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  react@18.3.1:
+    resolution: {integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==}
+    engines: {node: '>=0.10.0'}
+
+  readable-stream@3.6.2:
+    resolution: {integrity: sha512-9u/sniCrY3D5WdsERHzHE4G2YCXqoG5FTHUiCC4SIbr6XcLZBY05ya9EKjYek9O5xOAwjGq+1JdGBAS7Q9ScoA==}
+    engines: {node: '>= 6'}
+
+  real-require@0.2.0:
+    resolution: {integrity: sha512-57frrGM/OCTLqLOAh0mhVA9VBMHd+9U7Zb2THMGdBUoZVOtGbJzjxsYGDJ3A9AYYCP4hn6y1TVbaOfzWtm5GFg==}
+    engines: {node: '>= 12.13.0'}
+
+  reflect-metadata@0.2.2:
+    resolution: {integrity: sha512-urBwgfrvVP/eAyXx4hluJivBKzuEbSQs9rKWCrCkbSxNv8mxPcUZKeuoF3Uy4mJl3Lwprp6yy5/39VWigZ4K6Q==}
+
+  require-directory@2.1.1:
+    resolution: {integrity: sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==}
+    engines: {node: '>=0.10.0'}
+
+  require-from-string@2.0.2:
+    resolution: {integrity: sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==}
+    engines: {node: '>=0.10.0'}
+
+  require-in-the-middle@8.0.1:
+    resolution: {integrity: sha512-QT7FVMXfWOYFbeRBF6nu+I6tr2Tf3u0q8RIEjNob/heKY/nh7drD/k7eeMFmSQgnTtCzLDcCu/XEnpW2wk4xCQ==}
+    engines: {node: '>=9.3.0 || >=8.10.0 <9.0.0'}
+
+  resolve-from@4.0.0:
+    resolution: {integrity: sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==}
+    engines: {node: '>=4'}
+
+  rimraf@5.0.10:
+    resolution: {integrity: sha512-l0OE8wL34P4nJH/H2ffoaniAokM2qSmrtXHmlpvYr5AVVX8msAyW0l8NVJFDxlSK4u3Uh/f41cQheDVdnYijwQ==}
+    hasBin: true
+
+  rollup@4.64.0:
+    resolution: {integrity: sha512-gjA/kFeDfffII8COoPsvLPvE16hWDTEc1+0QKQNKUkuV8iJjqsC4xXs8/FzuL0v9EV39kuxTbAgcFoTRyy2TGQ==}
+    engines: {node: '>=18.0.0', npm: '>=8.0.0'}
+    hasBin: true
+
+  rope-sequence@1.3.4:
+    resolution: {integrity: sha512-UT5EDe2cu2E/6O4igUr5PSFs23nvvukicWHx6GnOPlHAiiYbzNuCRQCuiUdHJQcqKalLKlrYJnjY0ySGsXNQXQ==}
+
+  rxjs@7.8.2:
+    resolution: {integrity: sha512-dhKf903U/PQZY6boNNtAGdWbG85WAbjT/1xYoZIC7FAY0yWapOBQVsVrDl58W86//e1VpMNBtRV4MaXfdMySFA==}
+
+  safe-buffer@5.2.1:
+    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
+
+  safe-stable-stringify@2.5.0:
+    resolution: {integrity: sha512-b3rppTKm9T+PsVCBEOUR46GWI7fdOs00VKZ1+9c1EWDaDMvjQc6tUwuFyIprgGgTcWoVHSKrU8H31ZHA2e0RHA==}
+    engines: {node: '>=10'}
+
+  safer-buffer@2.1.2:
+    resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
+
+  scheduler@0.23.2:
+    resolution: {integrity: sha512-UOShsPwz7NrMUqhR6t0hWjFduvOzbtv7toDH1/hIrfRNIDBnnBWd0CwJTGvTpngVlmwGCdP9/Zl/tVrDqcuYzQ==}
+
+  schema-utils@4.5.0:
+    resolution: {integrity: sha512-zJlMCZ0cAR5p/Y4oVpRoqioDMJcGxaXRrQ/4rP4WyR84vc5z/DolXdbvXeDpTwbtocDFr2rhPqHPErDCUtz2kA==}
+    engines: {node: '>= 10.13.0'}
+
+  semver@7.8.5:
+    resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  send@0.19.2:
+    resolution: {integrity: sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==}
+    engines: {node: '>= 0.8.0'}
+
+  serve-static@1.16.3:
+    resolution: {integrity: sha512-x0RTqQel6g5SY7Lg6ZreMmsOzncHFU7nhnRWkKgWuMTu5NN0DR5oruckMqRvacAN9d5w6ARnRBXl9xhDCgfMeA==}
+    engines: {node: '>= 0.8.0'}
+
+  setprototypeof@1.2.0:
+    resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==}
+
+  shebang-command@2.0.0:
+    resolution: {integrity: sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==}
+    engines: {node: '>=8'}
+
+  shebang-regex@3.0.0:
+    resolution: {integrity: sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==}
+    engines: {node: '>=8'}
+
+  side-channel-list@1.0.1:
+    resolution: {integrity: sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-map@1.0.1:
+    resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==}
+    engines: {node: '>= 0.4'}
+
+  side-channel-weakmap@1.0.2:
+    resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==}
+    engines: {node: '>= 0.4'}
+
+  side-channel@1.1.1:
+    resolution: {integrity: sha512-6x6dK6zJdpTzF4sQeNYxwtvBzf6Eg4GtlesS94HOvTudUeyK2WXAaIfmDgsyslYrRBeFIlsi54AYsFGUuhmvrQ==}
+    engines: {node: '>= 0.4'}
+
+  siginfo@2.0.0:
+    resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==}
+
+  signal-exit@4.1.0:
+    resolution: {integrity: sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==}
+    engines: {node: '>=14'}
+
+  sonic-boom@4.2.1:
+    resolution: {integrity: sha512-w6AxtubXa2wTXAUsZMMWERrsIRAdrK0Sc+FUytWvYAhBJLyuI4llrMIC1DtlNSdI99EI86KZum2MMq3EAZlF9Q==}
+
+  source-map-js@1.2.2:
+    resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==}
+    engines: {node: '>=0.10.0'}
+
+  source-map-loader@5.0.0:
+    resolution: {integrity: sha512-k2Dur7CbSLcAH73sBcIkV5xjPV4SzqO1NJ7+XaQl8if3VODDUj3FNchNGpqgJSKbvUfJuhVdv8K2Eu8/TNl2eA==}
+    engines: {node: '>= 18.12.0'}
+    peerDependencies:
+      webpack: ^5.72.1
+
+  source-map-support@0.5.21:
+    resolution: {integrity: sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==}
+
+  source-map@0.6.1:
+    resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==}
+    engines: {node: '>=0.10.0'}
+
+  source-map@0.7.6:
+    resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==}
+    engines: {node: '>= 12'}
+
+  split2@4.2.0:
+    resolution: {integrity: sha512-UcjcJOWknrNkF6PLX83qcHM6KHgVKNkV62Y8a5uYDVv9ydGQVwAHMKqHdJje1VTWpljG0WYpCDhrCdAOYH4TWg==}
+    engines: {node: '>= 10.x'}
+
+  stackback@0.0.2:
+    resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}
+
+  statuses@2.0.2:
+    resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}
+    engines: {node: '>= 0.8'}
+
+  std-env@3.10.0:
+    resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==}
+
+  streamsearch@1.1.0:
+    resolution: {integrity: sha512-Mcc5wHehp9aXz1ax6bZUyY5afg9u2rv5cqQI3mRrYkGC8rW2hM02jWuwjtL++LS5qinSyhj2QfLyNsuc+VsExg==}
+    engines: {node: '>=10.0.0'}
+
+  string-width@4.2.3:
+    resolution: {integrity: sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==}
+    engines: {node: '>=8'}
+
+  string-width@5.1.2:
+    resolution: {integrity: sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==}
+    engines: {node: '>=12'}
+
+  string_decoder@1.3.0:
+    resolution: {integrity: sha512-hkRX8U1WjJFd8LsDJ2yQ/wWWxaopEsABU1XfkM8A+j0+85JAGppt16cr1Whg6KIbb4okU6Mql6BOj+uup/wKeA==}
+
+  strip-ansi@6.0.1:
+    resolution: {integrity: sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==}
+    engines: {node: '>=8'}
+
+  strip-ansi@7.2.0:
+    resolution: {integrity: sha512-yDPMNjp4WyfYBkHnjIRLfca1i6KMyGCtsVgoKe/z1+6vukgaENdgGBZt+ZmKPc4gavvEZ5OgHfHdrazhgNyG7w==}
+    engines: {node: '>=12'}
+
+  strip-json-comments@3.1.1:
+    resolution: {integrity: sha512-6fPc+R4ihwqP6N/aIv2f1gMH8lOVtWQHoqC4yK6oSDVVocumAsfCqjkXnqiYMhmMwS/mEHLp7Vehlt3ql6lEig==}
+    engines: {node: '>=8'}
+
+  strtok3@10.3.5:
+    resolution: {integrity: sha512-ki4hZQfh5rX0QDLLkOCj+h+CVNkqmp/CMf8v8kZpkNVK6jGQooMytqzLZYUVYIZcFZ6yDB70EfD8POcFXiF5oA==}
+    engines: {node: '>=18'}
+
+  styled-jsx@5.1.1:
+    resolution: {integrity: sha512-pW7uC1l4mBZ8ugbiZrcIsiIvVx1UmTfw7UkC3Um2tmfUq9Bhk8IiyEIPl6F8agHgjzku6j0xQEZbfA5uSgSaCw==}
+    engines: {node: '>= 12.0.0'}
+    peerDependencies:
+      '@babel/core': '*'
+      babel-plugin-macros: '*'
+      react: '>= 16.8.0 || 17.x.x || ^18.0.0-0'
+    peerDependenciesMeta:
+      '@babel/core':
+        optional: true
+      babel-plugin-macros:
+        optional: true
+
+  supports-color@7.2.0:
+    resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==}
+    engines: {node: '>=8'}
+
+  supports-color@8.1.1:
+    resolution: {integrity: sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==}
+    engines: {node: '>=10'}
+
+  swc-loader@0.2.7:
+    resolution: {integrity: sha512-nwYWw3Fh9ame3Rtm7StS9SBLpHRRnYcK7bnpF3UKZmesAK0gw2/ADvlURFAINmPvKtDLzp+GBiP9yLoEjg6S9w==}
+    peerDependencies:
+      '@swc/core': ^1.2.147
+      webpack: '>=2'
+
+  systeminformation@5.33.15:
+    resolution: {integrity: sha512-s5RloL0F7xhN0ZjfHtLGnbf7EW74EI0N8NFL+1xR7Oxz9QA33obNZsl7lyfnJOhN04E/kGFPoJPlvY7TZ5fzmw==}
+    engines: {node: '>=10.0.0'}
+    os: [darwin, linux, win32, freebsd, openbsd, netbsd, sunos, android]
+    hasBin: true
+
+  tailwindcss@4.3.3:
+    resolution: {integrity: sha512-gOhV3P7ufE62QDGg1zVaTgCR+EtPv92k2nIhVcVKcLmxT1sUBsQGhnZj175j+MqRt4zLF7ic+sCYjfhxMxj7YQ==}
+
+  tapable@2.3.3:
+    resolution: {integrity: sha512-uxc/zpqFg6x7C8vOE7lh6Lbda8eEL9zmVm/PLeTPBRhh1xCgdWaQ+J1CUieGpIfm2HdtsUpRv+HshiasBMcc6A==}
+    engines: {node: '>=6'}
+
+  terser@5.51.2:
+    resolution: {integrity: sha512-bWnjSNscmuI+GJze6ZupnHP8G/cTcsJF+bXCeQknk2SHQsgbNJnLrqiH9jZ2W4STPVXH2mDKKRX3iwPhc9Cn/Q==}
+    engines: {node: '>=10'}
+    hasBin: true
+
+  thingies@2.6.1:
+    resolution: {integrity: sha512-cV/CMGTK3M4MlnJ/0At6ismOw/A0EEniDNScajjz/Br3c1sqE72YD01rGpPTKwd27wAxI5Pr+6+0w8yofzFRYw==}
+    engines: {node: '>=10.18'}
+    peerDependencies:
+      tslib: ^2
+
+  thread-stream@3.2.0:
+    resolution: {integrity: sha512-zLBvqpwr4Esa0kRjcrzGU6zL25lePWaCLMx0RQFrmteozIfeNdaMLpG5U7PeHzvlFkAWaRKA9/KVW4F60iB+qw==}
+
+  tinybench@2.9.0:
+    resolution: {integrity: sha512-0+DUvqWMValLmha6lr4kD8iAMK1HzV0/aKnCtWb9v9641TnP/MFb7Pc2bxoxQjTXAErryXVgUOfv2YqNllqGeg==}
+
+  tinyexec@0.3.2:
+    resolution: {integrity: sha512-KQQR9yN7R5+OSwaK0XQoj22pwHoTlgYqmUscPYoknOoWCWfj/5/ABTMRi69FrKU5ffPVh5QcFikpWJI/P1ocHA==}
+
+  tinyglobby@0.2.17:
+    resolution: {integrity: sha512-wXR/dYpcqKmfWpEdZjiKJOwCNFndD0DMnrW/cYjVGttEkBfVgcLFHoNrlj47mjOVic9yyNu65alsgF4NQyTa2g==}
+    engines: {node: '>=12.0.0'}
+
+  tinypool@1.1.1:
+    resolution: {integrity: sha512-Zba82s87IFq9A9XmjiX5uZA/ARWDrB03OHlq+Vw1fSdt0I+4/Kutwy8BP4Y/y/aORMo61FQ0vIb5j44vSo5Pkg==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+
+  tinyrainbow@1.2.0:
+    resolution: {integrity: sha512-weEDEq7Z5eTHPDh4xjX789+fHfF+P8boiFB+0vbWzpbnbsEr/GRaohi/uMKxg8RZMXnl1ItAi/IUHWMsjDV7kQ==}
+    engines: {node: '>=14.0.0'}
+
+  tinyspy@3.0.2:
+    resolution: {integrity: sha512-n1cw8k1k0x4pgA2+9XrOkFydTerNcJ1zWCO5Nn9scWHTD+5tp8dghT2x1uduQePZTZgd3Tupf+x9BxJjeJi77Q==}
+    engines: {node: '>=14.0.0'}
+
+  toidentifier@1.0.1:
+    resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==}
+    engines: {node: '>=0.6'}
+
+  token-types@6.1.2:
+    resolution: {integrity: sha512-dRXchy+C0IgK8WPC6xvCHFRIWYUbqqdEIKPaKo/AcTUNzwLTK6AH7RjdLWsEZcAN/TBdtfUw3PYEgPr5VPr6ww==}
+    engines: {node: '>=14.16'}
+
+  tr46@0.0.3:
+    resolution: {integrity: sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==}
+
+  tree-dump@1.1.0:
+    resolution: {integrity: sha512-rMuvhU4MCDbcbnleZTFezWsaZXRFemSqAM+7jPnzUl1fo9w3YEKOxAeui0fz3OI4EU4hf23iyA7uQRVko+UaBA==}
+    engines: {node: '>=10.0'}
+    peerDependencies:
+      tslib: '2'
+
+  ts-api-utils@2.5.0:
+    resolution: {integrity: sha512-OJ/ibxhPlqrMM0UiNHJ/0CKQkoKF243/AEmplt3qpRgkW8VG7IfOS41h7V8TjITqdByHzrjcS/2si+y4lIh8NA==}
+    engines: {node: '>=18.12'}
+    peerDependencies:
+      typescript: '>=4.8.4'
+
+  tslib@2.8.1:
+    resolution: {integrity: sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==}
+
+  tsx@4.23.15:
+    resolution: {integrity: sha512-Yiex1Ovn8z2xPpOWckIiysV1SSyRMY9BkLF++q0yKiDxCqRhosKfMg3janKkiLBwZ5c/YryloKwGZcrEmtwxKw==}
+    engines: {node: '>=18.0.0'}
+    hasBin: true
+
+  turbo@2.11.7:
+    resolution: {integrity: sha512-RhXHbqfvY6o3xt/zSHCwSNwLrZlXiqHzewi4eAj9PtZ1T1CqgMJ2yIDb7SKPTG9IikTm925mfzL6hldQVdyNWw==}
+    hasBin: true
+
+  type-check@0.4.0:
+    resolution: {integrity: sha512-XleUoc9uwGXqjWwXaUTZAmzMcFZ5858QA2vvx1Ur5xIcixXIP+8LnFDgRplU30us6teqdlskFfu+ae4K79Ooew==}
+    engines: {node: '>= 0.8.0'}
+
+  type-is@1.6.18:
+    resolution: {integrity: sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==}
+    engines: {node: '>= 0.6'}
+
+  typedarray@0.0.6:
+    resolution: {integrity: sha512-/aCDEGatGvZ2BIk+HmLf4ifCJFwvKFNb9/JeZPMulfgFracn9QFcAf5GO8B/mweUjSoblS5In0cWhqpfs/5PQA==}
+
+  typescript-eslint@8.71.0:
+    resolution: {integrity: sha512-fBdHYiqQ14RW6mOMXD14Svn82ZsCYAoQSzGRzyEjR59S5A2Krh/l7fGTOQ7iCr8gGy/mHVXtEF7s5fgjEdV0Pw==}
+    engines: {node: ^18.18.0 || ^20.9.0 || >=21.1.0}
+    peerDependencies:
+      eslint: ^8.57.0 || ^9.0.0 || ^10.0.0
+      typescript: '>=4.8.4 <6.1.0'
+
+  typescript@5.9.3:
+    resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==}
+    engines: {node: '>=14.17'}
+    hasBin: true
+
+  uid@2.0.2:
+    resolution: {integrity: sha512-u3xV3X7uzvi5b1MncmZo3i2Aw222Zk1keqLA1YkHldREkAhAqi65wuPfe7lHx8H/Wzy+8CE7S7uS3jekIM5s8g==}
+    engines: {node: '>=8'}
+
+  uint8array-extras@1.6.0:
+    resolution: {integrity: sha512-8iAasVS4wUx0gPLjH8Xtz2PeDzTSiy8QiLGu2DT3X5GU+egFEQhpnbtkehbAwjvDcxIERmCYcysiODFmE3Ud0Q==}
+    engines: {node: '>=18'}
+
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
+  unionfs@4.6.0:
+    resolution: {integrity: sha512-fJAy3gTHjFi5S3TP5EGdjs/OUMFFvI/ady3T8qVuZfkv8Qi8prV/Q8BuFEgODJslhZTT2z2qdD2lGdee9qjEnA==}
+
+  unpipe@1.0.0:
+    resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==}
+    engines: {node: '>= 0.8'}
+
+  update-browserslist-db@1.3.3:
+    resolution: {integrity: sha512-pJ2sYawQS0R/WI928Gj5GlPhTGzbMelq0+4INtSYNDV9ErKJcX6xjGWkoG/VnB3dpUm00zALaqkrUD77pO5TDQ==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
+  uri-js@4.4.1:
+    resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}
+
+  use-callback-ref@1.3.3:
+    resolution: {integrity: sha512-jQL3lRnocaFtu3V00JToYz/4QkNWswxijDaCVNZRiRTO3HQDLsdu1ZtmIUvV4yPp+rvWm5j0y0TG/S61cuijTg==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sidecar@1.1.3:
+    resolution: {integrity: sha512-Fedw0aZvkhynoPYlA5WXrMCAMm+nSWdZt6lzJQ7Ok8S6Q+VsHmHpRWndVRJ8Be0ZbkfPc5LRYH+5XrzXcEeLRQ==}
+    engines: {node: '>=10'}
+    peerDependencies:
+      '@types/react': '*'
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0 || ^19.0.0-rc
+    peerDependenciesMeta:
+      '@types/react':
+        optional: true
+
+  use-sync-external-store@1.7.0:
+    resolution: {integrity: sha512-6L+EeigHMQhdaIPNIFUKwfWJSwWFQ8gJbJ2DLOs5sDIegTwR9fRxvnM3uciHKjIZhFz+KAv2emhWMRvDmMcY8A==}
+    peerDependencies:
+      react: ^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0
+
+  util-deprecate@1.0.2:
+    resolution: {integrity: sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==}
+
+  utils-merge@1.0.1:
+    resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==}
+    engines: {node: '>= 0.4.0'}
+
+  uuid@11.1.1:
+    resolution: {integrity: sha512-vIYxrBCC/N/K+Js3qSN88go7kIfNPssr/hHCesKCQNAjmgvYS2oqr69kIufEG+O4+PfezOH4EbIeHCfFov8ZgQ==}
+    hasBin: true
+
+  vary@1.1.2:
+    resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==}
+    engines: {node: '>= 0.8'}
+
+  vite-node@2.1.9:
+    resolution: {integrity: sha512-AM9aQ/IPrW/6ENLQg3AGY4K1N2TGZdR5e4gu/MmmR2xR3Ll1+dib+nook92g4TV3PXVyeyxdWwtaCAiUL0hMxA==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+
+  vite@5.4.21:
+    resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+    peerDependencies:
+      '@types/node': ^18.0.0 || >=20.0.0
+      less: '*'
+      lightningcss: ^1.21.0
+      sass: '*'
+      sass-embedded: '*'
+      stylus: '*'
+      sugarss: '*'
+      terser: ^5.4.0
+    peerDependenciesMeta:
+      '@types/node':
+        optional: true
+      less:
+        optional: true
+      lightningcss:
+        optional: true
+      sass:
+        optional: true
+      sass-embedded:
+        optional: true
+      stylus:
+        optional: true
+      sugarss:
+        optional: true
+      terser:
+        optional: true
+
+  vitest@2.1.9:
+    resolution: {integrity: sha512-MSmPM9REYqDGBI8439mA4mWhV5sKmDlBKWIYbA3lRb2PTHACE0mgKwA8yQ2xq9vxDTuk4iPrECBAEW2aoFXY0Q==}
+    engines: {node: ^18.0.0 || >=20.0.0}
+    hasBin: true
+    peerDependencies:
+      '@edge-runtime/vm': '*'
+      '@types/node': ^18.0.0 || >=20.0.0
+      '@vitest/browser': 2.1.9
+      '@vitest/ui': 2.1.9
+      happy-dom: '*'
+      jsdom: '*'
+    peerDependenciesMeta:
+      '@edge-runtime/vm':
+        optional: true
+      '@types/node':
+        optional: true
+      '@vitest/browser':
+        optional: true
+      '@vitest/ui':
+        optional: true
+      happy-dom:
+        optional: true
+      jsdom:
+        optional: true
+
+  w3c-keyname@2.2.8:
+    resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
+
+  watchpack@2.5.2:
+    resolution: {integrity: sha512-6i/00NBjP4yGPs+caKSyRfpTF/8Torsu0MOW3mMzIbhgISFder8i7xbqgHlLMwJrdiN8ndBV3UA1/AfzPSr+jg==}
+    engines: {node: '>=10.13.0'}
+
+  web-streams-polyfill@3.3.3:
+    resolution: {integrity: sha512-d2JWLCivmZYTSIoge9MsgFCZrt571BikcWGYkjC1khllbTeDlGqZ2D8vD8E/lJa8WGWbb7Plm8/XJYV7IJHZZw==}
+    engines: {node: '>= 8'}
+
+  webidl-conversions@3.0.1:
+    resolution: {integrity: sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==}
+
+  webpack-sources@3.6.0:
+    resolution: {integrity: sha512-EIMmPVvNI0CYXyRPp34F2Qk7W37/BZVZIofS6LAUnrNjCVahS+hO4mxwFJDjQjODTGZDtVzLYoN2+1dYkhk9qA==}
+    engines: {node: '>=10.13.0'}
+
+  webpack@5.111.1:
+    resolution: {integrity: sha512-cNypaz0RP+S4cvQVi1M/3bRUkvNP0xZpL0TjFx+c6jg64VbxD+2weWDgY9UnjRI6dhZgtaj8DU76GGFcJ79xPQ==}
+    engines: {node: '>=10.13.0'}
+    hasBin: true
+    peerDependencies:
+      webpack-cli: '*'
+    peerDependenciesMeta:
+      webpack-cli:
+        optional: true
+
+  whatwg-url@5.0.0:
+    resolution: {integrity: sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==}
+
+  which@2.0.2:
+    resolution: {integrity: sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==}
+    engines: {node: '>= 8'}
+    hasBin: true
+
+  why-is-node-running@2.3.0:
+    resolution: {integrity: sha512-hUrmaWBdVDcxvYqnyh09zunKzROWjbZTiNy8dBEjkS7ehEDQibXJ7XvlmtbwuTclUiIyN+CyXQD4Vmko8fNm8w==}
+    engines: {node: '>=8'}
+    hasBin: true
+
+  word-wrap@1.2.5:
+    resolution: {integrity: sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==}
+    engines: {node: '>=0.10.0'}
+
+  wrap-ansi@7.0.0:
+    resolution: {integrity: sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==}
+    engines: {node: '>=10'}
+
+  wrap-ansi@8.1.0:
+    resolution: {integrity: sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==}
+    engines: {node: '>=12'}
+
+  xtend@4.0.2:
+    resolution: {integrity: sha512-LKYU1iAXJXUgAXn9URjiu+MWhyUXHsvfp7mcuYm9dSUKK0/CjtrUwFAxD82/mCWbtLsGjFIad0wIsod4zrTAEQ==}
+    engines: {node: '>=0.4'}
+
+  y18n@5.0.8:
+    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
+    engines: {node: '>=10'}
+
+  yaml@2.9.1:
+    resolution: {integrity: sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
+  yargs-parser@21.1.1:
+    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
+    engines: {node: '>=12'}
+
+  yargs@17.7.3:
+    resolution: {integrity: sha512-GZtjxm/J/4TSxuL3FNYjCmLktBTnIw/rVmKSIyKeYAZpmJB2ig9VauCC5xsa82GNKVKDAqpOn3KVzNt0zmrU0g==}
+    engines: {node: '>=12'}
+
+  yocto-queue@0.1.0:
+    resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
+    engines: {node: '>=10'}
+
+snapshots:
+
+  '@alloc/quick-lru@5.3.0': {}
+
+  '@aws-sdk/checksums@3.1001.1':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/client-s3@3.1146.0':
+    dependencies:
+      '@aws-sdk/checksums': 3.1001.1
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/credential-provider-node': 3.972.84
+      '@aws-sdk/middleware-sdk-s3': 3.972.77
+      '@aws-sdk/signature-v4-multi-region': 3.996.47
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/fetch-http-handler': 5.8.0
+      '@smithy/node-http-handler': 4.12.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/core@3.978.1':
+    dependencies:
+      '@aws-sdk/types': 3.974.6
+      '@aws-sdk/xml-builder': 3.972.41
+      '@aws/lambda-invoke-store': 0.3.0
+      '@smithy/core': 3.35.1
+      '@smithy/signature-v4': 5.7.4
+      '@smithy/types': 4.19.0
+      bowser: 2.14.1
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-env@3.972.72':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-http@3.972.74':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/fetch-http-handler': 5.8.0
+      '@smithy/node-http-handler': 4.12.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-ini@3.973.17':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/credential-provider-env': 3.972.72
+      '@aws-sdk/credential-provider-http': 3.972.74
+      '@aws-sdk/credential-provider-login': 3.972.79
+      '@aws-sdk/credential-provider-process': 3.972.72
+      '@aws-sdk/credential-provider-sso': 3.973.16
+      '@aws-sdk/credential-provider-web-identity': 3.972.78
+      '@aws-sdk/nested-clients': 3.997.46
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/credential-provider-imds': 4.5.2
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-login@3.972.79':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/nested-clients': 3.997.46
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-node@3.972.84':
+    dependencies:
+      '@aws-sdk/credential-provider-env': 3.972.72
+      '@aws-sdk/credential-provider-http': 3.972.74
+      '@aws-sdk/credential-provider-ini': 3.973.17
+      '@aws-sdk/credential-provider-process': 3.972.72
+      '@aws-sdk/credential-provider-sso': 3.973.16
+      '@aws-sdk/credential-provider-web-identity': 3.972.78
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/credential-provider-imds': 4.5.2
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-process@3.972.72':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-sso@3.973.16':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/nested-clients': 3.997.46
+      '@aws-sdk/token-providers': 3.1138.0
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/credential-provider-web-identity@3.972.78':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/nested-clients': 3.997.46
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/middleware-sdk-s3@3.972.77':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/signature-v4-multi-region': 3.996.47
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/nested-clients@3.997.46':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/signature-v4-multi-region': 3.996.47
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/fetch-http-handler': 5.8.0
+      '@smithy/node-http-handler': 4.12.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/s3-request-presigner@3.1146.0':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/signature-v4-multi-region': 3.996.47
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/signature-v4-multi-region@3.996.47':
+    dependencies:
+      '@aws-sdk/types': 3.974.6
+      '@smithy/signature-v4': 5.7.4
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/token-providers@3.1138.0':
+    dependencies:
+      '@aws-sdk/core': 3.978.1
+      '@aws-sdk/nested-clients': 3.997.46
+      '@aws-sdk/types': 3.974.6
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/types@3.974.6':
+    dependencies:
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws-sdk/xml-builder@3.972.41':
+    dependencies:
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@aws/lambda-invoke-store@0.3.0': {}
+
+  '@borewit/text-codec@0.2.2': {}
+
+  '@esbuild/aix-ppc64@0.21.5':
+    optional: true
+
+  '@esbuild/aix-ppc64@0.28.2':
+    optional: true
+
+  '@esbuild/android-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/android-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/android-arm@0.21.5':
+    optional: true
+
+  '@esbuild/android-arm@0.28.2':
+    optional: true
+
+  '@esbuild/android-x64@0.21.5':
+    optional: true
+
+  '@esbuild/android-x64@0.28.2':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/darwin-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/darwin-x64@0.21.5':
+    optional: true
+
+  '@esbuild/darwin-x64@0.28.2':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/freebsd-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/freebsd-x64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-arm@0.21.5':
+    optional: true
+
+  '@esbuild/linux-arm@0.28.2':
+    optional: true
+
+  '@esbuild/linux-ia32@0.21.5':
+    optional: true
+
+  '@esbuild/linux-ia32@0.28.2':
+    optional: true
+
+  '@esbuild/linux-loong64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-loong64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.21.5':
+    optional: true
+
+  '@esbuild/linux-mips64el@0.28.2':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-ppc64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-riscv64@0.28.2':
+    optional: true
+
+  '@esbuild/linux-s390x@0.21.5':
+    optional: true
+
+  '@esbuild/linux-s390x@0.28.2':
+    optional: true
+
+  '@esbuild/linux-x64@0.21.5':
+    optional: true
+
+  '@esbuild/linux-x64@0.28.2':
+    optional: true
+
+  '@esbuild/netbsd-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/netbsd-x64@0.28.2':
+    optional: true
+
+  '@esbuild/openbsd-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.21.5':
+    optional: true
+
+  '@esbuild/openbsd-x64@0.28.2':
+    optional: true
+
+  '@esbuild/openharmony-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/sunos-x64@0.21.5':
+    optional: true
+
+  '@esbuild/sunos-x64@0.28.2':
+    optional: true
+
+  '@esbuild/win32-arm64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-arm64@0.28.2':
+    optional: true
+
+  '@esbuild/win32-ia32@0.21.5':
+    optional: true
+
+  '@esbuild/win32-ia32@0.28.2':
+    optional: true
+
+  '@esbuild/win32-x64@0.21.5':
+    optional: true
+
+  '@esbuild/win32-x64@0.28.2':
+    optional: true
+
+  '@eslint-community/eslint-utils@4.10.1(eslint@9.39.5(jiti@2.7.0))':
+    dependencies:
+      eslint: 9.39.5(jiti@2.7.0)
+      eslint-visitor-keys: 3.4.3
+
+  '@eslint-community/regexpp@4.12.2': {}
+
+  '@eslint/config-array@0.21.2':
+    dependencies:
+      '@eslint/object-schema': 2.1.7
+      debug: 4.4.3
+      minimatch: 3.1.5
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/config-helpers@0.4.2':
+    dependencies:
+      '@eslint/core': 0.17.0
+
+  '@eslint/core@0.17.0':
+    dependencies:
+      '@types/json-schema': 7.0.15
+
+  '@eslint/eslintrc@3.3.7':
+    dependencies:
+      ajv: 6.15.0
+      debug: 4.4.3
+      espree: 10.4.0
+      globals: 14.0.0
+      ignore: 5.3.2
+      import-fresh: 3.3.1
+      js-yaml: 4.3.2
+      minimatch: 3.1.5
+      strip-json-comments: 3.1.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@eslint/js@9.39.5': {}
+
+  '@eslint/object-schema@2.1.7': {}
+
+  '@eslint/plugin-kit@0.4.1':
+    dependencies:
+      '@eslint/core': 0.17.0
+      levn: 0.4.1
+
+  '@floating-ui/core@1.8.0':
+    dependencies:
+      '@floating-ui/utils': 0.2.12
+    optional: true
+
+  '@floating-ui/dom@1.8.0':
+    dependencies:
+      '@floating-ui/core': 1.8.0
+      '@floating-ui/utils': 0.2.12
+    optional: true
+
+  '@floating-ui/utils@0.2.12':
+    optional: true
+
+  '@grpc/grpc-js@1.14.5':
+    dependencies:
+      '@grpc/proto-loader': 0.8.1
+      '@js-sdsl/ordered-map': 4.4.2
+
+  '@grpc/proto-loader@0.8.1':
+    dependencies:
+      lodash.camelcase: 4.3.0
+      long: 5.3.2
+      protobufjs: 7.6.6
+      yargs: 17.7.3
+
+  '@humanfs/core@0.19.2':
+    dependencies:
+      '@humanfs/types': 0.15.0
+
+  '@humanfs/node@0.16.8':
+    dependencies:
+      '@humanfs/core': 0.19.2
+      '@humanfs/types': 0.15.0
+      '@humanwhocodes/retry': 0.4.3
+
+  '@humanfs/types@0.15.0': {}
+
+  '@humanwhocodes/module-importer@1.0.1': {}
+
+  '@humanwhocodes/retry@0.4.3': {}
+
+  '@isaacs/cliui@8.0.2':
+    dependencies:
+      string-width: 5.1.2
+      string-width-cjs: string-width@4.2.3
+      strip-ansi: 7.2.0
+      strip-ansi-cjs: strip-ansi@6.0.1
+      wrap-ansi: 8.1.0
+      wrap-ansi-cjs: wrap-ansi@7.0.0
+
+  '@jridgewell/gen-mapping@0.3.13':
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.6.0
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/remapping@2.3.5':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/resolve-uri@3.1.2': {}
+
+  '@jridgewell/source-map@0.3.11':
+    dependencies:
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+
+  '@jridgewell/sourcemap-codec@1.6.0': {}
+
+  '@jridgewell/trace-mapping@0.3.31':
+    dependencies:
+      '@jridgewell/resolve-uri': 3.1.2
+      '@jridgewell/sourcemap-codec': 1.6.0
+
+  '@js-sdsl/ordered-map@4.4.2': {}
+
+  '@jsonjoy.com/base64@1.1.2(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/base64@17.67.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/buffers@1.2.1(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/buffers@17.67.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/codegen@1.0.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/codegen@17.67.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-core@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-node-builtins': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      thingies: 2.6.1(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-fsa@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-core': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      thingies: 2.6.1(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node-builtins@4.80.0(tslib@2.8.1)':
+    dependencies:
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node-to-fsa@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-fsa': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node-utils@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-node-builtins': 4.80.0(tslib@2.8.1)
+      glob-to-regex.js: 1.3.1(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-node@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-core': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-print': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-snapshot': 4.80.0(tslib@2.8.1)
+      glob-to-regex.js: 1.3.1(tslib@2.8.1)
+      thingies: 2.6.1(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-print@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/fs-snapshot@4.80.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/buffers': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/json-pack': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 17.67.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pack@1.21.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/base64': 1.1.2(tslib@2.8.1)
+      '@jsonjoy.com/buffers': 1.2.1(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 1.0.0(tslib@2.8.1)
+      '@jsonjoy.com/json-pointer': 1.0.2(tslib@2.8.1)
+      '@jsonjoy.com/util': 1.9.0(tslib@2.8.1)
+      hyperdyperid: 1.2.0
+      thingies: 2.6.1(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pack@17.67.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/base64': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/buffers': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/json-pointer': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 17.67.0(tslib@2.8.1)
+      hyperdyperid: 1.2.0
+      thingies: 2.6.1(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pointer@1.0.2(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/codegen': 1.0.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 1.9.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/json-pointer@17.67.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/util': 17.67.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/util@1.9.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/buffers': 1.2.1(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 1.0.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@jsonjoy.com/util@17.67.0(tslib@2.8.1)':
+    dependencies:
+      '@jsonjoy.com/buffers': 17.67.0(tslib@2.8.1)
+      '@jsonjoy.com/codegen': 17.67.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  '@lukeed/csprng@1.1.0': {}
+
+  '@napi-rs/lzma-linux-x64-gnu@1.5.1':
+    optional: true
+
+  '@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2)':
+    dependencies:
+      file-type: 20.4.1
+      iterare: 1.2.1
+      reflect-metadata: 0.2.2
+      rxjs: 7.8.2
+      tslib: 2.8.1
+      uid: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  '@nestjs/core@10.4.22(@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/platform-express@10.4.22)(reflect-metadata@0.2.2)(rxjs@7.8.2)':
+    dependencies:
+      '@nestjs/common': 10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nuxtjs/opencollective': 0.3.2
+      fast-safe-stringify: 2.1.1
+      iterare: 1.2.1
+      path-to-regexp: 3.3.0
+      reflect-metadata: 0.2.2
+      rxjs: 7.8.2
+      tslib: 2.8.1
+      uid: 2.0.2
+    optionalDependencies:
+      '@nestjs/platform-express': 10.4.22(@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@10.4.22)
+    transitivePeerDependencies:
+      - encoding
+
+  '@nestjs/platform-express@10.4.22(@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/core@10.4.22)':
+    dependencies:
+      '@nestjs/common': 10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      '@nestjs/core': 10.4.22(@nestjs/common@10.4.22(reflect-metadata@0.2.2)(rxjs@7.8.2))(@nestjs/platform-express@10.4.22)(reflect-metadata@0.2.2)(rxjs@7.8.2)
+      body-parser: 1.20.4
+      cors: 2.8.5
+      express: 4.22.1
+      multer: 2.0.2
+      tslib: 2.8.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@next/env@14.2.35': {}
+
+  '@next/swc-darwin-arm64@14.2.33':
+    optional: true
+
+  '@next/swc-darwin-x64@14.2.33':
+    optional: true
+
+  '@next/swc-linux-arm64-gnu@14.2.33':
+    optional: true
+
+  '@next/swc-linux-arm64-musl@14.2.33':
+    optional: true
+
+  '@next/swc-linux-x64-gnu@14.2.33':
+    optional: true
+
+  '@next/swc-linux-x64-musl@14.2.33':
+    optional: true
+
+  '@next/swc-win32-arm64-msvc@14.2.33':
+    optional: true
+
+  '@next/swc-win32-ia32-msvc@14.2.33':
+    optional: true
+
+  '@next/swc-win32-x64-msvc@14.2.33':
+    optional: true
+
+  '@nuxtjs/opencollective@0.3.2':
+    dependencies:
+      chalk: 4.1.2
+      consola: 2.15.3
+      node-fetch: 2.7.0
+    transitivePeerDependencies:
+      - encoding
+
+  '@opentelemetry/api-logs@0.222.0':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+
+  '@opentelemetry/api@1.9.1': {}
+
+  '@opentelemetry/auto-instrumentations-node@0.80.0(@opentelemetry/api@1.9.1)(@opentelemetry/core@2.11.0(@opentelemetry/api@1.9.1))':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-amqplib': 0.69.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-aws-lambda': 0.74.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-aws-sdk': 0.77.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-bunyan': 0.67.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-cassandra-driver': 0.67.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-connect': 0.65.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-cucumber': 0.38.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-dataloader': 0.39.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-dns': 0.65.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-express': 0.70.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-fs': 0.41.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-generic-pool': 0.65.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-graphql': 0.70.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-grpc': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-hapi': 0.68.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-host-metrics': 0.5.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-http': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-ioredis': 0.70.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-kafkajs': 0.31.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-knex': 0.66.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-koa': 0.70.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-lru-memoizer': 0.66.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-memcached': 0.65.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-mongodb': 0.75.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-mongoose': 0.68.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-mysql': 0.68.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-mysql2': 0.68.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-nestjs-core': 0.68.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-net': 0.66.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-openai': 0.20.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-oracledb': 0.47.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-pg': 0.74.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-pino': 0.68.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-redis': 0.70.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-restify': 0.67.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-router': 0.66.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-runtime-node': 0.35.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-socket.io': 0.69.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-tedious': 0.41.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-undici': 0.32.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation-winston': 0.66.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resource-detector-alibaba-cloud': 0.37.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resource-detector-aws': 2.22.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resource-detector-azure': 0.30.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resource-detector-container': 0.8.13(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resource-detector-gcp': 0.57.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-node': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/configuration@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      yaml: 2.9.1
+
+  '@opentelemetry/context-async-hooks@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+
+  '@opentelemetry/core@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/exporter-logs-otlp-grpc@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-grpc-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-logs-otlp-http@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-logs-otlp-proto@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-metrics-otlp-grpc@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/exporter-metrics-otlp-http': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-grpc-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-metrics-otlp-http@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-metrics': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-metrics-otlp-proto@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/exporter-metrics-otlp-http': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-prometheus@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-metrics': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/exporter-trace-otlp-grpc@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-grpc-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-trace-otlp-http@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-trace-otlp-proto@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/exporter-zipkin@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/instrumentation-amqplib@0.69.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-aws-lambda@0.74.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/propagator-aws-xray': 2.2.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+      '@types/aws-lambda': 8.10.164
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-aws-sdk@0.77.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-bunyan@0.67.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-cassandra-driver@0.67.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-connect@0.65.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+      '@types/connect': 3.4.38
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-cucumber@0.38.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-dataloader@0.39.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-dns@0.65.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-express@0.70.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-fs@0.41.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-generic-pool@0.65.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-graphql@0.70.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-grpc@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-hapi@0.68.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-host-metrics@0.5.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      systeminformation: 5.33.15
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-http@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+      forwarded-parse: 2.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-ioredis@0.70.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/redis-common': 0.38.3
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-kafkajs@0.31.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-knex@0.66.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-koa@0.70.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-lru-memoizer@0.66.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-memcached@0.65.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+      '@types/memcached': 2.2.10
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-mongodb@0.75.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-mongoose@0.68.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-mysql2@0.68.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+      '@opentelemetry/sql-common': 0.42.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-mysql@0.68.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-nestjs-core@0.68.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-net@0.66.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-openai@0.20.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-oracledb@0.47.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-pg@0.74.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+      '@opentelemetry/sql-common': 0.42.0(@opentelemetry/api@1.9.1)
+      '@types/pg': 8.15.6
+      '@types/pg-pool': 2.0.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-pino@0.68.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-redis@0.70.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/redis-common': 0.38.3
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-restify@0.67.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-router@0.66.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-runtime-node@0.35.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-socket.io@0.69.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-tedious@0.41.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-undici@0.32.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation-winston@0.66.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/instrumentation@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      import-in-the-middle: 3.5.2
+      require-in-the-middle: 8.0.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/otlp-exporter-base@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/otlp-grpc-exporter-base@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@grpc/grpc-js': 1.14.5
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-transformer': 0.222.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/otlp-transformer@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-metrics': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/propagator-aws-xray@2.2.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+
+  '@opentelemetry/propagator-b3@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/propagator-jaeger@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/redis-common@0.38.3': {}
+
+  '@opentelemetry/resource-detector-alibaba-cloud@0.37.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/resource-detector-aws@2.22.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/resource-detector-azure@0.30.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/resource-detector-container@0.8.13(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/resource-detector-gcp@0.57.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      gcp-metadata: 8.1.4
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/resources@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/sdk-logs@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/sdk-metrics@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/sdk-node@0.222.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/api-logs': 0.222.0
+      '@opentelemetry/configuration': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/context-async-hooks': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-logs-otlp-grpc': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-logs-otlp-http': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-logs-otlp-proto': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-metrics-otlp-grpc': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-metrics-otlp-http': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-metrics-otlp-proto': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-prometheus': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-trace-otlp-grpc': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-trace-otlp-http': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-trace-otlp-proto': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/exporter-zipkin': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/instrumentation': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/otlp-grpc-exporter-base': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/propagator-b3': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/propagator-jaeger': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-logs': 0.222.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-metrics': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace-base': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace-node': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+    transitivePeerDependencies:
+      - supports-color
+
+  '@opentelemetry/sdk-trace-base@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/sdk-trace-node@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/context-async-hooks': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/sdk-trace-base': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@opentelemetry/sdk-trace@2.11.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/resources': 2.11.0(@opentelemetry/api@1.9.1)
+      '@opentelemetry/semantic-conventions': 1.43.0
+
+  '@opentelemetry/semantic-conventions@1.43.0': {}
+
+  '@opentelemetry/sql-common@0.42.0(@opentelemetry/api@1.9.1)':
+    dependencies:
+      '@opentelemetry/api': 1.9.1
+      '@opentelemetry/core': 2.11.0(@opentelemetry/api@1.9.1)
+
+  '@pinojs/redact@0.4.0': {}
+
+  '@pkgjs/parseargs@0.11.0':
+    optional: true
+
+  '@protobufjs/aspromise@1.1.2': {}
+
+  '@protobufjs/base64@1.1.2': {}
+
+  '@protobufjs/codegen@2.0.5': {}
+
+  '@protobufjs/eventemitter@1.1.1': {}
+
+  '@protobufjs/fetch@1.1.1':
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+
+  '@protobufjs/float@1.0.2': {}
+
+  '@protobufjs/path@1.1.2': {}
+
+  '@protobufjs/pool@1.1.0': {}
+
+  '@protobufjs/utf8@1.1.2': {}
+
+  '@radix-ui/primitive@1.1.7': {}
+
+  '@radix-ui/react-compose-refs@1.1.5(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-context@1.2.2(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-dialog@1.2.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.7
+      '@radix-ui/react-compose-refs': 1.1.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-context': 1.2.2(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dismissable-layer': 1.1.20(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-focus-guards': 1.1.6(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-focus-scope': 1.2.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-portal': 1.1.18(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-presence': 1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-slot': 1.4.0(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-controllable-state': 1.2.6(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      aria-hidden: 1.2.6
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      react-remove-scroll: 2.7.2(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-dismissable-layer@1.1.20(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.7
+      '@radix-ui/react-compose-refs': 1.1.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-effect-event': 0.0.5(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-focus-guards@1.1.6(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-focus-scope@1.2.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-callback-ref': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-id@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-portal@1.1.18(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-primitive': 2.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-presence@1.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-primitive@2.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-slot': 1.4.0(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+
+  '@radix-ui/react-slot@1.4.0(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.5(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-callback-ref@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-controllable-state@1.2.6(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/primitive': 1.1.7
+      '@radix-ui/react-use-effect-event': 0.0.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-effect-event@0.0.5(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      '@radix-ui/react-use-layout-effect': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@radix-ui/react-use-layout-effect@1.1.4(@types/react@18.3.31)(react@18.3.1)':
+    dependencies:
+      react: 18.3.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  '@rollup/rollup-android-arm-eabi@4.64.0':
+    optional: true
+
+  '@rollup/rollup-android-arm64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-darwin-arm64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-darwin-x64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-freebsd-arm64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-freebsd-x64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm-gnueabihf@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm-musleabihf@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-arm64-musl@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-loong64-musl@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-ppc64-musl@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-riscv64-musl@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-s390x-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-x64-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-linux-x64-musl@4.64.0':
+    optional: true
+
+  '@rollup/rollup-openbsd-x64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-openharmony-arm64@4.64.0':
+    optional: true
+
+  '@rollup/rollup-win32-arm64-msvc@4.64.0':
+    optional: true
+
+  '@rollup/rollup-win32-ia32-msvc@4.64.0':
+    optional: true
+
+  '@rollup/rollup-win32-x64-gnu@4.64.0':
+    optional: true
+
+  '@rollup/rollup-win32-x64-msvc@4.64.0':
+    optional: true
+
+  '@smithy/core@3.35.1':
+    dependencies:
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@smithy/credential-provider-imds@4.5.2':
+    dependencies:
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@smithy/fetch-http-handler@5.8.0':
+    dependencies:
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@smithy/node-http-handler@4.12.1':
+    dependencies:
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@smithy/signature-v4@5.7.4':
+    dependencies:
+      '@smithy/core': 3.35.1
+      '@smithy/types': 4.19.0
+      tslib: 2.8.1
+
+  '@smithy/types@4.19.0':
+    dependencies:
+      tslib: 2.8.1
+
+  '@swc/core-darwin-arm64@1.16.13':
+    optional: true
+
+  '@swc/core-darwin-x64@1.16.13':
+    optional: true
+
+  '@swc/core-linux-arm-gnueabihf@1.16.13':
+    optional: true
+
+  '@swc/core-linux-arm64-gnu@1.16.13':
+    optional: true
+
+  '@swc/core-linux-arm64-musl@1.16.13':
+    optional: true
+
+  '@swc/core-linux-ppc64-gnu@1.16.13':
+    optional: true
+
+  '@swc/core-linux-s390x-gnu@1.16.13':
+    optional: true
+
+  '@swc/core-linux-x64-gnu@1.16.13':
+    optional: true
+
+  '@swc/core-linux-x64-musl@1.16.13':
+    optional: true
+
+  '@swc/core-win32-arm64-msvc@1.16.13':
+    optional: true
+
+  '@swc/core-win32-ia32-msvc@1.16.13':
+    optional: true
+
+  '@swc/core-win32-x64-msvc@1.16.13':
+    optional: true
+
+  '@swc/core@1.16.13':
+    dependencies:
+      '@swc/counter': 0.1.3
+      '@swc/types': 0.1.28
+    optionalDependencies:
+      '@swc/core-darwin-arm64': 1.16.13
+      '@swc/core-darwin-x64': 1.16.13
+      '@swc/core-linux-arm-gnueabihf': 1.16.13
+      '@swc/core-linux-arm64-gnu': 1.16.13
+      '@swc/core-linux-arm64-musl': 1.16.13
+      '@swc/core-linux-ppc64-gnu': 1.16.13
+      '@swc/core-linux-s390x-gnu': 1.16.13
+      '@swc/core-linux-x64-gnu': 1.16.13
+      '@swc/core-linux-x64-musl': 1.16.13
+      '@swc/core-win32-arm64-msvc': 1.16.13
+      '@swc/core-win32-ia32-msvc': 1.16.13
+      '@swc/core-win32-x64-msvc': 1.16.13
+
+  '@swc/counter@0.1.3': {}
+
+  '@swc/helpers@0.5.5':
+    dependencies:
+      '@swc/counter': 0.1.3
+      tslib: 2.8.1
+
+  '@swc/types@0.1.28':
+    dependencies:
+      '@swc/counter': 0.1.3
+
+  '@tailwindcss/node@4.3.3':
+    dependencies:
+      '@jridgewell/remapping': 2.3.5
+      enhanced-resolve: 5.26.0
+      jiti: 2.7.0
+      lightningcss: 1.32.0
+      magic-string: 0.30.21
+      source-map-js: 1.2.2
+      tailwindcss: 4.3.3
+
+  '@tailwindcss/oxide-android-arm64@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-arm64@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-darwin-x64@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-freebsd-x64@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm-gnueabihf@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-gnu@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-linux-arm64-musl@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-gnu@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-linux-x64-musl@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-wasm32-wasi@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-win32-arm64-msvc@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide-win32-x64-msvc@4.3.3':
+    optional: true
+
+  '@tailwindcss/oxide@4.3.3':
+    optionalDependencies:
+      '@tailwindcss/oxide-android-arm64': 4.3.3
+      '@tailwindcss/oxide-darwin-arm64': 4.3.3
+      '@tailwindcss/oxide-darwin-x64': 4.3.3
+      '@tailwindcss/oxide-freebsd-x64': 4.3.3
+      '@tailwindcss/oxide-linux-arm-gnueabihf': 4.3.3
+      '@tailwindcss/oxide-linux-arm64-gnu': 4.3.3
+      '@tailwindcss/oxide-linux-arm64-musl': 4.3.3
+      '@tailwindcss/oxide-linux-x64-gnu': 4.3.3
+      '@tailwindcss/oxide-linux-x64-musl': 4.3.3
+      '@tailwindcss/oxide-wasm32-wasi': 4.3.3
+      '@tailwindcss/oxide-win32-arm64-msvc': 4.3.3
+      '@tailwindcss/oxide-win32-x64-msvc': 4.3.3
+
+  '@tailwindcss/postcss@4.3.3':
+    dependencies:
+      '@alloc/quick-lru': 5.3.0
+      '@tailwindcss/node': 4.3.3
+      '@tailwindcss/oxide': 4.3.3
+      postcss: 8.5.29
+      tailwindcss: 4.3.3
+
+  '@tanstack/react-virtual@3.14.13(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@tanstack/virtual-core': 3.17.11
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+
+  '@tanstack/virtual-core@3.17.11': {}
+
+  '@temporalio/activity@1.24.0':
+    dependencies:
+      '@temporalio/client': 1.24.0
+      '@temporalio/common': 1.24.0
+
+  '@temporalio/client@1.24.0':
+    dependencies:
+      '@grpc/grpc-js': 1.14.5
+      '@temporalio/common': 1.24.0
+      '@temporalio/proto': 1.24.0
+      abort-controller: 3.0.0
+      long: 5.3.2
+      nexus-rpc: 0.0.3
+      uuid: 11.1.1
+
+  '@temporalio/common@1.24.0':
+    dependencies:
+      '@temporalio/proto': 1.24.0
+      long: 5.3.2
+      ms: 3.0.0-canary.1
+      nexus-rpc: 0.0.3
+      protobufjs: 8.8.0
+
+  '@temporalio/core-bridge@1.24.0':
+    dependencies:
+      '@grpc/grpc-js': 1.14.5
+      '@temporalio/common': 1.24.0
+
+  '@temporalio/nexus@1.24.0':
+    dependencies:
+      '@temporalio/client': 1.24.0
+      '@temporalio/common': 1.24.0
+      '@temporalio/proto': 1.24.0
+      long: 5.3.2
+      nexus-rpc: 0.0.3
+
+  '@temporalio/proto@1.24.0':
+    dependencies:
+      long: 5.3.2
+      protobufjs: 8.8.0
+
+  '@temporalio/worker@1.24.0(lightningcss@1.32.0)':
+    dependencies:
+      '@grpc/grpc-js': 1.14.5
+      '@swc/core': 1.16.13
+      '@temporalio/activity': 1.24.0
+      '@temporalio/client': 1.24.0
+      '@temporalio/common': 1.24.0
+      '@temporalio/core-bridge': 1.24.0
+      '@temporalio/nexus': 1.24.0
+      '@temporalio/proto': 1.24.0
+      '@temporalio/workflow': 1.24.0
+      heap-js: 2.7.1
+      memfs: 4.80.0
+      nexus-rpc: 0.0.3
+      protobufjs: 8.8.0
+      rxjs: 7.8.2
+      source-map: 0.7.6
+      source-map-loader: 5.0.0(webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0))
+      supports-color: 8.1.1
+      swc-loader: 0.2.7(@swc/core@1.16.13)(webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0))
+      unionfs: 4.6.0
+      webpack: 5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)
+    transitivePeerDependencies:
+      - '@minify-html/node'
+      - '@napi-rs/image'
+      - '@swc/css'
+      - '@swc/helpers'
+      - '@swc/html'
+      - clean-css
+      - cssnano
+      - csso
+      - esbuild
+      - html-minifier-terser
+      - imagemin
+      - lightningcss
+      - postcss
+      - sharp
+      - svgo
+      - uglify-js
+      - webpack-cli
+
+  '@temporalio/workflow@1.24.0':
+    dependencies:
+      '@temporalio/common': 1.24.0
+      '@temporalio/proto': 1.24.0
+      nexus-rpc: 0.0.3
+
+  '@tiptap/core@3.31.4(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-blockquote@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-bold@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-bubble-menu@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@floating-ui/dom': 1.8.0
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+    optional: true
+
+  '@tiptap/extension-bullet-list@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-character-count@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-code-block@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-code@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-document@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-dropcursor@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-floating-menu@3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@floating-ui/dom': 1.8.0
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+    optional: true
+
+  '@tiptap/extension-gapcursor@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-hard-break@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-heading@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-horizontal-rule@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-italic@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-link@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+      linkifyjs: 4.3.3
+
+  '@tiptap/extension-list-item@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-list-keymap@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/extension-ordered-list@3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-paragraph@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-placeholder@3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-strike@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-text@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extension-underline@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+
+  '@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tiptap/pm@3.31.4':
+    dependencies:
+      prosemirror-changeset: 2.4.4
+      prosemirror-commands: 1.7.2
+      prosemirror-dropcursor: 1.8.4
+      prosemirror-gapcursor: 1.4.1
+      prosemirror-history: 1.5.1
+      prosemirror-inputrules: 1.5.1
+      prosemirror-keymap: 1.2.3
+      prosemirror-model: 1.25.12
+      prosemirror-schema-list: 1.5.1
+      prosemirror-state: 1.4.4
+      prosemirror-tables: 1.8.5
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  '@tiptap/react@3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+      '@types/react': 18.3.31
+      '@types/react-dom': 18.3.7(@types/react@18.3.31)
+      '@types/use-sync-external-store': 0.0.6
+      fast-equals: 5.4.3
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      use-sync-external-store: 1.7.0(react@18.3.1)
+    optionalDependencies:
+      '@tiptap/extension-bubble-menu': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-floating-menu': 3.31.4(@floating-ui/dom@1.8.0)(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+    transitivePeerDependencies:
+      - '@floating-ui/dom'
+
+  '@tiptap/starter-kit@3.31.4':
+    dependencies:
+      '@tiptap/core': 3.31.4(@tiptap/pm@3.31.4)
+      '@tiptap/extension-blockquote': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-bold': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-bullet-list': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-code': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-code-block': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-document': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-dropcursor': 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-gapcursor': 3.31.4(@tiptap/extensions@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-hard-break': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-heading': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-horizontal-rule': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-italic': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-link': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-list': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/extension-list-item': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-list-keymap': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-ordered-list': 3.31.4(@tiptap/extension-list@3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4))
+      '@tiptap/extension-paragraph': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-strike': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-text': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extension-underline': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))
+      '@tiptap/extensions': 3.31.4(@tiptap/core@3.31.4(@tiptap/pm@3.31.4))(@tiptap/pm@3.31.4)
+      '@tiptap/pm': 3.31.4
+
+  '@tokenizer/inflate@0.2.7':
+    dependencies:
+      debug: 4.4.3
+      fflate: 0.8.3
+      token-types: 6.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  '@tokenizer/token@0.3.0': {}
+
+  '@turbo/darwin-64@2.11.7':
+    optional: true
+
+  '@turbo/darwin-arm64@2.11.7':
+    optional: true
+
+  '@turbo/linux-64@2.11.7':
+    optional: true
+
+  '@turbo/linux-arm64@2.11.7':
+    optional: true
+
+  '@turbo/windows-64@2.11.7':
+    optional: true
+
+  '@turbo/windows-arm64@2.11.7':
+    optional: true
+
+  '@types/aws-lambda@8.10.164': {}
+
+  '@types/body-parser@1.19.6':
+    dependencies:
+      '@types/connect': 3.4.38
+      '@types/node': 22.20.5
+
+  '@types/connect@3.4.38':
+    dependencies:
+      '@types/node': 22.20.5
+
+  '@types/estree@1.0.9': {}
+
+  '@types/express-serve-static-core@4.19.9':
+    dependencies:
+      '@types/node': 22.20.5
+      '@types/qs': 6.15.1
+      '@types/range-parser': 1.2.7
+      '@types/send': 1.2.1
+
+  '@types/express@4.17.25':
+    dependencies:
+      '@types/body-parser': 1.19.6
+      '@types/express-serve-static-core': 4.19.9
+      '@types/qs': 6.15.1
+      '@types/serve-static': 1.15.10
+
+  '@types/http-errors@2.0.5': {}
+
+  '@types/json-schema@7.0.15': {}
+
+  '@types/memcached@2.2.10':
+    dependencies:
+      '@types/node': 22.20.5
+
+  '@types/mime@1.3.5': {}
+
+  '@types/node@22.20.5':
+    dependencies:
+      undici-types: 6.21.0
+
+  '@types/pg-pool@2.0.7':
+    dependencies:
+      '@types/pg': 8.23.1
+
+  '@types/pg@8.15.6':
+    dependencies:
+      '@types/node': 22.20.5
+      pg-protocol: 1.16.1
+      pg-types: 2.2.0
+
+  '@types/pg@8.23.1':
+    dependencies:
+      '@types/node': 22.20.5
+      pg-protocol: 1.16.1
+      pg-types: 2.2.0
+
+  '@types/prop-types@15.7.15': {}
+
+  '@types/qs@6.15.1': {}
+
+  '@types/range-parser@1.2.7': {}
+
+  '@types/react-dom@18.3.7(@types/react@18.3.31)':
+    dependencies:
+      '@types/react': 18.3.31
+
+  '@types/react@18.3.31':
+    dependencies:
+      '@types/prop-types': 15.7.15
+      csstype: 3.2.3
+
+  '@types/send@0.17.6':
+    dependencies:
+      '@types/mime': 1.3.5
+      '@types/node': 22.20.5
+
+  '@types/send@1.2.1':
+    dependencies:
+      '@types/node': 22.20.5
+
+  '@types/serve-static@1.15.10':
+    dependencies:
+      '@types/http-errors': 2.0.5
+      '@types/node': 22.20.5
+      '@types/send': 0.17.6
+
+  '@types/use-sync-external-store@0.0.6': {}
+
+  '@typescript-eslint/eslint-plugin@8.71.0(@typescript-eslint/parser@8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/regexpp': 4.12.2
+      '@typescript-eslint/parser': 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      '@typescript-eslint/scope-manager': 8.71.0
+      '@typescript-eslint/type-utils': 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.71.0
+      eslint: 9.39.5(jiti@2.7.0)
+      ignore: 7.0.12
+      natural-compare: 1.4.0
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/parser@8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/scope-manager': 8.71.0
+      '@typescript-eslint/types': 8.71.0
+      '@typescript-eslint/typescript-estree': 8.71.0(typescript@5.9.3)
+      '@typescript-eslint/visitor-keys': 8.71.0
+      debug: 4.4.3
+      eslint: 9.39.5(jiti@2.7.0)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/project-service@8.71.0(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/tsconfig-utils': 8.71.0(typescript@5.9.3)
+      '@typescript-eslint/types': 8.71.0
+      debug: 4.4.3
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/scope-manager@8.71.0':
+    dependencies:
+      '@typescript-eslint/types': 8.71.0
+      '@typescript-eslint/visitor-keys': 8.71.0
+
+  '@typescript-eslint/tsconfig-utils@8.71.0(typescript@5.9.3)':
+    dependencies:
+      typescript: 5.9.3
+
+  '@typescript-eslint/type-utils@8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/types': 8.71.0
+      '@typescript-eslint/typescript-estree': 8.71.0(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      debug: 4.4.3
+      eslint: 9.39.5(jiti@2.7.0)
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/types@8.71.0': {}
+
+  '@typescript-eslint/typescript-estree@8.71.0(typescript@5.9.3)':
+    dependencies:
+      '@typescript-eslint/project-service': 8.71.0(typescript@5.9.3)
+      '@typescript-eslint/tsconfig-utils': 8.71.0(typescript@5.9.3)
+      '@typescript-eslint/types': 8.71.0
+      '@typescript-eslint/visitor-keys': 8.71.0
+      debug: 4.4.3
+      minimatch: 10.2.6
+      semver: 7.8.5
+      tinyglobby: 0.2.17
+      ts-api-utils: 2.5.0(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/utils@8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)':
+    dependencies:
+      '@eslint-community/eslint-utils': 4.10.1(eslint@9.39.5(jiti@2.7.0))
+      '@typescript-eslint/scope-manager': 8.71.0
+      '@typescript-eslint/types': 8.71.0
+      '@typescript-eslint/typescript-estree': 8.71.0(typescript@5.9.3)
+      eslint: 9.39.5(jiti@2.7.0)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  '@typescript-eslint/visitor-keys@8.71.0':
+    dependencies:
+      '@typescript-eslint/types': 8.71.0
+      eslint-visitor-keys: 5.0.1
+
+  '@vitest/expect@2.1.9':
+    dependencies:
+      '@vitest/spy': 2.1.9
+      '@vitest/utils': 2.1.9
+      chai: 5.3.3
+      tinyrainbow: 1.2.0
+
+  '@vitest/mocker@2.1.9(vite@5.4.21(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2))':
+    dependencies:
+      '@vitest/spy': 2.1.9
+      estree-walker: 3.0.3
+      magic-string: 0.30.21
+    optionalDependencies:
+      vite: 5.4.21(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+
+  '@vitest/pretty-format@2.1.9':
+    dependencies:
+      tinyrainbow: 1.2.0
+
+  '@vitest/runner@2.1.9':
+    dependencies:
+      '@vitest/utils': 2.1.9
+      pathe: 1.1.2
+
+  '@vitest/snapshot@2.1.9':
+    dependencies:
+      '@vitest/pretty-format': 2.1.9
+      magic-string: 0.30.21
+      pathe: 1.1.2
+
+  '@vitest/spy@2.1.9':
+    dependencies:
+      tinyspy: 3.0.2
+
+  '@vitest/utils@2.1.9':
+    dependencies:
+      '@vitest/pretty-format': 2.1.9
+      loupe: 3.2.1
+      tinyrainbow: 1.2.0
+
+  '@webassemblyjs/ast@1.14.1':
+    dependencies:
+      '@webassemblyjs/helper-numbers': 1.13.2
+      '@webassemblyjs/helper-wasm-bytecode': 1.13.2
+
+  '@webassemblyjs/floating-point-hex-parser@1.13.2': {}
+
+  '@webassemblyjs/helper-api-error@1.13.2': {}
+
+  '@webassemblyjs/helper-buffer@1.14.1': {}
+
+  '@webassemblyjs/helper-numbers@1.13.2':
+    dependencies:
+      '@webassemblyjs/floating-point-hex-parser': 1.13.2
+      '@webassemblyjs/helper-api-error': 1.13.2
+      '@xtuc/long': 4.2.2
+
+  '@webassemblyjs/helper-wasm-bytecode@1.13.2': {}
+
+  '@webassemblyjs/helper-wasm-section@1.14.1':
+    dependencies:
+      '@webassemblyjs/ast': 1.14.1
+      '@webassemblyjs/helper-buffer': 1.14.1
+      '@webassemblyjs/helper-wasm-bytecode': 1.13.2
+      '@webassemblyjs/wasm-gen': 1.14.1
+
+  '@webassemblyjs/ieee754@1.13.2':
+    dependencies:
+      '@xtuc/ieee754': 1.2.0
+
+  '@webassemblyjs/leb128@1.13.2':
+    dependencies:
+      '@xtuc/long': 4.2.2
+
+  '@webassemblyjs/utf8@1.13.2': {}
+
+  '@webassemblyjs/wasm-edit@1.14.1':
+    dependencies:
+      '@webassemblyjs/ast': 1.14.1
+      '@webassemblyjs/helper-buffer': 1.14.1
+      '@webassemblyjs/helper-wasm-bytecode': 1.13.2
+      '@webassemblyjs/helper-wasm-section': 1.14.1
+      '@webassemblyjs/wasm-gen': 1.14.1
+      '@webassemblyjs/wasm-opt': 1.14.1
+      '@webassemblyjs/wasm-parser': 1.14.1
+      '@webassemblyjs/wast-printer': 1.14.1
+
+  '@webassemblyjs/wasm-gen@1.14.1':
+    dependencies:
+      '@webassemblyjs/ast': 1.14.1
+      '@webassemblyjs/helper-wasm-bytecode': 1.13.2
+      '@webassemblyjs/ieee754': 1.13.2
+      '@webassemblyjs/leb128': 1.13.2
+      '@webassemblyjs/utf8': 1.13.2
+
+  '@webassemblyjs/wasm-opt@1.14.1':
+    dependencies:
+      '@webassemblyjs/ast': 1.14.1
+      '@webassemblyjs/helper-buffer': 1.14.1
+      '@webassemblyjs/wasm-gen': 1.14.1
+      '@webassemblyjs/wasm-parser': 1.14.1
+
+  '@webassemblyjs/wasm-parser@1.14.1':
+    dependencies:
+      '@webassemblyjs/ast': 1.14.1
+      '@webassemblyjs/helper-api-error': 1.13.2
+      '@webassemblyjs/helper-wasm-bytecode': 1.13.2
+      '@webassemblyjs/ieee754': 1.13.2
+      '@webassemblyjs/leb128': 1.13.2
+      '@webassemblyjs/utf8': 1.13.2
+
+  '@webassemblyjs/wast-printer@1.14.1':
+    dependencies:
+      '@webassemblyjs/ast': 1.14.1
+      '@xtuc/long': 4.2.2
+
+  '@xtuc/ieee754@1.2.0': {}
+
+  '@xtuc/long@4.2.2': {}
+
+  abort-controller@3.0.0:
+    dependencies:
+      event-target-shim: 5.0.1
+
+  accepts@1.3.8:
+    dependencies:
+      mime-types: 2.1.35
+      negotiator: 0.6.3
+
+  acorn-jsx@5.3.2(acorn@8.19.0):
+    dependencies:
+      acorn: 8.19.0
+
+  acorn@8.19.0: {}
+
+  agent-base@7.1.4: {}
+
+  ajv-formats@3.0.1(ajv@8.20.0):
+    optionalDependencies:
+      ajv: 8.20.0
+
+  ajv-keywords@5.1.0(ajv@8.20.0):
+    dependencies:
+      ajv: 8.20.0
+      fast-deep-equal: 3.1.3
+
+  ajv@6.15.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-json-stable-stringify: 2.1.0
+      json-schema-traverse: 0.4.1
+      uri-js: 4.4.1
+
+  ajv@8.20.0:
+    dependencies:
+      fast-deep-equal: 3.1.3
+      fast-uri: 3.1.8
+      json-schema-traverse: 1.0.0
+      require-from-string: 2.0.2
+
+  ansi-regex@5.0.1: {}
+
+  ansi-regex@6.4.0: {}
+
+  ansi-styles@4.3.0:
+    dependencies:
+      color-convert: 2.0.1
+
+  ansi-styles@6.2.3: {}
+
+  append-field@1.0.0: {}
+
+  argparse@2.0.1: {}
+
+  aria-hidden@1.2.6:
+    dependencies:
+      tslib: 2.8.1
+
+  array-flatten@1.1.1: {}
+
+  assertion-error@2.0.1: {}
+
+  atomic-sleep@1.0.0: {}
+
+  balanced-match@1.0.2: {}
+
+  balanced-match@4.0.4: {}
+
+  baseline-browser-mapping@2.11.27: {}
+
+  bignumber.js@9.3.1: {}
+
+  body-parser@1.20.4:
+    dependencies:
+      bytes: 3.1.2
+      content-type: 1.0.5
+      debug: 2.6.9
+      depd: 2.0.0
+      destroy: 1.2.0
+      http-errors: 2.0.1
+      iconv-lite: 0.4.24
+      on-finished: 2.4.1
+      qs: 6.14.2
+      raw-body: 2.5.3
+      type-is: 1.6.18
+      unpipe: 1.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  bowser@2.14.1: {}
+
+  brace-expansion@1.1.21:
+    dependencies:
+      balanced-match: 1.0.2
+      concat-map: 0.0.1
+
+  brace-expansion@2.1.7:
+    dependencies:
+      balanced-match: 1.0.2
+
+  brace-expansion@5.0.12:
+    dependencies:
+      balanced-match: 4.0.4
+
+  browserslist@4.29.3:
+    dependencies:
+      baseline-browser-mapping: 2.11.27
+      caniuse-lite: 1.0.30001814
+      electron-to-chromium: 1.5.444
+      node-releases: 2.0.57
+      update-browserslist-db: 1.3.3(browserslist@4.29.3)
+
+  buffer-from@1.1.2: {}
+
+  busboy@1.6.0:
+    dependencies:
+      streamsearch: 1.1.0
+
+  bytes@3.1.2: {}
+
+  cac@6.7.14: {}
+
+  call-bind-apply-helpers@1.0.2:
+    dependencies:
+      es-errors: 1.3.0
+      function-bind: 1.1.2
+
+  call-bound@1.0.4:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      get-intrinsic: 1.3.0
+
+  callsites@3.1.0: {}
+
+  caniuse-lite@1.0.30001814: {}
+
+  chai@5.3.3:
+    dependencies:
+      assertion-error: 2.0.1
+      check-error: 2.1.3
+      deep-eql: 5.0.2
+      loupe: 3.2.1
+      pathval: 2.0.1
+
+  chalk@4.1.2:
+    dependencies:
+      ansi-styles: 4.3.0
+      supports-color: 7.2.0
+
+  check-error@2.1.3: {}
+
+  chrome-trace-event@1.0.4: {}
+
+  cjs-module-lexer@2.3.0: {}
+
+  client-only@0.0.1: {}
+
+  cliui@8.0.1:
+    dependencies:
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+      wrap-ansi: 7.0.0
+
+  cmdk@1.1.1(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      '@radix-ui/react-compose-refs': 1.1.5(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-dialog': 1.2.0(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      '@radix-ui/react-id': 1.1.4(@types/react@18.3.31)(react@18.3.1)
+      '@radix-ui/react-primitive': 2.1.11(@types/react-dom@18.3.7(@types/react@18.3.31))(@types/react@18.3.31)(react-dom@18.3.1(react@18.3.1))(react@18.3.1)
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+    transitivePeerDependencies:
+      - '@types/react'
+      - '@types/react-dom'
+
+  color-convert@2.0.1:
+    dependencies:
+      color-name: 1.1.4
+
+  color-name@1.1.4: {}
+
+  commander@2.20.3: {}
+
+  concat-map@0.0.1: {}
+
+  concat-stream@2.0.0:
+    dependencies:
+      buffer-from: 1.1.2
+      inherits: 2.0.4
+      readable-stream: 3.6.2
+      typedarray: 0.0.6
+
+  consola@2.15.3: {}
+
+  content-disposition@0.5.4:
+    dependencies:
+      safe-buffer: 5.2.1
+
+  content-type@1.0.5: {}
+
+  cookie-signature@1.0.7: {}
+
+  cookie@0.7.2: {}
+
+  cors@2.8.5:
+    dependencies:
+      object-assign: 4.1.1
+      vary: 1.1.2
+
+  cross-spawn@7.0.6:
+    dependencies:
+      path-key: 3.1.1
+      shebang-command: 2.0.0
+      which: 2.0.2
+
+  csstype@3.2.3: {}
+
+  data-uri-to-buffer@4.0.1: {}
+
+  debug@2.6.9:
+    dependencies:
+      ms: 2.0.0
+
+  debug@4.4.3:
+    dependencies:
+      ms: 2.1.3
+
+  deep-eql@5.0.2: {}
+
+  deep-is@0.1.4: {}
+
+  depd@2.0.0: {}
+
+  destroy@1.2.0: {}
+
+  detect-libc@2.1.2: {}
+
+  detect-node-es@1.1.0: {}
+
+  dunder-proto@1.0.1:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-errors: 1.3.0
+      gopd: 1.2.0
+
+  eastasianwidth@0.2.0: {}
+
+  ee-first@1.1.1: {}
+
+  electron-to-chromium@1.5.444: {}
+
+  emoji-regex@8.0.0: {}
+
+  emoji-regex@9.2.2: {}
+
+  encodeurl@2.0.0: {}
+
+  enhanced-resolve@5.26.0:
+    dependencies:
+      graceful-fs: 4.2.11
+      tapable: 2.3.3
+
+  es-define-property@1.0.1: {}
+
+  es-errors@1.3.0: {}
+
+  es-module-lexer@1.7.0: {}
+
+  es-module-lexer@2.3.2: {}
+
+  es-module-lexer@3.0.3: {}
+
+  es-object-atoms@1.1.2:
+    dependencies:
+      es-errors: 1.3.0
+
+  esbuild@0.21.5:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.21.5
+      '@esbuild/android-arm': 0.21.5
+      '@esbuild/android-arm64': 0.21.5
+      '@esbuild/android-x64': 0.21.5
+      '@esbuild/darwin-arm64': 0.21.5
+      '@esbuild/darwin-x64': 0.21.5
+      '@esbuild/freebsd-arm64': 0.21.5
+      '@esbuild/freebsd-x64': 0.21.5
+      '@esbuild/linux-arm': 0.21.5
+      '@esbuild/linux-arm64': 0.21.5
+      '@esbuild/linux-ia32': 0.21.5
+      '@esbuild/linux-loong64': 0.21.5
+      '@esbuild/linux-mips64el': 0.21.5
+      '@esbuild/linux-ppc64': 0.21.5
+      '@esbuild/linux-riscv64': 0.21.5
+      '@esbuild/linux-s390x': 0.21.5
+      '@esbuild/linux-x64': 0.21.5
+      '@esbuild/netbsd-x64': 0.21.5
+      '@esbuild/openbsd-x64': 0.21.5
+      '@esbuild/sunos-x64': 0.21.5
+      '@esbuild/win32-arm64': 0.21.5
+      '@esbuild/win32-ia32': 0.21.5
+      '@esbuild/win32-x64': 0.21.5
+
+  esbuild@0.28.2:
+    optionalDependencies:
+      '@esbuild/aix-ppc64': 0.28.2
+      '@esbuild/android-arm': 0.28.2
+      '@esbuild/android-arm64': 0.28.2
+      '@esbuild/android-x64': 0.28.2
+      '@esbuild/darwin-arm64': 0.28.2
+      '@esbuild/darwin-x64': 0.28.2
+      '@esbuild/freebsd-arm64': 0.28.2
+      '@esbuild/freebsd-x64': 0.28.2
+      '@esbuild/linux-arm': 0.28.2
+      '@esbuild/linux-arm64': 0.28.2
+      '@esbuild/linux-ia32': 0.28.2
+      '@esbuild/linux-loong64': 0.28.2
+      '@esbuild/linux-mips64el': 0.28.2
+      '@esbuild/linux-ppc64': 0.28.2
+      '@esbuild/linux-riscv64': 0.28.2
+      '@esbuild/linux-s390x': 0.28.2
+      '@esbuild/linux-x64': 0.28.2
+      '@esbuild/netbsd-arm64': 0.28.2
+      '@esbuild/netbsd-x64': 0.28.2
+      '@esbuild/openbsd-arm64': 0.28.2
+      '@esbuild/openbsd-x64': 0.28.2
+      '@esbuild/openharmony-arm64': 0.28.2
+      '@esbuild/sunos-x64': 0.28.2
+      '@esbuild/win32-arm64': 0.28.2
+      '@esbuild/win32-ia32': 0.28.2
+      '@esbuild/win32-x64': 0.28.2
+
+  escalade@3.2.0: {}
+
+  escape-html@1.0.3: {}
+
+  escape-string-regexp@4.0.0: {}
+
+  eslint-scope@8.4.0:
+    dependencies:
+      esrecurse: 4.3.0
+      estraverse: 5.3.0
+
+  eslint-visitor-keys@3.4.3: {}
+
+  eslint-visitor-keys@4.2.1: {}
+
+  eslint-visitor-keys@5.0.1: {}
+
+  eslint@9.39.5(jiti@2.7.0):
+    dependencies:
+      '@eslint-community/eslint-utils': 4.10.1(eslint@9.39.5(jiti@2.7.0))
+      '@eslint-community/regexpp': 4.12.2
+      '@eslint/config-array': 0.21.2
+      '@eslint/config-helpers': 0.4.2
+      '@eslint/core': 0.17.0
+      '@eslint/eslintrc': 3.3.7
+      '@eslint/js': 9.39.5
+      '@eslint/plugin-kit': 0.4.1
+      '@humanfs/node': 0.16.8
+      '@humanwhocodes/module-importer': 1.0.1
+      '@humanwhocodes/retry': 0.4.3
+      '@types/estree': 1.0.9
+      ajv: 6.15.0
+      chalk: 4.1.2
+      cross-spawn: 7.0.6
+      debug: 4.4.3
+      escape-string-regexp: 4.0.0
+      eslint-scope: 8.4.0
+      eslint-visitor-keys: 4.2.1
+      espree: 10.4.0
+      esquery: 1.7.0
+      esutils: 2.0.3
+      fast-deep-equal: 3.1.3
+      file-entry-cache: 8.0.0
+      find-up: 5.0.0
+      glob-parent: 6.0.2
+      ignore: 5.3.2
+      imurmurhash: 0.1.4
+      is-glob: 4.0.3
+      json-stable-stringify-without-jsonify: 1.0.1
+      lodash.merge: 4.6.2
+      minimatch: 3.1.5
+      natural-compare: 1.4.0
+      optionator: 0.9.4
+    optionalDependencies:
+      jiti: 2.7.0
+    transitivePeerDependencies:
+      - supports-color
+
+  espree@10.4.0:
+    dependencies:
+      acorn: 8.19.0
+      acorn-jsx: 5.3.2(acorn@8.19.0)
+      eslint-visitor-keys: 4.2.1
+
+  esquery@1.7.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  esrecurse@4.3.0:
+    dependencies:
+      estraverse: 5.3.0
+
+  estraverse@5.3.0: {}
+
+  estree-walker@3.0.3:
+    dependencies:
+      '@types/estree': 1.0.9
+
+  esutils@2.0.3: {}
+
+  etag@1.8.1: {}
+
+  event-target-shim@5.0.1: {}
+
+  events@3.3.0: {}
+
+  expect-type@1.4.0: {}
+
+  express@4.22.1:
+    dependencies:
+      accepts: 1.3.8
+      array-flatten: 1.1.1
+      body-parser: 1.20.4
+      content-disposition: 0.5.4
+      content-type: 1.0.5
+      cookie: 0.7.2
+      cookie-signature: 1.0.7
+      debug: 2.6.9
+      depd: 2.0.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      finalhandler: 1.3.2
+      fresh: 0.5.2
+      http-errors: 2.0.1
+      merge-descriptors: 1.0.3
+      methods: 1.1.2
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      path-to-regexp: 0.1.13
+      proxy-addr: 2.0.8
+      qs: 6.14.2
+      range-parser: 1.2.1
+      safe-buffer: 5.2.1
+      send: 0.19.2
+      serve-static: 1.16.3
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      type-is: 1.6.18
+      utils-merge: 1.0.1
+      vary: 1.1.2
+    transitivePeerDependencies:
+      - supports-color
+
+  extend@3.0.2: {}
+
+  fast-deep-equal@3.1.3: {}
+
+  fast-equals@5.4.3: {}
+
+  fast-json-stable-stringify@2.1.0: {}
+
+  fast-levenshtein@2.0.6: {}
+
+  fast-safe-stringify@2.1.1: {}
+
+  fast-uri@3.1.8: {}
+
+  fdir@6.5.0(picomatch@4.0.7):
+    optionalDependencies:
+      picomatch: 4.0.7
+
+  fetch-blob@3.2.0:
+    dependencies:
+      node-domexception: 1.0.0
+      web-streams-polyfill: 3.3.3
+
+  fflate@0.8.3: {}
+
+  file-entry-cache@8.0.0:
+    dependencies:
+      flat-cache: 4.0.1
+
+  file-type@20.4.1:
+    dependencies:
+      '@tokenizer/inflate': 0.2.7
+      strtok3: 10.3.5
+      token-types: 6.1.2
+      uint8array-extras: 1.6.0
+    transitivePeerDependencies:
+      - supports-color
+
+  finalhandler@1.3.2:
+    dependencies:
+      debug: 2.6.9
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      on-finished: 2.4.1
+      parseurl: 1.3.3
+      statuses: 2.0.2
+      unpipe: 1.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  find-up@5.0.0:
+    dependencies:
+      locate-path: 6.0.0
+      path-exists: 4.0.0
+
+  flat-cache@4.0.1:
+    dependencies:
+      flatted: 3.4.4
+      keyv: 4.5.4
+
+  flatted@3.4.4: {}
+
+  foreground-child@3.3.1:
+    dependencies:
+      cross-spawn: 7.0.6
+      signal-exit: 4.1.0
+
+  formdata-polyfill@4.0.10:
+    dependencies:
+      fetch-blob: 3.2.0
+
+  forwarded-parse@2.1.2: {}
+
+  forwarded@0.2.0: {}
+
+  fresh@0.5.2: {}
+
+  fs-monkey@1.1.0: {}
+
+  fsevents@2.3.3:
+    optional: true
+
+  function-bind@1.1.2: {}
+
+  gaxios@7.1.3:
+    dependencies:
+      extend: 3.0.2
+      https-proxy-agent: 7.0.6
+      node-fetch: 3.3.2
+      rimraf: 5.0.10
+    transitivePeerDependencies:
+      - supports-color
+
+  gcp-metadata@8.1.4:
+    dependencies:
+      gaxios: 7.1.3
+      google-logging-utils: 1.1.3
+      json-bigint: 1.0.0
+    transitivePeerDependencies:
+      - supports-color
+
+  get-caller-file@2.0.5: {}
+
+  get-intrinsic@1.3.0:
+    dependencies:
+      call-bind-apply-helpers: 1.0.2
+      es-define-property: 1.0.1
+      es-errors: 1.3.0
+      es-object-atoms: 1.1.2
+      function-bind: 1.1.2
+      get-proto: 1.0.1
+      gopd: 1.2.0
+      has-symbols: 1.1.0
+      hasown: 2.0.4
+      math-intrinsics: 1.1.0
+
+  get-nonce@1.0.1: {}
+
+  get-proto@1.0.1:
+    dependencies:
+      dunder-proto: 1.0.1
+      es-object-atoms: 1.1.2
+
+  glob-parent@6.0.2:
+    dependencies:
+      is-glob: 4.0.3
+
+  glob-to-regex.js@1.3.1(tslib@2.8.1):
+    dependencies:
+      tslib: 2.8.1
+
+  glob@10.5.0:
+    dependencies:
+      foreground-child: 3.3.1
+      jackspeak: 3.4.3
+      minimatch: 9.0.9
+      minipass: 7.1.3
+      package-json-from-dist: 1.0.1
+      path-scurry: 1.11.1
+
+  globals@14.0.0: {}
+
+  google-logging-utils@1.1.3: {}
+
+  gopd@1.2.0: {}
+
+  graceful-fs@4.2.11: {}
+
+  has-flag@4.0.0: {}
+
+  has-symbols@1.1.0: {}
+
+  hasown@2.0.4:
+    dependencies:
+      function-bind: 1.1.2
+
+  heap-js@2.7.1: {}
+
+  http-errors@2.0.1:
+    dependencies:
+      depd: 2.0.0
+      inherits: 2.0.4
+      setprototypeof: 1.2.0
+      statuses: 2.0.2
+      toidentifier: 1.0.1
+
+  https-proxy-agent@7.0.6:
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
+  hyperdyperid@1.2.0: {}
+
+  iconv-lite@0.4.24:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  iconv-lite@0.6.3:
+    dependencies:
+      safer-buffer: 2.1.2
+
+  ieee754@1.2.1: {}
+
+  ignore@5.3.2: {}
+
+  ignore@7.0.12: {}
+
+  import-fresh@3.3.1:
+    dependencies:
+      parent-module: 1.0.1
+      resolve-from: 4.0.0
+
+  import-in-the-middle@3.5.2:
+    dependencies:
+      cjs-module-lexer: 2.3.0
+      es-module-lexer: 3.0.3
+      module-details-from-path: 1.0.4
+
+  imurmurhash@0.1.4: {}
+
+  inherits@2.0.4: {}
+
+  ipaddr.js@1.9.1: {}
+
+  is-extglob@2.1.1: {}
+
+  is-fullwidth-code-point@3.0.0: {}
+
+  is-glob@4.0.3:
+    dependencies:
+      is-extglob: 2.1.1
+
+  isexe@2.0.0: {}
+
+  iterare@1.2.1: {}
+
+  jackspeak@3.4.3:
+    dependencies:
+      '@isaacs/cliui': 8.0.2
+    optionalDependencies:
+      '@pkgjs/parseargs': 0.11.0
+
+  jest-worker@27.5.1:
+    dependencies:
+      '@types/node': 22.20.5
+      merge-stream: 2.0.0
+      supports-color: 8.1.1
+
+  jiti@2.7.0: {}
+
+  jose@6.2.12: {}
+
+  js-tokens@4.0.0: {}
+
+  js-yaml@4.3.2:
+    dependencies:
+      argparse: 2.0.1
+
+  json-bigint@1.0.0:
+    dependencies:
+      bignumber.js: 9.3.1
+
+  json-buffer@3.0.1: {}
+
+  json-schema-traverse@0.4.1: {}
+
+  json-schema-traverse@1.0.0: {}
+
+  json-stable-stringify-without-jsonify@1.0.1: {}
+
+  keyv@4.5.4:
+    dependencies:
+      json-buffer: 3.0.1
+
+  levn@0.4.1:
+    dependencies:
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+
+  lightningcss-android-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-arm64@1.32.0:
+    optional: true
+
+  lightningcss-darwin-x64@1.32.0:
+    optional: true
+
+  lightningcss-freebsd-x64@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm-gnueabihf@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-arm64-musl@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-gnu@1.32.0:
+    optional: true
+
+  lightningcss-linux-x64-musl@1.32.0:
+    optional: true
+
+  lightningcss-win32-arm64-msvc@1.32.0:
+    optional: true
+
+  lightningcss-win32-x64-msvc@1.32.0:
+    optional: true
+
+  lightningcss@1.32.0:
+    dependencies:
+      detect-libc: 2.1.2
+    optionalDependencies:
+      lightningcss-android-arm64: 1.32.0
+      lightningcss-darwin-arm64: 1.32.0
+      lightningcss-darwin-x64: 1.32.0
+      lightningcss-freebsd-x64: 1.32.0
+      lightningcss-linux-arm-gnueabihf: 1.32.0
+      lightningcss-linux-arm64-gnu: 1.32.0
+      lightningcss-linux-arm64-musl: 1.32.0
+      lightningcss-linux-x64-gnu: 1.32.0
+      lightningcss-linux-x64-musl: 1.32.0
+      lightningcss-win32-arm64-msvc: 1.32.0
+      lightningcss-win32-x64-msvc: 1.32.0
+
+  linkifyjs@4.3.3: {}
+
+  locate-path@6.0.0:
+    dependencies:
+      p-locate: 5.0.0
+
+  lodash.camelcase@4.3.0: {}
+
+  lodash.merge@4.6.2: {}
+
+  long@5.3.2: {}
+
+  loose-envify@1.4.0:
+    dependencies:
+      js-tokens: 4.0.0
+
+  loupe@3.2.1: {}
+
+  lru-cache@10.4.3: {}
+
+  magic-string@0.30.21:
+    dependencies:
+      '@jridgewell/sourcemap-codec': 1.6.0
+
+  math-intrinsics@1.1.0: {}
+
+  media-typer@0.3.0: {}
+
+  memfs@4.80.0:
+    dependencies:
+      '@jsonjoy.com/fs-core': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-fsa': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-builtins': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-to-fsa': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-node-utils': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-print': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/fs-snapshot': 4.80.0(tslib@2.8.1)
+      '@jsonjoy.com/json-pack': 1.21.0(tslib@2.8.1)
+      '@jsonjoy.com/util': 1.9.0(tslib@2.8.1)
+      glob-to-regex.js: 1.3.1(tslib@2.8.1)
+      thingies: 2.6.1(tslib@2.8.1)
+      tree-dump: 1.1.0(tslib@2.8.1)
+      tslib: 2.8.1
+
+  merge-descriptors@1.0.3: {}
+
+  merge-stream@2.0.0: {}
+
+  methods@1.1.2: {}
+
+  mime-db@1.52.0: {}
+
+  mime-db@1.54.0: {}
+
+  mime-types@2.1.35:
+    dependencies:
+      mime-db: 1.52.0
+
+  mime@1.6.0: {}
+
+  minimatch@10.2.6:
+    dependencies:
+      brace-expansion: 5.0.12
+
+  minimatch@3.1.5:
+    dependencies:
+      brace-expansion: 1.1.21
+
+  minimatch@9.0.9:
+    dependencies:
+      brace-expansion: 2.1.7
+
+  minimist@1.2.8: {}
+
+  minimizer-webpack-plugin@5.13.0(@swc/core@1.16.13)(lightningcss@1.32.0)(webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)):
+    dependencies:
+      '@jridgewell/trace-mapping': 0.3.31
+      jest-worker: 27.5.1
+      schema-utils: 4.5.0
+      terser: 5.51.2
+      webpack: 5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)
+    optionalDependencies:
+      '@swc/core': 1.16.13
+      lightningcss: 1.32.0
+
+  minipass@7.1.3: {}
+
+  mkdirp@0.5.6:
+    dependencies:
+      minimist: 1.2.8
+
+  module-details-from-path@1.0.4: {}
+
+  ms@2.0.0: {}
+
+  ms@2.1.3: {}
+
+  ms@3.0.0-canary.1: {}
+
+  multer@2.0.2:
+    dependencies:
+      append-field: 1.0.0
+      busboy: 1.6.0
+      concat-stream: 2.0.0
+      mkdirp: 0.5.6
+      object-assign: 4.1.1
+      type-is: 1.6.18
+      xtend: 4.0.2
+
+  nanoid@3.3.20: {}
+
+  natural-compare@1.4.0: {}
+
+  negotiator@0.6.3: {}
+
+  next@14.2.35(@opentelemetry/api@1.9.1)(react-dom@18.3.1(react@18.3.1))(react@18.3.1):
+    dependencies:
+      '@next/env': 14.2.35
+      '@swc/helpers': 0.5.5
+      busboy: 1.6.0
+      caniuse-lite: 1.0.30001814
+      graceful-fs: 4.2.11
+      postcss: 8.4.31
+      react: 18.3.1
+      react-dom: 18.3.1(react@18.3.1)
+      styled-jsx: 5.1.1(react@18.3.1)
+    optionalDependencies:
+      '@next/swc-darwin-arm64': 14.2.33
+      '@next/swc-darwin-x64': 14.2.33
+      '@next/swc-linux-arm64-gnu': 14.2.33
+      '@next/swc-linux-arm64-musl': 14.2.33
+      '@next/swc-linux-x64-gnu': 14.2.33
+      '@next/swc-linux-x64-musl': 14.2.33
+      '@next/swc-win32-arm64-msvc': 14.2.33
+      '@next/swc-win32-ia32-msvc': 14.2.33
+      '@next/swc-win32-x64-msvc': 14.2.33
+      '@opentelemetry/api': 1.9.1
+    transitivePeerDependencies:
+      - '@babel/core'
+      - babel-plugin-macros
+
+  nexus-rpc@0.0.3: {}
+
+  node-domexception@1.0.0: {}
+
+  node-fetch@2.7.0:
+    dependencies:
+      whatwg-url: 5.0.0
+
+  node-fetch@3.3.2:
+    dependencies:
+      data-uri-to-buffer: 4.0.1
+      fetch-blob: 3.2.0
+      formdata-polyfill: 4.0.10
+
+  node-releases@2.0.57: {}
+
+  object-assign@4.1.1: {}
+
+  object-inspect@1.13.4: {}
+
+  on-exit-leak-free@2.1.2: {}
+
+  on-finished@2.4.1:
+    dependencies:
+      ee-first: 1.1.1
+
+  optionator@0.9.4:
+    dependencies:
+      deep-is: 0.1.4
+      fast-levenshtein: 2.0.6
+      levn: 0.4.1
+      prelude-ls: 1.2.1
+      type-check: 0.4.0
+      word-wrap: 1.2.5
+
+  orderedmap@2.1.1: {}
+
+  p-limit@3.1.0:
+    dependencies:
+      yocto-queue: 0.1.0
+
+  p-locate@5.0.0:
+    dependencies:
+      p-limit: 3.1.0
+
+  package-json-from-dist@1.0.1: {}
+
+  parent-module@1.0.1:
+    dependencies:
+      callsites: 3.1.0
+
+  parseurl@1.3.3: {}
+
+  path-exists@4.0.0: {}
+
+  path-key@3.1.1: {}
+
+  path-scurry@1.11.1:
+    dependencies:
+      lru-cache: 10.4.3
+      minipass: 7.1.3
+
+  path-to-regexp@0.1.13: {}
+
+  path-to-regexp@3.3.0: {}
+
+  pathe@1.1.2: {}
+
+  pathval@2.0.1: {}
+
+  pg-cloudflare@1.4.1:
+    optional: true
+
+  pg-connection-string@2.14.1: {}
+
+  pg-int8@1.0.1: {}
+
+  pg-pool@3.14.0(pg@8.23.1):
+    dependencies:
+      pg: 8.23.1
+
+  pg-protocol@1.16.1: {}
+
+  pg-types@2.2.0:
+    dependencies:
+      pg-int8: 1.0.1
+      postgres-array: 2.0.0
+      postgres-bytea: 1.0.1
+      postgres-date: 1.0.7
+      postgres-interval: 1.2.0
+
+  pg@8.23.1:
+    dependencies:
+      pg-connection-string: 2.14.1
+      pg-pool: 3.14.0(pg@8.23.1)
+      pg-protocol: 1.16.1
+      pg-types: 2.2.0
+      pgpass: 1.0.5
+    optionalDependencies:
+      pg-cloudflare: 1.4.1
+
+  pgpass@1.0.5:
+    dependencies:
+      split2: 4.2.0
+
+  picocolors@1.1.1: {}
+
+  picomatch@4.0.7: {}
+
+  pino-abstract-transport@2.0.0:
+    dependencies:
+      split2: 4.2.0
+
+  pino-std-serializers@7.1.0: {}
+
+  pino@9.14.0:
+    dependencies:
+      '@pinojs/redact': 0.4.0
+      atomic-sleep: 1.0.0
+      on-exit-leak-free: 2.1.2
+      pino-abstract-transport: 2.0.0
+      pino-std-serializers: 7.1.0
+      process-warning: 5.1.0
+      quick-format-unescaped: 4.0.4
+      real-require: 0.2.0
+      safe-stable-stringify: 2.5.0
+      sonic-boom: 4.2.1
+      thread-stream: 3.2.0
+
+  playwright-core@1.63.0: {}
+
+  playwright@1.63.0:
+    dependencies:
+      playwright-core: 1.63.0
+
+  postcss@8.4.31:
+    dependencies:
+      nanoid: 3.3.20
+      picocolors: 1.1.1
+      source-map-js: 1.2.2
+
+  postcss@8.5.29:
+    dependencies:
+      nanoid: 3.3.20
+      picocolors: 1.1.1
+      source-map-js: 1.2.2
+
+  postgres-array@2.0.0: {}
+
+  postgres-bytea@1.0.1: {}
+
+  postgres-date@1.0.7: {}
+
+  postgres-interval@1.2.0:
+    dependencies:
+      xtend: 4.0.2
+
+  prelude-ls@1.2.1: {}
+
+  process-warning@5.1.0: {}
+
+  prosemirror-changeset@2.4.4:
+    dependencies:
+      prosemirror-transform: 1.12.2
+
+  prosemirror-commands@1.7.2:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  prosemirror-dropcursor@1.8.4:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  prosemirror-gapcursor@1.4.1:
+    dependencies:
+      prosemirror-keymap: 1.2.3
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-view: 1.42.6
+
+  prosemirror-history@1.5.1:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+      rope-sequence: 1.3.4
+
+  prosemirror-inputrules@1.5.1:
+    dependencies:
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  prosemirror-keymap@1.2.3:
+    dependencies:
+      prosemirror-state: 1.4.4
+      w3c-keyname: 2.2.8
+
+  prosemirror-model@1.25.12:
+    dependencies:
+      orderedmap: 2.1.1
+
+  prosemirror-schema-list@1.5.1:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  prosemirror-state@1.4.4:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  prosemirror-tables@1.8.5:
+    dependencies:
+      prosemirror-keymap: 1.2.3
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+      prosemirror-view: 1.42.6
+
+  prosemirror-transform@1.12.2:
+    dependencies:
+      prosemirror-model: 1.25.12
+
+  prosemirror-view@1.42.6:
+    dependencies:
+      prosemirror-model: 1.25.12
+      prosemirror-state: 1.4.4
+      prosemirror-transform: 1.12.2
+
+  protobufjs@7.6.6:
+    dependencies:
+      '@protobufjs/aspromise': 1.1.2
+      '@protobufjs/base64': 1.1.2
+      '@protobufjs/codegen': 2.0.5
+      '@protobufjs/eventemitter': 1.1.1
+      '@protobufjs/fetch': 1.1.1
+      '@protobufjs/float': 1.0.2
+      '@protobufjs/path': 1.1.2
+      '@protobufjs/pool': 1.1.0
+      '@protobufjs/utf8': 1.1.2
+      '@types/node': 22.20.5
+      long: 5.3.2
+
+  protobufjs@8.8.0:
+    dependencies:
+      long: 5.3.2
+
+  proxy-addr@2.0.8:
+    dependencies:
+      forwarded: 0.2.0
+      ipaddr.js: 1.9.1
+
+  punycode@2.3.1: {}
+
+  qs@6.14.2:
+    dependencies:
+      side-channel: 1.1.1
+
+  quick-format-unescaped@4.0.4: {}
+
+  range-parser@1.2.1: {}
+
+  raw-body@2.5.3:
+    dependencies:
+      bytes: 3.1.2
+      http-errors: 2.0.1
+      iconv-lite: 0.4.24
+      unpipe: 1.0.0
+
+  react-dom@18.3.1(react@18.3.1):
+    dependencies:
+      loose-envify: 1.4.0
+      react: 18.3.1
+      scheduler: 0.23.2
+
+  react-remove-scroll-bar@2.3.8(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  react-remove-scroll@2.7.2(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      react-remove-scroll-bar: 2.3.8(@types/react@18.3.31)(react@18.3.1)
+      react-style-singleton: 2.2.3(@types/react@18.3.31)(react@18.3.1)
+      tslib: 2.8.1
+      use-callback-ref: 1.3.3(@types/react@18.3.31)(react@18.3.1)
+      use-sidecar: 1.1.3(@types/react@18.3.31)(react@18.3.1)
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  react-style-singleton@2.2.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      get-nonce: 1.0.1
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  react@18.3.1:
+    dependencies:
+      loose-envify: 1.4.0
+
+  readable-stream@3.6.2:
+    dependencies:
+      inherits: 2.0.4
+      string_decoder: 1.3.0
+      util-deprecate: 1.0.2
+
+  real-require@0.2.0: {}
+
+  reflect-metadata@0.2.2: {}
+
+  require-directory@2.1.1: {}
+
+  require-from-string@2.0.2: {}
+
+  require-in-the-middle@8.0.1:
+    dependencies:
+      debug: 4.4.3
+      module-details-from-path: 1.0.4
+    transitivePeerDependencies:
+      - supports-color
+
+  resolve-from@4.0.0: {}
+
+  rimraf@5.0.10:
+    dependencies:
+      glob: 10.5.0
+
+  rollup@4.64.0:
+    dependencies:
+      '@types/estree': 1.0.9
+    optionalDependencies:
+      '@napi-rs/lzma-linux-x64-gnu': 1.5.1
+      '@rollup/rollup-android-arm-eabi': 4.64.0
+      '@rollup/rollup-android-arm64': 4.64.0
+      '@rollup/rollup-darwin-arm64': 4.64.0
+      '@rollup/rollup-darwin-x64': 4.64.0
+      '@rollup/rollup-freebsd-arm64': 4.64.0
+      '@rollup/rollup-freebsd-x64': 4.64.0
+      '@rollup/rollup-linux-arm-gnueabihf': 4.64.0
+      '@rollup/rollup-linux-arm-musleabihf': 4.64.0
+      '@rollup/rollup-linux-arm64-gnu': 4.64.0
+      '@rollup/rollup-linux-arm64-musl': 4.64.0
+      '@rollup/rollup-linux-loong64-gnu': 4.64.0
+      '@rollup/rollup-linux-loong64-musl': 4.64.0
+      '@rollup/rollup-linux-ppc64-gnu': 4.64.0
+      '@rollup/rollup-linux-ppc64-musl': 4.64.0
+      '@rollup/rollup-linux-riscv64-gnu': 4.64.0
+      '@rollup/rollup-linux-riscv64-musl': 4.64.0
+      '@rollup/rollup-linux-s390x-gnu': 4.64.0
+      '@rollup/rollup-linux-x64-gnu': 4.64.0
+      '@rollup/rollup-linux-x64-musl': 4.64.0
+      '@rollup/rollup-openbsd-x64': 4.64.0
+      '@rollup/rollup-openharmony-arm64': 4.64.0
+      '@rollup/rollup-win32-arm64-msvc': 4.64.0
+      '@rollup/rollup-win32-ia32-msvc': 4.64.0
+      '@rollup/rollup-win32-x64-gnu': 4.64.0
+      '@rollup/rollup-win32-x64-msvc': 4.64.0
+      fsevents: 2.3.3
+
+  rope-sequence@1.3.4: {}
+
+  rxjs@7.8.2:
+    dependencies:
+      tslib: 2.8.1
+
+  safe-buffer@5.2.1: {}
+
+  safe-stable-stringify@2.5.0: {}
+
+  safer-buffer@2.1.2: {}
+
+  scheduler@0.23.2:
+    dependencies:
+      loose-envify: 1.4.0
+
+  schema-utils@4.5.0:
+    dependencies:
+      '@types/json-schema': 7.0.15
+      ajv: 8.20.0
+      ajv-formats: 3.0.1(ajv@8.20.0)
+      ajv-keywords: 5.1.0(ajv@8.20.0)
+
+  semver@7.8.5: {}
+
+  send@0.19.2:
+    dependencies:
+      debug: 2.6.9
+      depd: 2.0.0
+      destroy: 1.2.0
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      etag: 1.8.1
+      fresh: 0.5.2
+      http-errors: 2.0.1
+      mime: 1.6.0
+      ms: 2.1.3
+      on-finished: 2.4.1
+      range-parser: 1.2.1
+      statuses: 2.0.2
+    transitivePeerDependencies:
+      - supports-color
+
+  serve-static@1.16.3:
+    dependencies:
+      encodeurl: 2.0.0
+      escape-html: 1.0.3
+      parseurl: 1.3.3
+      send: 0.19.2
+    transitivePeerDependencies:
+      - supports-color
+
+  setprototypeof@1.2.0: {}
+
+  shebang-command@2.0.0:
+    dependencies:
+      shebang-regex: 3.0.0
+
+  shebang-regex@3.0.0: {}
+
+  side-channel-list@1.0.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-map@1.0.1:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+
+  side-channel-weakmap@1.0.2:
+    dependencies:
+      call-bound: 1.0.4
+      es-errors: 1.3.0
+      get-intrinsic: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-map: 1.0.1
+
+  side-channel@1.1.1:
+    dependencies:
+      es-errors: 1.3.0
+      object-inspect: 1.13.4
+      side-channel-list: 1.0.1
+      side-channel-map: 1.0.1
+      side-channel-weakmap: 1.0.2
+
+  siginfo@2.0.0: {}
+
+  signal-exit@4.1.0: {}
+
+  sonic-boom@4.2.1:
+    dependencies:
+      atomic-sleep: 1.0.0
+
+  source-map-js@1.2.2: {}
+
+  source-map-loader@5.0.0(webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)):
+    dependencies:
+      iconv-lite: 0.6.3
+      source-map-js: 1.2.2
+      webpack: 5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)
+
+  source-map-support@0.5.21:
+    dependencies:
+      buffer-from: 1.1.2
+      source-map: 0.6.1
+
+  source-map@0.6.1: {}
+
+  source-map@0.7.6: {}
+
+  split2@4.2.0: {}
+
+  stackback@0.0.2: {}
+
+  statuses@2.0.2: {}
+
+  std-env@3.10.0: {}
+
+  streamsearch@1.1.0: {}
+
+  string-width@4.2.3:
+    dependencies:
+      emoji-regex: 8.0.0
+      is-fullwidth-code-point: 3.0.0
+      strip-ansi: 6.0.1
+
+  string-width@5.1.2:
+    dependencies:
+      eastasianwidth: 0.2.0
+      emoji-regex: 9.2.2
+      strip-ansi: 7.2.0
+
+  string_decoder@1.3.0:
+    dependencies:
+      safe-buffer: 5.2.1
+
+  strip-ansi@6.0.1:
+    dependencies:
+      ansi-regex: 5.0.1
+
+  strip-ansi@7.2.0:
+    dependencies:
+      ansi-regex: 6.4.0
+
+  strip-json-comments@3.1.1: {}
+
+  strtok3@10.3.5:
+    dependencies:
+      '@tokenizer/token': 0.3.0
+
+  styled-jsx@5.1.1(react@18.3.1):
+    dependencies:
+      client-only: 0.0.1
+      react: 18.3.1
+
+  supports-color@7.2.0:
+    dependencies:
+      has-flag: 4.0.0
+
+  supports-color@8.1.1:
+    dependencies:
+      has-flag: 4.0.0
+
+  swc-loader@0.2.7(@swc/core@1.16.13)(webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)):
+    dependencies:
+      '@swc/core': 1.16.13
+      '@swc/counter': 0.1.3
+      webpack: 5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0)
+
+  systeminformation@5.33.15: {}
+
+  tailwindcss@4.3.3: {}
+
+  tapable@2.3.3: {}
+
+  terser@5.51.2:
+    dependencies:
+      '@jridgewell/source-map': 0.3.11
+      acorn: 8.19.0
+      commander: 2.20.3
+      source-map-support: 0.5.21
+
+  thingies@2.6.1(tslib@2.8.1):
+    dependencies:
+      tslib: 2.8.1
+
+  thread-stream@3.2.0:
+    dependencies:
+      real-require: 0.2.0
+
+  tinybench@2.9.0: {}
+
+  tinyexec@0.3.2: {}
+
+  tinyglobby@0.2.17:
+    dependencies:
+      fdir: 6.5.0(picomatch@4.0.7)
+      picomatch: 4.0.7
+
+  tinypool@1.1.1: {}
+
+  tinyrainbow@1.2.0: {}
+
+  tinyspy@3.0.2: {}
+
+  toidentifier@1.0.1: {}
+
+  token-types@6.1.2:
+    dependencies:
+      '@borewit/text-codec': 0.2.2
+      '@tokenizer/token': 0.3.0
+      ieee754: 1.2.1
+
+  tr46@0.0.3: {}
+
+  tree-dump@1.1.0(tslib@2.8.1):
+    dependencies:
+      tslib: 2.8.1
+
+  ts-api-utils@2.5.0(typescript@5.9.3):
+    dependencies:
+      typescript: 5.9.3
+
+  tslib@2.8.1: {}
+
+  tsx@4.23.15:
+    dependencies:
+      esbuild: 0.28.2
+    optionalDependencies:
+      fsevents: 2.3.3
+
+  turbo@2.11.7:
+    optionalDependencies:
+      '@turbo/darwin-64': 2.11.7
+      '@turbo/darwin-arm64': 2.11.7
+      '@turbo/linux-64': 2.11.7
+      '@turbo/linux-arm64': 2.11.7
+      '@turbo/windows-64': 2.11.7
+      '@turbo/windows-arm64': 2.11.7
+
+  type-check@0.4.0:
+    dependencies:
+      prelude-ls: 1.2.1
+
+  type-is@1.6.18:
+    dependencies:
+      media-typer: 0.3.0
+      mime-types: 2.1.35
+
+  typedarray@0.0.6: {}
+
+  typescript-eslint@8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3):
+    dependencies:
+      '@typescript-eslint/eslint-plugin': 8.71.0(@typescript-eslint/parser@8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3))(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      '@typescript-eslint/parser': 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      '@typescript-eslint/typescript-estree': 8.71.0(typescript@5.9.3)
+      '@typescript-eslint/utils': 8.71.0(eslint@9.39.5(jiti@2.7.0))(typescript@5.9.3)
+      eslint: 9.39.5(jiti@2.7.0)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - supports-color
+
+  typescript@5.9.3: {}
+
+  uid@2.0.2:
+    dependencies:
+      '@lukeed/csprng': 1.1.0
+
+  uint8array-extras@1.6.0: {}
+
+  undici-types@6.21.0: {}
+
+  unionfs@4.6.0:
+    dependencies:
+      fs-monkey: 1.1.0
+
+  unpipe@1.0.0: {}
+
+  update-browserslist-db@1.3.3(browserslist@4.29.3):
+    dependencies:
+      browserslist: 4.29.3
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
+  uri-js@4.4.1:
+    dependencies:
+      punycode: 2.3.1
+
+  use-callback-ref@1.3.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  use-sidecar@1.1.3(@types/react@18.3.31)(react@18.3.1):
+    dependencies:
+      detect-node-es: 1.1.0
+      react: 18.3.1
+      tslib: 2.8.1
+    optionalDependencies:
+      '@types/react': 18.3.31
+
+  use-sync-external-store@1.7.0(react@18.3.1):
+    dependencies:
+      react: 18.3.1
+
+  util-deprecate@1.0.2: {}
+
+  utils-merge@1.0.1: {}
+
+  uuid@11.1.1: {}
+
+  vary@1.1.2: {}
+
+  vite-node@2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2):
+    dependencies:
+      cac: 6.7.14
+      debug: 4.4.3
+      es-module-lexer: 1.7.0
+      pathe: 1.1.2
+      vite: 5.4.21(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+    transitivePeerDependencies:
+      - '@types/node'
+      - less
+      - lightningcss
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+
+  vite@5.4.21(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2):
+    dependencies:
+      esbuild: 0.21.5
+      postcss: 8.5.29
+      rollup: 4.64.0
+    optionalDependencies:
+      '@types/node': 22.20.5
+      fsevents: 2.3.3
+      lightningcss: 1.32.0
+      terser: 5.51.2
+
+  vitest@2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2):
+    dependencies:
+      '@vitest/expect': 2.1.9
+      '@vitest/mocker': 2.1.9(vite@5.4.21(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2))
+      '@vitest/pretty-format': 2.1.9
+      '@vitest/runner': 2.1.9
+      '@vitest/snapshot': 2.1.9
+      '@vitest/spy': 2.1.9
+      '@vitest/utils': 2.1.9
+      chai: 5.3.3
+      debug: 4.4.3
+      expect-type: 1.4.0
+      magic-string: 0.30.21
+      pathe: 1.1.2
+      std-env: 3.10.0
+      tinybench: 2.9.0
+      tinyexec: 0.3.2
+      tinypool: 1.1.1
+      tinyrainbow: 1.2.0
+      vite: 5.4.21(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+      vite-node: 2.1.9(@types/node@22.20.5)(lightningcss@1.32.0)(terser@5.51.2)
+      why-is-node-running: 2.3.0
+    optionalDependencies:
+      '@types/node': 22.20.5
+    transitivePeerDependencies:
+      - less
+      - lightningcss
+      - msw
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+
+  w3c-keyname@2.2.8: {}
+
+  watchpack@2.5.2:
+    dependencies:
+      graceful-fs: 4.2.11
+
+  web-streams-polyfill@3.3.3: {}
+
+  webidl-conversions@3.0.1: {}
+
+  webpack-sources@3.6.0: {}
+
+  webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0):
+    dependencies:
+      '@types/estree': 1.0.9
+      '@types/json-schema': 7.0.15
+      '@webassemblyjs/ast': 1.14.1
+      '@webassemblyjs/wasm-edit': 1.14.1
+      '@webassemblyjs/wasm-parser': 1.14.1
+      browserslist: 4.29.3
+      chrome-trace-event: 1.0.4
+      enhanced-resolve: 5.26.0
+      es-module-lexer: 2.3.2
+      events: 3.3.0
+      graceful-fs: 4.2.11
+      mime-db: 1.54.0
+      minimizer-webpack-plugin: 5.13.0(@swc/core@1.16.13)(lightningcss@1.32.0)(webpack@5.111.1(@swc/core@1.16.13)(lightningcss@1.32.0))
+      schema-utils: 4.5.0
+      tapable: 2.3.3
+      watchpack: 2.5.2
+      webpack-sources: 3.6.0
+    transitivePeerDependencies:
+      - '@minify-html/node'
+      - '@napi-rs/image'
+      - '@swc/core'
+      - '@swc/css'
+      - '@swc/html'
+      - clean-css
+      - cssnano
+      - csso
+      - esbuild
+      - html-minifier-terser
+      - imagemin
+      - lightningcss
+      - postcss
+      - sharp
+      - svgo
+      - uglify-js
+
+  whatwg-url@5.0.0:
+    dependencies:
+      tr46: 0.0.3
+      webidl-conversions: 3.0.1
+
+  which@2.0.2:
+    dependencies:
+      isexe: 2.0.0
+
+  why-is-node-running@2.3.0:
+    dependencies:
+      siginfo: 2.0.0
+      stackback: 0.0.2
+
+  word-wrap@1.2.5: {}
+
+  wrap-ansi@7.0.0:
+    dependencies:
+      ansi-styles: 4.3.0
+      string-width: 4.2.3
+      strip-ansi: 6.0.1
+
+  wrap-ansi@8.1.0:
+    dependencies:
+      ansi-styles: 6.2.3
+      string-width: 5.1.2
+      strip-ansi: 7.2.0
+
+  xtend@4.0.2: {}
+
+  y18n@5.0.8: {}
+
+  yaml@2.9.1: {}
+
+  yargs-parser@21.1.1: {}
+
+  yargs@17.7.3:
+    dependencies:
+      cliui: 8.0.1
+      escalade: 3.2.0
+      get-caller-file: 2.0.5
+      require-directory: 2.1.1
+      string-width: 4.2.3
+      y18n: 5.0.8
+      yargs-parser: 21.1.1
+
+  yocto-queue@0.1.0: {}
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
new file mode 100644
index 0000000..3ff5faa
--- /dev/null
+++ b/pnpm-workspace.yaml
@@ -0,0 +1,3 @@
+packages:
+  - "apps/*"
+  - "packages/*"
diff --git a/scripts/build-manual.py b/scripts/build-manual.py
new file mode 100644
index 0000000..b39d3ed
--- /dev/null
+++ b/scripts/build-manual.py
@@ -0,0 +1,430 @@
+#!/usr/bin/env python3
+"""SuperPoster User Manual PDF — with embedded screenshots from the running app."""
+import os
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import inch, mm
+from reportlab.lib.colors import HexColor
+from reportlab.lib.styles import ParagraphStyle
+from reportlab.lib.enums import TA_LEFT, TA_CENTER
+from reportlab.platypus import (
+    SimpleDocTemplate, Paragraph, Spacer, PageBreak, Image, Table, TableStyle,
+    HRFlowable, KeepTogether, NextPageTemplate, PageTemplate, Frame,
+)
+from reportlab.lib.utils import ImageReader
+
+SHOTS = "apps/web/runs/manual/shots"
+OUT = "docs/SuperPoster-User-Manual.pdf"
+
+# Colors (match the app's dark-first identity)
+BG = HexColor("#0a0a0b")
+SURFACE = HexColor("#1a1a1e")
+ACCENT = HexColor("#6c7cff")
+TEXT = HexColor("#e0e0e6")
+MUTED = HexColor("#8b8b96")
+WHITE = HexColor("#ffffff")
+DARK_TEXT = HexColor("#1a1a2e")
+DARK_MUTED = HexColor("#555566")
+BRAND_INDIGO = HexColor("#5b6cff")
+BRAND_DARK = HexColor("#111118")
+LIGHT_BG = HexColor("#f5f5fa")
+
+# Styles
+title_s = ParagraphStyle("title", fontName="Helvetica-Bold", fontSize=32, textColor=BRAND_INDIGO, spaceAfter=6, leading=38)
+subtitle_s = ParagraphStyle("subtitle", fontName="Helvetica", fontSize=14, textColor=DARK_MUTED, spaceAfter=20)
+h1_s = ParagraphStyle("h1", fontName="Helvetica-Bold", fontSize=22, textColor=BRAND_INDIGO, spaceBefore=30, spaceAfter=10, leading=26)
+h2_s = ParagraphStyle("h2", fontName="Helvetica-Bold", fontSize=16, textColor=DARK_TEXT, spaceBefore=20, spaceAfter=8)
+body_s = ParagraphStyle("body", fontName="Helvetica", fontSize=10.5, textColor=DARK_TEXT, leading=16, spaceAfter=8)
+step_s = ParagraphStyle("step", fontName="Helvetica-Bold", fontSize=11, textColor=BRAND_INDIGO, spaceBefore=14, spaceAfter=6)
+note_s = ParagraphStyle("note", fontName="Helvetica-Oblique", fontSize=9.5, textColor=DARK_MUTED, leading=14, spaceAfter=8)
+caption_s = ParagraphStyle("caption", fontName="Helvetica-Oblique", fontSize=9, textColor=DARK_MUTED, spaceBefore=4, spaceAfter=12)
+kbd_s = ParagraphStyle("kbd", fontName="Courier-Bold", fontSize=10, textColor=BRAND_INDIGO, backColor=LIGHT_BG, borderPadding=4, spaceAfter=8)
+toc_s = ParagraphStyle("toc", fontName="Helvetica", fontSize=11, textColor=DARK_TEXT, leading=22)
+
+def img(name, width=6.5*inch):
+    path = os.path.join(SHOTS, name)
+    if not os.path.exists(path):
+        return Paragraph(f"[screenshot: {name}]", note_s)
+    img = ImageReader(path)
+    iw, ih = img.getSize()
+    h = width * ih / iw
+    return Image(path, width=width, height=h)
+
+def screenshot(name, caption):
+    return KeepTogether([img(name), Paragraph(caption, caption_s)])
+
+doc = SimpleDocTemplate(OUT, pagesize=A4,
+    leftMargin=25*mm, rightMargin=25*mm, topMargin=20*mm, bottomMargin=20*mm,
+    title="SuperPoster User Manual", author="SuperPoster")
+
+story = []
+
+# ══════════════════════════════════════ COVER ══════════════════════════════════════
+story.append(Spacer(1, 80))
+story.append(Paragraph("SuperPoster", title_s))
+story.append(Paragraph("User Manual", subtitle_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=2, spaceAfter=20))
+story.append(Paragraph("""
+Version 1.0 · October 2026<br/><br/>
+This guide covers everything you need to get started: creating your workspace,
+inviting your team, connecting social accounts, monitoring streams, composing
+and scheduling posts, and using the audit trail.<br/><br/>
+<b>Design identity reference:</b> Canva Visual Kit · Canva Post Kit · Canva Graphic Resources
+""", body_s))
+story.append(Spacer(1, 40))
+story.append(screenshot("streams-01-overview.png", "SuperPoster — Streams view, the monitoring hub"))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ CONTENTS ══════════════════════════════════════
+story.append(Paragraph("Contents", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+toc_items = [
+    ("1.", "Getting Started — Onboarding"),
+    ("2.", "Understanding Streams"),
+    ("3.", "Composing and Scheduling Posts"),
+    ("4.", "Managing Connected Accounts"),
+    ("5.", "Team, Groups and Permissions"),
+    ("6.", "Inbox — Direct Messages"),
+    ("7.", "Audit Trail — Who Did What"),
+    ("8.", "Keyboard Shortcuts"),
+    ("9.", "Troubleshooting"),
+]
+for num, title in toc_items:
+    story.append(Paragraph(f"{num}&nbsp;&nbsp;{title}", toc_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 1. GETTING STARTED ══════════════════════════════════════
+story.append(Paragraph("1. Getting Started", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(Paragraph("Creating Your Workspace", h2_s))
+story.append(Paragraph("""
+The first time you use SuperPoster, you'll see the onboarding wizard. A workspace
+is your team's tenant boundary — everything (accounts, drafts, posts, audit)
+belongs to exactly one workspace and is isolated from all others.
+""", body_s))
+
+story.append(Paragraph("Step 1 — Name your workspace", step_s))
+story.append(screenshot("onboard-01-start.png", "The onboarding wizard starts here"))
+story.append(Paragraph("Type a name that identifies your team or organisation.", body_s))
+story.append(screenshot("onboard-02-named.png", "Enter a descriptive name — you can change it later in Settings"))
+
+story.append(Paragraph("Step 2 — Invite your team", step_s))
+story.append(screenshot("onboard-03-invite.png", "Enter email addresses separated by commas"))
+story.append(Paragraph("""
+Add teammates by email. They'll receive an invitation and can join with the role
+you assign them (or the default role). You can always change roles later from
+the Team screen.
+""", body_s))
+story.append(screenshot("onboard-04-emails-filled.png", "Multiple invitations entered"))
+
+story.append(Paragraph("Step 3 — Connect your first accounts", step_s))
+story.append(screenshot("onboard-05-connect.png", "Choose platforms to connect — OAuth only, no passwords stored"))
+story.append(Paragraph("""
+Click <b>Connect</b> on any platform. You'll be redirected to that platform's own
+OAuth page where you log in securely. SuperPoster never sees or stores your
+platform password — only an encrypted access token.
+""", body_s))
+story.append(Paragraph("""
+<b>Important:</b> SuperPoster stores OAuth tokens only. Your account password never
+transits or rests in this system. You can revoke access at any time from either
+SuperPoster or the platform itself.
+""", note_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 2. STREAMS ══════════════════════════════════════
+story.append(Paragraph("2. Understanding Streams", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(Paragraph("Your Monitoring Hub", h2_s))
+story.append(screenshot("streams-01-overview.png", "Streams — three columns, each tracking a different feed"))
+story.append(Paragraph("""
+The Streams screen is your command centre. Each column tracks a feed from a
+connected platform. Cards show the author, age, text, and engagement. Hover over
+any card to reveal its amplify bar.
+""", body_s))
+
+story.append(Paragraph("Selecting Items", h2_s))
+story.append(screenshot("streams-02-item-selected.png", "An item is selected (highlighted in blue) — its amplify bar is now visible"))
+story.append(Paragraph("""
+Press <b>j</b> to move to the next item or <b>k</b> to go back. You can also click any
+card. The selected card shows a blue highlight and reveals its amplify buttons.
+""", body_s))
+
+story.append(Paragraph("Amplifying — Boost, Quote and Share", h2_s))
+story.append(screenshot("streams-03-repost-toast.png", "Pressing r boosts the selected item — a toast confirms the action"))
+story.append(Paragraph("""
+Each platform's amplify bar shows <b>only what that API truly supports</b>:
+""", body_s))
+story.append(Paragraph("""
+<b>Mastodon:</b> Boost (native reblog) and Quote (native quote-post)<br/>
+<b>Telegram:</b> Forward<br/>
+<b>Bluesky:</b> Repost and Quote<br/>
+<b>Instagram:</b> No native reshare — but Quote… with attribution always works<br/>
+<b>Facebook:</b> Share link (approximation)<br/>
+<b>Reddit:</b> Crosspost
+""", body_s))
+
+story.append(screenshot("streams-04-quote-popover.png", "Pressing q opens the quote composer"))
+story.append(Paragraph("""
+Type your commentary. The character limit matches the platform you're quoting
+on. The original post is shown above for reference.
+""", body_s))
+story.append(screenshot("streams-05-quote-typed.png", "Your commentary appears above the quoted content"))
+
+story.append(Paragraph("Quote with Attribution", h2_s))
+story.append(Paragraph("""
+On platforms without a native quote API (like Instagram or Facebook), SuperPoster
+offers <b>Quote… with attribution</b> — this composes a new original post that
+references the source with proper attribution. It's indicated by a dashed-border
+button. This isn't a native API call; it's your own post with attribution text,
+which every platform allows.
+""", body_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 3. COMPOSING ══════════════════════════════════════
+story.append(Paragraph("3. Composing and Scheduling Posts", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(Paragraph("Writing a Post", h2_s))
+story.append(screenshot("compose-01-blank.png", "The Compose screen — a rich editor with markdown support"))
+story.append(Paragraph("""
+Type your post in the rich editor. Markdown formatting is supported (bold with
+**text**, headings with #, etc.). As you type, the character counter updates.
+""", body_s))
+
+story.append(screenshot("compose-02-typed.png", "A composed post — note the character counter and platform previews"))
+
+story.append(Paragraph("Targeting Platforms", h2_s))
+story.append(Paragraph("""
+Click platform chips (Mastodon, Telegram, Facebook, Instagram) to toggle targets.
+Each target shows its own character limit. The overall counter reflects the
+<b>tightest</b> limit among your selected targets.
+""", body_s))
+
+story.append(Paragraph("The Approval Flow", h2_s))
+story.append(Paragraph("""
+If your workspace uses approvals, the flow is:<br/><br/>
+<b>Draft</b> → Submit for Review → <b>In Review</b> → Approve/Reject → <b>Approved</b> → Schedule/Publish
+""", body_s))
+story.append(Paragraph("""
+Every transition is permission-checked and recorded in the audit trail with a
+full diff of what changed.
+""", note_s))
+
+story.append(Paragraph("Scheduling", h2_s))
+story.append(Paragraph("""
+Set a date and time in the Schedule field. Your post enters the Temporal-backed
+scheduling pipeline — durable, idempotent, and survives restarts. If Temporal
+is briefly unavailable, your scheduled post sits safely as "pending" until the
+worker picks it up.
+""", body_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 4. CONNECTIONS ══════════════════════════════════════
+story.append(Paragraph("4. Managing Connected Accounts", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(screenshot("connections-01-overview.png", "The Channels screen — each card shows platform, handle, capabilities and health"))
+story.append(Paragraph("""
+Every connected account appears as a card showing:
+""", body_s))
+story.append(Paragraph("""
+<b>Platform and handle</b> — which account this is<br/>
+<b>Capability chips</b> — what this platform's API actually supports<br/>
+<b>Health badge</b> — healthy (green) or token expiring (amber)<br/>
+<b>Capacity chip</b> — how many posts you have left in your rolling 24h window
+""", body_s))
+
+story.append(Paragraph("Post Capacity", h2_s))
+story.append(Paragraph("""
+Click the capacity chip (e.g., <b>17/25 posts left</b>) to see your usage bar,
+when the next slot frees, and any tier notes. Provider caps are rolling 24-hour
+windows — slots free up continuously as older posts age out, not at midnight.
+""", body_s))
+
+story.append(Paragraph("Connecting a New Account", h2_s))
+story.append(Paragraph("""
+1. Click <b>Connect account</b> (or the Connect button on a disconnected card)<br/>
+2. You'll be redirected to the platform's OAuth page<br/>
+3. Log in on the platform's own page and authorize SuperPoster<br/>
+4. You're redirected back — the connection appears with its capabilities
+""", body_s))
+story.append(Paragraph("""
+<b>Security guarantee:</b> OAuth tokens are envelope-encrypted in the vault.
+Nobody — not even workspace Owners — can read raw tokens through any interface.
+""", note_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 5. TEAM ══════════════════════════════════════
+story.append(Paragraph("5. Team, Groups and Permissions", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(screenshot("team-01-overview.png", "The Team screen — members, roles and the shared asset library"))
+
+story.append(Paragraph("Roles", h2_s))
+story.append(Paragraph("""
+SuperPoster ships with 10 seeded roles. Each role is a bundle of permissions —
+the system checks permissions, never role names, so you can customise roles
+without breaking anything:
+""", body_s))
+
+role_table = Table([
+    ["Role", "Can Do"],
+    ["Owner", "Everything, including credential management"],
+    ["Admin", "Everything except credential management"],
+    ["Publisher", "Compose, schedule, publish, manage media"],
+    ["Editor", "Compose and edit drafts, manage media"],
+    ["Approver", "Review and approve/reject submitted drafts"],
+    ["Analyst", "View analytics and audit trail"],
+    ["Moderator", "Manage inbox, live chat moderation"],
+    ["Video Publisher", "Compose, schedule and publish video content"],
+    ["Stream Operator", "Manage livestreams"],
+    ["Broadcast Operator", "Virtual channel control, director actions, live chat"],
+], colWidths=[1.6*inch, 4.9*inch])
+role_table.setStyle(TableStyle([
+    ("FONTNAME", (0,0), (-1,0), "Helvetica-Bold"),
+    ("FONTSIZE", (0,0), (-1,-1), 9),
+    ("TEXTCOLOR", (0,0), (0,-1), BRAND_INDIGO),
+    ("TEXTCOLOR", (1,0), (1,-1), DARK_TEXT),
+    ("VALIGN", (0,0), (-1,-1), "TOP"),
+    ("BOTTOMPADDING", (0,0), (-1,-1), 6),
+    ("TOPPADDING", (0,0), (-1,-1), 6),
+    ("LINEBELOW", (0,0), (-1,-2), 0.5, HexColor("#e0e0e8")),
+    ("BACKGROUND", (0,0), (-1,0), LIGHT_BG),
+]))
+story.append(role_table)
+
+story.append(Paragraph("Changing Roles and Removing Members", h2_s))
+story.append(Paragraph("""
+Use the role dropdown on any member row. Removing a member takes effect
+immediately — their active sessions fail closed on their next request thanks
+to the authorization epoch system. They are logged out instantly; no stale
+access lingers.
+""", body_s))
+
+story.append(Paragraph("Groups (Coming Soon)", h2_s))
+story.append(Paragraph("""
+Groups let you scope which connected accounts and media assets each sub-team
+can use. For example: the "Breaking News" group gets access to the main
+Mastodon and Bluesky accounts, while the "Lifestyle" group only sees the
+Instagram and Facebook pages. A member's publish targets filter automatically
+to show only the accounts their groups permit.
+""", body_s))
+
+story.append(Paragraph("Asset Library", h2_s))
+story.append(Paragraph("""
+The shared asset library holds your team's images, videos and documents.
+Assets can be scoped to groups (shown with a lock icon) — members outside the
+group see the lock but cannot access the file.
+""", body_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 6. INBOX ══════════════════════════════════════
+story.append(Paragraph("6. Inbox — Direct Messages", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(screenshot("inbox-01-overview.png", "The Inbox — unified conversations across all connected accounts"))
+story.append(Paragraph("""
+All direct-message conversations from your connected accounts appear in one list.
+Unread badges show new messages; assignee initials show who's handling each thread.
+""", body_s))
+story.append(Paragraph("""
+<b>Reply windows:</b> Messaging APIs allow replies within each platform's window
+(typically 24 hours for Meta platforms). Outside the window, only pre-approved
+template messages are allowed. SuperPoster shows you exactly what's possible
+rather than failing silently.
+""", note_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 7. AUDIT ══════════════════════════════════════
+story.append(Paragraph("7. Audit Trail — Who Did What", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+story.append(screenshot("audit-01-overview.png", "The Audit Trail — filterable, hash-chained, tamper-evident"))
+story.append(Paragraph("""
+Every meaningful action is recorded: posts published, roles changed, credentials
+rotated, connections added. The chain is <b>hash-linked</b> — each entry's hash
+incorporates the previous entry's hash, so any tampering is mathematically
+detectable.
+""", body_s))
+
+story.append(screenshot("audit-02-diff-open.png", "Click any row to see the exact field-by-field diff"))
+story.append(Paragraph("""
+The diff viewer shows <b>before → after</b> values with red/green highlighting.
+Secret values always appear as <b>[REDACTED]</b> — they are stripped before the
+audit entry is created, not hidden by the UI. This is enforced at the database
+function level.
+""", body_s))
+story.append(Paragraph("""
+Use the filter bar to narrow by actor or action. Export to CSV for compliance
+reporting.
+""", body_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 8. SHORTCUTS ══════════════════════════════════════
+story.append(Paragraph("8. Keyboard Shortcuts", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+keys = Table([
+    ["Shortcut", "Action", "Where"],
+    ["j / ↓", "Next item", "Streams"],
+    ["k / ↑", "Previous item", "Streams"],
+    ["r", "Repost/boost selected item", "Streams"],
+    ["q", "Quote selected item", "Streams"],
+    ["Esc", "Close popover/dialog", "Everywhere"],
+    ["⌘K / Ctrl+K", "Command palette", "Everywhere"],
+], colWidths=[1.4*inch, 3.3*inch, 1.8*inch])
+keys.setStyle(TableStyle([
+    ("FONTNAME", (0,0), (-1,0), "Helvetica-Bold"),
+    ("FONTSIZE", (0,0), (-1,-1), 10),
+    ("FONTNAME", (0,1), (0,-1), "Courier-Bold"),
+    ("TEXTCOLOR", (0,1), (0,-1), BRAND_INDIGO),
+    ("TEXTCOLOR", (1,0), (1,-1), DARK_TEXT),
+    ("VALIGN", (0,0), (-1,-1), "TOP"),
+    ("BOTTOMPADDING", (0,0), (-1,-1), 8),
+    ("TOPPADDING", (0,0), (-1,-1), 8),
+    ("LINEBELOW", (0,0), (-1,-2), 0.5, HexColor("#e0e0e8")),
+    ("BACKGROUND", (0,0), (-1,0), LIGHT_BG),
+]))
+story.append(keys)
+story.append(Spacer(1, 20))
+story.append(Paragraph("""
+The command palette (⌘K) lets you jump to any screen, compose a new post, or
+trigger actions without touching the mouse.
+""", body_s))
+story.append(PageBreak())
+
+# ══════════════════════════════════════ 9. TROUBLESHOOTING ══════════════════════════════════════
+story.append(Paragraph("9. Troubleshooting", h1_s))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=14))
+
+faq = Table([
+    ["Question", "Answer"],
+    ["Why can't I boost on some columns?", "That platform's API doesn't expose resharing. The button is simply not there — we never fake capabilities. Use Quote… with attribution instead."],
+    ["Why did everyone get logged out?", "A role or membership change bumped the workspace's authorization epoch. Stale sessions fail closed immediately. One re-login fixes it."],
+    ["Where are my passwords?", "Nowhere. SuperPoster stores OAuth tokens only, envelope-encrypted in the vault. Revoke access from the platform or in SuperPoster at any time."],
+    ["Who can see my stream keys?", "Nobody through any interface. Keys are redacted from every screen, log, API response, and audit entry by database-level enforcement."],
+    ["Why is my capacity at 0?", "You've hit your API tier's rolling 24h cap. The capacity chip shows when the next slot frees — as your oldest post exits the window."],
+    ["Posts stuck as 'pending'?", "The scheduler worker picks them up automatically. Check that the Temporal service is running (your admin can verify via /readyz)."],
+], colWidths=[1.8*inch, 4.7*inch])
+faq.setStyle(TableStyle([
+    ("FONTNAME", (0,0), (-1,0), "Helvetica-Bold"),
+    ("FONTSIZE", (0,0), (-1,-1), 9.5),
+    ("TEXTCOLOR", (0,1), (0,-1), BRAND_INDIGO),
+    ("TEXTCOLOR", (1,1), (1,-1), DARK_TEXT),
+    ("VALIGN", (0,0), (-1,-1), "TOP"),
+    ("BOTTOMPADDING", (0,0), (-1,-1), 10),
+    ("TOPPADDING", (0,0), (-1,-1), 10),
+    ("LINEBELOW", (0,0), (-1,-2), 0.5, HexColor("#e0e0e8")),
+    ("BACKGROUND", (0,0), (-1,0), LIGHT_BG),
+]))
+story.append(faq)
+
+story.append(Spacer(1, 30))
+story.append(HRFlowable(width="100%", color=BRAND_INDIGO, thickness=1, spaceAfter=10))
+story.append(Paragraph("SuperPoster · Version 1.0 · October 2026", ParagraphStyle(
+    "footer", fontName="Helvetica", fontSize=9, textColor=DARK_MUTED, alignment=TA_CENTER
+)))
+
+doc.build(story)
+print(f"PDF: {OUT} ({os.path.getsize(OUT):,} bytes)")
diff --git a/tsconfig.base.json b/tsconfig.base.json
new file mode 100644
index 0000000..b9493bc
--- /dev/null
+++ b/tsconfig.base.json
@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "sourceMap": true,
+    "outDir": "dist",
+    "baseUrl": "."
+  }
+}
diff --git a/turbo.json b/turbo.json
new file mode 100644
index 0000000..bb6c842
--- /dev/null
+++ b/turbo.json
@@ -0,0 +1,19 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "agentGuidance": false,
+  "tasks": {
+    "build": {
+      "dependsOn": ["^build"],
+      "outputs": ["dist/**", ".next/**", "!.next/cache/**"]
+    },
+    "lint": {},
+    "typecheck": {
+      "dependsOn": ["^build"]
+    },
+    "test": {},
+    "dev": {
+      "cache": false,
+      "persistent": true
+    }
+  }
+}